diff options
Diffstat (limited to 'doc/user')
327 files changed, 6469 insertions, 3772 deletions
diff --git a/doc/user/abuse_reports.md b/doc/user/abuse_reports.md index e2f2038f240..66b7c3c6ac7 100644 --- a/doc/user/abuse_reports.md +++ b/doc/user/abuse_reports.md @@ -1,68 +1,8 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'report_abuse.md' --- -# Abuse reports **(FREE)** +This file was moved to [another location](report_abuse.md). -You can report abuse from other GitLab users to GitLab administrators. - -A GitLab administrator [can then choose](admin_area/abuse_reports.md) to: - -- Remove the user, which deletes them from the instance. -- Block the user, which denies them access to the instance. -- Or remove the report, which retains the user's access to the instance. - -You can report a user through their: - -- [Profile](#reporting-abuse-through-a-users-profile) -- [Comments](#reporting-abuse-through-a-users-comment) -- [Issues and Merge requests](#reporting-abuse-through-a-users-issue-or-merge-request) - -## Reporting abuse through a user's profile - -To report abuse from a user's profile page: - -1. Click on the exclamation point report abuse button at the top right of the - user's profile. -1. Complete an abuse report. -1. Click the **Send report** button. - -## Reporting abuse through a user's comment - -To report abuse from a user's comment: - -1. Click on the vertical ellipsis (⋮) more actions button to open the dropdown. -1. Select **Report as abuse**. -1. Complete an abuse report. -1. Click the **Send report** button. - -NOTE: -A URL to the reported user's comment is pre-filled in the abuse report's -**Message** field. - -## Reporting abuse through a user's issue or merge request - -The **Report abuse** button is displayed at the top right of the issue or merge request: - -- When **Report abuse** is selected from the menu that appears when the - **Close issue** or **Close merge request** button is clicked, for users that - have permission to close the issue or merge request. -- When viewing the issue or merge request, for users that don't have permission - to close the issue or merge request. - -With the **Report abuse** button displayed, to submit an abuse report: - -1. Click the **Report abuse** button. -1. Submit an abuse report. -1. Click the **Send report** button. - -NOTE: -A URL to the reported user's issue or merge request is pre-filled -in the abuse report's **Message** field. - -## Managing abuse reports - -Admins are able to view and resolve abuse reports. -For more information, see [abuse reports administration documentation](admin_area/abuse_reports.md). +<!-- This redirect file can be deleted after <2021-07-21>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/abuse_reports.md b/doc/user/admin_area/abuse_reports.md index 85ad0667322..5424d4d2cb4 100644 --- a/doc/user/admin_area/abuse_reports.md +++ b/doc/user/admin_area/abuse_reports.md @@ -1,90 +1,8 @@ --- -stage: Manage -group: Access -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, howto +redirect_to: 'review_abuse_reports.md' --- -# Abuse reports **(FREE SELF)** +This file was moved to [another location](review_abuse_reports.md). -View and resolve abuse reports from GitLab users. - -GitLab administrators can view and [resolve](#resolving-abuse-reports) abuse -reports in the Admin Area. - -## Receiving notifications of abuse reports - -To receive notifications of new abuse reports by e-mail, follow these steps: - -1. Select **Admin Area > Settings > Reporting**. -1. Expand the **Abuse reports** section. -1. Provide an email address. - -The notification email address can also be set and retrieved -[using the API](../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls). - -## Reporting abuse - -To find out more about reporting abuse, see [abuse reports user -documentation](../abuse_reports.md). - -## Resolving abuse reports - -To access abuse reports, go to **Admin Area > Abuse Reports**. - -There are 3 ways to resolve an abuse report, with a button for each method: - -- Remove user & report. This: - - [Deletes the reported user](../profile/account/delete_account.md) from the - instance. - - Removes the abuse report from the list. -- [Block user](#blocking-users). -- Remove report. This: - - Removes the abuse report from the list. - - Removes access restrictions for the reported user. - -The following is an example of the **Abuse Reports** page: - - - -### Blocking users - -A blocked user cannot log in or access any repositories, but all of their data -remains. - -Blocking a user: - -- Leaves them in the abuse report list. -- Changes the **Block user** button to a disabled **Already blocked** button. - -The user is notified with the following message: - -```plaintext -Your account has been blocked. If you believe this is in error, contact a staff member. -``` - -After blocking, you can still either: - -- Remove the user and report if necessary. -- Remove the report. - -The following is an example of a blocked user listed on the **Abuse Reports** -page: - - - -NOTE: -Users can be [blocked](../../api/users.md#block-user) and -[unblocked](../../api/users.md#unblock-user) using the GitLab API. - -<!-- ## 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. --> +<!-- This redirect file can be deleted after <2021-07-21>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/activating_deactivating_users.md b/doc/user/admin_area/activating_deactivating_users.md index 144ee2dbf98..cafc7caf981 100644 --- a/doc/user/admin_area/activating_deactivating_users.md +++ b/doc/user/admin_area/activating_deactivating_users.md @@ -1,69 +1,8 @@ --- -stage: Manage -group: Access -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: howto +redirect_to: 'moderate_users.md' --- -# Activating and deactivating users +This document was moved to [another location](moderate_users.md). -GitLab administrators can deactivate and activate users. - -## Deactivating a user - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4. - -In order to temporarily prevent access by a GitLab user that has no recent activity, administrators -can choose to deactivate the user. - -Deactivating a user is functionally identical to [blocking a user](blocking_unblocking_users.md), -with the following differences: - -- It does not prohibit the user from logging back in via the UI. -- Once a deactivated user logs back into the GitLab UI, their account is set to active. - -A deactivated user: - -- Cannot access Git repositories or the API. -- Will not receive any notifications from GitLab. -- Will not be able to use [slash commands](../../integration/slash_commands.md). - -Personal projects, and group and user history of the deactivated user will be left intact. - -A user can be deactivated from the Admin Area. To do this: - -1. Navigate to **Admin Area > Overview > Users**. -1. Select a user. -1. Under the **Account** tab, click **Deactivate user**. - -Please note that for the deactivation option to be visible to an admin, the user: - -- Must be currently active. -- Must not have signed in, or have any activity, in the last 90 days. - -Users can also be deactivated using the [GitLab API](../../api/users.md#deactivate-user). - -NOTE: -A deactivated user does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). - -## Activating a user - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4. - -A deactivated user can be activated from the Admin Area. - -To do this: - -1. Navigate to **Admin Area > Overview > Users**. -1. Click on the **Deactivated** tab. -1. Select a user. -1. Under the **Account** tab, click **Activate user**. - -Users can also be activated using the [GitLab API](../../api/users.md#activate-user). - -NOTE: -Activating a user changes the user's state to active and consumes a -[seat](../../subscriptions/self_managed/index.md#billable-users). - -NOTE: -A deactivated user can also activate their account themselves by logging back in via the UI. +<!-- This redirect file can be deleted after <2021-08-12>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/analytics/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index a8f6e8ec8fa..b13faf2bb3e 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -27,8 +27,6 @@ of top-performing instances based on [usage ping data](../settings/usage_statist collected. Your score is compared to the lead score of each feature and then expressed as a percentage at the bottom of said feature. Your overall **DevOps Score** is an average of your feature scores. You can use this score to compare your DevOps status to other organizations. - - The page also provides helpful links to articles and GitLab docs, to help you improve your scores. @@ -58,8 +56,6 @@ DevOps Adoption allows you to: - Identify specific groups that are lagging in their adoption of GitLab so you can help them along in their DevOps journey. - Find the groups that have adopted certain features and can provide guidance to other groups on how to use those features. - - ### Disable or enable DevOps Adoption DevOps Adoption is deployed behind a feature flag that is **disabled by default**. diff --git a/doc/user/admin_area/analytics/img/dev_ops_adoption_v13_9.png b/doc/user/admin_area/analytics/img/dev_ops_adoption_v13_9.png Binary files differdeleted file mode 100644 index a295179dda3..00000000000 --- a/doc/user/admin_area/analytics/img/dev_ops_adoption_v13_9.png +++ /dev/null diff --git a/doc/user/admin_area/analytics/img/dev_ops_report_v13_4.png b/doc/user/admin_area/analytics/img/dev_ops_report_v13_4.png Binary files differdeleted file mode 100644 index d47d86cd514..00000000000 --- a/doc/user/admin_area/analytics/img/dev_ops_report_v13_4.png +++ /dev/null diff --git a/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6.png b/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6.png Binary files differdeleted file mode 100644 index da9e4c64e12..00000000000 --- a/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6.png +++ /dev/null diff --git a/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6_a.png b/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6_a.png Binary files differnew file mode 100644 index 00000000000..210c5c2609a --- /dev/null +++ b/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6_a.png diff --git a/doc/user/admin_area/analytics/usage_trends.md b/doc/user/admin_area/analytics/usage_trends.md index 38cd2dee4e9..7fb23f702a4 100644 --- a/doc/user/admin_area/analytics/usage_trends.md +++ b/doc/user/admin_area/analytics/usage_trends.md @@ -39,4 +39,4 @@ in the categories shown in [Total counts](#total-counts). These charts help you visualize how rapidly these records are being created on your instance. - + diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index e2e96f980f5..0d72f09dfd9 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -16,9 +16,7 @@ section. By default, the navigation 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 1MB) and it is automatically resized. - - +used (less than 1 MB) and it is automatically resized. After you select and upload an image, click **Update appearance settings** at the bottom of the page to activate it in the GitLab instance. @@ -34,8 +32,6 @@ By default, the favicon (used by the browser as the tab icon, as well as the CI uses the GitLab logo, but this can be customized with any icon desired. It must be a 32x32 `.png` or `.ico` image. - - After you select and upload an icon, click **Update appearance settings** at the bottom of the page to activate it in the GitLab instance. @@ -52,8 +48,6 @@ Limited [Markdown](../markdown.md) is supported, such as bold, italics, and link example. Other Markdown features, including lists, images, and quotes are not supported as the header and footer messages can only be a single line. - - If desired, you can select **Enable header and footer in emails** to have the text of the header and footer added to all emails sent by the GitLab instance. @@ -63,16 +57,12 @@ to activate it in the GitLab instance. ## Sign in / Sign up pages You can replace the default message on the sign in / sign up page with your own message -and logo. You can make full use of [Markdown](../markdown.md) in the description: - - +and logo. You can make full use of [Markdown](../markdown.md) in the description. The optimal size for the logo is 640x360px, but any image can be used (below 1MB) and it is resized automatically. The logo image appears between the title and the description, on the left of the sign-up page. - - After you add a message, click **Update appearance settings** at the bottom of the page to activate it in the GitLab instance. You can also click on the **Sign-in page** button, to review the saved appearance settings: @@ -85,8 +75,6 @@ You can add also add a [customized help message](settings/help_page.md) below th You can add a new project guidelines message to the **New project page** within GitLab. You can make full use of [Markdown](../markdown.md) in the description: - - The message is displayed below the **New Project** message, on the left side of the **New project page**. @@ -94,8 +82,6 @@ After you add a message, click **Update appearance settings** at the bottom of t to activate it in the GitLab instance. You can also click on the **New project page** button, which brings you to the new project page so you can review the change. - - ## Libravatar [Libravatar](https://www.libravatar.org) is supported by GitLab for avatar images, but you must diff --git a/doc/user/admin_area/approving_users.md b/doc/user/admin_area/approving_users.md index 9141d7f488d..2b3b90cb1a4 100644 --- a/doc/user/admin_area/approving_users.md +++ b/doc/user/admin_area/approving_users.md @@ -21,7 +21,7 @@ When a user registers for an account while this setting is enabled: A user pending approval: -- Is functionally identical to a [blocked](blocking_unblocking_users.md) user. +- Is functionally identical to a [blocked](moderate_users.md#blocking-a-user) user. - Cannot sign in. - Cannot access Git repositories or the GitLab API. - Does not receive any notifications from GitLab. diff --git a/doc/user/admin_area/blocking_unblocking_users.md b/doc/user/admin_area/blocking_unblocking_users.md index 1dba9e5adda..cafc7caf981 100644 --- a/doc/user/admin_area/blocking_unblocking_users.md +++ b/doc/user/admin_area/blocking_unblocking_users.md @@ -1,51 +1,8 @@ --- -stage: Manage -group: Access -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: howto +redirect_to: 'moderate_users.md' --- -# Blocking and unblocking users +This document was moved to [another location](moderate_users.md). -GitLab administrators block and unblock users. - -## Blocking a user - -In order to completely prevent access of a user to the GitLab instance, administrators can choose to -block the user. - -Users can be blocked [via an abuse report](abuse_reports.md#blocking-users), -or directly from the Admin Area. To do this: - -1. Navigate to **Admin Area > Overview > Users**. -1. Select a user. -1. Under the **Account** tab, click **Block user**. - -A blocked user: - -- Cannot log in. -- Cannot access Git repositories or the API. -- Does not receive any notifications from GitLab. -- Cannot use [slash commands](../../integration/slash_commands.md). - -Personal projects, and group and user history of the blocked user are left intact. - -Users can also be blocked using the [GitLab API](../../api/users.md#block-user). - -NOTE: -A blocked user does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). - -## Unblocking a user - -A blocked user can be unblocked from the Admin Area. To do this: - -1. Navigate to **Admin Area > Overview > Users**. -1. Click on the **Blocked** tab. -1. Select a user. -1. Under the **Account** tab, click **Unblock user**. - -Users can also be unblocked using the [GitLab API](../../api/users.md#unblock-user). - -NOTE: -Unblocking a user changes the user's state to active and consumes a -[seat](../../subscriptions/self_managed/index.md#billable-users). +<!-- This redirect file can be deleted after <2021-08-12>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index 6f6aed68620..67a89f896ff 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Growth +group: Activation 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, howto --- @@ -66,11 +66,16 @@ To add a broadcast message: 1. Navigate to the **Admin Area > Messages** page. 1. Add the text for the message to the **Message** field. Markdown and emoji are supported. 1. Select one of the suggested background colors, or add the hex code of a different color. The default color is orange. -1. If required, add a **Target Path** to only show the broadcast message on URLs matching that path. You can use the wildcard character `*` to match multiple URLs, for example `/users/*/issues`. +1. If required, add a **Target Path** to only show the broadcast message on URLs matching that path. You can use the wildcard character `*` to match multiple URLs, for example `mygroup/myproject*`. 1. Select a date for the message to start and end. 1. Click the **Add broadcast message** button. NOTE: +When scoping messages, you can't use preceding or trailing slashes. For example, +instead of `/mygroup/myproject/`, you must use `mygroup/myproject`. A fix is +[planned for GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59482). + +NOTE: The **Background color** field expects the value to be a hexadecimal code because the form uses the [color_field](https://api.rubyonrails.org/v6.0.3.4/classes/ActionView/Helpers/FormHelper.html#method-i-color_field) helper method, which generates the proper HTML to render. diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index 0ae6e41264c..c47dc7d70f5 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -33,7 +33,7 @@ The following is an example of the Credentials inventory page: If you see a **Revoke** button, you can revoke that user's PAT. Whether you see a **Revoke** button depends on the token state, and if an expiration date has been set. For more information, see the following table: -| Token state | [Token expiration enforced?](settings/account_and_limit_settings.md#optional-non-enforcement-of-personal-access-token-expiration) | Show Revoke button? | Comments | +| Token state | [Token expiration enforced?](settings/account_and_limit_settings.md#do-not-enforce-personal-access-token-expiration) | Show Revoke button? | Comments | |-------------|------------------------|--------------------|----------------------------------------------------------------------------| | Active | Yes | Yes | Allows administrators to revoke the PAT, such as for a compromised account | | Active | No | Yes | Allows administrators to revoke the PAT, such as for a compromised account | @@ -56,14 +56,7 @@ The instance then notifies the user. ## Review existing GPG keys > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/282429) in GitLab 13.10. -> - [Deployed behind a feature flag](../feature_flags.md), disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/292961) in GitLab 13.11. -> - Enabled on GitLab.com. -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-the-gpg-keys-view). - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292961) in GitLab 13.12. You can view all existing GPG in your GitLab instance by navigating to the credentials inventory GPG Keys tab, as well as the following properties: @@ -73,22 +66,3 @@ credentials inventory GPG Keys tab, as well as the following properties: - Whether the GPG key is [verified or unverified](../project/repository/gpg_signed_commits/index.md)  - -### Enable or disable the GPG keys view - -Enabling or disabling the GPG keys view is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -Feature.enable(:credential_inventory_gpg_keys) -``` - -To disable it: - -```ruby -Feature.disable(:credential_inventory_gpg_keys) -``` diff --git a/doc/user/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md index 83b1869c7f2..32756ab4780 100644 --- a/doc/user/admin_area/diff_limits.md +++ b/doc/user/admin_area/diff_limits.md @@ -9,7 +9,7 @@ type: reference You can set a maximum size for display of diff files (patches). -For details about diff files, [View changes between files](../project/merge_requests/reviewing_and_managing_merge_requests.md#view-changes-between-file-versions). +For details about diff files, [view changes between files](../project/merge_requests/changes.md). ## Maximum diff patch size @@ -23,10 +23,10 @@ This affects merge requests and branch comparison views. To set the maximum diff patch size: -1. Go to **Admin Area > Settings > General**. +1. Go to the Admin Area (**{admin}**) and select **Settings > General**. 1. Expand **Diff limits**. 1. Enter a value for **Maximum diff patch size**, measured in bytes. -1. Click on **Save changes**. +1. Select **Save changes**. WARNING: This setting is experimental. An increased maximum increases resource diff --git a/doc/user/admin_area/img/abuse_reports_page_v13_11.png b/doc/user/admin_area/img/abuse_reports_page_v13_11.png Binary files differindex bcb2aec9e64..ef57f45ab77 100644 --- a/doc/user/admin_area/img/abuse_reports_page_v13_11.png +++ b/doc/user/admin_area/img/abuse_reports_page_v13_11.png diff --git a/doc/user/admin_area/img/appearance_favicon_v12_3.png b/doc/user/admin_area/img/appearance_favicon_v12_3.png Binary files differdeleted file mode 100644 index 0bab0638265..00000000000 --- a/doc/user/admin_area/img/appearance_favicon_v12_3.png +++ /dev/null diff --git a/doc/user/admin_area/img/appearance_header_footer_v12_3.png b/doc/user/admin_area/img/appearance_header_footer_v12_3.png Binary files differdeleted file mode 100644 index da68ddcf166..00000000000 --- a/doc/user/admin_area/img/appearance_header_footer_v12_3.png +++ /dev/null diff --git a/doc/user/admin_area/img/appearance_header_logo_v12_3.png b/doc/user/admin_area/img/appearance_header_logo_v12_3.png Binary files differdeleted file mode 100644 index 414301b8efa..00000000000 --- a/doc/user/admin_area/img/appearance_header_logo_v12_3.png +++ /dev/null diff --git a/doc/user/admin_area/img/appearance_new_project_preview_v12_3.png b/doc/user/admin_area/img/appearance_new_project_preview_v12_3.png Binary files differdeleted file mode 100644 index 92593399843..00000000000 --- a/doc/user/admin_area/img/appearance_new_project_preview_v12_3.png +++ /dev/null diff --git a/doc/user/admin_area/img/appearance_new_project_v12_3.png b/doc/user/admin_area/img/appearance_new_project_v12_3.png Binary files differdeleted file mode 100644 index 120a191de27..00000000000 --- a/doc/user/admin_area/img/appearance_new_project_v12_3.png +++ /dev/null diff --git a/doc/user/admin_area/img/appearance_sign_in_preview_v12_3.png b/doc/user/admin_area/img/appearance_sign_in_preview_v12_3.png Binary files differdeleted file mode 100644 index d05bda71545..00000000000 --- a/doc/user/admin_area/img/appearance_sign_in_preview_v12_3.png +++ /dev/null diff --git a/doc/user/admin_area/img/appearance_sign_in_v12_3.png b/doc/user/admin_area/img/appearance_sign_in_v12_3.png Binary files differdeleted file mode 100644 index 0caa29aae2c..00000000000 --- a/doc/user/admin_area/img/appearance_sign_in_v12_3.png +++ /dev/null diff --git a/doc/user/admin_area/img/cohorts_v13_9.png b/doc/user/admin_area/img/cohorts_v13_9.png Binary files differdeleted file mode 100644 index 6a616b201c9..00000000000 --- a/doc/user/admin_area/img/cohorts_v13_9.png +++ /dev/null diff --git a/doc/user/admin_area/img/cohorts_v13_9_a.png b/doc/user/admin_area/img/cohorts_v13_9_a.png Binary files differnew file mode 100644 index 00000000000..a891b5b12c2 --- /dev/null +++ b/doc/user/admin_area/img/cohorts_v13_9_a.png diff --git a/doc/user/admin_area/img/license_upload_v13_12.png b/doc/user/admin_area/img/license_upload_v13_12.png Binary files differnew file mode 100644 index 00000000000..81dc162c1f0 --- /dev/null +++ b/doc/user/admin_area/img/license_upload_v13_12.png diff --git a/doc/user/admin_area/img/license_upload_v13_8.png b/doc/user/admin_area/img/license_upload_v13_8.png Binary files differdeleted file mode 100644 index c15bc2bfa02..00000000000 --- a/doc/user/admin_area/img/license_upload_v13_8.png +++ /dev/null diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 08fcd4674dc..5d1fde1c767 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -28,7 +28,7 @@ The Admin Area is made up of the following sections: | **{messages}** Messages | Send and manage [broadcast messages](broadcast_messages.md) for your users. | | **{hook}** System Hooks | Configure [system hooks](../../system_hooks/system_hooks.md) for many events. | | **{applications}** Applications | Create system [OAuth applications](../../integration/oauth_provider.md) for integrations with other services. | -| **{slight-frown}** Abuse Reports | Manage [abuse reports](abuse_reports.md) submitted by your users. | +| **{slight-frown}** Abuse Reports | Manage [abuse reports](review_abuse_reports.md) submitted by your users. | | **{license}** License | Upload, display, and remove [licenses](license.md). | | **{cloud-gear}** Kubernetes | Create and manage instance-level [Kubernetes clusters](../instance/clusters/index.md). | | **{push-rules}** Push rules | Configure pre-defined Git [push rules](../../push_rules/push_rules.md) for projects. Also, configure [merge requests approvers rules](merge_requests_approvals.md). | @@ -117,8 +117,8 @@ To list users matching a specific criteria, click on one of the following tabs o - **2FA Enabled** - **2FA Disabled** - **External** -- **[Blocked](blocking_unblocking_users.md)** -- **[Deactivated](activating_deactivating_users.md)** +- **[Blocked](moderate_users.md#blocking-a-user)** +- **[Deactivated](moderate_users.md#deactivating-a-user)** - **Without projects** For each user, the following are listed: @@ -126,6 +126,7 @@ For each user, the following are listed: 1. Username 1. Email address 1. Project membership count +1. Group membership count ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276215) in GitLab 13.12) 1. Date of account creation 1. Date of last activity diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index 85ff5f8e7b1..73472fcf67a 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -38,24 +38,24 @@ to **Admin Area > License**. Otherwise, you can: -1. Navigate manually to the **Admin Area** by clicking the wrench (**{admin}**) icon in the menu bar. +1. Navigate manually to the **Admin Area** by selecting the wrench (**{admin}**) icon in the top menu. -1. Navigate to the **License** tab, and click **Upload New License**. +1. Navigate to the **License** tab, and select **Upload New License**. - *If you've received a `.gitlab-license` file:* 1. Download the license file to your local machine. 1. Select **Upload `.gitlab-license` file**. - 1. Select **Choose File** and select the license file. + 1. Select **Choose file** and select the license file. In this example the license file is named `GitLab.gitlab-license`. - 1. Check the **Subscription Agreement** checkbox. + 1. Select the **Terms of Service** checkbox. 1. Select **Upload License**. -  +  - *If you've received your license as plain text:* 1. Select **Enter license key**. 1. Copy the license and paste it into the **License key** field. - 1. Check the **Subscription Agreement** checkbox. + 1. Select the **Terms of Service** checkbox. 1. Select **Upload License**. ## Add your license at install time diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index e8c435a2b5e..fadccadaf2c 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -32,4 +32,4 @@ any commits to the source branch. - **Prevent users from modifying merge request approvers list**. Prevents users from modifying the approvers list in project settings or in individual merge requests. -Also read the [project level merge request approval rules](../project/merge_requests/merge_request_approvals.md), which are affected by instance level rules. +Also read the [project level merge request approval rules](../project/merge_requests/approvals/index.md), which are affected by instance level rules. diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md new file mode 100644 index 00000000000..c04003dd75f --- /dev/null +++ b/doc/user/admin_area/moderate_users.md @@ -0,0 +1,157 @@ +--- +stage: Manage +group: Access +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: howto +--- + +# Moderate users + +GitLab administrators can moderate user access by blocking, banning, or deactivating users. + +## Blocking and unblocking users + +GitLab administrators can block and unblock users. + +### Blocking a user + +In order to completely prevent access of a user to the GitLab instance, +administrators can choose to block the user. + +Users can be blocked [via an abuse report](review_abuse_reports.md#blocking-users), +or directly from the Admin Area. To do this: + +1. Navigate to **Admin Area > Overview > Users**. +1. Select a user. +1. Under the **Account** tab, click **Block user**. + +A blocked user: + +- Cannot log in. +- Cannot access Git repositories or the API. +- Does not receive any notifications from GitLab. +- Cannot use [slash commands](../../integration/slash_commands.md). + +Personal projects, and group and user history of the blocked user are left intact. + +Users can also be blocked using the [GitLab API](../../api/users.md#block-user). + +NOTE: +A blocked user does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). + +### Unblocking a user + +A blocked user can be unblocked from the Admin Area. To do this: + +1. Navigate to **Admin Area > Overview > Users**. +1. Click on the **Blocked** tab. +1. Select a user. +1. Under the **Account** tab, click **Unblock user**. + +Users can also be unblocked using the [GitLab API](../../api/users.md#unblock-user). + +NOTE: +Unblocking a user changes the user's state to active and consumes a +[seat](../../subscriptions/self_managed/index.md#billable-users). + +## Activating and deactivating users + +GitLab administrators can deactivate and activate users. + +### Deactivating a user + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4. + +In order to temporarily prevent access by a GitLab user that has no recent activity, +administrators can choose to deactivate the user. + +Deactivating a user is functionally identical to [blocking a user](#blocking-and-unblocking-users), +with the following differences: + +- It does not prohibit the user from logging back in via the UI. +- Once a deactivated user logs back into the GitLab UI, their account is set to active. + +A deactivated user: + +- Cannot access Git repositories or the API. +- Will not receive any notifications from GitLab. +- Will not be able to use [slash commands](../../integration/slash_commands.md). + +Personal projects, and group and user history of the deactivated user are left intact. + +A user can be deactivated from the Admin Area. To do this: + +1. Navigate to **Admin Area > Overview > Users**. +1. Select a user. +1. Under the **Account** tab, click **Deactivate user**. + +Please note that for the deactivation option to be visible to an admin, the user: + +- Must be currently active. +- Must not have signed in, or have any activity, in the last 90 days. + +Users can also be deactivated using the [GitLab API](../../api/users.md#deactivate-user). + +NOTE: +A deactivated user does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). + +### Activating a user + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4. + +A deactivated user can be activated from the Admin Area. + +To do this: + +1. Navigate to **Admin Area > Overview > Users**. +1. Click on the **Deactivated** tab. +1. Select a user. +1. Under the **Account** tab, click **Activate user**. + +Users can also be activated using the [GitLab API](../../api/users.md#activate-user). + +NOTE: +Activating a user changes the user's state to active and consumes a +[seat](../../subscriptions/self_managed/index.md#billable-users). + +NOTE: +A deactivated user can also activate their account themselves by logging back in via the UI. + +## Ban and unban users + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327353) in GitLab 13.12. + +GitLab administrators can ban users. + +NOTE: +This feature is behind a feature flag that is disabled by default. GitLab administrators +with access to the GitLab Rails console can [enable](../../administration/feature_flags.md) +this feature for your GitLab instance. + +### Ban a user + +To completely block a user, administrators can choose to ban the user. + +Users can be banned using the Admin Area. To do this: + +1. Navigate to **Admin Area > Overview > Users**. +1. Select a user. +1. Under the **Account** tab, click **Ban user**. + +NOTE: +This feature is a work in progress. Currently, banning a user +only blocks them and does not hide their comments or issues. +This functionality will be implemented in follow up issues. + +### Unban a user + +A banned user can be unbanned using the Admin Area. To do this: + +1. Navigate to **Admin Area > Overview > Users**. +1. Click on the **Banned** tab. +1. Select a user. +1. Under the **Account** tab, click **Unban user**. + +NOTE: +Unbanning a user changes the user's state to active and consumes a +[seat](../../subscriptions/self_managed/index.md#billable-users). diff --git a/doc/user/admin_area/monitoring/background_migrations.md b/doc/user/admin_area/monitoring/background_migrations.md new file mode 100644 index 00000000000..50593959710 --- /dev/null +++ b/doc/user/admin_area/monitoring/background_migrations.md @@ -0,0 +1,81 @@ +--- +stage: Enablement +group: Database +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 +--- + +# Batched Background Migrations **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51332) in GitLab 13.11. +> - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/329511) in GitLab 13.12. +> - Enabled on GitLab.com. +> - Recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-batched-background-migrations). **(FREE SELF)** + +There can be [risks when disabling released features](../../../user/feature_flags.md#risks-when-disabling-released-features). +Refer to this feature's version history for more details. + +To update database tables in batches, GitLab can use batched background migrations. These migrations +are created by GitLab developers and run automatically on upgrade. However, such migrations are +limited in scope to help with migrating some `integer` database columns to `bigint`. This is needed to +prevent integer overflow for some tables. + +All migrations must be finished before upgrading GitLab. To check the status of the existing +migrations, execute this command: + +```ruby +Gitlab::Database::BackgroundMigration::BatchedMigration.pluck(:id, :table_name, :status) +``` + +## Enable or disable Batched Background Migrations **(FREE SELF)** + +Batched Background Migrations is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:execute_batched_migrations_on_schedule) +``` + +To disable it: + +```ruby +Feature.disable(:execute_batched_migrations_on_schedule) +``` + +## Automatic batch size optimization **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60133) in GitLab 13.12. +> - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/329511) in GitLab 13.12. +> - Enabled on GitLab.com. +> - Recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-automatic-batch-size-optimization). **(FREE SELF)** + +There can be [risks when disabling released features](../../../user/feature_flags.md#risks-when-disabling-released-features). +Refer to this feature's version history for more details. + +To maximize throughput of batched background migrations (in terms of the number of tuples updated per time unit), batch sizes are automatically adjusted based on how long the previous batches took to complete. + +## Enable or disable automatic batch size optimization **(FREE SELF)** + +Automatic batch size optimization for Batched Background Migrations is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:optimize_batched_migrations) +``` + +To disable it: + +```ruby +Feature.disable(:optimize_batched_migrations) +``` diff --git a/doc/user/admin_area/review_abuse_reports.md b/doc/user/admin_area/review_abuse_reports.md new file mode 100644 index 00000000000..12a3111c6f3 --- /dev/null +++ b/doc/user/admin_area/review_abuse_reports.md @@ -0,0 +1,90 @@ +--- +stage: Manage +group: Access +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, howto +--- + +# Review abuse reports **(FREE SELF)** + +View and resolve abuse reports from GitLab users. + +GitLab administrators can view and [resolve](#resolving-abuse-reports) abuse +reports in the Admin Area. + +## Receiving notifications of abuse reports + +To receive notifications of new abuse reports by e-mail, follow these steps: + +1. Select **Admin Area > Settings > Reporting**. +1. Expand the **Abuse reports** section. +1. Provide an email address. + +The notification email address can also be set and retrieved +[using the API](../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls). + +## Reporting abuse + +To find out more about reporting abuse, see [abuse reports user +documentation](../report_abuse.md). + +## Resolving abuse reports + +To access abuse reports, go to **Admin Area > Abuse Reports**. + +There are 3 ways to resolve an abuse report, with a button for each method: + +- Remove user & report. This: + - [Deletes the reported user](../profile/account/delete_account.md) from the + instance. + - Removes the abuse report from the list. +- [Block user](#blocking-users). +- Remove report. This: + - Removes the abuse report from the list. + - Removes access restrictions for the reported user. + +The following is an example of the **Abuse Reports** page: + + + +### Blocking users + +A blocked user cannot log in or access any repositories, but all of their data +remains. + +Blocking a user: + +- Leaves them in the abuse report list. +- Changes the **Block user** button to a disabled **Already blocked** button. + +The user is notified with the following message: + +```plaintext +Your account has been blocked. If you believe this is in error, contact a staff member. +``` + +After blocking, you can still either: + +- Remove the user and report if necessary. +- Remove the report. + +The following is an example of a blocked user listed on the **Abuse Reports** +page: + + + +NOTE: +Users can be [blocked](../../api/users.md#block-user) and +[unblocked](../../api/users.md#unblock-user) using the GitLab API. + +<!-- ## 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. --> 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 0f391118215..8bc5a035e2a 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -50,7 +50,7 @@ You can set a global prefix for all generated Personal Access Tokens. A prefix can help you identify PATs visually, as well as with automation tools. -### Setting a prefix +### Set a prefix Only a GitLab administrator can set the prefix, which is a global setting applied to any PAT generated in the system by any user: @@ -148,7 +148,7 @@ To set a limit on how long these sessions are valid: 1. Fill in the **Session duration for Git operations when 2FA is enabled (minutes)** field. 1. Click **Save changes**. -## Limiting lifetime of personal access tokens **(ULTIMATE SELF)** +## Limit the lifetime of personal access tokens **(ULTIMATE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in GitLab Ultimate 12.6. @@ -160,7 +160,7 @@ Personal access tokens are the only tokens needed for programmatic access to Git However, organizations with security requirements may want to enforce more protection by requiring the regular rotation of these tokens. -### Setting a lifetime +### Set a lifetime Only a GitLab administrator can set a lifetime. Leaving it empty means there are no restrictions. @@ -180,12 +180,16 @@ Once a lifetime for personal access tokens is set, GitLab: allowed lifetime. Three hours is given to allow administrators to change the allowed lifetime, or remove it, before revocation takes place. -## Optional enforcement of SSH key expiration **(ULTIMATE SELF)** +## Enforce SSH key expiration **(ULTIMATE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250480) in GitLab 13.9. By default, expired SSH keys **can still be used**. -You can prevent the use of expired SSH keys with the following steps: + +WARNING: +Allowing use of expired SSH keys by default is deprecated and scheduled to change in GitLab 14.0. + +To prevent the use of expired SSH keys: 1. Navigate to **Admin Area > Settings > General**. 1. Expand the **Account and limit** section. @@ -195,7 +199,7 @@ Enforcing SSH key expiration immediately disables all expired SSH keys. For more information, see the following issue on [SSH key expiration](https://gitlab.com/gitlab-org/gitlab/-/issues/320970). -## Optional non-enforcement of Personal Access Token expiration **(ULTIMATE SELF)** +## Do not enforce Personal Access Token expiration **(ULTIMATE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214723) in GitLab Ultimate 13.1. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/296881) in GitLab 13.9. @@ -209,7 +213,7 @@ To do this: 1. Expand the **Account and limit** section. 1. Uncheck the **Enforce personal access token expiration** checkbox. -## Disabling user profile name changes **(PREMIUM SELF)** +## Disable user profile name changes **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24605) in GitLab 12.7. diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 29b5bdd5e05..decd204dbe5 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -19,11 +19,11 @@ for all projects: 1. Go to **Admin Area > 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/index.md#auto-devops-base-domain) - which is going to be used for Auto Deploy and Auto Review Apps. + which is used for Auto Deploy and Auto Review Apps. 1. Hit **Save changes** for the changes to take effect. From now on, every existing project and newly created ones that don't have a -`.gitlab-ci.yml`, will use the Auto DevOps pipelines. +`.gitlab-ci.yml`, uses the Auto DevOps pipelines. If you want to disable it for a specific project, you can do so in [its settings](../../../topics/autodevops/index.md#enable-or-disable-auto-devops). @@ -49,13 +49,13 @@ To change it at the: 1. Change the value of maximum artifacts size (in MB). 1. Click **Save changes** for the changes to take effect. -- Group level (this will override the instance setting): +- Group level (this overrides the instance setting): 1. Go to the group's **Settings > CI/CD > General Pipelines**. 1. Change the value of **maximum artifacts size (in MB)**. 1. Click **Save changes** for the changes to take effect. -- Project level (this will override the instance and group settings): +- Project level (this overrides the instance and group settings): 1. Go to the project's **Settings > CI/CD > General Pipelines**. 1. Change the value of **maximum artifacts size (in MB)**. @@ -80,7 +80,7 @@ This setting is set per job and can be overridden in To disable the expiration, set it to `0`. The default unit is in seconds. NOTE: -Any changes to this setting will apply to new artifacts only. The expiration time will not +Any changes to this setting applies to new artifacts only. The expiration time is not be updated for artifacts created before this setting was changed. The administrator may need to manually search for and expire previously-created artifacts, as described in the [troubleshooting documentation](../../../administration/troubleshooting/gitlab_rails_cheat_sheet.md#remove-artifacts-more-than-a-week-old). @@ -117,7 +117,7 @@ All application settings have a [customizable cache expiry interval](../../../ad If you have enabled shared runners for your GitLab instance, you can limit their usage by setting a maximum number of pipeline minutes that a group can use on -shared runners per month. Setting this to `0` (default value) will grant +shared runners per month. Setting this to `0` (default value) grants unlimited pipeline minutes. While build limits are stored as minutes, the counting is done in seconds. Usage resets on the first day of each month. On GitLab.com, the quota is calculated based on your @@ -157,18 +157,18 @@ Archiving jobs is useful for reducing the CI/CD footprint on the system by removing some of the capabilities of the jobs (metadata needed to run the job), but persisting the traces and artifacts for auditing purposes. -To set the duration for which the jobs will be considered as old and expired: +To set the duration for which the jobs are considered as old and expired: 1. Go to **Admin Area > Settings > CI/CD**. 1. Expand the **Continuous Integration and Deployment** section. 1. Set the value of **Archive jobs**. 1. Hit **Save changes** for the changes to take effect. -Once that time passes, the jobs will be archived and no longer able to be +Once that time passes, the jobs are archived and no longer able to be retried. Make it empty to never expire jobs. It has to be no less than 1 day, for example: <code>15 days</code>, <code>1 month</code>, <code>2 years</code>. -As of June 22, 2020 the [value is set](../../gitlab_com/index.md#gitlab-cicd) to 3 months on GitLab.com. Jobs created before that date will be archived after September 22, 2020. +As of June 22, 2020 the [value is set](../../gitlab_com/index.md#gitlab-cicd) to 3 months on GitLab.com. Jobs created before that date were archived after September 22, 2020. ## Default CI configuration path diff --git a/doc/user/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md index 1ac54bdc037..5739c3e4f10 100644 --- a/doc/user/admin_area/settings/help_page.md +++ b/doc/user/admin_area/settings/help_page.md @@ -18,13 +18,8 @@ You can add a help message, which is shown on the GitLab `/help` page (e.g., 1. Navigate to **Admin Area > Settings > Preferences**, then expand **Help page**. 1. Under **Help page text**, fill in the information you wish to display on `/help`. - -  - 1. Save your changes. You can now see the message on `/help`. - - ## Adding a help message to the login page **(STARTER)** You can add a help message, which is shown on the GitLab login page in a new section diff --git a/doc/user/admin_area/settings/img/help_page_help_page_text_ex_v12_3.png b/doc/user/admin_area/settings/img/help_page_help_page_text_ex_v12_3.png Binary files differdeleted file mode 100644 index 421fa2977f9..00000000000 --- a/doc/user/admin_area/settings/img/help_page_help_page_text_ex_v12_3.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/help_page_help_page_text_v12_3.png b/doc/user/admin_area/settings/img/help_page_help_page_text_v12_3.png Binary files differdeleted file mode 100644 index 13c17fb118a..00000000000 --- a/doc/user/admin_area/settings/img/help_page_help_page_text_v12_3.png +++ /dev/null diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 60081f2e0bd..a1f4c6a06e2 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -72,7 +72,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | Option | Description | | ------ | ----------- | | [Spam and Anti-bot Protection](../../../integration/recaptcha.md) | Enable reCAPTCHA or Akismet and set IP limits. For reCAPTCHA, we currently only support [v2](https://developers.google.com/recaptcha/docs/versions). | -| [Abuse reports](../abuse_reports.md) | Set notification email for abuse reports. | +| [Abuse reports](../review_abuse_reports.md) | Set notification email for abuse reports. | ## Metrics and profiling @@ -91,6 +91,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | ------ | ----------- | | Performance optimization | [Write to "authorized_keys" file](../../../administration/operations/fast_ssh_key_lookup.md#setting-up-fast-lookup-via-gitlab-shell) and [Push event activities limit and bulk push events](push_event_activities_limit.md). Various settings that affect GitLab performance. | | [User and IP rate limits](user_and_ip_rate_limits.md) | Configure limits for web and API requests. | +| [Package Registry Rate Limits](package_registry_rate_limits.md) | Configure specific limits for Packages API requests that supersede the user and IP rate limits. | | [Outbound requests](../../../security/webhooks.md) | Allow requests to the local network from hooks and services. | | [Protected Paths](protected_paths.md) | Configure paths to be protected by Rack Attack. | | [Incident Management](../../../operations/incident_management/index.md) Limits | Configure limits on the number of inbound alerts able to be sent to a project. | @@ -107,6 +108,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | Option | Description | | ------ | ----------- | | [Email](email.md) | Various email settings. | +| [What's new](../../../administration/whats-new.md) | Configure What's new drawer and content. | | [Help page](help_page.md) | Help page text and support page URL. | | [Pages](../../../administration/pages/index.md#custom-domain-verification) | Size and domain settings for static websites | | [Real-time features](../../../administration/polling.md) | Change this value to influence how frequently the GitLab UI polls for updates. | diff --git a/doc/user/admin_area/settings/package_registry_rate_limits.md b/doc/user/admin_area/settings/package_registry_rate_limits.md new file mode 100644 index 00000000000..578b7cd1236 --- /dev/null +++ b/doc/user/admin_area/settings/package_registry_rate_limits.md @@ -0,0 +1,33 @@ +--- +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 +type: reference +--- + +# Package Registry Rate Limits **(FREE SELF)** + +Rate limiting is a common technique used to improve the security and durability of a web +application. For more details, see [Rate limits](../../../security/rate_limits.md). General user and +IP rate limits can be enforced in **Admin Area > Settings > Network > User and IP rate limits**. +For more details, see [User and IP rate limits](user_and_ip_rate_limits.md). + +With the [GitLab Package Registry](../../packages/package_registry/index.md), +you can use GitLab as a private or public registry for a variety of common package managers. You can +publish and share packages, which others can consume as a dependency in downstream projects through +the [Packages API](../../../api/packages.md). + +When downloading such dependencies in downstream projects, many requests are made through the +Packages API. You may therefore reach enforced user and IP rate limits. To address this issue, you +can define specific rate limits for the Packages API in +**Admin Area > Settings > Network > Package Registry Rate Limits**: + +- Unauthenticated Packages API requests +- Authenticated Packages API requests + +These limits are disabled by default. When enabled, they supersede the general user and IP rate +limits for requests to the Packages API. You can therefore keep the general user and IP rate limits, +and increase (if necessary) the rate limits for the Packages API. + +Besides this precedence, there are no differences in functionality compared to the general user and +IP rate limits. For more details, see [User and IP rate limits](user_and_ip_rate_limits.md). diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 7b2928a3873..647f9332119 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -20,14 +20,12 @@ To access sign-in restriction settings: You can restrict the password authentication for web interface and Git over HTTP(S): -- **Web interface**: When this feature is disabled, an [external authentication provider](../../../administration/auth/README.md) must be used. +- **Web interface**: When this feature is disabled, the **Standard** sign-in tab is removed and an [external authentication provider](../../../administration/auth/README.md) must be used. - **Git over HTTP(S)**: When this feature is disabled, a [Personal Access Token](../../profile/personal_access_tokens.md) must be used to authenticate. ## Admin Mode > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2158) in GitLab 13.10. -> - It's [deployed behind the feature flag](../../../user/feature_flags.md) `:user_mode_in_session`, disabled by default. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to enable it. When this feature is enabled, instance administrators are limited as regular users. During that period, they do not have access to all projects, groups, or the **Admin Area** menu. @@ -81,25 +79,6 @@ If necessary, you can disable **Admin Mode** as an administrator by using one of ::Gitlab::CurrentSettings.update_attributes!(admin_mode: false) ``` -## Enable or disable Admin Mode - -Admin Mode is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:user_mode_in_session) -``` - -To disable it: - -```ruby -Feature.disable(:user_mode_in_session) -``` - ## Two-factor authentication When this feature is enabled, all users must use the [two-factor authentication](../../profile/account/two_factor_authentication.md). 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 ba4ef890caa..9e64dd59a74 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 @@ -133,6 +133,8 @@ The possible names are: - `throttle_unauthenticated_protected_paths` - `throttle_authenticated_protected_paths_api` - `throttle_authenticated_protected_paths_web` +- `throttle_unauthenticated_packages_api` +- `throttle_authenticated_packages_api` For example, to try out throttles for all authenticated requests to non-protected paths can be done by setting diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md index f3c913b409a..b01a299178d 100644 --- a/doc/user/admin_area/user_cohorts.md +++ b/doc/user/admin_area/user_cohorts.md @@ -6,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Cohorts **(FREE)** -As a benefit of having the [usage ping active](settings/usage_statistics.md), -you can analyze your users' GitLab activities over time. +You can analyze your users' GitLab activities over time. To see user cohorts, go to **Admin Area > Overview > Users**. @@ -16,7 +15,7 @@ To see user cohorts, go to **Admin Area > Overview > Users**. How do you interpret the user cohorts table? Let's review an example with the following user cohorts: - + For the cohort of March 2020, three users were added to this server and have been active since this month. One month later (April 2020), two users are still diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index 397f311adae..284e87e9b35 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -50,9 +50,9 @@ The following table shows the supported metrics, at which level they are support | Metric | Level | API version | Chart (UI) version | Comments | | --------------- | ----------- | --------------- | ---------- | ------- | -| `deployment_frequency` | Project-level | [13.7+](../../api/dora/metrics.md) | [13.8+](#deployment-frequency-charts) | The [old API endopint](../../api/dora4_project_analytics.md) was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/323713) in 13.10. | +| `deployment_frequency` | Project-level | [13.7+](../../api/dora/metrics.md) | [13.8+](#deployment-frequency-charts) | The [old API endpoint](../../api/dora4_project_analytics.md) was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/323713) in 13.10. | | `deployment_frequency` | Group-level | [13.10+](../../api/dora/metrics.md) | To be supported | | -| `lead_time_for_changes` | Project-level | [13.10+](../../api/dora/metrics.md) | To be supported | Unit in seconds. Aggregation method is median. | +| `lead_time_for_changes` | Project-level | [13.10+](../../api/dora/metrics.md) | [13.11+](#lead-time-charts) | Unit in seconds. Aggregation method is median. | | `lead_time_for_changes` | Group-level | [13.10+](../../api/dora/metrics.md) | To be supported | Unit in seconds. Aggregation method is median. | | `change_failure_rate` | Project/Group-level | To be supported | To be supported | | | `time_to_restore_service` | Project/Group-level | To be supported | To be supported | | @@ -61,11 +61,14 @@ The following table shows the supported metrics, at which level they are support > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.8. -The **Analytics > CI/CD Analytics** page shows information about the deployment frequency to the -`production` environment. The environment **must** be named `production` for its deployment -information to appear on the graphs. +The **Analytics > CI/CD Analytics** page shows information about the deployment +frequency to the `production` environment. The environment must be part of the +[production deployment tier](../../ci/environments/index.md#deployment-tier-of-environments) +for its deployment information to appear on the graphs. - + + +These charts are available for both groups and projects. ### Lead time charts **(ULTIMATE)** @@ -81,3 +84,5 @@ processes. For time periods in which no merge requests were deployed, the charts render a red, dashed line. + +These charts are only available for projects. 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 differindex e337afa3ace..b559b934a89 100644 --- a/doc/user/analytics/img/code_review_analytics_v13_11.png +++ b/doc/user/analytics/img/code_review_analytics_v13_11.png diff --git a/doc/user/analytics/img/deployment_frequency_chart_v13_8.png b/doc/user/analytics/img/deployment_frequency_chart_v13_8.png Binary files differdeleted file mode 100644 index 40dd2fa0321..00000000000 --- a/doc/user/analytics/img/deployment_frequency_chart_v13_8.png +++ /dev/null diff --git a/doc/user/analytics/img/deployment_frequency_charts_v13_12.png b/doc/user/analytics/img/deployment_frequency_charts_v13_12.png Binary files differnew file mode 100644 index 00000000000..2242363d25e --- /dev/null +++ b/doc/user/analytics/img/deployment_frequency_charts_v13_12.png diff --git a/doc/user/analytics/img/issues_created_per_month_v13_11.png b/doc/user/analytics/img/issues_created_per_month_v13_11.png Binary files differindex 01ebde5a54d..da3340bfdc2 100644 --- a/doc/user/analytics/img/issues_created_per_month_v13_11.png +++ b/doc/user/analytics/img/issues_created_per_month_v13_11.png diff --git a/doc/user/analytics/img/pipelines_duration_chart.png b/doc/user/analytics/img/pipelines_duration_chart.png Binary files differindex 12ec262dadb..17ab7173557 100644 --- a/doc/user/analytics/img/pipelines_duration_chart.png +++ b/doc/user/analytics/img/pipelines_duration_chart.png diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 6e3c9cf7a5f..d50a183aa54 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -4,29 +4,65 @@ 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 --- -# Analytics +# Analytics **(FREE)** ## Definitions When we describe GitLab analytics, we use the following terms: -- Cycle time: The duration of your value stream, from start to finish. Often displayed in combination with "lead time." GitLab measures cycle time from issue creation to issue close. GitLab displays cycle time in [Value Stream Analytics](value_stream_analytics.md). -- DORA (DevOps Research and Assessment) ["Four Keys"](https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance): - - Speed - - Deployment Frequency: How often an organization successfully releases to production. - - Lead Time for Changes: The time it takes for a commit to get into production. This differs from ordinary "lead time" as it "focuses on measuring only the time to deliver a feature once it has been developed", -as described in ([Measuring DevOps Performance](https://devops.com/measuring-devops-performance/)). - - Stability - - Change Failure Rate: The percentage of deployments causing a failure in production. - - Time to Restore Service: How long it takes an organization to recover from a failure in production. -- MTTC (Mean Time to Change): The average duration between idea and delivery. GitLab measures MTTC from issue creation to the issue's latest related merge request's deployment to production. -- MTTD (Mean Time to Detect): The average duration that a bug goes undetected in production. GitLab measures MTTD from deployment of bug to issue creation. -- MTTM (Mean Time To Merge): The average lifespan of a merge request. GitLab measures MTTM from merge request creation to merge request merge (and closed/un-merged merge requests are excluded). For more information, see [Merge Request Analytics](merge_request_analytics.md). -- MTTR (Mean Time to Recover/Repair/Resolution/Resolve/Restore): The average duration that a bug is not fixed in production. GitLab measures MTTR from deployment of bug to deployment of fix. -- Lead time: The duration of the work itself. Often displayed in combination with "cycle time." GitLab measures from issue first merge request creation to issue close. Note: Work started before the creation of the first merge request. We plan to start measuring from "issue first commit" as a better proxy, although still imperfect. GitLab displays lead time in [Value Stream Analytics](value_stream_analytics.md). -- Throughput: The number of issues closed or merge requests merged (not closed) in some period of time. Often measured per sprint. GitLab displays merge request throughput in [Merge Request Analytics](merge_request_analytics.md). -- Value Stream: The entire work process that is followed to deliver value to customers. For example, the [DevOps lifecycle](https://about.gitlab.com/stages-devops-lifecycle/) is a value stream that starts with "plan" and ends with "monitor". GitLab helps you track your value stream using [Value Stream Analytics](value_stream_analytics.md). -- Velocity: The total issue burden completed in some period of time. The burden is usually measured in points or weight, often per sprint. For example, your velocity may be "30 points per sprint". GitLab measures velocity as the total points/weight of issues closed in a given period of time. +- **Cycle time:** The duration of only the execution work alone. Often displayed in combination with "lead time," which is longer. GitLab measures cycle time from issue first merge request creation to issue close. This approach underestimates lead time because merge request creation is always later than commit time. GitLab displays cycle time in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md). +- **Deploys:** The total number of successful deployments to production in the given time frame (across all applicable projects). GitLab displays deploys in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md). +- **DORA (DevOps Research and Assessment)** ["Four Keys"](https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance): + - **Speed/Velocity** + + - **Deployment frequency:** The average number of successful deployments to production per period. + This effectively measures how often you are delivering value to end users. A higher deployment + frequency means you are able to get feedback and iterate more quickly in delivering + improvements and features faster. GitLab measures this as the number of deployments to a + [production environment](../../ci/environments/index.md#deployment-tier-of-environments) in + the given time period. + GitLab displays deployment frequency in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md). + - **Lead Time for Changes:** The time it takes for a commit to get into production. (1) GitLab + measures this as the median duration between merge request merge and deployment to a + [production environment](../../ci/environments/index.md#deployment-tier-of-environments) for + all MRs deployed in the given time period. This measure under-estimates lead time because + merge time is always later than commit time. The + [standard definition](https://github.com/GoogleCloudPlatform/fourkeys/blob/main/METRICS.md#lead-time-for-changes) uses median commit time. We plan to start + [measuring from "issue first commit"](https://gitlab.com/gitlab-org/gitlab/-/issues/328459) + as a better proxy, although still imperfect. + + - **Stability** + - **Change Failure Rate:** The percentage of deployments causing a failure in production. + GitLab measures this as the number of [incidents](../../operations/incident_management/incidents.md) + divided by the number of deployments to a + [production environment](../../ci/environments/index.md#deployment-tier-of-environments) in + the given time period. This assumes: + + - All incidents are related to a production environment. + - Incidents and deployments have a strictly one-to-one relationship (meaning any incident is + related to only one production deployment, and any production deployment is related to no + more than one incident). + + - **Time to Restore Service:** How long it takes an organization to recover from a failure in + production. GitLab measures this as the average time required to close the + [incidents](../../operations/incident_management/incidents.md) in the given time period. + This assumes: + + - All incidents are related to a [production environment](../../ci/environments/index.md#deployment-tier-of-environments). + - Incidents and deployments have a strictly one-to-one relationship (meaning any incident is related to only one production deployment, and any production deployment is related to no more than one incident). + +- **Lead time:** The duration of your value stream, from start to finish. Different from [Lead time for changes](#lead-time-for-changes). Often displayed in combination with "cycle time," which is shorter. GitLab measures lead time from issue creation to issue close. GitLab displays lead time in [group-level Value Stream Analytics](../group/value_stream_analytics/index.md). +- **MTTC (Mean Time to Change):** The average duration between idea and delivery. GitLab measures MTTC from issue creation to the issue's latest related merge request's deployment to production. +- **MTTD (Mean Time to Detect):** The average duration that a bug goes undetected in production. GitLab measures MTTD from deployment of bug to issue creation. +- **MTTM (Mean Time To Merge):** The average lifespan of a merge request. GitLab measures MTTM from merge request creation to merge request merge (and closed/un-merged merge requests are excluded). For more information, see [Merge Request Analytics](merge_request_analytics.md). +- **MTTR (Mean Time to Recover/Repair/Resolution/Resolve/Restore):** The average duration that a bug is not fixed in production. GitLab measures MTTR from deployment of bug to deployment of fix. +- **Throughput:** The number of issues closed or merge requests merged (not closed) in some period of time. Often measured per sprint. GitLab displays merge request throughput in [Merge Request Analytics](merge_request_analytics.md). +- **Value Stream:** The entire work process that is followed to deliver value to customers. For example, the [DevOps lifecycle](https://about.gitlab.com/stages-devops-lifecycle/) is a value stream that starts with "plan" and ends with "monitor". GitLab helps you track your value stream using [Value Stream Analytics](value_stream_analytics.md). +- **Velocity:** The total issue burden completed in some period of time. The burden is usually measured in points or weight, often per sprint. For example, your velocity may be "30 points per sprint". GitLab measures velocity as the total points/weight of issues closed in a given period of time. + +### Lead time for changes + +"Lead Time for Changes" differs from ordinary "Lead Time" because it "focuses on measuring only the time to deliver a feature once it has been developed", as described in ([Measuring DevOps Performance](https://devops.com/measuring-devops-performance/)). ## Instance-level analytics @@ -38,38 +74,38 @@ in one place. [Learn more about instance-level analytics](../admin_area/analytics/index.md). -## Group-level analytics +## Group-level analytics **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195979) in GitLab 12.8. -> - Moved to [GitLab Premium](https://about.gitlab.com/pricing/) due to Starter/Bronze being [discontinued](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) in 13.9. +> - Moved to GitLab Premium in 13.9. The following analytics features are available at the group level: -- [Contribution](../group/contribution_analytics/index.md). **(PREMIUM)** -- [DevOps Adoption](../group/devops_adoption/index.md). **(ULTIMATE)** -- [Insights](../group/insights/index.md). **(ULTIMATE)** -- [Issue](../group/issues_analytics/index.md). **(PREMIUM)** -- [Productivity](productivity_analytics.md). **(PREMIUM)** -- [Repositories](../group/repositories_analytics/index.md). **(PREMIUM)** -- [Value Stream](../group/value_stream_analytics/index.md). **(PREMIUM)** -- [Application Security](../application_security/security_dashboard/#group-security-dashboard). **(ULTIMATE)** +- [Application Security](../application_security/security_dashboard/#group-security-dashboard) +- [Contribution](../group/contribution_analytics/index.md) +- [DevOps Adoption](../group/devops_adoption/index.md) +- [Insights](../group/insights/index.md) +- [Issue](../group/issues_analytics/index.md) +- [Productivity](productivity_analytics.md) +- [Repositories](../group/repositories_analytics/index.md) +- [Value Stream](../group/value_stream_analytics/index.md) ## Project-level analytics The following analytics features are available at the project level: -- [CI/CD](ci_cd_analytics.md). **(FREE)** -- [Code Review](code_review_analytics.md). **(PREMIUM)** -- [Insights](../project/insights/index.md). **(ULTIMATE)** -- [Issue](../group/issues_analytics/index.md). **(PREMIUM)** +- [Application Security](../application_security/security_dashboard/#project-security-dashboard) +- [CI/CD](ci_cd_analytics.md) +- [Code Review](code_review_analytics.md) +- [Insights](../project/insights/index.md) +- [Issue](../group/issues_analytics/index.md) - [Merge Request](merge_request_analytics.md), enabled with the `project_merge_request_analytics` - [feature flag](../../development/feature_flags/index.md#enabling-a-feature-flag-locally-in-development). **(PREMIUM)** -- [Repository](repository_analytics.md). **(FREE)** -- [Value Stream](value_stream_analytics.md). **(FREE)** -- [Application Security](../application_security/security_dashboard/#project-security-dashboard). **(ULTIMATE)** + [feature flag](../../development/feature_flags/index.md#enabling-a-feature-flag-locally-in-development) +- [Repository](repository_analytics.md) +- [Value Stream](value_stream_analytics.md) -## User-configurable analytics +## User-configurable analytics **(ULTIMATE)** The following analytics features are available for users to create personalized views: -- [Application Security](../application_security/security_dashboard/#security-center). **(ULTIMATE)** +- [Application Security](../application_security/security_dashboard/#security-center) diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 909eb7e585f..321e2f0fc24 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -7,8 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Merge Request Analytics **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229045) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.3. -> - Moved to [GitLab Premium](https://about.gitlab.com/pricing/) due to Starter/Bronze being [discontinued](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) in 13.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229045) in GitLab 13.3. +> - Moved to GitLab Premium in 13.9. Merge Request Analytics helps you understand the efficiency of your code review process, and the productivity of your team. @@ -56,7 +56,7 @@ The throughput chart shows the number of merge requests merged per month. ### Throughput table -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232651) in GitLab 13.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232651) in GitLab 13.3. The Throughput table displays the most recent merge requests merged in the date range. The table displays up to 20 merge requests at a time. If there are more than 20 merge requests, diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index f77070ea943..9016bf6393f 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -25,6 +25,7 @@ You can find Repository Analytics in the project's sidebar. To access the page, NOTE: Without a Git commit in the default branch, the menu item won't be visible. +Commits in a project's [wiki](../project/wiki/index.md#track-wiki-events) are not included in the analysis. ### Charts diff --git a/doc/user/application_security/api_fuzzing/create_har_files.md b/doc/user/application_security/api_fuzzing/create_har_files.md new file mode 100644 index 00000000000..220d00adc7b --- /dev/null +++ b/doc/user/application_security/api_fuzzing/create_har_files.md @@ -0,0 +1,234 @@ +--- +stage: Secure +group: Fuzz Testing +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +type: howto +--- + +# HTTP Archive format + +HTTP Archive (HAR) format files are an industry standard for exchanging information about HTTP +requests and HTTP responses. A HAR file's content is JSON formatted, containing browser interactions +with a web site. The file extension `.har` is commonly used. + +The HAR files can be used to perform [web API Fuzz Testing](index.md#http-archive-har) as part of +your [GitLab CI/CD](../../../ci/README.md) pipelines. + +WARNING: +**DANGER** A HAR file stores information exchanged between web client and web server. It could also +store sensitive information such as authentication tokens, API keys, and session cookies. We +recommend that you review the HAR file contents before adding them to a repository. + +## HAR file creation + +You can create HAR files manually or by using a specialized tool for recording web sessions. We +recommend using a specialized tool. However, it is important to make sure files created by these +tools do not expose sensitive information, and can be safely used. + +The following tools can be used generate a HAR file based on your network activity. They +automatically record your network activity and generate the HAR file: + +1. [GitLab HAR Recorder](#gitlab-har-recorder). +1. [Insomnia API Client](#insomnia-api-client). +1. [Fiddler debugging proxy](#fiddler-debugging-proxy). +1. [Safari web browser](#safari-web-browser). +1. [Chrome web browser](#chrome-web-browser). +1. [Firefox web browser](#firefox-web-browser). + +WARNING: +**DANGER** HAR files may contain sensitive information such as authentication tokens, API keys, and +session cookies. We recommend that you review the HAR file contents before adding them to a +repository. + +### GitLab HAR Recorder + +[GitLab HAR Recorder](https://gitlab.com/gitlab-org/security-products/har-recorder) is a command +line tool for recording HTTP messages and saving them to HTTP Archive (HAR) files. For more details +about the GitLab HAR Recorder, see the [homepage](https://gitlab.com/gitlab-org/security-products/har-recorder). + +#### Install GitLab HAR Recorder + +Prerequisites: + +- Install Python 3.6 or greater. +- For Microsoft Windows, you must also install `Microsoft Visual C++ 14.0`. It's included with + *Build Tools for Visual Studio* from [Visual Studio Downloads page](https://visualstudio.microsoft.com/downloads/). +- Install HAR Recorder. + +Install GitLab HAR Recorder: + + ```shell + pip install gitlab-har-recorder --extra-index-url https://gitlab.com/api/v4/projects/22441624/packages/pypi/simple + ``` + +#### Create a HAR file with GitLab HAR Recorder + +1. Start recorder with the proxy port and HAR filename. +1. Complete the browser actions, using the proxy. + 1. Make sure proxy is used! +1. Stop the recorder. + +To verify the HAR contains all requests, use the [HAR Viewer (online)](http://www.softwareishard.com/har/viewer/). +[Google Admin Toolbox HAR Analyzer](https://toolbox.googleapps.com/apps/har_analyzer/) + +### Insomnia API Client + +[Insomnia API Client](https://insomnia.rest/) is an API design tool that among many uses, helps +you to design, describe, and test your API. You can also use it to generate HAR files that can be +used in [Web API Fuzz Testing](index.md#http-archive-har). + +#### Create a HAR file with the Insomnia API Client + +1. Define or import your API. + - Postman v2. + - Curl. + - OpenAPI v2, v3. +1. Verify each API call works. + - If you imported an OpenAPI specification, go through and add working data. +1. Select **API > Import/Export**. +1. Select **Export Data > Current Workspace**. +1. Select requests to include in the HAR file. +1. Select **Export**. +1. In the **Select Export Type** dropdown select **HAR -- HTTP Archive Format**. +1. Select **Done**. +1. Enter a location and filename for the HAR file. + +### Fiddler debugging proxy + +[Fiddler](https://www.telerik.com/fiddler) is a web debugger tool. It captures HTTP and HTTP(S) +network traffic and allows you to examine each request. It also lets you export the requests and +responses in HAR format. + +#### Create a HAR file with Fiddler + +1. Go to the [Fiddler home page](https://www.telerik.com/fiddler) and sign in. If you don't already +have an account, first create an account. +1. Browse pages that call an API. Fiddler automatically captures the requests. +1. Select one or more requests, then from the context menu, select **Export > Selected Sessions**. +1. In the **Choose Format** dropdown select **HTTPArchive v1.2**. +1. Enter a filename and select **Save**. + +Fiddler shows a popup message confirming the export has succeeded. + +### Safari web browser + +[Safari](https://www.apple.com/safari/) is a web browser maintained by Apple. As web development +evolves, browsers support new capabilities. With Safari you can explore network traffic and +export it as a HAR file. + +#### Create a HAR file with Safari + +Prerequisites: + +- Enable the `Develop` menu item. + 1. Open Safari's preferences. Press <kbd>Command</kbd>+<kbd>,</kbd> or from the menu, select + **Safari > Preferences...**. + 1. Select **Advanced** tab, then select `Show Develop menu item in menu bar`. + 1. Close the **Preferences** window. + +1. Open the **Web Inspector**. Press <kbd>Option</kbd>+<kbd>Command</kbd>+<kbd>i</kbd>, or from the + menu, select **Develop > Show Web Inspector**. +1. Select the **Network** tab, and select **Preserve Log**. +1. Browse pages that call the API. +1. Open the **Web Inspector** and select the **Network** tab +1. Right-click on the request to export and select **Export HAR**. +1. Enter a filename and select **Save**. + +### Chrome web browser + +[Chrome](https://www.google.com/chrome/) is a web browser maintained by Google. As web development +evolves, browsers support new capabilities. With Chrome you can explore network traffic and +export it as a HAR file. + +#### Create a HAR file with Chrome + +1. From the Chrome context menu, select **Inspect**. +1. Select the **Network** tab. +1. Select **Preserve log**. +1. Browse pages that call the API. +1. Select one or more requests. +1. Right click and select **Save all as HAR with content**. +1. Enter a filename and select **Save**. +1. To append additional requests, select and save them to the same file. + +### Firefox Web Browser + +[Firefox](https://www.mozilla.org/en-US/firefox/new/) is a web browser maintained by Mozilla. As web +development evolves, browsers support new capabilities. With Firefox you can explore network traffic +and export it as a HAR file. + +#### Create a HAR file with Firefox + +1. From the Firefox context menu, select **Inspect**. +1. Select the **Network** tab. +1. Browse pages that call the API. +1. Check the **Network** tab and confirm requests are being recorded. If there is a message + `Perform a request or Reload the page to see detailed information about network activity`, + select **Reload** to start recording requests. +1. Select one or more requests. +1. Right click and select **Save All As HAR**. +1. Enter a filename and select **Save**. +1. To append additional requests, select and save them to the same file. + +## HAR verification + +Before using HAR files it's important to make sure they don't expose any sensitive information. + +For each HAR file you should: + +- View the HAR file's content +- Review the HAR file for sensitive information +- Edit or remove sensitive information + +### View HAR file contents + +We recommend viewing a HAR file's content in a tool that can present its content in a structured +way. Several HAR file viewers are available online. If you would prefer not to upload the HAR file, +you can use a tool installed on your computer. HAR files used JSON format, so can also be viewed in +a text editor. + +Tools recommended for viewing HAR files include: + +- [HAR Viewer](http://www.softwareishard.com/har/viewer/) - (online) +- [Google Admin Toolbox HAR Analyzer](https://toolbox.googleapps.com/apps/har_analyzer/) - (online) +- [Fiddler](https://www.telerik.com/fiddler) - local +- [Insomnia API Client](https://insomnia.rest/) - local + +## Review HAR file content + +Review the HAR file for any of the following: + +- Information that could help to grant access to your application, for example: authentication + tokens, authentication tokens, cookies, API keys. +- [Personally Identifiable Information (PII)](https://en.wikipedia.org/wiki/Personal_data). + +We strongly recommended that you [edit or remove it](#edit-or-remove-sensitive-information) any +sensitive information. + +Use the following as a checklist to start with. Note that it's not an exhaustive list. + +- Look for secrets. For example: if your application requires authentication, check common locations + or authentication information: + - Authentication related headers. For example: cookies, authorization. These headers could contain + valid information. + - A request related to authentication. The body of these requests might contain information such + as user credentials or tokens. + - Session tokens. Session tokens could grant access to your application. The location of these + token could vary. They could be in headers, query parameters or body. +- Look for Personally Identifiable Information + - For example, if your application retrieves a list of users and their personal data: phones, + names, emails. + - Authentication information might also contain personal information. + +## Edit or remove sensitive information + +Edit or remove sensitive information found during the [HAR file content review](#review-har-file-content). +HAR files are JSON files and can be edited in any text editor. + +After editing the HAR file, open it in a HAR file viewer to verify its formatting and structure are +intact. + +The following example demonstrates use of [Visual Studio Code](https://code.visualstudio.com/) text +editor to edit an Authorization token found in a header. + + diff --git a/doc/user/application_security/api_fuzzing/img/vscode_har_edit_auth_header.png b/doc/user/application_security/api_fuzzing/img/vscode_har_edit_auth_header.png Binary files differnew file mode 100644 index 00000000000..a6bc45e67d3 --- /dev/null +++ b/doc/user/application_security/api_fuzzing/img/vscode_har_edit_auth_header.png diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index dfb7e12a8be..8511c919c14 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -7,17 +7,51 @@ type: reference, howto # Web API Fuzz Testing **(ULTIMATE)** -You can add web API fuzzing to your [GitLab CI/CD](../../../ci/README.md) -pipelines. This helps you discover bugs and potential security issues that other QA processes may -miss. API fuzzing performs fuzz testing of API operation parameters. Fuzz testing sets operation +Web API fuzzing performs fuzz testing of API operation parameters. Fuzz testing sets operation parameters to unexpected values in an effort to cause unexpected behavior and errors in the API -backend. +backend. This helps you discover bugs and potential security issues that other QA processes may +miss. We recommend that you use fuzz testing in addition to [GitLab Secure](../index.md)'s other security scanners and your own test processes. If you're using [GitLab CI/CD](../../../ci/README.md), you can run fuzz tests as part your CI/CD workflow. -## Requirements +## When Web API fuzzing runs + +Web API fuzzing runs in the `fuzz` stage of the CI/CD pipeline. To ensure API fuzzing scans the +latest code, your CI/CD pipeline should deploy changes to a test environment in one of the stages +preceding the `fuzz` stage. + +Note the following changes have been made to the API fuzzing template: + +- In GitLab 14.0 and later, you must define a `fuzz` stage in your `.gitlab-ci.yml` file. +- In GitLab 13.12 and earlier, the API fuzzing template defines `build`, `test`, `deploy`, and + `fuzz` stages. The `fuzz` stage runs last by default. The predefined stages were deprecated, and removed from the `API-Fuzzing.latest.gitlab-ci.yml` template. They will be removed in a future GitLab + version. + +If your pipeline is configured to deploy to the same web server on each run, running a +pipeline while another is still running could cause a race condition in which one pipeline +overwrites the code from another. The API to scan should be excluded from changes for the duration +of a fuzzing scan. The only changes to the API should be from the fuzzing scanner. Any changes made +to the API (for example, by users, scheduled tasks, database changes, code changes, other pipelines, +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.0 or 3.0 +- [HTTP Archive](#http-archive-har) (HAR) +- [Postman Collection](#postman-collection) - version 2.0 or 2.1 + +Example projects using these methods are available: + +- [Example OpenAPI v2 Specification project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/openapi) +- [Example HTTP Archive (HAR) project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/har) +- [Example Postman Collection project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing/postman-api-fuzzing-example) +- [Example GraphQL project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing/graphql-api-fuzzing-example) + +## Enable Web API fuzzing + +Requirements: - One of the following web API types: - REST API @@ -29,49 +63,26 @@ you can run fuzz tests as part your CI/CD workflow. - HTTP Archive (HAR) of API requests to test - Postman Collection v2.0 or v2.1 -## When fuzzing scans run - -When using the `API-Fuzzing.gitlab-ci.yml` template, the `fuzz` job runs last, as shown here. To -ensure API fuzzing scans the latest code, your CI pipeline should deploy changes to a test -environment in one of the jobs preceding the `fuzz` job: - -```yaml -stages: - - build - - test - - deploy - - fuzz -``` - -Note that if your pipeline is configured to deploy to the same web server on each run, running a -pipeline while another is still running could cause a race condition in which one pipeline -overwrites the code from another. The API to scan should be excluded from changes for the duration -of a fuzzing scan. The only changes to the API should be from the fuzzing scanner. Be aware that -any changes made to the API (for example, by users, scheduled tasks, database changes, code -changes, other pipelines, or other scanners) during a scan could cause inaccurate results. - -## Configuration + WARNING: + **NEVER** run fuzz testing against a production server. Not only can it perform *any* function that + the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting + data. Only run fuzzing against a test server. -There are three ways to perform scans. See the configuration section for the one you wish to use: +To enable Web API fuzzing: -- [OpenAPI v2 or v3 specification](#openapi-specification) -- [HTTP Archive (HAR)](#http-archive-har) -- [Postman Collection v2.0 or v2.1](#postman-collection) +- Include the API fuzzing template in your `.gitlab-ci.yml` file. +- From GitLab 13.10 and later, use the Web API fuzzing configuration form. -Examples of both configurations can be found here: +- For manual configuration instructions, see the respective section, depending on the API type: + - [OpenAPI Specification](#openapi-specification) + - [HTTP Archive (HAR)](#http-archive-har) + - [Postman Collection](#postman-collection) +- Otherwise, see [Web API fuzzing configuration form](#web-api-fuzzing-configuration-form). -- [Example OpenAPI v2 specification project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/openapi) -- [Example HTTP Archive (HAR) project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/har) -- [Example Postman Collection project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing/postman-api-fuzzing-example) -- [Example GraphQL project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing/graphql-api-fuzzing-example) - -WARNING: -GitLab 14.0 will require that you place API fuzzing configuration files (for example, -`gitlab-api-fuzzing-config.yml`) in your repository's `.gitlab` directory instead of your -repository's root. You can continue using your existing configuration files as they are, but -starting in GitLab 14.0, GitLab will not check your repository's root for configuration files. +In GitLab 14.0 and later, API fuzzing configuration files must be in your repository's +`.gitlab` directory instead of your repository's root. -### Configuration form +### Web API fuzzing configuration form > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299234) in GitLab 13.10. @@ -82,6 +93,8 @@ The API fuzzing configuration form helps you create or modify your project's API configuration. The form lets you choose values for the most common API fuzzing options and builds a YAML snippet that you can paste in your GitLab CI/CD configuration. +#### Configure Web API fuzzing with the configuration form + To generate an API Fuzzing configuration snippet: 1. From your project's home page, go to **Security & Compliance > Configuration** in the left @@ -89,25 +102,23 @@ To generate an API Fuzzing configuration snippet: 1. Select **Configure** in the **API Fuzzing** row. 1. Complete the form as needed. Read below for more information on available configuration options. 1. Select **Generate code snippet**. - -A modal opens with the YAML snippet corresponding to the options you've selected in the form. - - - -Select **Copy code and open `.gitlab-ci.yml` file** to copy the snippet to your clipboard and be redirected -to your project's `.gitlab-ci.yml` file where you can paste the YAML configuration. - -Select **Copy code only** to copy the snippet to your clipboard and close the modal. + A modal opens with the YAML snippet corresponding to the options you've selected in the form. +1. Choose one of the following actions: + 1. Select **Copy code and open `.gitlab-ci.yml` file** to copy the snippet to your clipboard and + be redirected to your project's `.gitlab-ci.yml` file where you can paste the YAML + configuration. + 1. Select **Copy code only** to copy the snippet to your clipboard and close the modal. ### OpenAPI Specification -> Support for OpenAPI Specification v3 was +> Support for OpenAPI Specification using YAML format was +> [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330583) in GitLab 14.0. +> Support for OpenAPI Specification v3.0 was > [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228652) in GitLab 13.9. -The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an -API description format for REST APIs. This section shows you how to configure API fuzzing by using -an OpenAPI specification to provide information about the target API to test. OpenAPI specifications -are provided as a file system resource or URL. +The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an API description format for REST APIs. +This section shows you how to configure API fuzzing using an OpenAPI Specification to provide information about the target API to test. +OpenAPI Specifications are provided as a file system resource or URL. Both JSON and YAML OpenAPI formats are supported. API fuzzing uses an OpenAPI document to generate the request body. When a request body is required, the body generation is limited to these body types: @@ -116,59 +127,42 @@ the body generation is limited to these body types: - `multipart/form-data` - `application/json` -Follow these steps to configure API fuzzing in GitLab with an OpenAPI specification: +#### Configure Web API fuzzing with an OpenAPI Specification -1. To use API fuzzing, you must [include](../../../ci/yaml/README.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) - that's provided as part of your GitLab installation. To do so, add the following to your - `.gitlab-ci.yml` file: - - ```yaml - include: - - template: API-Fuzzing.gitlab-ci.yml - ``` +To configure API fuzzing in GitLab with an OpenAPI Specification: -1. Add the configuration file [`gitlab-api-fuzzing-config.yml`](https://gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing/-/blob/master/gitlab-api-fuzzing-config.yml) to your repository's root as `.gitlab-api-fuzzing.yml`. +1. Add the `fuzz` stage to your `.gitlab-ci.yml` file. -1. The [configuration file](#configuration-files) has several testing profiles defined with varying - amounts of fuzzing. We recommend that you start with the `Quick-10` profile. Testing with this - profile completes quickly, allowing for easier configuration validation. +1. [Include](../../../ci/yaml/README.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. - Provide the profile by adding the `FUZZAPI_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, - substituting `Quick-10` for the profile you choose: +1. Provide the profile by adding the `FUZZAPI_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file. + The profile specifies how many tests are run. Substitute `Quick-10` for the profile you choose. For more details, see [API fuzzing profiles](#api-fuzzing-profiles). ```yaml - include: - - template: API-Fuzzing.gitlab-ci.yml - variables: FUZZAPI_PROFILE: Quick-10 ``` -1. Provide the location of the OpenAPI specification. You can provide the specification as a file - or URL. Specify the location by adding the `FUZZAPI_OPENAPI` variable: +1. Provide the location of the OpenAPI Specification. You can provide the specification as a file + or URL. Specify the location by adding the `FUZZAPI_OPENAPI` variable. - ```yaml - include: - - template: API-Fuzzing.gitlab-ci.yml - - variables: - FUZZAPI_PROFILE: Quick-10 - FUZZAPI_OPENAPI: test-api-specification.json - ``` - -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. +1. Provide the target API instance's base URL. Use either 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. To run API fuzzing against an app dynamically created during a GitLab CI/CD - pipeline, have the app persist its domain in an `environment_url.txt` file. API fuzzing - automatically parses that file to find its scan target. You can see an - [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). + dynamic environments. To run API fuzzing against an application dynamically created during a + GitLab CI/CD pipeline, have the application persist its URL in an `environment_url.txt` file. + API fuzzing automatically parses that file to find its scan target. You can see an + example of this in the [Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). - Here's an example of using `FUZZAPI_TARGET_URL`: +Example `.gitlab-ci.yml` file using an OpenAPI Specification: ```yaml + stages: + - fuzz + include: - template: API-Fuzzing.gitlab-ci.yml @@ -184,10 +178,7 @@ This is a minimal configuration for API Fuzzing. From here you can: - [Add authentication](#authentication). - Learn how to [handle false positives](#handling-false-positives). -WARNING: -**NEVER** run fuzz testing against a production server. Not only can it perform *any* function that -the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting -data. Only run fuzzing against a test server. +For details of API fuzzing configuration options, see [Available CI/CD variables](#available-cicd-variables). ### HTTP Archive (HAR) @@ -196,59 +187,33 @@ is an archive file format for logging HTTP transactions. When used with the GitL must contain records of calling the web API to test. The API fuzzer extracts all the requests and uses them to perform testing. -You can use various tools to generate HAR files: - -- [Fiddler](https://www.telerik.com/fiddler): Web debugging proxy -- [Insomnia Core](https://insomnia.rest/): API client -- [Chrome](https://www.google.com/chrome/): Browser -- [Firefox](https://www.mozilla.org/en-US/firefox/): Browser -- [GitLab HAR Recorder](https://gitlab.com/gitlab-org/security-products/har-recorder): Command line +For more details, including how to create a HAR file, see [HTTP Archive format](create_har_files.md). WARNING: HAR files may contain sensitive information such as authentication tokens, API keys, and session cookies. We recommend that you review the HAR file contents before adding them to a repository. -Follow these steps to configure API fuzzing to use a HAR file that provides information about the -target API to test: +#### Configure Web API fuzzing with a HAR file -1. To use API fuzzing, you must [include](../../../ci/yaml/README.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) - that's provided as part of your GitLab installation. To do so, add the following to your - `.gitlab-ci.yml` file: +To configure API fuzzing to use a HAR file: - ```yaml - include: - - template: API-Fuzzing.gitlab-ci.yml - ``` +1. Add the `fuzz` stage to your `.gitlab-ci.yml` file. -1. Add the configuration file [`gitlab-api-fuzzing-config.yml`](https://gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing/-/blob/master/gitlab-api-fuzzing-config.yml) to your repository's root as `.gitlab-api-fuzzing.yml`. - -1. The [configuration file](#configuration-files) has several testing profiles defined with varying - amounts of fuzzing. We recommend that you start with the `Quick-10` profile. Testing with this - profile completes quickly, allowing for easier configuration validation. +1. [Include](../../../ci/yaml/README.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. - Provide the profile by adding the `FUZZAPI_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, - substituting `Quick-10` for the profile you choose: +1. Provide the profile by adding the `FUZZAPI_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file. + The profile specifies how many tests are run. Substitute `Quick-10` for the profile you choose. For more details, see [API fuzzing profiles](#api-fuzzing-profiles). ```yaml - include: - - template: API-Fuzzing.gitlab-ci.yml - variables: FUZZAPI_PROFILE: Quick-10 ``` 1. Provide the location of the HAR specification. You can provide the specification as a file - or URL. [URL support was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285020) in GitLab 13.10 and later. Specify the location by adding the `FUZZAPI_HAR` variable: - - ```yaml - include: - - template: API-Fuzzing.gitlab-ci.yml - - variables: - FUZZAPI_PROFILE: Quick-10 - FUZZAPI_HAR: test-api-recording.har - ``` + or URL. [URL support was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285020) + in GitLab 13.10 and later. Specify the location by adding the `FUZZAPI_HAR` 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. @@ -259,9 +224,12 @@ target API to test: automatically parses that file to find its scan target. You can see an [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). - Here's an example of using `FUZZAPI_TARGET_URL`: +Example `.gitlab-ci.yml` file using a HAR file: ```yaml + stages: + - fuzz + include: - template: API-Fuzzing.gitlab-ci.yml @@ -271,16 +239,13 @@ target API to test: FUZZAPI_TARGET_URL: http://test-deployment/ ``` -This is a minimal configuration for API Fuzzing. From here you can: +This 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). -WARNING: -**NEVER** run fuzz testing against a production server. Not only can it perform *any* function that -the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting -data. Only run fuzzing against a test server. +For details of API fuzzing configuration options, see [Available CI/CD variables](#available-cicd-variables). ### Postman Collection @@ -299,51 +264,31 @@ Postman Collection files may contain sensitive information such as authenticatio and session cookies. We recommend that you review the Postman Collection file contents before adding them to a repository. -Follow these steps to configure API fuzzing to use a Postman Collection file that provides -information about the target API to test: +#### Configure Web API fuzzing with a Postman Collection file -1. To use API fuzzing, you must [include](../../../ci/yaml/README.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) - that's provided as part of your GitLab installation. To do so, add the following to your - `.gitlab-ci.yml` file: +To configure API fuzzing to use a Postman Collection file: - ```yaml - include: - - template: API-Fuzzing.gitlab-ci.yml - ``` +1. Add the `fuzz` stage to your `.gitlab-ci.yml` file. -1. Add the configuration file [`gitlab-api-fuzzing-config.yml`](https://gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing/-/blob/master/gitlab-api-fuzzing-config.yml) - to your repository's root as `.gitlab-api-fuzzing.yml`. - -1. The [configuration file](#configuration-files) has several testing profiles defined with varying - amounts of fuzzing. We recommend that you start with the `Quick-10` profile. Testing with this - profile completes quickly, allowing for easier configuration validation. +1. [Include](../../../ci/yaml/README.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. - Provide the profile by adding the `FUZZAPI_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, - substituting `Quick-10` for the profile you choose: +1. Provide the profile by adding the `FUZZAPI_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file. + The profile specifies how many tests are run. Substitute `Quick-10` for the profile you choose. For more details, see [API fuzzing profiles](#api-fuzzing-profiles). ```yaml - include: - - template: API-Fuzzing.gitlab-ci.yml - variables: FUZZAPI_PROFILE: Quick-10 ``` -1. Provide the location of the Postman Collection specification. You can provide the specification as a file - or URL. [URL support was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285020) in GitLab 13.10 and later. Specify the location by adding the `FUZZAPI_POSTMAN_COLLECTION` variable: - - ```yaml - include: - - template: API-Fuzzing.gitlab-ci.yml - - variables: - FUZZAPI_PROFILE: Quick-10 - FUZZAPI_POSTMAN_COLLECTION: postman-collection_serviceA.json - ``` +1. Provide the location of the Postman Collection specification. You can provide the specification + as a file or URL. [URL support was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285020) + in GitLab 13.10 and later. Specify the location by adding the `FUZZAPI_POSTMAN_COLLECTION` + 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. +1. Provide the target API instance's base URL. Use either 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. To run API fuzzing against an app dynamically created during a GitLab CI/CD @@ -351,9 +296,12 @@ information about the target API to test: automatically parses that file to find its scan target. You can see an [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). - Here's an example of using `FUZZAPI_TARGET_URL`: +Example `.gitlab-ci.yml` file using a Postman Collection file: ```yaml + stages: + - fuzz + include: - template: API-Fuzzing.gitlab-ci.yml @@ -369,15 +317,13 @@ This is a minimal configuration for API Fuzzing. From here you can: - [Add authentication](#authentication). - Learn how to [handle false positives](#handling-false-positives). -WARNING: -**NEVER** run fuzz testing against a production server. Not only can it perform *any* function that -the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting -data. Only run fuzzing against a test server. +For details of API fuzzing configuration options, see [Available CI/CD variables](#available-cicd-variables). #### Postman variables 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 the Postman documentation, +[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: @@ -398,7 +344,7 @@ Postman file. For example, Postman does not export environment-scoped variables file. By default, the API fuzzer uses the Postman file to resolve Postman variable values. If a JSON file -is set in a GitLab CI environment variable `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`, then the JSON +is set in a GitLab CI/CD variable `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`, then the JSON file takes precedence to get Postman variable values. Although Postman can export environment variables into a JSON file, the format is not compatible @@ -407,6 +353,9 @@ with the JSON expected by `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`. Here is an example of using `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`: ```yaml +stages: + - fuzz + include: - template: API-Fuzzing.gitlab-ci.yml @@ -428,6 +377,13 @@ values. For example: } ``` +## API fuzzing configuration + +The API fuzzing behavior can be changed through CI/CD variables. + +From GitLab 13.12 and later, the default API fuzzing configuration file is `.gitlab/gitlab-api-fuzzing-config.yml`. In GitLab 14.0 and later, API fuzzing configuration files must be in your repository's +`.gitlab` directory instead of your repository's root. + ### Authentication Authentication is handled by providing the authentication token as a header or cookie. You can @@ -449,6 +405,9 @@ GitLab projects page at **Settings > CI/CD**, in the **Variables** section. Use as the value for `FUZZAPI_HTTP_PASSWORD`: ```yaml +stages: + - fuzz + include: - template: API-Fuzzing.gitlab-ci.yml @@ -487,6 +446,9 @@ Follow these steps to provide the bearer token with `FUZZAPI_OVERRIDES_ENV`: 1. In your `.gitlab-ci.yml` file, set `FUZZAPI_OVERRIDES_ENV` to the variable you just created: ```yaml + stages: + - fuzz + include: - template: API-Fuzzing.gitlab-ci.yml @@ -522,6 +484,9 @@ This file can be generated by a prior stage and provided to API fuzzing through Set `FUZZAPI_OVERRIDES_FILE` in your `.gitlab-ci.yml` file: ```yaml +stages: + - fuzz + include: - template: API-Fuzzing.gitlab-ci.yml @@ -561,6 +526,9 @@ You must provide three CI/CD variables, each set for correct operation: For example: ```yaml +stages: + - fuzz + include: - template: API-Fuzzing.gitlab-ci.yml @@ -576,16 +544,15 @@ variables: To validate that authentication is working, run an API fuzzing test and review the fuzzing logs and the test API's application logs. -### Configuration files +### API fuzzing profiles -To get you started quickly, GitLab provides the configuration file +GitLab provides the configuration file [`gitlab-api-fuzzing-config.yml`](https://gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing/-/blob/master/gitlab-api-fuzzing-config.yml). -This file has several testing profiles that perform various numbers of tests. The run time of each -profile increases as the test numbers go up. To use a configuration file, add it to your -repository's root as `.gitlab-api-fuzzing.yml`. +It contains several testing profiles that perform a specific numbers of tests. The runtime of each +profile increases as the number of tests increases. -| Profile | Fuzz Tests (per parameter) | -|:---------|:-----------| +| Profile | Fuzz Tests (per parameter) | +|:----------|:---------------------------| | Quick-10 | 10 | | Medium-20 | 20 | | Medium-50 | 50 | @@ -593,35 +560,23 @@ repository's root as `.gitlab-api-fuzzing.yml`. ### Available CI/CD variables -| CI/CD variable | Description | -|------------------------------------------------------|--------------------| -| `FUZZAPI_VERSION` | Specify API Fuzzing container version. Defaults to `latest`. | -| `FUZZAPI_TARGET_URL` | Base URL of API testing target. | -|[`FUZZAPI_CONFIG`](#configuration-files) | API Fuzzing configuration file. Defaults to `.gitlab-apifuzzer.yml`. | -|[`FUZZAPI_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | -| `FUZZAPI_REPORT` | Scan report filename. Defaults to `gl-api_fuzzing-report.xml`. | -|[`FUZZAPI_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | -|[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | -|[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | -|[`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. | -|[`FUZZAPI_OVERRIDES_CMD`](#overrides) | Overrides command. | -|[`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_D_TARGET_IMAGE`](#target-container) |API target docker image | -|[`FUZZAPI_D_TARGET_ENV`](#target-container) |Docker environment options | -|[`FUZZAPI_D_TARGET_VOLUME`](#target-container) | Docker volume options | -|[`FUZZAPI_D_TARGET_PORTS`](#target-container) |Docker port options | -| `FUZZAPI_D_WORKER_IMAGE` |Custom worker docker image | -| `FUZZAPI_D_WORKER_ENV` |Custom worker docker environment options | -| `FUZZAPI_D_WORKER_VOLUME` |Custom worker docker volume options | -| `FUZZAPI_D_WORKER_PORTS` |Custom worker docker port options | -| `FUZZAPI_D_NETWORK` |Name of docker network, defaults to "testing-net"| -| `FUZZAPI_D_PRE_SCRIPT` |Pre script runs after docker login and docker network create, but before starting the scanning image container.| -| `FUZZAPI_D_POST_SCRIPT` |Post script runs after scanning image container is started. This is the place to start your target(s) and kick off scanning when using an advanced configuration.| --> +| CI/CD variable | Description | +|-------------------------------------------------------------|-------------| +| `SECURE_ANALYZERS_PREFIX` | Specify the Docker registry base address from which to download the analyzer. | +| `FUZZAPI_VERSION` | Specify API Fuzzing container version. Defaults to `latest`. | +| `FUZZAPI_TARGET_URL` | Base URL of API testing target. | +| `FUZZAPI_CONFIG` | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/276395) in GitLab 13.12, replaced with default `.gitlab/gitlab-api-fuzzing-config.yml`. API Fuzzing configuration file. | +|[`FUZZAPI_PROFILE`](#api-fuzzing-profiles) | Configuration profile to use during testing. Defaults to `Quick-10`. | +|[`FUZZAPI_OPENAPI`](#openapi-specification) | OpenAPI Specification file or URL. | +|[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | +|[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | +|[`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. | +|[`FUZZAPI_OVERRIDES_CMD`](#overrides) | Overrides command. | +|[`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. | ### Overrides @@ -788,6 +743,9 @@ To provide the overrides JSON as a file, the `FUZZAPI_OVERRIDES_FILE` CI/CD vari Here's an example `.gitlab-ci.yml`: ```yaml +stages: + - fuzz + include: - template: API-Fuzzing.gitlab-ci.yml @@ -806,6 +764,9 @@ This allows you to place the JSON as variables that can be masked and protected. In this example `.gitlab-ci.yml`, the `FUZZAPI_OVERRIDES_ENV` variable is set directly to the JSON: ```yaml +stages: + - fuzz + include: - template: API-Fuzzing.gitlab-ci.yml @@ -820,6 +781,9 @@ In this example `.gitlab-ci.yml`, the `SECRET_OVERRIDES` variable provides the J [group or instance level CI/CD variable defined in the UI](../../../ci/variables/README.md#instance-cicd-variables): ```yaml +stages: + - fuzz + include: - template: API-Fuzzing.gitlab-ci.yml @@ -845,6 +809,9 @@ You must provide three CI/CD variables, each set for correct operation: - `FUZZAPI_OVERRIDES_INTERVAL`: Interval in seconds to run command. ```yaml +stages: + - fuzz + include: - template: API-Fuzzing.gitlab-ci.yml @@ -1009,7 +976,7 @@ pipelines. For more information, see the [Security Dashboard documentation](../s Fuzzing faults show up as vulnerabilities with a severity of Unknown. Once a fault is found, you can interact with it. Read more on how to -[address the vulnerabilities](../index.md#addressing-vulnerabilities). +[address the vulnerabilities](../vulnerabilities/index.md). ## Handling False Positives @@ -1026,7 +993,7 @@ False positives can be handled in two ways: ### Turn off a Check Checks perform testing of a specific type and can be turned on and off for specific configuration -profiles. The provided [configuration files](#configuration-files) define several profiles that you +profiles. The default configuration file defines several profiles that you can use. The profile definition in the configuration file lists all the checks that are active during a scan. To turn off a specific check, remove it from the profile definition in the configuration file. The profiles are defined in the `Profiles` section of the configuration file. @@ -1143,13 +1110,19 @@ Profiles: UnicodeFuzzing: true ``` +## Running API fuzzing in an offline environment + +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 Web API Fuzz testing job to +successfully run. For more information, see [Offline environments](../offline_deployments/index.md). + ## Troubleshooting ### Error, the OpenAPI document is not valid. Errors were found during validation of the document using the published OpenAPI schema -At the start of an API Fuzzing job the OpenAPI specification is validated against the [published schema](https://github.com/OAI/OpenAPI-Specification/tree/master/schemas). This error is shown when the provided OpenAPI specification has validation errors. Errors can be introduced when creating an OpenAPI specification manually, and also when the schema is generated. +At the start of an API Fuzzing job the OpenAPI Specification is validated against the [published schema](https://github.com/OAI/OpenAPI-Specification/tree/master/schemas). This error is shown when the provided OpenAPI Specification has validation errors. Errors can be introduced when creating an OpenAPI Specification manually, and also when the schema is generated. -For OpenAPI specifications that are generated automatically validation errors are often the result of missing code annotations. +For OpenAPI Specifications that are generated automatically validation errors are often the result of missing code annotations. **Error message** @@ -1157,9 +1130,9 @@ For OpenAPI specifications that are generated automatically validation errors ar - `OpenAPI 2.0 schema validation error ...` - `OpenAPI 3.0.x schema validation error ...` -**Solution** +**Solution** -**For generated OpenAPI specifications** +**For generated OpenAPI Specifications** 1. Identify the validation errors. 1. Use the [Swagger Editor](https://editor.swagger.io/) to identify validation problems in your specification. The visual nature of the Swagger Editor makes it easier to understand what needs to change. @@ -1170,7 +1143,7 @@ For OpenAPI specifications that are generated automatically validation errors ar **For manually created OpenAPI Specifications** 1. Identify the validation errors. - 1. The simplest solution is to use a visual tool to edit and validate the OpenAPI document. For example the [Swagger Editor](https://editor.swagger.io/) will point out schema errors and possible solutions. + 1. The simplest solution is to use a visual tool to edit and validate the OpenAPI document. For example the [Swagger Editor](https://editor.swagger.io/) highlights schema errors and possible solutions. 1. Alternatively, you can check the log output and look for schema validation warnings. They are prefixed with messages such as `OpenAPI 2.0 schema validation error` or `OpenAPI 3.0.x schema validation error`. Each failed validation provides extra information about `location` and `description`. Correct each of the validation failures and then resubmit the OpenAPI doc. Note that JSON Schema validation message might not be easy to understand. This is why we recommend the use of editors to validate document. 1. Once the validation issues are resolved, re-run your pipeline. @@ -1183,11 +1156,61 @@ The API Fuzzing engine outputs an error message when it cannot establish a conne - 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?`. -**Solution** +**Solution** - Remove the `FUZZAPI_API` variable from the `.gitlab-ci.yml` file. The value will be inherited from the API Fuzzing CI/CD template. We recommend this method instead of manually setting a value. - If removing the variable is not possible, check to see if this value has changed in the latest version of the [API Fuzzing CI/CD template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml). If so, update the value in the `.gitlab-ci.yml` file. +### Application cannot determine the base URL for the target API + +The API Fuzzing analyzer outputs an error message when it cannot determine the target API after inspecting the OpenAPI document. This error message is shown when the target API has not been set in the `.gitlab-ci.yml`file, it is not available in the `environment_url.txt` file, and it could not be computed using the OpenAPI document. + +There is an order of precedence in which the API Fuzzing analyzer tries to get the target API when checking the different sources. First, it will try to use the `FUZZAPI_TARGET_URL`. If the environment variable has not been set, then the API Fuzzing analyzer will attempt to use the `environment_url.txt` file. If there is no file `environment_url.txt`, the API Fuzzing analyzer will then use the OpenAPI document contents and the URL provided in `FUZZAPI_OPENAPI` (if a URL is provided) to try to compute the target API. + +The best-suited solution will depend on whether or not your target API changes for each deployment. In static environments, the target API is the same for each deployment, in this case please refer to the [static environment solution](#static-environment-solution). If the target API changes for each deployment a [dynamic environment solution](#dynamic-environment-solutions) should be applied. + +#### Static environment solution + +This solution is for pipelines in which the target API URL doesn't change (is static). + +**Add environmental variable** + +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 +include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OPENAPI: test-api-specification.json +``` + +#### Dynamic environment solutions + +In a dynamic environment your target API changes for each different deployment. In this case, there is more than one possible solution, we recommend to use the `environment_url.txt` file when dealing with dynamic environments. + +**Use environment_url.txt** + +To support dynamic environments in which the target API URL changes during each pipeline, API Fuzzing supports the use of an `environment_url.txt` file that contains the URL to use. This file is not checked into the repository, instead it's created during the pipeline by the job that deploys the test target and collected as an artifact that can be used by later jobs in the pipeline. The job that creates the `environment_url.txt` file must run before the API Fuzzing job. + +1. Modify the test target deployment job adding the base URL in an `environment_url.txt` file at the root of your project. +1. Modify the test target deployment job collecting the `environment_url.txt` as an artifact. + +Example: + +```yaml +deploy-test-target: + script: + # Perform deployment steps + # Create environment_url.txt (example) + - echo http://${CI_PROJECT_ID}-${CI_ENVIRONMENT_SLUG}.example.org > environment_url.txt + + artifacts: + paths: + - environment_url.txt +``` + <!-- ### Target Container diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 4d5e3529762..8c34303ca00 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. **(ULTIMATE)** > - SAST configuration was [enabled](https://gitlab.com/groups/gitlab-org/-/epics/3659) in 13.3 and [improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in 13.4. **(ULTIMATE)** > - DAST Profiles feature was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40474) in 13.4. **(ULTIMATE)** -> - A simplified version was made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/294076) in GitLab 13.9. +> - A simplified version was made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/294076) in GitLab 13.10. WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -49,3 +49,6 @@ You can configure the following security controls: - Click either **Enable** or **Configure** to use SAST for the current project. For more details, see [Configure SAST in the UI](../sast/index.md#configure-sast-in-the-ui). - DAST Profiles - Click **Manage** to manage the available DAST profiles used for on-demand scans. For more details, see [DAST on-demand scans](../dast/index.md#on-demand-scans). +- Secret Detection + - Select **Configure via Merge Request** to create a merge request with the changes required to + enable Secret Detection. For more details, see [Enable Secret Detection via an automatic merge request](../secret_detection/index.md#enable-secret-detection-via-an-automatic-merge-request). diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index fcf5c81db74..5ab56634d29 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -11,22 +11,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: GitLab 14.0 will replace its container scanning engine with Trivy. Currently, GitLab uses the open -source Clair engine for container scanning. GitLab 13.9 deprecates Clair. This is not a hard -breaking change, as customers who wish to continue to use Clair can do so by setting the -`CS_MAJOR_VERSION` CI/CD variable to version 3 (or earlier) in their `gitlab-ci.yaml` file. Since Clair is -deprecated, however, note that GitLab will no longer update or maintain that scanning engine -beginning in the 14.0 release. We advise customers to use the new default of Trivy beginning in -GitLab 14.0 for regular updates and the latest features. +source Clair engine for container scanning. GitLab 13.9 deprecates Clair. Until GitLab 14.0, this is +not a hard breaking change. Beginning in GitLab 14.0, GitLab will no longer update or maintain +Clair. To ensure that you get regular updates and the latest features, you must use the Trivy +container scanning engine beginning in GitLab 14.0. See the following sections for instructions on +moving from Clair to Trivy. Your application's Docker image may itself be based on Docker images that contain known vulnerabilities. By including an extra job in your pipeline that scans for those vulnerabilities and displays them in a merge request, you can use GitLab to audit your Docker-based apps. -By default, container scanning in GitLab is based on [Clair](https://github.com/quay/clair) and -[Klar](https://github.com/optiopay/klar), which are open-source tools for vulnerability static analysis in -containers. The GitLab [Klar analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar/) -scans the containers and serves as a wrapper for Clair. -To integrate security scanners other than Clair and Klar into GitLab, see +GitLab provides integration with two different open-source tools for vulnerability static analysis +in containers: + +- [Clair](https://github.com/quay/claircore) +- [Trivy](https://github.com/aquasecurity/trivy) + +To integrate GitLab with security scanners other than those listed here, see [Security scanner integration](../../../development/integrations/secure.md). You can enable container scanning by doing one of the following: @@ -52,7 +53,13 @@ To enable container scanning in your pipeline, you need the following: or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. - Docker `18.09.03` or higher installed on the same computer as the runner. If you're using the shared runners on GitLab.com, then this is already the case. -- An image matching [Clair's list of supported distributions](https://quay.github.io/claircore/). +- An image matching the following supported distributions (depending on the analyzer being used): + + | Scanning Engine | Supported distributions | + | --- | --- | + | [Clair](https://github.com/quay/claircore) | [Supported operating systems and languages](https://quay.github.io/claircore/) | + | [Trivy](https://github.com/aquasecurity/trivy) | Supported [operating systems](https://aquasecurity.github.io/trivy/latest/vuln-detection/os/) and [languages](https://aquasecurity.github.io/trivy/latest/vuln-detection/library/) | + - [Build and push](../../packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd) your Docker image to your project's container registry. The name of the Docker image should use the following [predefined CI/CD variables](../../../ci/variables/predefined_variables.md): @@ -86,7 +93,19 @@ How you enable container scanning depends on your GitLab version: that comes with your GitLab installation. - GitLab versions earlier than 11.9: Copy and use the job from the [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml). -- GitLab 13.6 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263482) better support for [FIPS](https://csrc.nist.gov/publications/detail/fips/140/2/final) by upgrading the `CS_MAJOR_VERSION` from `2` to `3`. +- GitLab 13.6 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263482) better support for + [FIPS](https://csrc.nist.gov/publications/detail/fips/140/2/final) by upgrading the + `CS_MAJOR_VERSION` from `2` to `3`. Version `3` of the `container_scanning` Docker image uses + [`centos:centos8`](https://hub.docker.com/_/centos) + as the new base. It also removes the use of the [start.sh](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/merge_requests/77) + script and instead executes the analyzer by default. Any customizations made to the + `container_scanning` job's [`before_script`](../../../ci/yaml/README.md#before_script) + and [`after_script`](../../../ci/yaml/README.md#after_script) + blocks may not work with the new version. To roll back to the previous [`alpine:3.11.3`](https://hub.docker.com/_/alpine)-based + Docker image, you can specify the major version through the [`CS_MAJOR_VERSION`](#available-variables) + variable. +- GitLab 13.9 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322656) integration with + [Trivy](https://github.com/aquasecurity/trivy) by upgrading `CS_MAJOR_VERSION` from `3` to `4`. To include the `Container-Scanning.gitlab-ci.yml` template (GitLab 11.9 and later), add the following to your `.gitlab-ci.yml` file: @@ -138,31 +157,34 @@ include: ### Customizing the container scanning settings There may be cases where you want to customize how GitLab scans your containers. For example, you -may want to enable more verbose output from Clair or Klar, access a Docker registry that requires +may want to enable more verbose output, access a Docker registry that requires authentication, and more. To change such settings, use the [`variables`](../../../ci/yaml/README.md#variables) parameter in your `.gitlab-ci.yml` to set [CI/CD variables](#available-variables). The variables you set in your `.gitlab-ci.yml` overwrite those in `Container-Scanning.gitlab-ci.yml`. This example [includes](../../../ci/yaml/README.md#include) the container scanning template and -enables verbose output from Clair by setting the `CLAIR_OUTPUT` variable to `High`: +enables verbose output for both analyzers: + +Clair: ```yaml include: - template: Container-Scanning.gitlab-ci.yml variables: - CLAIR_OUTPUT: High + CLAIR_TRACE: true ``` -Version `3` of the `container_scanning` Docker image uses [`centos:centos8`](https://hub.docker.com/_/centos) -as the new base. It also removes the use of the [start.sh](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/merge_requests/77) -script and instead executes the analyzer by default. Any customizations made to the -`container_scanning` job's [`before_script`](../../../ci/yaml/README.md#before_script) -and [`after_script`](../../../ci/yaml/README.md#after_script) -blocks may not work with the new version. To roll back to the previous [`alpine:3.11.3`](https://hub.docker.com/_/alpine)-based -Docker image, you can specify the major version through the [`CS_MAJOR_VERSION`](#available-variables) -variable. +Trivy: + +```yaml +include: + - template: Container-Scanning.gitlab-ci.yml + +variables: + TRIVY_DEBUG: true +``` This example [includes](../../../ci/yaml/README.md#include) the container scanning template and enables version `2` of the analyzer: @@ -181,57 +203,109 @@ variables: #### Available variables -You can [configure](#customizing-the-container-scanning-settings) container -scanning by using the following CI/CD variables: - -| CI/CD Variable | Default | Description | -| ------------------------------ | ------------- | ----------- | -| `ADDITIONAL_CA_CERT_BUNDLE` | `""` | Bundle of CA certs that you want to trust. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. | -| `CLAIR_DB_CONNECTION_STRING` | `postgresql://postgres:password@clair-vulnerabilities-db:5432/postgres?sslmode=disable&statement_timeout=60000` | This variable represents the [connection string](https://www.postgresql.org/docs/9.3/libpq-connect.html#AEN39692) to the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) database and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone container scanning tool](#running-the-standalone-container-scanning-tool) section. The host value for the connection string must match the [alias](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) value of the `Container-Scanning.gitlab-ci.yml` template file, which defaults to `clair-vulnerabilities-db`. | -| `CLAIR_DB_IMAGE` | `arminc/clair-db:latest` | The Docker image name and tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes, or to refer to a locally hosted vulnerabilities database for an on-premise offline installation. | -| `CLAIR_DB_IMAGE_TAG` | `latest` | (**DEPRECATED - use `CLAIR_DB_IMAGE` instead**) The Docker image tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes. | -| `CLAIR_OUTPUT` | `Unknown` | Severity level threshold. Vulnerabilities with severity level higher than or equal to this threshold are outputted. Supported levels are `Unknown`, `Negligible`, `Low`, `Medium`, `High`, `Critical` and `Defcon1`. | -| `CLAIR_TRACE` | `"false"` | Set to true to enable more verbose output from the Clair server process. | -| `CLAIR_VULNERABILITIES_DB_URL` | `clair-vulnerabilities-db` | (**DEPRECATED - use `CLAIR_DB_CONNECTION_STRING` instead**) This variable is explicitly set in the [services section](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) of the `Container-Scanning.gitlab-ci.yml` file and defaults to `clair-vulnerabilities-db`. This value represents the address that the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) is running on and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone container scanning tool](#running-the-standalone-container-scanning-tool) section. | -| `CI_APPLICATION_REPOSITORY` | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | Docker repository URL for the image to be scanned. | -| `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | -| `CS_MAJOR_VERSION` | `3` | The major version of the Docker image tag. | -| `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. | -| `DOCKER_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access secure Docker registries using HTTPS with bad (or self-signed) SSL certificates. | -| `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. | -| `DOCKER_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. | -| `DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to be used for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project, so this variable should only be configured 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. | -| `KLAR_TRACE` | `"false"` | Set to true to enable more verbose output from Klar. | -| `REGISTRY_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | -| `SECURE_ANALYZERS_PREFIX` | `"registry.gitlab.com/gitlab-org/security-products/analyzers"` | Set the Docker registry base address from which to download the analyzer. | -| `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. | +You can [configure](#customizing-the-container-scanning-settings) both analyzers by using the following CI/CD variables: + +| CI/CD Variable | Default | Description | Supported by| +| ------------------------------ | ------------- | ----------- | ------------ | +| `ADDITIONAL_CA_CERT_BUNDLE` | `""` | Bundle of CA certs that you want to trust. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. | Both | +| `CLAIR_DB_CONNECTION_STRING` | `postgresql://postgres:password@clair-vulnerabilities-db:5432/postgres?sslmode=disable&statement_timeout=60000` | This variable represents the [connection string](https://www.postgresql.org/docs/9.3/libpq-connect.html#AEN39692) to the [PostgreSQL server hosting the vulnerability definitions](https://hub.docker.com/r/arminc/clair-db) database. **Do not change this** unless you're running the image locally as described in [Running the standalone container scanning tool](#running-the-standalone-container-scanning-tool). The host value for the connection string must match the [alias](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) value of the `Container-Scanning.gitlab-ci.yml` template file, which defaults to `clair-vulnerabilities-db`. | Clair | +| `CLAIR_DB_IMAGE` | `arminc/clair-db:latest` | The Docker image name and tag for the [PostgreSQL server hosting the vulnerability definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version (for example, to provide a consistent set of vulnerabilities for integration testing purposes, or to refer to a locally hosted vulnerability database for an on-premise offline installation). | Clair | +| `CLAIR_DB_IMAGE_TAG` | `latest` | (**DEPRECATED - use `CLAIR_DB_IMAGE` instead**) The Docker image tag for the [PostgreSQL server hosting the vulnerability definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version (for example, to provide a consistent set of vulnerabilities for integration testing purposes). | Clair | +| `CLAIR_OUTPUT` | `Unknown` | Severity level threshold. Vulnerabilities with severity level higher than or equal to this threshold are output. Supported levels are `Unknown`, `Negligible`, `Low`, `Medium`, `High`, `Critical`, and `Defcon1`. | Clair | +| `CLAIR_TRACE` | `"false"` | Set to true to enable more verbose output from the Clair server process. | Clair | +| `CLAIR_VULNERABILITIES_DB_URL` | `clair-vulnerabilities-db` | (**DEPRECATED - use `CLAIR_DB_CONNECTION_STRING` instead**) This variable is explicitly set in the [services section](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) of the `Container-Scanning.gitlab-ci.yml` file and defaults to `clair-vulnerabilities-db`. This value represents the address that the [PostgreSQL server hosting the vulnerability definitions](https://hub.docker.com/r/arminc/clair-db) is running on. **Do not change this** unless you're running the image locally as described in [Running the standalone container scanning tool](#running-the-standalone-container-scanning-tool). | Clair | +| `CI_APPLICATION_REPOSITORY` | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | Docker repository URL for the image to be scanned. | Both | +| `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | Both | +| `CS_ANALYZER_IMAGE` | `$SECURE_ANALYZERS_PREFIX/$CS_PROJECT:$CS_MAJOR_VERSION` | Docker image of the analyzer. | Both | +| `CS_MAJOR_VERSION` | `3` | The major version of the Docker image tag. | Both | +| `CS_PROJECT` | Depends on `$CS_MAJOR_VERSION`. `klar` if `$CS_MAJOR_VERSION` is set to `1`, `2` or `3`, and `container-scanning` otherwise. | Analyzer project to be used. | Both | +| `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. | Both | +| `DOCKER_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access secure Docker registries using HTTPS with bad (or self-signed) SSL certificates. | Clair | +| `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. | Clair | +| `DOCKER_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. | Clair | +| `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. | Both | +| `KLAR_TRACE` | `"false"` | Set to true to enable more verbose output from Klar. | Clair | +| `REGISTRY_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | Clair | +| `SECURE_ANALYZERS_PREFIX` | `"registry.gitlab.com/gitlab-org/security-products/analyzers"` | Set the Docker registry base address from which to download the analyzer. | Both | +| `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. | Both | +| `TRIVY_DEBUG` | `"false"` | Set to true to enable more verbose output from the Trivy process. | Trivy | ### Overriding the container scanning template If you want to override the job definition (for example, to change properties like `variables`), you -must declare a `container_scanning` job after the template inclusion, and then -specify any additional keys. For example: +must declare and override a job after the template inclusion, and then +specify any additional keys. + +This example sets `GIT_STRATEGY` to `fetch` to be considered by both Clair and Trivy: ```yaml include: - template: Container-Scanning.gitlab-ci.yml -container_scanning: +.cs_common: variables: GIT_STRATEGY: fetch ``` +This example sets `KLAR_TRACE` to `true`, which is specific to Clair: + +```yaml +include: + - template: Container-Scanning.gitlab-ci.yml + +container_scanning: + variables: + CLAIR_TRACE: true +``` + +This example sets `TRIVY_DEBUG` to `true`, which is specific to Trivy: + +```yaml +include: + - template: Container-Scanning.gitlab-ci.yml + +container_scanning_new: + variables: + TRIVY_DEBUG: true +``` + WARNING: -GitLab 13.0 and later doesn't support [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic). +GitLab 13.0 and later doesn't support [`only` and `except`](../../../ci/yaml/README.md#only--except). When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. +### Migrating from Clair to Trivy + +If you are currently using Clair and want to migrate to Trivy before GitLab 14.0, you can do so by +taking the following steps: + +1. Take the following actions in your CI file: + + - Set the variable `CS_MAJOR_VERSION` to `4`. The job scope is global variables, or under `.cs_common`. + - Remove the variable `CS_PROJECT` from your CI file. The job scope is `container_scanning_new`. + Setting this variable to `container-scanning` under the correct scope has the same effect as + removing it from your CI file. + - Remove the `CS_ANALYZER_IMAGE` variable from your CI file. The job scope is `.cs_common`. Note + that instead of overriding this variable, you can use `CS_MAJOR_VERSION`. + +1. Remove any variables that are only applicable to Clair. For a complete list of these variables, + see the [available variables](#available-variables). +1. Make any [necessary customizations](#customizing-the-container-scanning-settings) to the + `Trivy` scanner. We strongly recommended that you minimize customizations, as they + might require changes in future GitLab major releases. + +**Troubleshooting** + +Prior to the GitLab 14.0 release, any variable defined under the scope `container_scanning` is not +considered for the Trivy scanner. Verify that all variables for Trivy are +either defined as a global variable, or under `.cs_common` and `container_scanning_new`. + ### Using a custom SSL CA certificate authority You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority, which is used to verify the peer when fetching Docker images from a registry which uses HTTPS. 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: ```yaml -container_scanning: +.cs_common: variables: ADDITIONAL_CA_CERT_BUNDLE: | -----BEGIN CERTIFICATE----- @@ -250,7 +324,7 @@ To allowlist specific vulnerabilities, follow these steps: 1. Set `GIT_STRATEGY: fetch` in your `.gitlab-ci.yml` file by following the instructions in [overriding the container scanning template](#overriding-the-container-scanning-template). 1. Define the allowlisted vulnerabilities in a YAML file named `vulnerability-allowlist.yml`. This must use - the format described in [vulnerability-allowlist.yml data format](#vulnerability-allowlistyml-data-format). + the format described in [`vulnerability-allowlist.yml` data format](#vulnerability-allowlistyml-data-format). 1. Add the `vulnerability-allowlist.yml` file to the root folder of your project's Git repository. #### vulnerability-allowlist.yml data format @@ -291,9 +365,9 @@ This example excludes from `gl-container-scanning-report.json`: You can specify container image in multiple ways: - - as image name only (ie. `centos`). - - as full image name with registry hostname (ie. `your.private.registry:5000/centos`). - - as full image name with registry hostname and sha256 label (ie. `registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256`). + - as image name only (such as `centos`). + - as full image name with registry hostname (such as `your.private.registry:5000/centos`). + - as full image name with registry hostname and sha256 label (such as `registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256`). NOTE: The string after CVE ID (`cups` and `libxml2` in the previous example) is an optional comment format. It has **no impact** on the handling of vulnerabilities. You can include comments to describe the vulnerability. @@ -341,7 +415,13 @@ successfully run. For more information, see [Offline environments](../offline_de To use container scanning in an offline environment, you need: - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). -- To configure a local Docker container registry with copies of the container scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar) images, found in the [container scanning container registry](https://gitlab.com/gitlab-org/security-products/analyzers/klar/container_registry). +- To configure a local Docker container registry with copies of the container scanning images. You + can find these images in their respective registries: + +| GitLab Analyzer | Container Registry | +| --- | --- | +| [Klar](https://gitlab.com/gitlab-org/security-products/analyzers/klar/) (used to run Clair) | [Klar container registry](https://gitlab.com/gitlab-org/security-products/analyzers/klar/container_registry) | +| [Container-Scanning](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning) (used to run Trivy) | [Container-Scanning container registry](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/container_registry/1741162) | Note that 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 @@ -354,25 +434,34 @@ enables the use of updated scanners in your CI/CD pipelines. Support for custom certificate authorities was introduced in the following versions: -| Analyzer | Version | +| Scanner | Version | | -------- | ------- | -| `klar` | [v2.3.0](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/releases/v2.3.0) | +| `Clair` | [v2.3.0](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/releases/v2.3.0) | +| `Trivy` | [4.0.0](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/-/releases/4.0.0) | #### Make GitLab container scanning analyzer images available inside your Docker registry For container scanning, import the following default images from `registry.gitlab.com` into your [local Docker container registry](../../packages/container_registry/index.md): +Clair: + ```plaintext registry.gitlab.com/gitlab-org/security-products/analyzers/klar https://hub.docker.com/r/arminc/clair-db ``` +Trivy: + +```plaintext +registry.gitlab.com/gitlab-org/security-products/analyzers/container-scanning +``` + 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 you can import or temporarily access external resources. Note that these scanners -are [updated periodically](../index.md#maintenance-and-update-of-the-vulnerabilities-database) -with new definitions, so consider if you are able to make periodic updates yourself. +process by which you can import or temporarily access external resources. These scanners +are [periodically updated](../vulnerabilities/index.md#vulnerability-scanner-maintenance), +and you may be able to make occasional updates on your own. For more information, see [the specific steps on how to update an image with a pipeline](#automating-container-scanning-vulnerability-database-updates-with-a-pipeline). @@ -384,49 +473,72 @@ For details on saving and transporting Docker images as a file, see Docker's doc 1. [Override the container scanning template](#overriding-the-container-scanning-template) in your `.gitlab-ci.yml` file to refer to the Docker images hosted on your local Docker container registry: + Clair: + ```yaml include: - template: Container-Scanning.gitlab-ci.yml - container_scanning: + .cs_common: image: $CI_REGISTRY/namespace/gitlab-klar-analyzer variables: CLAIR_DB_IMAGE: $CI_REGISTRY/namespace/clair-vulnerabilities-db ``` + Trivy: + + ```yaml + include: + - template: Container-Scanning.gitlab-ci.yml + + .cs_common: + image: $CI_REGISTRY/namespace/gitlab-container-scanning + ``` + 1. If your local Docker container registry is running securely over `HTTPS`, but you're using a self-signed certificate, then you must set `DOCKER_INSECURE: "true"` in the above - `container_scanning` section of your `.gitlab-ci.yml`. + `container_scanning` section of your `.gitlab-ci.yml`. This only applies to Clair. #### Automating container scanning vulnerability database updates with a pipeline -It can be worthwhile to set up a [scheduled pipeline](../../../ci/pipelines/schedules.md) to -build a new version of the vulnerabilities database on a preset schedule. Automating -this with a pipeline means you do not have to do it manually each time. You can use the following -`.gitlab-yml.ci` as a template: +We recommend that you set up a [scheduled pipeline](../../../ci/pipelines/schedules.md) +to fetch the latest vulnerabilities database on a preset schedule. Because the Clair scanner is +deprecated, the latest vulnerabilities are currently only available for the Trivy scanner. +Automating this with a pipeline means you do not have to do it manually each time. You can use the +following `.gitlab-yml.ci` example as a template. ```yaml -image: docker:stable +variables: + # If using Clair, uncomment the following 2 lines and comment the Trivy lines below + # SOURCE_IMAGE: arminc/clair-db:latest + # TARGET_IMAGE: $CI_REGISTRY/$CI_PROJECT_PATH/clair-vulnerabilities-db -stages: - - build + # If using Trivy, uncomment the following 3 lines and comment the Clair lines above + CS_MAJOR_VERSION: 4 # ensure that this value matches the one you use in your scanning jobs + SOURCE_IMAGE: registry.gitlab.com/gitlab-org/security-products/analyzers/container-scanning:$CS_MAJOR_VERSION + TARGET_IMAGE: $CI_REGISTRY/$CI_PROJECT_PATH/gitlab-container-scanning -build_latest_vulnerabilities: - stage: build +image: docker:stable + +update-vulnerabilities-db: services: - - docker:19.03.12-dind + - docker:19-dind script: - - docker pull arminc/clair-db:latest - - docker tag arminc/clair-db:latest $CI_REGISTRY/namespace/clair-vulnerabilities-db - - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY - - docker push $CI_REGISTRY/namespace/clair-vulnerabilities-db + - docker pull $SOURCE_IMAGE + - docker tag $SOURCE_IMAGE $TARGET_IMAGE + - echo "$CI_REGISTRY_PASSWORD" | docker login $CI_REGISTRY --username $CI_REGISTRY_USER --password-stdin + - docker push $TARGET_IMAGE ``` -The above template works for a GitLab Docker registry running on a local installation, however, if you're using a non-GitLab Docker registry, you need to change the `$CI_REGISTRY` value and the `docker login` credentials to match the details of your local registry. +The above template works for a GitLab Docker registry running on a local installation. However, if +you're using a non-GitLab Docker registry, you must change the `$CI_REGISTRY` value and the +`docker login` credentials to match your local registry's details. ## Running the standalone container scanning tool -It's possible to run the [GitLab container scanning tool](https://gitlab.com/gitlab-org/security-products/analyzers/klar) +### Clair + +It's possible to run [Klar](https://gitlab.com/gitlab-org/security-products/analyzers/klar) against a Docker container without needing to run it within the context of a CI job. To scan an image directly, follow these steps: @@ -458,6 +570,30 @@ image directly, follow these steps: The results are stored in `gl-container-scanning-report.json`. +### Trivy + +It's possible to run the [GitLab container scanning tool](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning) +against a Docker container without needing to run it within the context of a CI job. To scan an +image directly, follow these steps: + +1. Run [Docker Desktop](https://www.docker.com/products/docker-desktop) + or [Docker Machine](https://github.com/docker/machine). + +1. Run the analyzer's Docker image, passing the image and tag you want to analyze in the + `CI_APPLICATION_REPOSITORY` and `CI_APPLICATION_TAG` variables: + + ```shell + docker run \ + --interactive --rm \ + --volume "$PWD":/tmp/app \ + -e CI_PROJECT_DIR=/tmp/app \ + -e CI_APPLICATION_REPOSITORY=registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256 \ + -e CI_APPLICATION_TAG=bc09fe2e0721dfaeee79364115aeedf2174cce0947b9ae5fe7c33312ee019a4e \ + registry.gitlab.com/gitlab-org/security-products/analyzers/container-scanning + ``` + +The results are stored in `gl-container-scanning-report.json`. + ## Reports JSON format The container scanning tool emits a JSON report file. For more information, see the @@ -467,19 +603,19 @@ Here's an example container scanning report: ```json-doc { - "version": "2.3", + "version": "3.0.0", "vulnerabilities": [ { - "id": "ac0997ad-1006-4c81-81fb-ee2bbe6e78e3", + "id": "df52bc8ce9a2ae56bbcb0c4ecda62123fbd6f69b", "category": "container_scanning", - "message": "CVE-2019-3462 in apt", + "message": "CVE-2019-3462 in apt-1.4.8", "description": "Incorrect sanitation of the 302 redirect field in HTTP transport method of apt versions 1.4.8 and earlier can lead to content injection by a MITM attacker, potentially leading to remote code execution on the target machine.", "severity": "High", "confidence": "Unknown", "solution": "Upgrade apt from 1.4.8 to 1.4.9", "scanner": { - "id": "klar", - "name": "klar" + "id": "trivy", + "name": "trivy" }, "location": { "dependency": { @@ -488,7 +624,7 @@ Here's an example container scanning report: }, "version": "1.4.8" }, - "operating_system": "debian:9", + "operating_system": "debian:9.4", "image": "registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256:bc09fe2e0721dfaeee79364115aeedf2174cce0947b9ae5fe7c33312ee019a4e" }, "identifiers": [ @@ -496,27 +632,62 @@ Here's an example container scanning report: "type": "cve", "name": "CVE-2019-3462", "value": "CVE-2019-3462", - "url": "https://security-tracker.debian.org/tracker/CVE-2019-3462" + "url": "http://www.securityfocus.com/bid/106690" } ], "links": [ { - "url": "https://security-tracker.debian.org/tracker/CVE-2019-3462" + "url": "http://www.securityfocus.com/bid/106690" + }, + { + "url": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-3462" + }, + { + "url": "https://lists.apache.org/thread.html/8338a0f605bdbb3a6098bb76f666a95fc2b2f53f37fa1ecc89f1146f@%3Cdevnull.infra.apache.org%3E" + }, + { + "url": "https://lists.debian.org/debian-lts-announce/2019/01/msg00013.html" + }, + { + "url": "https://lists.debian.org/debian-lts-announce/2019/01/msg00014.html" + }, + { + "url": "https://security.netapp.com/advisory/ntap-20190125-0002/" + }, + { + "url": "https://usn.ubuntu.com/3863-1/" + }, + { + "url": "https://usn.ubuntu.com/3863-2/" + }, + { + "url": "https://usn.ubuntu.com/usn/usn-3863-1" + }, + { + "url": "https://usn.ubuntu.com/usn/usn-3863-2" + }, + { + "url": "https://www.debian.org/security/2019/dsa-4371" } ] } ], - "remediations": [ - { - "fixes": [ - { - "id": "c0997ad-1006-4c81-81fb-ee2bbe6e78e3" - } - ], - "summary": "Upgrade apt from 1.4.8 to 1.4.9", - "diff": "YXB0LWdldCB1cGRhdGUgJiYgYXB0LWdldCB1cGdyYWRlIC15IGFwdA==" - } - ] + "remediations": [] + "scan": { + "scanner": { + "id": "trivy", + "name": "Trivy", + "url": "https://github.com/aquasecurity/trivy/", + "vendor": { + "name": "GitLab" + }, + "version": "0.16.0" + }, + "type": "container_scanning", + "start_time": "2021-04-14T19:45:58", + "end_time": "2021-04-14T19:46:18", + "status": "success" + } } ``` @@ -527,12 +698,12 @@ the security vulnerabilities in your groups, projects and pipelines. ## Vulnerabilities database update -For more information about the vulnerabilities database update, check the -[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database). +If you're using Klar and want more information about the vulnerabilities database update, see the +[maintenance table](../vulnerabilities/index.md#vulnerability-scanner-maintenance). ## Interacting with the vulnerabilities -After a vulnerability is found, you can [address it](../index.md#addressing-vulnerabilities). +After a vulnerability is found, you can [address it](../vulnerabilities/index.md). ## Solutions for vulnerabilities (auto-remediation) @@ -546,7 +717,7 @@ file, it's necessary to set [`GIT_STRATEGY: fetch`](../../../ci/runners/README.m your `.gitlab-ci.yml` file by following the instructions described in this document's [overriding the container scanning template](#overriding-the-container-scanning-template) section. -Read more about the [solutions for vulnerabilities](../index.md#apply-an-automatic-remediation-for-a-vulnerability). +Read more about the [solutions for vulnerabilities](../vulnerabilities/index.md#remediate-a-vulnerability-automatically). ## Troubleshooting diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index e9097836d83..8b0a84eae4b 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -237,7 +237,7 @@ The `covfuzz-ci.yml` is the same as that in the [original synchronous example](h ## Interacting with the vulnerabilities -After a vulnerability is found, you can [address it](../index.md#addressing-vulnerabilities). +After a vulnerability is found, you can [address it](../vulnerabilities/index.md). The merge request widget lists the vulnerability and contains a button for downloading the fuzzing artifacts. By clicking one of the detected vulnerabilities, you can see its details. diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md new file mode 100644 index 00000000000..b8c3529225c --- /dev/null +++ b/doc/user/application_security/dast/browser_based.md @@ -0,0 +1,148 @@ +--- +stage: Secure +group: Dynamic 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 +type: reference, howto +--- + +# DAST browser-based crawler **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323423) in GitLab 13.12. + +WARNING: +This product is an early access and is considered a [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) feature. + +GitLab DAST's new browser-based crawler is a crawl engine built by GitLab to test Single Page Applications (SPAs) and traditional web applications. +Due to the reliance of modern web applications on JavaScript, handling SPAs or applications that are dependent on JavaScript is paramount to ensuring proper coverage of an application for Dynamic Application Security Testing (DAST). + +The browser-based crawler works by loading the target application into a specially-instrumented Chromium browser. A snapshot of the page is taken prior to a search to find any actions that a user might perform, +such as clicking on a link or filling in a form. For each action found, the crawler will execute it, take a new snapshot and determine what in the page changed from the previous snapshot. +Crawling continues by taking more snapshots and finding subsequent actions. + +The benefit of crawling by following user actions in a browser is that the crawler can interact with the target application much like a real user would, identifying complex flows that traditional web crawlers don’t understand. This results in better coverage of the website. + +Scanning a web application with both the browser-based crawler and GitLab DAST should provide greater coverage, compared with only GitLab DAST. The new crawler does not support API scanning or the DAST AJAX crawler. + +## Enable browser-based crawler + +The browser-based crawler is an extension to the GitLab DAST product. DAST should be included in the CI/CD configuration and the browser-based crawler enabled using CI/CD variables: + +1. Install the DAST [prerequisites](index.md#prerequisite). +1. Include the [DAST CI template](index.md#include-the-dast-template). +1. Set the target website using the `DAST_WEBSITE` CI/CD variable. +1. Set the CI/CD variable `DAST_BROWSER_SCAN` to `true`. + +An example configuration might look like the following: + +```yaml +include: + - template: DAST.gitlab-ci.yml + +variables: + DAST_WEBSITE: "https://example.com" + DAST_BROWSER_SCAN: "true" +``` + +### Available variables + +The browser-based crawler can be configured using CI/CD variables. + +| CI/CD variable | Type | Example | Description | +|--------------------------------------| ----------------| --------------------------------- | ------------| +| `DAST_WEBSITE` | URL | `http://www.site.com` | The URL of the website to scan. | +| `DAST_BROWSER_SCAN` | boolean | `true` | Configures DAST to use the browser-based crawler engine. | +| `DAST_BROWSER_ALLOWED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered in scope when crawled. By default the `DAST_WEBSITE` hostname is included in the allowed hosts list. | +| `DAST_BROWSER_EXCLUDED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered excluded and connections are forcibly dropped. | +| `DAST_BROWSER_IGNORED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are accessed but not reported against. | +| `DAST_BROWSER_MAX_ACTIONS` | number | `10000` | The maximum number of actions that the crawler performs. For example, clicking a link, or filling a form. | +| `DAST_BROWSER_MAX_DEPTH` | number | `10` | The maximum number of chained actions that the crawler takes. For example, `Click -> Form Fill -> Click` is a depth of three. | +| `DAST_BROWSER_NUMBER_OF_BROWSERS` | number | `3` | The maximum number of concurrent browser instances to use. For shared runners on GitLab.com we recommended a maximum of three. Private runners with more resources may benefit from a higher number, but will likely produce little benefit after five to seven instances. | +| `DAST_BROWSER_COOKIES` | dictionary | `abtesting_group:3,region:locked` | A cookie name and value to be added to every request. | +| `DAST_BROWSER_LOG` | List of strings | `brows:debug,auth:debug` | A list of modules and their intended log level. | +| `DAST_AUTH_URL` | string | `https://example.com/sign-in` | The URL of page that hosts the sign-in form. | +| `DAST_USERNAME` | string | `user123` | The username to enter into the username field on the sign-in HTML form. | +| `DAST_PASSWORD` | string | `p@55w0rd` | The password to enter into the password field on the sign-in HTML form. | +| `DAST_USERNAME_FIELD` | selector | `id:user` | A selector describing the username field on the sign-in HTML form. | +| `DAST_PASSWORD_FIELD` | selector | `css:.password-field` | A selector describing the password field on the sign-in HTML form. | +| `DAST_SUBMIT_FIELD` | selector | `xpath://input[@value='Login']` | A selector describing the element that when clicked submits the login form or the password form of a multi-page login process. | +| `DAST_FIRST_SUBMIT_FIELD` | selector | `.submit` | A selector describing the element that when clicked submits the username form of a multi-page login process. | + +The [DAST variables](index.md#available-variables) `SECURE_ANALYZERS_PREFIX`, `DAST_FULL_SCAN_ENABLED`, `DAST_AUTO_UPDATE_ADDONS`, `DAST_EXCLUDE_RULES`, `DAST_REQUEST_HEADERS`, `DAST_HTML_REPORT`, `DAST_MARKDOWN_REPORT`, `DAST_XML_REPORT`, +`DAST_INCLUDE_ALPHA_VULNERABILITIES`, `DAST_PATHS_FILE`, `DAST_PATHS`, `DAST_ZAP_CLI_OPTIONS`, and `DAST_ZAP_LOG_CONFIGURATION` are also compatible with browser-based crawler scans. + +#### Selectors + +Selectors are used by CI/CD variables to specify the location of an element displayed on a page in a browser. +Selectors have the format `type`:`search string`. The crawler will search for the selector using the search string based on the type. + +| Selector type | Example | Description | +| ------------- | ------------------------------ | ----------- | +| `css` | `css:.password-field` | Searches for a HTML element having the supplied CSS selector. Selectors should be as specific as possible for performance reasons. | +| `id` | `id:element` | Searches for an HTML element with the provided element ID. | +| `name` | `name:element` | Searches for an HTML element with the provided element name. | +| `xpath` | `xpath://*[@id="my-button"]/a` | Searches for a HTML element with the provided XPath. Note that XPath searches are expected to be less performant than other searches. | +| None provided | `a.click-me` | Defaults to searching using a CSS selector. | + +## Vulnerability detection + +While the browser-based crawler crawls modern web applications efficiently, vulnerability detection is still managed by the standard DAST/Zed Attack Proxy (ZAP) solution. + +The crawler runs the target website in a browser with DAST/ZAP configured as the proxy server. This ensures that all requests and responses made by the browser are passively scanned by DAST/ZAP. +When running a full scan, active vulnerability checks executed by DAST/ZAP do not use a browser. This difference in how vulnerabilities are checked can cause issues that require certain features of the target website to be disabled to ensure the scan works as intended. + +For example, for a target website that contains forms with Anti-CSRF tokens, a passive scan will scan as intended because the browser displays pages/forms as if a user is viewing the page. +However, active vulnerability checks run in a full scan will not be able to submit forms containing Anti-CSRF tokens. In such cases we recommend you disable Anti-CSRF tokens when running a full scan. + +## Managing scan time + +It is expected that running the browser-based crawler will result in better coverage for many web applications, when compared to the normal GitLab DAST solution. +This can come at a cost of increased scan time. + +You can manage the trade-off between coverage and scan time with the following measures: + +- Limit the number of actions executed by the browser with the [variable](#available-variables) `DAST_BROWSER_MAX_ACTIONS`. The default is `10,000`. +- Limit the page depth that the browser-based crawler will check coverage on with the [variable](#available-variables) `DAST_BROWSER_MAX_DEPTH`. The crawler uses a breadth-first search strategy, so pages with smaller depth are crawled first. The default is `10`. +- Vertically scaling the runner and using a higher number of browsers with [variable](#available-variables) `DAST_BROWSER_NUMBER_OF_BROWSERS`. The default is `3`. + +## Debugging scans using logging + +Logging can be used to help you troubleshoot a scan. + +The CI/CD variable `DAST_BROWSER_LOG` configures the logging level for particular modules of the crawler. Each module represents a component of the browser-based crawler and is separated so that debug logs can be configured just for the area of the crawler that requires further inspection. For more details, see [Crawler modules](#crawler-modules). + +For example, the following job definition enables the browsing module and the authentication module to be logged in debug-mode: + +```yaml +include: + - template: DAST.gitlab-ci.yml + +variables: + DAST_WEBSITE: "https://my.site.com" + DAST_BROWSER_SCAN: "true" + DAST_BROWSER_LOG: "brows:debug,auth:debug" +``` + +### Log message format + +Log messages have the format `[time] [log level] [log module] [message] [additional properties]`. For example, the following log entry has level `INFO`, is part of the `CRAWL` log module, and has the message `Crawled path`. + +```txt +2021-04-21T00:34:04.000 INF CRAWL Crawled path nav_id=0cc7fd path="LoadURL [https://my.site.com:8090]" +``` + +### Crawler modules + +The modules that can be configured for logging are as follows: + +| Log module | Component overview | +| ---------- | ----------- | +| `AUTH` | Used for creating an authenticated scan. | +| `BROWS` | Used for querying the state/page of the browser. | +| `BPOOL` | The set of browsers that are leased out for crawling. | +| `CRAWL` | Used for the core crawler algorithm. | +| `DATAB` | Used for persisting data to the internal database. | +| `LEASE` | Used to create browsers to add them to the browser pool. | +| `MAIN` | Used for the flow of the main event loop of the crawler. | +| `NAVDB` | Used for persistence mechanisms to store navigation entries. | +| `REPT` | Used for generating reports. | +| `STAT` | Used for general statistics while running the scan. | diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 65ddece1bde..1093e7cfabd 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -144,6 +144,14 @@ image. Using the `DAST_VERSION` variable, you can choose how DAST updates: Find the latest DAST versions on the [Releases](https://gitlab.com/gitlab-org/security-products/dast/-/releases) page. +#### Crawling web applications dependent on JavaScript + +GitLab has released a new browser-based crawler, an add-on to DAST that uses a browser to crawl web applications for content. This crawler replaces the standard DAST Spider and Ajax Crawler. + +The browser-based crawler crawls websites by browsing web pages as a user would. This approach works well with web applications that make heavy use of JavaScript, such as Single Page Applications. + +For more details, including setup instructions, see [DAST browser-based crawler](browser_based.md). + ## Deployment options Depending on the complexity of the target application, there are a few options as to how to deploy and configure @@ -452,11 +460,14 @@ configured to act as a remote proxy and add the `Gitlab-DAST-Permission` header. ### API scan -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10928) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10928) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. +> - A new DAST API scanning engine was introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. Using an API specification as a scan's target is a useful way to seed URLs for scanning an API. Vulnerability rules in an API scan are different than those in a normal website scan. +A new DAST API scanning engine is available in GitLab 13.12 and later. For more details, see [DAST API scanning engine](../dast_api). The new scanning engine supports REST, SOAP, GraphQL, and generic APIs using forms, XML, and JSON. Testing can be performed using OpenAPI, Postman Collections, and HTTP Archive (HAR) documents. + #### Specification format API scans support OpenAPI V2 and OpenAPI V3 specifications. You can define these specifications using `JSON` or `YAML`. @@ -471,7 +482,7 @@ include: - template: DAST.gitlab-ci.yml variables: - DAST_API_SPECIFICATION: http://my.api/api-specification.yml + DAST_API_OPENAPI: http://my.api/api-specification.yml ``` #### Import API specification from a file @@ -486,7 +497,7 @@ dast: - cp api-specification.yml /zap/wrk/api-specification.yml variables: GIT_STRATEGY: fetch - DAST_API_SPECIFICATION: api-specification.yml + DAST_API_OPENAPI: api-specification.yml ``` #### Full API scan @@ -522,7 +533,7 @@ include: - template: DAST.gitlab-ci.yml variables: - DAST_API_SPECIFICATION: http://api-test.host.com/api-specification.yml + DAST_API_OPENAPI: http://api-test.host.com/api-specification.yml DAST_API_HOST_OVERRIDE: api-test.host.com ``` @@ -537,7 +548,7 @@ include: - template: DAST.gitlab-ci.yml variables: - DAST_API_SPECIFICATION: http://api-test.api.com/api-specification.yml + DAST_API_OPENAPI: http://api-test.api.com/api-specification.yml DAST_REQUEST_HEADERS: "Authorization: Bearer my.token" ``` @@ -610,10 +621,42 @@ When using `DAST_PATHS` and `DAST_PATHS_FILE`, note the following: To perform a [full scan](#full-scan) on the listed paths, use the `DAST_FULL_SCAN_ENABLED` CI/CD variable. +### View details of a vulnerability detected by DAST + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. + +Vulnerabilities detected by DAST occur in the live web application. Addressing these types of +vulnerabilities requires specific information. DAST provides the information required to +investigate and rectify the underlying cause. + +To view details of vulnerabilities detected by DAST: + +1. To see all vulnerabilities detected, either: + - Go to your project and select **Security & Compliance**. + - Go to the merge request and select the **Security** tab. + +1. Select a vulnerability's description. The following details are provided: + + | Field | Description | + |:-----------------|:------------------------------------------------------------------ | + | Description | Description of the vulnerability. | + | Project | Namespace and project in which the vulnerability was detected. | + | Method | HTTP method used to detect the vulnerability. | + | URL | URL at which the vulnerability was detected. | + | Request Headers | Headers of the request. | + | Response Status | Response status received from the application. | + | Response Headers | Headers of the response received from the application. | + | Evidence | Evidence of the data found that verified the vulnerability. Often a snippet of the request or response, this can be used to help verify that the finding is a vulnerability. | + | Identifiers | Identifiers of the vulnerability. | + | Severity | Severity of the vulnerability. | + | Scanner Type | Type of vulnerability report. | + | Links | Links to further details of the detected vulnerability. | + | Solution | Details of a recommended solution to the vulnerability (optional). | + ### Customizing the DAST settings WARNING: -Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) +Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#only--except) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. The DAST settings can be changed through CI/CD variables by using the @@ -641,8 +684,9 @@ DAST can be [configured](#customizing-the-dast-settings) using CI/CD variables. | CI/CD variable | Type | Description | |------------------------------| --------|-------------| | `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | -| `DAST_WEBSITE` | URL | The URL of the website to scan. `DAST_API_SPECIFICATION` must be specified if this is omitted. | -| `DAST_API_SPECIFICATION` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | +| `DAST_WEBSITE` | URL | The URL of the website to scan. `DAST_API_OPENAPI` must be specified if this is omitted. | +| `DAST_API_OPENAPI` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | +| `DAST_API_SPECIFICATION` | URL or string | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/290241) in GitLab 13.12 and replaced by `DAST_API_OPENAPI`. To be removed in GitLab 15.0. The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | | `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | | `DAST_AUTH_URL` | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. | | `DAST_AUTH_VERIFICATION_URL` | URL | A URL only accessible to logged in users that DAST can use to confirm successful authentication. If provided, DAST will exit if it cannot access the URL. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207335) in GitLab 13.8. @@ -658,6 +702,7 @@ DAST can be [configured](#customizing-the-dast-settings) using CI/CD variables. | `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false` | | `DAST_API_HOST_OVERRIDE` | string | Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080` | | `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). For example, `HTTP Parameter Override` has a rule ID of `10026`. **Note:** In earlier versions of GitLab the excluded rules were executed but alerts they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | +| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. | | `DAST_REQUEST_HEADERS` | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | | `DAST_DEBUG` | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_SPIDER_MINS` | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | @@ -794,9 +839,9 @@ For DAST, import the following default DAST analyzer image from `registry.gitlab 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. Note -that these scanners are [updated periodically](../index.md#maintenance-and-update-of-the-vulnerabilities-database) -with new definitions, so consider if you're able to make periodic updates yourself. +process by which external resources can be imported or temporarily accessed. +These scanners are [periodically updated](../vulnerabilities/index.md#vulnerability-scanner-maintenance) +with new definitions, and you may be able to make occasional updates on your own. 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/), @@ -944,15 +989,18 @@ required for an on-demand DAST scan. A site profile contains the following: - **Profile name**: A name you assign to the site to be scanned. +- **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. - **Request headers**: A comma-separated list of HTTP request headers, including names and values. These headers are added to every request made by DAST. - **Authentication**: - - **Authenticated URL**: The URL of the page containing the sign-in HTML form on the target website. The username and password are submitted with the login form to create an authenticated scan. + - **Authenticated URL**: The URL of the page containing the sign-in HTML form on the target website. The username and password are submitted with the login form to create an authenticated scan. - **Username**: The username used to authenticate to the website. - **Password**: The password used to authenticate to the website. - - **Username form field**: The name of username field at the sign-in HTML form. - - **Password form field**: The name of password field at the sign-in HTML form. + - **Username form field**: The name of username field at the sign-in HTML form. + - **Password form field**: The name of password field at the sign-in HTML form. + +When an API site type is selected, a [host override](#host-override) is used to ensure the API being scanned is on the same host as the target. This is done to reduce the risk of running an active scan against the wrong API. #### Site profile validation diff --git a/doc/user/application_security/dast_api/img/dast_api_postman_collection_edit_variable.png b/doc/user/application_security/dast_api/img/dast_api_postman_collection_edit_variable.png Binary files differnew file mode 100644 index 00000000000..3a2799ecdc1 --- /dev/null +++ b/doc/user/application_security/dast_api/img/dast_api_postman_collection_edit_variable.png diff --git a/doc/user/application_security/dast_api/img/dast_api_postman_environment_edit_variable.png b/doc/user/application_security/dast_api/img/dast_api_postman_environment_edit_variable.png Binary files differnew file mode 100644 index 00000000000..656ba7652cd --- /dev/null +++ b/doc/user/application_security/dast_api/img/dast_api_postman_environment_edit_variable.png diff --git a/doc/user/application_security/dast_api/img/dast_api_postman_request_edit.png b/doc/user/application_security/dast_api/img/dast_api_postman_request_edit.png Binary files differnew file mode 100644 index 00000000000..3750af8f455 --- /dev/null +++ b/doc/user/application_security/dast_api/img/dast_api_postman_request_edit.png diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md new file mode 100644 index 00000000000..5e47f545ef9 --- /dev/null +++ b/doc/user/application_security/dast_api/index.md @@ -0,0 +1,1140 @@ +--- +stage: Secure +group: Dynamic 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 +type: reference, howto +--- + +# DAST API **(ULTIMATE)** + +You can add dynamic application security testing of web APIs to your [GitLab CI/CD](../../../ci/README.md) pipelines. +This helps you discover bugs and potential security issues that other QA processes may miss. + +We recommend that you use DAST API testing in addition to [GitLab Secure](../index.md)'s +other security scanners and your own test processes. If you're using [GitLab CI/CD](../../../ci/README.md), +you can run DAST API tests as part your CI/CD workflow. + +## Requirements + +- One of the following web API types: + - REST API + - SOAP + - GraphQL + - Form bodies, JSON, or XML +- One of the following assets to provide APIs to test: + - OpenAPI v2 or v3 API definition + - Postman Collection v2.0 or v2.1 + - HTTP Archive (HAR) of API requests to test + +## When DAST API scans run + +When using the `DAST-API.gitlab-ci.yml` template, the defined jobs use the `dast` stage by default. To enable your `.gitlab-ci.yml` file must include the `dast` stage in your `stages` definition. To ensure DAST API scans the latest code, your CI pipeline should deploy changes to a test environment in a stage before the `dast` stage: + +```yaml +stages: + - build + - test + - deploy + - dast +``` + +Note that if your pipeline is configured to deploy to the same web server on each run, running a +pipeline while another is still running could cause a race condition in which one pipeline +overwrites the code from another. The API to scan should be excluded from changes for the duration +of a DAST API scan. The only changes to the API should be from the DAST API scanner. Be aware that +any changes made to the API (for example, by users, scheduled tasks, database changes, code +changes, other pipelines, or other scanners) during a scan could cause inaccurate results. + +## Enable DAST API scanning + +There are three ways to perform scans. See the configuration section for the one you wish to use: + +- [OpenAPI v2 or v3 specification](#openapi-specification) +- [HTTP Archive (HAR)](#http-archive-har) +- [Postman Collection v2.0 or v2.1](#postman-collection) + +Examples of various configurations can be found here: + +- [Example OpenAPI v2 specification project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/openapi-example) +- [Example HTTP Archive (HAR) project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/har-example) +- [Example Postman Collection project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/postman-example) +- [Example GraphQL project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/graphql-example) + +WARNING: +GitLab 14.0 will require that you place DAST API configuration files (for example, +`gitlab-dast-api-config.yml`) in your repository's `.gitlab` directory instead of your +repository's root. You can continue using your existing configuration files as they are, but +starting in GitLab 14.0, GitLab will not check your repository's root for configuration files. + +### OpenAPI Specification + +> Support for OpenAPI Specification using YAML format was +> [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330583) in GitLab 14.0. + +The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an API description format for REST APIs. +This section shows you how to configure API fuzzing using an OpenAPI Specification to provide information about the target API to test. +OpenAPI Specifications are provided as a file system resource or URL. Both JSON and YAML OpenAPI formats are supported. + +DAST API uses an OpenAPI document to generate the request body. When a request body is required, +the body generation is limited to these body types: + +- `application/x-www-form-urlencoded` +- `multipart/form-data` +- `application/json` + +Follow these steps to configure DAST API in GitLab with an OpenAPI specification: + +1. To use DAST API, you must [include](../../../ci/yaml/README.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) + that's provided as part of your GitLab installation. Add the following to your + `.gitlab-ci.yml` file: + + ```yaml + stages: + - dast + + include: + - template: DAST-API.gitlab-ci.yml + ``` + +1. The [configuration file](#configuration-files) has several testing profiles defined with different checks enabled. We recommend that you start with the `Quick` profile. + Testing with this profile completes faster, allowing for easier configuration validation. + + Provide the profile by adding the `DAST_API_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, + substituting `Quick` for the profile you choose: + + ```yaml + stages: + - dast + + include: + - template: DAST-API.gitlab-ci.yml + + variables: + DAST_API_PROFILE: Quick + ``` + +1. Provide the location of the OpenAPI specification. You can provide the specification as a file + or URL. Specify the location by adding the `DAST_API_OPENAPI` variable: + + ```yaml + stages: + - dast + + include: + - template: DAST-API.gitlab-ci.yml + + variables: + DAST_API_PROFILE: Quick + DAST_API_OPENAPI: test-api-specification.json + ``` + +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. To run DAST API against an app dynamically created during a GitLab CI/CD + pipeline, have the app persist its URL in an `environment_url.txt` file. DAST API + automatically parses that file to find its scan target. You can see an + [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). + + Here's an example of using `DAST_API_TARGET_URL`: + + ```yaml + stages: + - dast + + include: + - template: DAST-API.gitlab-ci.yml + + variables: + DAST_API_PROFILE: Quick + DAST_API_OPENAPI: test-api-specification.json + DAST_API_TARGET_URL: http://test-deployment/ + ``` + +This 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). + +WARNING: +**NEVER** run DAST API testing against a production server. Not only can it perform *any* function that the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting data. Only run DAST API scanning against a test server. + +### HTTP Archive (HAR) + +The [HTTP Archive format (HAR)](http://www.softwareishard.com/blog/har-12-spec/) +is an archive file format for logging HTTP transactions. When used with the GitLab DAST API scanner, HAR must contain records of calling the web API to test. The DAST API scanner extracts all the requests and +uses them to perform testing. + +You can use various tools to generate HAR files: + +- [Insomnia Core](https://insomnia.rest/): API client +- [Chrome](https://www.google.com/chrome/): Browser +- [Firefox](https://www.mozilla.org/en-US/firefox/): Browser +- [Fiddler](https://www.telerik.com/fiddler): Web debugging proxy +- [GitLab HAR Recorder](https://gitlab.com/gitlab-org/security-products/har-recorder): Command line + +WARNING: +HAR files may contain sensitive information such as authentication tokens, API keys, and session +cookies. We recommend that you review the HAR file contents before adding them to a repository. + +Follow these steps to configure DAST API to use a HAR file that provides information about the +target API to test: + +1. To use DAST API, you must [include](../../../ci/yaml/README.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) + that's provided as part of your GitLab installation. To do so, add the following to your + `.gitlab-ci.yml` file: + + ```yaml + stages: + - dast + + include: + - template: DAST-API.gitlab-ci.yml + ``` + +1. The [configuration file](#configuration-files) has several testing profiles defined with different checks enabled. We recommend that you start with the `Quick` profile. + Testing with this profile completes faster, allowing for easier configuration validation. + + Provide the profile by adding the `DAST_API_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, + substituting `Quick` for the profile you choose: + + ```yaml + stages: + - dast + + include: + - template: DAST-API.gitlab-ci.yml + + variables: + DAST_API_PROFILE: Quick + ``` + +1. Provide the location of the HAR specification. You can provide the specification as a file + or URL. [URL support was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285020) in GitLab 13.10 and later. Specify the location by adding the `DAST_API_HAR` variable: + + ```yaml + stages: + - dast + + include: + - template: DAST-API.gitlab-ci.yml + + variables: + DAST_API_PROFILE: Quick + DAST_API_HAR: test-api-recording.har + ``` + +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. To run DAST API against an app dynamically created during a GitLab CI/CD + pipeline, have the app persist its URL in an `environment_url.txt` file. DAST API + automatically parses that file to find its scan target. You can see an + [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). + + Here's an example of using `DAST_API_TARGET_URL`: + + ```yaml + stages: + - dast + + include: + - template: DAST-API.gitlab-ci.yml + + variables: + DAST_API_PROFILE: Quick + DAST_API_HAR: test-api-recording.har + DAST_API_TARGET_URL: http://test-deployment/ + ``` + +This 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). + +WARNING: +**NEVER** run DAST API testing against a production server. Not only can it perform *any* function that +the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting +data. Only run DAST API against a test server. + +### Postman Collection + +The [Postman API Client](https://www.postman.com/product/api-client/) is a popular tool that +developers and testers use to call various types of APIs. The API definitions +[can be exported as a Postman Collection file](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-postman-data) +for use with DAST API. When exporting, make sure to select a supported version of Postman +Collection: v2.0 or v2.1. + +When used with the GitLab DAST API scanner, Postman Collections must contain definitions of the web API to +test with valid data. The DAST API scanner extracts all the API definitions and uses them to perform +testing. + +WARNING: +Postman Collection files may contain sensitive information such as authentication tokens, API keys, +and session cookies. We recommend that you review the Postman Collection file contents before adding +them to a repository. + +Follow these steps to configure DAST API to use a Postman Collection file that provides +information about the target API to test: + +1. To use DAST API, you must [include](../../../ci/yaml/README.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) + that's provided as part of your GitLab installation. To do so, add the following to your + `.gitlab-ci.yml` file: + + ```yaml + stages: + - dast + + include: + - template: DAST-API.gitlab-ci.yml + ``` + +1. The [configuration file](#configuration-files) has several testing profiles defined with different checks enabled. We recommend that you start with the `Quick` profile. + Testing with this profile completes faster, allowing for easier configuration validation. + + Provide the profile by adding the `DAST_API_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, + substituting `Quick` for the profile you choose: + + ```yaml + stages: + - dast + + include: + - template: DAST-API.gitlab-ci.yml + + variables: + DAST_API_PROFILE: Quick + ``` + +1. Provide the location of the Postman Collection specification. You can provide the specification as a file or URL. Specify the location by adding the `DAST_API_POSTMAN_COLLECTION` variable: + + ```yaml + stages: + - dast + + include: + - template: DAST-API.gitlab-ci.yml + + variables: + DAST_API_PROFILE: Quick + DAST_API_POSTMAN_COLLECTION: postman-collection_serviceA.json + ``` + +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. To run DAST API against an app dynamically created during a GitLab CI/CD + pipeline, have the app persist its URL in an `environment_url.txt` file. DAST API + automatically parses that file to find its scan target. You can see an + [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). + + Here's an example of using `DAST_API_TARGET_URL`: + + ```yaml + stages: + - dast + + include: + - template: DAST-API.gitlab-ci.yml + + variables: + DAST_API_PROFILE: Quick + DAST_API_POSTMAN_COLLECTION: postman-collection_serviceA.json + DAST_API_TARGET_URL: http://test-deployment/ + ``` + +This 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). + +WARNING: +**NEVER** run DAST API testing against a production server. Not only can it perform *any* function that +the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting +data. Only run DAST API against a test server. + +#### Postman variables + +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/). +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: + + + +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: + + + +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. + +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 environment variable `DAST_API_POSTMAN_COLLECTION_VARIABLES`, then the JSON +file takes precedence to get Postman variable values. + +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`. + +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_serviceA.json + DAST_API_POSTMAN_COLLECTION_VARIABLES: variable-collection-dictionary.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' +values. For example: + + ```json + { + "base_url": "http://127.0.0.1/", + "token": "Token 84816165151" + } + ``` + +### Authentication + +Authentication is handled by providing the authentication token as a header or cookie. You can +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 +[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. + +For the password, we recommended that you [create a CI/CD variable](../../../ci/variables/README.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`: + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +variables: + DAST_API_PROFILE: Quick + 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 +``` + +#### Bearer Tokens + +Bearer tokens are used by several different authentication mechanisms, including OAuth2 and JSON Web +Tokens (JWT). Bearer tokens are transmitted using the `Authorization` HTTP header. To use bearer +tokens with DAST API, you need one of the following: + +- A token that doesn't expire +- A way to generate a token that lasts the length of testing +- A Python script that DAST API can call to generate the token + +##### Token doesn't expire + +If the bearer token doesn't expire, use the `DAST_API_OVERRIDES_ENV` variable to provide it. This +variable's content is a JSON snippet that provides headers and cookies to add to DAST API's +outgoing HTTP requests. + +Follow these steps to provide the bearer token with `DAST_API_OVERRIDES_ENV`: + +1. [Create a CI/CD variable](../../../ci/variables/README.md#custom-cicd-variables), + for example `TEST_API_BEARERAUTH`, with the value + `{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}` (substitute your token). You + can create CI/CD variables from the GitLab projects page at **Settings > CI/CD**, in the + **Variables** section. + +1. In your `.gitlab-ci.yml` file, set `DAST_API_OVERRIDES_ENV` to the variable you just created: + + ```yaml + stages: + - dast + + include: + - template: DAST-API.gitlab-ci.yml + + variables: + DAST_API_PROFILE: Quick + DAST_API_OPENAPI: test-api-specification.json + DAST_API_TARGET_URL: http://test-deployment/ + DAST_API_OVERRIDES_ENV: $TEST_API_BEARERAUTH + ``` + +1. To validate that authentication is working, run an 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 to DAST API a file containing 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: + +```json +{ + "headers" : { + "Authorization" : "Bearer dXNlcm5hbWU6cGFzc3dvcmQ=" + } +} +``` + +This file can be generated by a prior stage and provided to DAST API through the +`DAST_API_OVERRIDES_FILE` CI/CD variable. + +Set `DAST_API_OVERRIDES_FILE` in your `.gitlab-ci.yml` file: + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +variables: + DAST_API_PROFILE: Quick + DAST_API_OPENAPI: test-api-specification.json + DAST_API_TARGET_URL: http://test-deployment/ + DAST_API_OVERRIDES_FILE: output/dast-api-overrides.json +``` + +To validate that authentication is working, run an DAST API test and review the job logs and +the test API's application logs. + +##### Token has short expiration + +If the bearer token must be generated and expires prior to the scan's completion, you can provide a +program or script for the DAST API scanner to execute on a provided interval. The provided script runs in +an Alpine Linux container that has Python 3 and Bash installed. If the Python script requires +additional packages, it must detect this and install the packages at runtime. + +The script must create a JSON file containing the bearer token in a specific format: + +```json +{ + "headers" : { + "Authorization" : "Bearer dXNlcm5hbWU6cGFzc3dvcmQ=" + } +} +``` + +You must provide three CI/CD variables, each set for correct operation: + +- `DAST_API_OVERRIDES_FILE`: JSON file the provided command generates. +- `DAST_API_OVERRIDES_CMD`: Command that generates the JSON file. +- `DAST_API_OVERRIDES_INTERVAL`: Interval (in seconds) to run command. + +For example: + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +variables: + DAST_API_PROFILE: Quick + DAST_API_OPENAPI: test-api-specification.json + DAST_API_TARGET_URL: http://test-deployment/ + DAST_API_OVERRIDES_FILE: output/dast-api-overrides.json + DAST_API_OVERRIDES_CMD: renew_token.py + DAST_API_OVERRIDES_INTERVAL: 300 +``` + +To validate that authentication is working, run an DAST API test and review the job logs and +the test API's application logs. + +### Configuration files + +To get you started quickly, GitLab provides the configuration file +[`gitlab-dast-api-config.yml`](https://gitlab.com/gitlab-org/security-products/analyzers/dast/-/blob/master/config/gitlab-dast-api-config.yml). +This file has several testing profiles that perform various numbers of tests. The run time of each +profile increases as the test numbers go up. To use a configuration file, add it to your +repository's root as `.gitlab/gitlab-dast-api-config.yml`. + +#### Profiles + +The following profiles are pre-defined in the default configuration file. Profiles +can be added, removed, and modified by creating a custom configuration. + +##### Quick + +- Application Information Check +- Cleartext Authentication Check +- FrameworkDebugModeCheck +- HTML Injection Check +- Insecure Http Methods Check +- JSON Hijacking Check +- JSON Injection Check +- Sensitive Information Check +- Session Cookie Check +- SQL Injection Check +- Token Check +- XML Injection Check + +##### Full + +- Application Information Check +- Cleartext AuthenticationCheck +- CORS Check +- DNS Rebinding Check +- Framework Debug Mode Check +- HTML Injection Check +- Insecure Http Methods Check +- JSON Hijacking Check +- JSON Injection Check +- Open Redirect Check +- Sensitive File Check +- Sensitive Information Check +- Session Cookie Check +- SQL Injection Check +- TLS Configuration Check +- Token Check +- XML Injection Check + +### Available CI/CD variables + +| CI/CD variable | Description | +|------------------------------------------------------|--------------------| +| `DAST_API_VERSION` | Specify DAST API container version. Defaults to `latest`. | +| `DAST_API_TARGET_URL` | Base URL of API testing target. | +|[`DAST_API_CONFIG`](#configuration-files) | DAST API configuration file. Defaults to `.gitlab-dast-api.yml`. | +|[`DAST_API_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | +|[`DAST_API_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | +|[`DAST_API_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | +|[`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_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. | +|[`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_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. | + +### Overrides + +DAST API provides a method to add or override specific items in your request, for example: + +- Headers +- Cookies +- Query string +- Form data +- JSON nodes +- XML nodes + +You can use this to inject semantic version headers, authentication, and so on. The +[authentication section](#authentication) includes examples of using overrides for that purpose. + +Overrides use a JSON document, where each type of override is represented by a JSON object: + +```json +{ + "headers": { + "header1": "value", + "header2": "value" + }, + "cookies": { + "cookie1": "value", + "cookie2": "value" + }, + "query": { + "query-string1": "value", + "query-string2": "value" + }, + "body-form": { + "form-param1": "value", + "form-param1": "value", + }, + "body-json": { + "json-path1": "value", + "json-path2": "value", + }, + "body-xml" : { + "xpath1": "value", + "xpath2": "value", + } +} +``` + +Example of setting a single header: + +```json +{ + "headers": { + "Authorization": "Bearer dXNlcm5hbWU6cGFzc3dvcmQ=" + } +} +``` + +Example of setting both a header and cookie: + +```json +{ + "headers": { + "Authorization": "Bearer dXNlcm5hbWU6cGFzc3dvcmQ=" + }, + "cookies": { + "flags": "677" + } +} +``` + +Example usage for setting a `body-form` override: + +```json +{ + "body-form": { + "username": "john.doe" + } +} +``` + +The override engine uses `body-form` when the request body has only form-data content. + +Example usage for setting a `body-json` override: + +```json +{ + "body-json": { + "$.credentials.access-token": "iddqd!42.$" + } +} +``` + +Note that each JSON property name in the object `body-json` is set to a [JSON Path](https://goessner.net/articles/JsonPath/) +expression. The JSON Path expression `$.credentials.access-token` identifies the node to be +overridden with the value `iddqd!42.$`. The override engine uses `body-json` when the request body +has only [JSON](https://www.json.org/json-en.html) content. + +For example, if the body is set to the following JSON: + +```json +{ + "credentials" : { + "username" :"john.doe", + "access-token" : "non-valid-password" + } +} +``` + +It is changed to: + +```json +{ + "credentials" : { + "username" :"john.doe", + "access-token" : "iddqd!42.$" + } +} +``` + +Here's an example for setting a `body-xml` override. The first entry overrides an XML attribute and +the second entry overrides an XML element: + +```json +{ + "body-xml" : { + "/credentials/@isEnabled": "true", + "/credentials/access-token/text()" : "iddqd!42.$" + } +} +``` + +Note that each JSON property name in the object `body-xml` is set to an +[XPath v2](https://www.w3.org/TR/xpath20/) +expression. The XPath expression `/credentials/@isEnabled` identifies the attribute node to override +with the value `true`. The XPath expression `/credentials/access-token/text()` identifies the +element node to override with the value `iddqd!42.$`. The override engine uses `body-xml` when the +request body has only [XML](https://www.w3.org/XML/) +content. + +For example, if the body is set to the following XML: + +```xml +<credentials isEnabled="false"> + <username>john.doe</username> + <access-token>non-valid-password</access-token> +</credentials> +``` + +It is changed to: + +```xml +<credentials isEnabled="true"> + <username>john.doe</username> + <access-token>iddqd!42.$</access-token> +</credentials> +``` + +You can provide this JSON document as a file or environment variable. You may also provide a command +to generate the JSON document. The command can run at intervals to support values that expire. + +#### Using a file + +To provide the overrides JSON as a file, the `DAST_API_OVERRIDES_FILE` CI/CD variable is set. The path is relative to the job current working directory. + +Here's an example `.gitlab-ci.yml`: + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +variables: + DAST_API_PROFILE: Quick + DAST_API_OPENAPI: test-api-specification.json + DAST_API_TARGET_URL: http://test-deployment/ + DAST_API_OVERRIDES_FILE: output/dast-api-overrides.json +``` + +#### Using a CI/CD variable + +To provide the overrides JSON as a CI/CD variable, use the `DAST_API_OVERRIDES_ENV` variable. +This allows you to place the JSON as variables that can be masked and protected. + +In this example `.gitlab-ci.yml`, the `DAST_API_OVERRIDES_ENV` variable is set directly to the JSON: + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +variables: + DAST_API_PROFILE: Quick + DAST_API_OPENAPI: test-api-specification.json + DAST_API_TARGET_URL: http://test-deployment/ + DAST_API_OVERRIDES_ENV: '{"headers":{"X-API-Version":"2"}}' +``` + +In this example `.gitlab-ci.yml`, the `SECRET_OVERRIDES` variable provides the JSON. This is a +[group or instance level CI/CD variable defined in the UI](../../../ci/variables/README.md#instance-cicd-variables): + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +variables: + DAST_API_PROFILE: Quick + DAST_API_OPENAPI: test-api-specification.json + DAST_API_TARGET_URL: http://test-deployment/ + DAST_API_OVERRIDES_ENV: $SECRET_OVERRIDES +``` + +#### Using a command + +If the value must be generated or regenerated on expiration, you can provide a program or script for +the DAST API scanner to execute on a specified interval. The provided script runs in an Alpine Linux +container that has Python 3 and Bash installed. If the Python script requires additional packages, +it must detect this and install the packages at runtime. The script creates the overrides JSON file +as defined above. + +You must provide three CI/CD variables, each set for correct operation: + +- `DAST_API_OVERRIDES_FILE`: File generated by the provided command. +- `DAST_API_OVERRIDES_CMD`: Command to generate JSON file. +- `DAST_API_OVERRIDES_INTERVAL`: Interval in seconds to run command. + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +variables: + DAST_API_PROFILE: Quick + DAST_API_OPENAPI: test-api-specification.json + DAST_API_TARGET_URL: http://test-deployment/ + DAST_API_OVERRIDES_FILE: output/dast-api-overrides.json + DAST_API_OVERRIDES_CMD: renew_token.py + DAST_API_OVERRIDES_INTERVAL: 300 +``` + +## Running your first scan + +When configured correctly, a CI/CD pipeline contains a `dast` stage and an `dast_api` job. The job only fails when an invalid configuration is provided. During normal operation, the job always succeeds even if vulnerabilities are identified during testing. + +Vulnerabilities are displayed on the **Security** pipeline tab with the suite name. When testing against the repositories default branch, the DAST API vulnerabilities are also shown on the Security & Compliance's Vulnerability Report page. + +To prevent an excessive number of reported vulnerabilities, the DAST API scanner limits the number of vulnerabilities it reports per operation. + +## Viewing DAST API vulnerabilities + +The DAST API analyzer produces a JSON report that is collected and used +[to populate the vulnerabilities into GitLab vulnerability screens](#view-details-of-a-dast-api-vulnerability). + +See [handling false positives](#handling-false-positives) for information about configuration changes you can make to limit the number of false positives reported. + +### View details of a DAST API vulnerability + +Follow these steps to view details of a vulnerability: + +1. You can view vulnerabilities in a project, or a merge request: + + - In a project, go to the project's **{shield}** **Security & Compliance > Vulnerability Report** + page. This page shows all vulnerabilities from the default branch only. + - In a merge request, go the merge request's **Security** section and click the **Expand** + button. DAST API vulnerabilities are available in a section labeled + **DAST detected N potential vulnerabilities**. Click the title to display the vulnerability + details. + +1. Click the vulnerabilities title to display the details. The table below describes these details. + + | Field | Description | + |:--------------------|:----------------------------------------------------------------------------------------| + | Description | Description of the vulnerability including what was modified. | + | Project | Namespace and project in which the vulnerability was detected. | + | Method | HTTP method used to detect the vulnerability. | + | URL | URL at which the vulnerability was detected. | + | Request | The HTTP request that caused the vulnerability. | + | Unmodified Response | Response from an unmodified request. This is what a normal working response looks like. | + | Actual Response | Response received from test request. | + | Evidence | How we determined a vulnerability occurred. | + | Identifiers | The DAST API check used to find this vulnerability. | + | Severity | Severity of the vulnerability. | + | Scanner Type | Scanner used to perform testing. | + +### Security Dashboard + +The Security Dashboard is a good place to get an overview of all the security vulnerabilities in your groups, projects and +pipelines. For more information, see the [Security Dashboard documentation](../security_dashboard/index.md). + +### Interacting with the vulnerabilities + +Once a vulnerability is found, you can interact with it. Read more on how to +[address the vulnerabilities](../vulnerabilities/index.md). + +## Handling False Positives + +False positives can be handled in several ways: + +- Dismiss the vulnerability. +- Some checks have several methods of detecting when a vulnerability is identified, called _Assertions_. + Assertions can also be turned off and configured. For example, the DAST API scanner by default uses HTTP + status codes to help identify when something is a real issue. If an API returns a 500 error during + testing, this creates a vulnerability. This isn't always desired, as some frameworks return 500 errors often. +- Turn off the Check producing the false positive. This prevents the check from generating any + vulnerabilities. Example checks are the SQL Injection Check, and JSON Hijacking Check. + +### Turn off a Check + +Checks perform testing of a specific type and can be turned on and off for specific configuration +profiles. The provided [configuration files](#configuration-files) define several profiles that you +can use. The profile definition in the configuration file lists all the checks that are active +during a scan. To turn off a specific check, remove it from the profile definition in the +configuration file. The profiles are defined in the `Profiles` section of the configuration file. + +Example profile definition: + +```yaml +Profiles: + - Name: Quick + DefaultProfile: Empty + Routes: + - Route: *Route0 + Checks: + - Name: ApplicationInformationCheck + - Name: CleartextAuthenticationCheck + - Name: FrameworkDebugModeCheck + - Name: HtmlInjectionCheck + - Name: InsecureHttpMethodsCheck + - Name: JsonHijackingCheck + - Name: JsonInjectionCheck + - Name: SensitiveInformationCheck + - Name: SessionCookieCheck + - Name: SqlInjectionCheck + - Name: TokenCheck + - Name: XmlInjectionCheck +``` + +To turn off the JSON Hijacking Check you can remove these lines: + +```yaml + - Name: JsonHijackingCheck +``` + +This results in the following YAML: + +```yaml +- Name: Quick + DefaultProfile: Empty + Routes: + - Route: *Route0 + Checks: + - Name: ApplicationInformationCheck + - Name: CleartextAuthenticationCheck + - Name: FrameworkDebugModeCheck + - Name: HtmlInjectionCheck + - Name: InsecureHttpMethodsCheck + - Name: JsonInjectionCheck + - Name: SensitiveInformationCheck + - Name: SessionCookieCheck + - Name: SqlInjectionCheck + - Name: TokenCheck + - Name: XmlInjectionCheck +``` + +### Turn off an Assertion for a Check + +Assertions detect vulnerabilities in tests produced by checks. Many checks support multiple Assertions such as Log Analysis, Response Analysis, and Status Code. When a vulnerability is found, the Assertion used is provided. To identify which Assertions are on by default, see the Checks default configuration in the configuration file. The section is called `Checks`. + +This example shows the SQL Injection Check: + +```yaml +- Name: SqlInjectionCheck + Configuration: + UserInjections: [] + Assertions: + - Name: LogAnalysisAssertion + - Name: ResponseAnalysisAssertion + - Name: StatusCodeAssertion +``` + +Here you can see three Assertions are on by default. A common source of false positives is +`StatusCodeAssertion`. To turn it off, modify its configuration in the `Profiles` section. This +example provides only the other two Assertions (`LogAnalysisAssertion`, +`ResponseAnalysisAssertion`). This prevents `SqlInjectionCheck` from using `StatusCodeAssertion`: + +```yaml +Profiles: + - Name: Quick + DefaultProfile: Empty + Routes: + - Route: *Route0 + Checks: + - Name: ApplicationInformationCheck + - Name: CleartextAuthenticationCheck + - Name: FrameworkDebugModeCheck + - Name: HtmlInjectionCheck + - Name: InsecureHttpMethodsCheck + - Name: JsonHijackingCheck + - Name: JsonInjectionCheck + - Name: SensitiveInformationCheck + - Name: SessionCookieCheck + - Name: SqlInjectionCheck + Assertions: + - Name: LogAnalysisAssertion + - Name: ResponseAnalysisAssertion + - Name: TokenCheck + - Name: XmlInjectionCheck +``` + +## Troubleshooting + +### Failed to start scanner session (version header not found) + +The DAST API engine outputs an error message when it cannot establish a connection with the scanner application component. The error message is shown in the job output window of the `dast_api` job. A common cause of this issue is changing the `DAST_API_API` variable from its default. + +**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?`. + +**Solution** + +- Remove the `DAST_API_API` variable from the `.gitlab-ci.yml` file. The value will be inherited from the DAST API CI/CD template. We recommend this method instead of manually setting a value. +- If removing the variable is not possible, check to see if this value has changed in the latest version of the [DAST API CI/CD template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml). If so, update the value in the `.gitlab-ci.yml` file. + +### Application cannot determine the base URL for the target API + +The DAST API engine outputs an error message when it cannot determine the target API after inspecting the OpenAPI document. This error message is shown when the target API has not been set in the `.gitlab-ci.yml` file, it is not available in the `environment_url.txt` file, and it could not be computed using the OpenAPI document. + +There is a order of precedence in which the DAST API engine tries to get the target API when checking the different sources. First, it will try to use the `DAST_API_TARGET_URL`. If the environment variable has not been set, then the DAST API engine will attempt to use the `environment_url.txt` file. If there is no file `environment_url.txt`, then the DAST API engine will use the OpenAPI document contents and the URL provided in `DAST_API_OPENAPI` (if a URL is provided) to try to compute the target API. + +The best-suited solution will depend on whether or not your target API changes for each deployment. In static environments, the target API is the same for each deployment, in this case please refer to the [static environment solution](#static-environment-solution). If the target API changes for each deployment a [dynamic environment solution](#dynamic-environment-solutions) should be applied. + +#### Static environment solution + +This solution is for pipelines in which the target API URL doesn't change (is static). + +**Add environmental variable** + +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 +include: + - template: DAST-API.gitlab-ci.yml + + variables: + DAST_API_TARGET_URL: http://test-deployment/ + DAST_API_OPENAPI: test-api-specification.json +``` + +#### Dynamic environment solutions + +In a dynamic environment your target API changes for each different deployment. In this case, there is more than one possible solution, we recommend you use the `environment_url.txt` file when dealing with dynamic environments. + +**Use environment_url.txt** + +To support dynamic environments in which the target API URL changes during each pipeline, DAST API engine supports the use of an `environment_url.txt` file that contains the URL to use. This file is not checked into the repository, instead it's created during the pipeline by the job that deploys the test target and collected as an artifact that can be used by later jobs in the pipeline. The job that creates the `environment_url.txt` file must run before the DAST API engine job. + +1. Modify the test target deployment job adding the base URL in an `environment_url.txt` file at the root of your project. +1. Modify the test target deployment job collecting the `environment_url.txt` as an artifact. + +Example: + +```yaml +deploy-test-target: + script: + # Perform deployment steps + # Create environment_url.txt (example) + - echo http://${CI_PROJECT_ID}-${CI_ENVIRONMENT_SLUG}.example.org > environment_url.txt + + artifacts: + paths: + - environment_url.txt +``` + +## Glossary + +- Assert: Assertions are detection modules used by checks to trigger a vulnerability. Many assertions have + configurations. A check can use multiple Assertions. For example, Log Analysis, Response Analysis, + and Status Code are common Assertions used together by checks. Checks with multiple Assertions + allow them to be turned on and off. +- Check: Performs a specific type of test, or performed a check for a type of vulnerability. For + example, the SQL Injection Check performs DAST testing for SQL Injection vulnerabilities. The DAST API scanner is comprised of several checks. Checks can be turned on and off in a profile. +- Profile: A configuration file has one or more testing profiles, or sub-configurations. You may + have a profile for feature branches and another with extra testing for a main branch. diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 25b7615a8ae..fcefba943ad 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -10,10 +10,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10075) in GitLab Ultimate 12.0. Use the dependency list to review your project's dependencies and key -details about those dependencies, including their known vulnerabilities. To see the dependency list, -in your project, go to **Security & Compliance > Dependency List**. +details about those dependencies, including their known vulnerabilities. It is a collection of dependencies in your project, including existing and new findings. To see the dependency list, go to your project and select **Security & Compliance > Dependency List**. This information is sometimes referred to as a Software Bill of Materials or SBoM / BOM. +The dependency list only shows the results of the last successful pipeline to run on the default branch. This is why we recommend not changing the default behavior of allowing the secure jobs to fail. + ## Prerequisites To view your project's dependencies, ensure you meet the following requirements: diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index 53d91bfcd78..0faa33e0123 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -56,10 +56,10 @@ variables: This configuration requires that your custom registry provides images for all the official analyzers. -### Selecting specific analyzers +### Disable specific analyzers -You can select the official analyzers you want to run. Here's how to enable -`bundler-audit` and `gemnasium` while disabling all the other default ones. +You can select the official analyzers you don't want to run. Here's how to disable +`bundler-audit` and `gemnasium` analyzers. In `.gitlab-ci.yml` define: ```yaml @@ -67,26 +67,23 @@ include: template: Dependency-Scanning.gitlab-ci.yml variables: - DS_DEFAULT_ANALYZERS: "bundler-audit,gemnasium" + DS_EXCLUDED_ANALYZERS: "bundler-audit, gemnasium" ``` -`bundler-audit` runs first. When merging the reports, Dependency Scanning -removes the duplicates and keeps the `bundler-audit` entries. - ### Disabling default analyzers -Setting `DS_DEFAULT_ANALYZERS` to an empty string disables all the official -default analyzers. In `.gitlab-ci.yml` define: +Setting `DS_EXCLUDED_ANALYZERS` to a list of the official analyzers disables them. +In `.gitlab-ci.yml` define: ```yaml include: template: Dependency-Scanning.gitlab-ci.yml variables: - DS_DEFAULT_ANALYZERS: "" + DS_EXCLUDED_ANALYZERS: "gemnasium, gemansium-maven, gemnasium-python, bundler-audit, retire.js" ``` -That's needed when one totally relies on [custom analyzers](#custom-analyzers). +This is used when one totally relies on [custom analyzers](#custom-analyzers). ## Custom analyzers diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 53387acefef..8e23db89dfd 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -77,6 +77,7 @@ The following languages and dependency managers are supported: 1. Support for [sbt](https://www.scala-sbt.org/) 1.3 and above was added in GitLab 13.9. Plans are underway for supporting the following languages, dependency managers, and dependency files. For details, see the issue link for each. +For workarounds, see the [Troubleshooting section](#troubleshooting) | Package Managers | Languages | Supported files | Scan tools | Issue | | ------------------- | --------- | --------------- | ---------- | ----- | @@ -129,7 +130,7 @@ configuration, the last mention of the variable takes precedence. ### Overriding dependency scanning jobs WARNING: -Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) +Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#only--except) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. To override a job definition (for example, to change properties like `variables` or `dependencies`), @@ -168,7 +169,8 @@ The following variables allow configuration of global dependency scanning settin | CI/CD variables | Description | | ----------------------------|------------ | | `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. The bundle of certificates provided here is also used by other tools during the scanning process, such as `git`, `yarn`, or `npm`. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. | -| `DS_DEFAULT_ANALYZERS` | Override the names of the official default images. Read more about [customizing analyzers](analyzers.md). | +| `DS_EXCLUDED_ANALYZERS` | Specify the analyzers (by name) to exclude from Dependency Scanning. For more information, see [Dependency Scanning Analyzers](analyzers.md). | +| `DS_DEFAULT_ANALYZERS` | ([**DEPRECATED - use `DS_EXCLUDED_ANALYZERS` instead**](https://gitlab.com/gitlab-org/gitlab/-/issues/287691)) Override the names of the official default images. For more information, see [Dependency Scanning Analyzers](analyzers.md). | | `DS_EXCLUDED_PATHS` | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"`. | | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). | | `SECURE_LOG_LEVEL` | 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. Default: `info`. | @@ -227,13 +229,13 @@ Read more on [how to use private Maven repositories](../index.md#using-private-m ## Interacting with the vulnerabilities Once a vulnerability is found, you can interact with it. Read more on how to -[address the vulnerabilities](../index.md#addressing-vulnerabilities). +[address the vulnerabilities](../vulnerabilities/index.md). ## Solutions for vulnerabilities (auto-remediation) Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. Read more about the -[solutions for vulnerabilities](../index.md#apply-an-automatic-remediation-for-a-vulnerability). +[solutions for vulnerabilities](../vulnerabilities/index.md#remediate-a-vulnerability-automatically). ## Security Dashboard @@ -243,8 +245,8 @@ vulnerabilities in your groups, projects and pipelines. Read more about the ## Vulnerabilities database update -For more information about the vulnerabilities database update, check the -[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database). +For more information about the vulnerabilities database update, see the +[maintenance table](../vulnerabilities/index.md#vulnerability-scanner-maintenance). ## Dependency List @@ -420,8 +422,8 @@ registry.gitlab.com/gitlab-org/security-products/analyzers/bundler-audit:2 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. -Note that these scanners are [updated periodically](../index.md#maintenance-and-update-of-the-vulnerabilities-database) -with new definitions, so consider if you can make periodic updates yourself. +These scanners are [periodically updated](../vulnerabilities/index.md#vulnerability-scanner-maintenance) +with new definitions, and you may be able to make occasional updates on your own. 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/), @@ -508,7 +510,7 @@ ensure that it can reach your private repository. Here is an example configurati ## Hosting a copy of the gemnasium_db advisory database -The [gemnasium_db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) Git repository is +The [`gemnasium_db`](https://gitlab.com/gitlab-org/security-products/gemnasium-db) Git repository is used by `gemnasium`, `gemnasium-maven`, and `gemnasium-python` as the source of vulnerability data. This repository updates at scan time to fetch the latest advisories. However, due to a restricted networking environment, running this update is sometimes not possible. In this case, a user can do @@ -563,11 +565,58 @@ such references: ERROR: Could not find dependencies: <dependency-name>. You may need to run npm install ``` -As a workaround, remove the [`retire.js`](analyzers.md#selecting-specific-analyzers) analyzer from -[DS_DEFAULT_ANALYZERS](#configuring-dependency-scanning). +As a workaround, add the [`retire.js`](analyzers.md) analyzer to +[`DS_EXCLUDED_ANALYZERS`](#configuring-dependency-scanning). ## Troubleshooting +### Working around missing support for certain languages or package managers + +As noted in the ["Supported languages" section](#supported-languages-and-package-managers) +some dependency definition files are not yet supported. +However, Dependency Scanning can be achieved if +the language, a package manager, or a third-party tool +can convert the definition file +into a supported format. + +Generally, the approach is the following: + +1. Define a dedicated converter job in your `.gitlab-ci.yml` file. + Use a suitable Docker image, script, or both to facilitate the conversion. +1. Let that job upload the converted, supported file as an artifact. +1. Add [`dependencies: [<your-converter-job>]`](../../../ci/yaml/README.md#dependencies) + to your `dependency_scanning` job to make use of the converted definitions files. + +For example, the currently unsupported `poetry.lock` file can be +[converted](https://python-poetry.org/docs/cli/#export) +to the supported `requirements.txt` as follows. + +```yaml +include: + - template: Dependency-Scanning.gitlab-ci.yml + +stages: + - .pre + - test + +variables: + PIP_REQUIREMENTS_FILE: "requirements-converted.txt" + +convert-poetry: + stage: .pre + image: python:3-slim + script: + - pip install poetry # Or via another method: https://python-poetry.org/docs/#installation + - poetry export --output "$PIP_REQUIREMENTS_FILE" + artifacts: + paths: + - "$PIP_REQUIREMENTS_FILE" + +dependency_scanning: + stage: test + dependencies: ["convert-poetry"] +``` + ### `Error response from daemon: error processing tar file: docker-tar: relocation error` This error occurs when the Docker version that runs the dependency scanning job is `19.03.0`. diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 1ba2161362c..82a018c0ae9 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -7,9 +7,16 @@ type: reference, howto # Application security **(ULTIMATE)** -GitLab can check your application for security vulnerabilities that may lead to unauthorized access, -data leaks, denial of services, and more. GitLab reports vulnerabilities in the merge request so you -can fix them before you merge. +GitLab can check your application for security vulnerabilities including: + +- Unauthorized access. +- Data leaks. +- Denial of service attacks. + +Statistics and details on vulnerabilities are included in the merge request. Providing +actionable information _before_ changes are merged enables you to be proactive. + +GitLab also provides high-level statistics of vulnerabilities across projects and groups: - The [Security Dashboard](security_dashboard/index.md) provides a high-level view of vulnerabilities detected in your projects, pipeline, and groups. @@ -18,50 +25,7 @@ can fix them before you merge. you can immediately begin risk analysis and remediation. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview of GitLab application security, see -[Security Deep Dive](https://www.youtube.com/watch?v=k4vEJnGYy84). - -## Quick start - -Get started quickly with Dependency Scanning, License Scanning, Static Application Security -Testing (SAST), and Secret Detection by adding the following to your [`.gitlab-ci.yml`](../../ci/yaml/README.md): - -```yaml -include: - - template: Security/Dependency-Scanning.gitlab-ci.yml - - template: Security/License-Scanning.gitlab-ci.yml - - template: Security/SAST.gitlab-ci.yml - - template: Security/Secret-Detection.gitlab-ci.yml -``` - -To add Dynamic Application Security Testing (DAST) scanning, add the following to your -`.gitlab-ci.yml` and replace `https://staging.example.com` with a staging server's web address: - -```yaml -include: - - template: Security/DAST.gitlab-ci.yml - -variables: - DAST_WEBSITE: https://staging.example.com -``` - -To ensure the DAST scanner runs *after* deploying the application to the staging server, review the [DAST full documentation](dast/index.md). - -To add Container Scanning, follow the steps listed in the [Container Scanning documentation](container_scanning/index.md#requirements). - -To further configure any of the other scanners, refer to each scanner's documentation. - -### SAST configuration - -You can set up and configure Static Application Security Testing -(SAST) for your project, without opening a text editor. For more details, -see [configure SAST in the UI](sast/index.md#configure-sast-in-the-ui). - -### Override the default registry base address - -By default, GitLab security scanners use `registry.gitlab.com/gitlab-org/security-products/analyzers` as the -base address for Docker images. You can override this globally by setting the CI/CD variable -`SECURE_ANALYZERS_PREFIX` to another location. Note that this affects all scanners at once. +For an overview of GitLab application security, see [Shifting Security Left](https://www.youtube.com/watch?v=XnYstHObqlA&t). ## Security scanning tools @@ -73,29 +37,17 @@ GitLab uses the following tools to scan and report known vulnerabilities found i | [Dependency List](dependency_list/index.md) **(ULTIMATE)** | View your project's dependencies and their known vulnerabilities. | | [Dependency Scanning](dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | | [Dynamic Application Security Testing (DAST)](dast/index.md) **(ULTIMATE)** | Analyze running web applications for known vulnerabilities. | +| [DAST API](dast_api/index.md) **(ULTIMATE)** | Analyze running web APIs for known vulnerabilities. | | [API fuzzing](api_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities in web APIs with fuzzing. | | [Secret Detection](secret_detection/index.md) | Analyze Git history for leaked secrets. | | [Security Dashboard](security_dashboard/index.md) **(ULTIMATE)** | View vulnerabilities in all your projects and groups. | | [Static Application Security Testing (SAST)](sast/index.md) | Analyze source code for known vulnerabilities. | | [Coverage fuzzing](coverage_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities with coverage-guided fuzzing. | -### Use security scanning tools with Pipelines for Merge Requests - -The security scanning tools can all be added to pipelines with [templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Security). -See each tool for details on how to use include each template in your CI/CD configuration. - -By default, the application security jobs are configured to run for branch pipelines only. -To use them with [pipelines for merge requests](../../ci/merge_request_pipelines/index.md), -you may need to override the default `rules:` configuration to add: - -```yaml -rules: - - if: $CI_PIPELINE_SOURCE == "merge_request_event" -``` +## Security scanning with Auto DevOps -## Security Scanning with Auto DevOps - -When [Auto DevOps](../../topics/autodevops/) is enabled, all GitLab Security scanning tools are configured using default settings. +To enable all GitLab Security scanning tools, with default settings, enable +[Auto DevOps](../../topics/autodevops/): - [Auto SAST](../../topics/autodevops/stages.md#auto-sast) - [Auto Secret Detection](../../topics/autodevops/stages.md#auto-secret-detection) @@ -106,170 +58,125 @@ When [Auto DevOps](../../topics/autodevops/) is enabled, all GitLab Security sca While you cannot directly customize Auto DevOps, you can [include the Auto DevOps template in your project's `.gitlab-ci.yml` file](../../topics/autodevops/customize.md#customizing-gitlab-ciyml). -## Maintenance and update of the vulnerabilities database - -The scanning tools and vulnerabilities database are updated regularly. +## Security scanning without Auto DevOps -| Secure scanning tool | Vulnerabilities database updates | -|:-------------------------------------------------------------|-------------------------------------------| -| [Container Scanning](container_scanning/index.md) | Uses `clair`. The latest `clair-db` version is used for each job by running the [`latest` Docker image tag](https://gitlab.com/gitlab-org/gitlab/blob/438a0a56dc0882f22bdd82e700554525f552d91b/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L37). The `clair-db` database [is updated daily according to the author](https://github.com/arminc/clair-local-scan#clair-server-or-local). | -| [Dependency Scanning](dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for npm packages), and `gemnasium` (the GitLab tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated at least once a week. See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | -| [Dynamic Application Security Testing (DAST)](dast/index.md) | The scanning engine is updated on a periodic basis. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/master/Dockerfile#L1). The scanning rules are downloaded at scan runtime. | -| [Static Application Security Testing (SAST)](sast/index.md) | Relies exclusively on [the tools GitLab wraps](sast/index.md#supported-languages-and-frameworks). The underlying analyzers are updated at least once per month if a relevant update is available. The vulnerabilities database is updated by the upstream tools. | +To enable all GitLab security scanning tools, with the option of customizing settings, add the +GitLab CI/CD templates to your `.gitlab-ci.yml` file. -Currently, you do not have to update GitLab to benefit from the latest vulnerabilities definitions. -The security tools are released as Docker images. The vendored job definitions that enable them use -major release tags according to [Semantic Versioning](https://semver.org/). Each new release of the -tools overrides these tags. -The Docker images are updated to match the previous GitLab releases, so users automatically get the -latest versions of the scanning tools without having to do anything. There are some known issues -with this approach, however, and there is a -[plan to resolve them](https://gitlab.com/gitlab-org/gitlab/-/issues/9725). - -## View security scan information in merge requests **(FREE)** +To enable Static Application Security Testing, Dependency Scanning, License Scanning, and Secret +Detection, add: -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4393) in GitLab Free 13.5. -> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/273205) in 13.6. -> - Report download dropdown [added](https://gitlab.com/gitlab-org/gitlab/-/issues/273418) in 13.7. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/249550) in GitLab 13.9. - -Merge requests which have run security scans let you know that the generated -reports are available to download. To download a report, click on the -**Download results** dropdown, and select the desired report. - - - -## View details of a DAST vulnerability - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. +```yaml +include: + - template: Security/Dependency-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml + - template: Security/Secret-Detection.gitlab-ci.yml +``` -Vulnerabilities detected by DAST occur in the live web application. Rectification of these types of -vulnerabilities requires specific information. DAST provides the information required to -investigate and rectify the underlying cause. +To enable Dynamic Application Security Testing (DAST) scanning, add the following to your +`.gitlab-ci.yml`. Replace `https://staging.example.com` with a staging server's web address: -To view details of DAST vulnerabilities: +```yaml +include: + - template: Security/DAST.gitlab-ci.yml -1. To see all vulnerabilities detected: - - In a project, go to the project's **{shield}** **Security & Compliance** page. - - Only in a merge request, go the merge request's **Security** tab. +variables: + DAST_WEBSITE: https://staging.example.com +``` -1. Select the vulnerability's description. The following details are provided: +For more details about each of the security scanning tools, see their respective +[documentation sections](#security-scanning-tools). -| Field | Description | -|:-----------------|:------------------------------------------------------------------ | -| Description | Description of the vulnerability. | -| Project | Namespace and project in which the vulnerability was detected. | -| Method | HTTP method used to detect the vulnerability. | -| URL | URL at which the vulnerability was detected. | -| Request Headers | Headers of the request. | -| Response Status | Response status received from the application. | -| Response Headers | Headers of the response received from the application. | -| Evidence | Evidence of the data found that verified the vulnerability. Often a snippet of the request or response, this can be used to help verify that the finding is a vulnerability. | -| Identifiers | Identifiers of the vulnerability. | -| Severity | Severity of the vulnerability. | -| Scanner Type | Type of vulnerability report. | -| Links | Links to further details of the detected vulnerability. | -| Solution | Details of a recommended solution to the vulnerability (optional). | +### Override the default registry base address -### Hide sensitive information in headers +By default, GitLab security scanners use `registry.gitlab.com/gitlab-org/security-products/analyzers` as the +base address for Docker images. You can override this globally by setting the CI/CD variable +`SECURE_ANALYZERS_PREFIX` to another location. Note that this affects all scanners at once. -HTTP request and response headers may contain sensitive information, including cookies and -authorization credentials. By default, content of specific headers are masked in DAST vulnerability -reports. You can specify the list of all headers to be masked. For details, see -[Hide sensitive information](dast/index.md#hide-sensitive-information). +### Use security scanning tools with Pipelines for Merge Requests -## Addressing vulnerabilities +By default, the application security jobs are configured to run for branch pipelines only. +To use them with [pipelines for merge requests](../../ci/merge_request_pipelines/index.md), +you may need to override the default `rules:` configuration to add: -> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.8. +```yaml +rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" +``` -For each security vulnerability in a merge request or [Vulnerability Report](vulnerability_report/index.md), -you can: +## Default behavior of GitLab security scanning tools -- [Dismiss the vulnerability](#dismiss-a-vulnerability). -- Create a [confidential](../project/issues/confidential_issues.md) - [issue](vulnerabilities/index.md#create-a-gitlab-issue-for-a-vulnerability). -- Apply an [automatically remediation](#apply-an-automatic-remediation-for-a-vulnerability). +### Secure jobs in your pipeline -### Dismiss a vulnerability +If you add the security scanning jobs as described in [Security scanning with Auto DevOps](#security-scanning-with-auto-devops) or [Security scanning without Auto DevOps](#security-scanning-without-auto-devops) to your `.gitlab-ci.yml` each added [security scanning tool](#security-scanning-tools) behave as described below. -> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0, a dismissal reason. +For each compatible analyzer, a job is created in the `test`, `dast` or `fuzz` stage of your pipeline and runs on the next new branch pipeline. Features such as the [Security Dashboard](security_dashboard/index.md), [Vulnerability Report](vulnerability_report/index.md), and [Dependency List](dependency_list/index.md) that rely on this scan data only show results from pipelines on the default branch. Please note that one tool may use many analyzers. -You can dismiss a vulnerability for the entire project. +Our language and package manager specific jobs attempt to assess which analyzer(s) they should run for your project so that you can do less configuration. -1. Select the vulnerability in the Security Dashboard. -1. In the top-right, from the **Status** selector menu, select **Dismissed**. -1. Optional. Add a reason for the dismissal and select **Save comment**. +If you want to override this to increase the pipeline speed you may choose which analyzers to exclude if you know they are not applicable (languages or package managers not contained in your project) by following variable customization directions for that specific tool. -To undo this action, select a different status from the same menu. +### Secure job status -#### Dismiss multiple vulnerabilities +Jobs pass if they are able to complete a scan. A _pass_ result does NOT indicate if they did, or did not, identify findings. The only exception is coverage fuzzing, which fails if it identifies findings. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35816) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. +Jobs fail if they are unable to complete a scan. You can view the pipeline logs for more information. -You can dismiss multiple vulnerabilities at once. +All jobs are permitted to fail by default. This means that if they fail it do not fail the pipeline. -1. In the list of vulnerabilities, select the checkbox for each vulnerability you want to dismiss. - To select all, select the checkbox in the table header. -1. Above the table, select a dismissal reason. -1. Select **Dismiss Selected**. +If you want to prevent vulnerabilities from being merged, you should do this by adding [Security Approvals in Merge Requests](#security-approvals-in-merge-requests) which prevents unknown, high or critical findings from being merged without an approval from a specific group of people that you choose. -### Create an issue for a vulnerability +We do not recommend changing the job [`allow_failure` setting](../../ci/yaml/README.md#allow_failure) as that fails the entire pipeline. -You can create a GitLab or Jira issue for a vulnerability. For details, see [Vulnerability Pages](vulnerabilities/index.md). +### JSON Artifact -#### Link to an existing issue +The artifact generated by the secure analyzer contains all findings it discovers on the target branch, regardless of whether they were previously found, dismissed, or completely new (it puts in everything that it finds). -If you already have an open issue, you can link to it from the vulnerability. +## View security scan information in merge requests **(FREE)** -- The vulnerability page shows related issues, but the issue page doesn't show the vulnerability it's related to. -- An issue can only be related to one vulnerability at a time. -- Issues can be linked across groups and projects. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4393) in GitLab Free 13.5. +> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/273205) in 13.6. +> - Report download dropdown [added](https://gitlab.com/gitlab-org/gitlab/-/issues/273418) in 13.7. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/249550) in GitLab 13.9. -To link to an existing issue: +### All tiers -1. Open the vulnerability. -1. [Add a linked issue](../project/issues/related_issues.md). +Merge requests which have run security scans let you know that the generated +reports are available to download. To download a report, click on the +**Download results** dropdown, and select the desired report. -### Apply an automatic remediation for a vulnerability + -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5656) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.7. +### Ultimate -Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. -The following scanners are supported: +A merge request contains a security widget which displays a summary of the NEW results. New results are determined by comparing the current findings against existing findings in the target (default) branch (if there are prior findings). -- [Dependency Scanning](dependency_scanning/index.md). - Automatic Patch creation is only available for Node.js projects managed with - `yarn`. -- [Container Scanning](container_scanning/index.md). +We recommended you run a scan of the `default` branch before enabling feature branch scans for your developers. Otherwise, there is no base for comparison and all feature branches display the full scan results in the merge request security widget. -#### Manually apply the suggested patch +The merge request security widget displays only a subset of the vulnerabilities in the generated JSON artifact because it contains both NEW and EXISTING findings. -To manually apply the patch that GitLab generated for a vulnerability: +From the merge request security widget, select **Expand** to unfold the widget, displaying any new and no longer detected (removed) findings by scan type. Select **View Full Report** to go directly to the **Security** tab in the latest branch pipeline. -1. Select the **Resolve with merge request** dropdown, then select **Download patch to resolve**: +## View security scan information in the pipeline Security tab -  +A pipeline's security tab lists all findings in the current branch. It includes new findings introduced by this branch and existing vulnerabilities that were already present when the branch was created. These results likely do not match the findings displayed in the Merge Request security widget as those do not include the existing vulnerabilities (with the exception of showing any existing vulnerabilities that are no longer detected in the feature branch). -1. Ensure your local project has the same commit checked out that was used to generate the patch. -1. Run `git apply remediation.patch`. -1. Verify and commit the changes to your branch. +For more details, see [security tab](security_dashboard/index.md#pipeline-security). -#### Create a merge request with the suggested patch +## View security scan information in the Security Dashboard -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9224) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. +The Security Dashboard show vulnerabilities present in a project's default branch. Data is updated every 24 hours. Vulnerability count updates resulting from any feature branches introducing new vulnerabilities that are merged to default are included after the daily data refresh. -In some cases, you can create a merge request that automatically remediates the -vulnerability. Any vulnerability that has a -[solution](#apply-an-automatic-remediation-for-a-vulnerability) can have a merge -request created to automatically solve the issue. +For more details, see [Security Dashboard](security_dashboard/index.md). -If this action is available: +## View security scan information in the Vulnerability Report -1. Select the **Resolve with merge request** dropdown, then select **Resolve with merge request**. +The vulnerability report shows the results of the last completed pipeline on the default branch. It is updated on every pipeline completion. All detected vulnerabilities are shown as well as any previous ones that are no longer detected in the latest scan. Vulnerabilities that are no longer detected may have been remediated or otherwise removed and can be marked as `Resolved` after proper verification. Vulnerabilities that are no longer detected are denoted with an icon for filtering and review. -  +By default, the vulnerability report does not show vulnerabilities of `dismissed` or `resolved` status so you can focus on open vulnerabilities. You can change the Status filter to see these. -A merge request is created. It that applies the solution to the source branch. +[Read more about the Vulnerability report](vulnerability_report/index.md). ## Security approvals in merge requests @@ -297,7 +204,7 @@ rating. ### Enabling Security Approvals within a project -To enable the `Vulnerability-Check` or `License-Check` Security Approvals, a [project approval rule](../project/merge_requests/merge_request_approvals.md#adding--editing-a-default-approval-rule) +To enable the `Vulnerability-Check` or `License-Check` Security Approvals, a [project approval rule](../project/merge_requests/approvals/rules.md#add-an-approval-rule) must be created. A [security scanner job](#security-scanning-tools) must be enabled for `Vulnerability-Check`, and a [license scanning](../compliance/license_compliance/index.md#configuration) job must be enabled for `License-Check`. When the proper jobs aren't configured, the following @@ -412,6 +319,70 @@ You can do it quickly by following the hyperlink given to run a new pipeline.  +## DAST On-Demand Scans + +If you don’t want scans running in your normal DevOps process you can use on-demand scans instead. For more details, see [on-demand scans](dast/index.md#on-demand-scans). This feature is only available for DAST. If you run an on-demand scan against the default branch, it is reported as a "successful pipeline" and these results are included in the security dashboard and vulnerability report. + +## Security report validation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321918) in GitLab 13.11. + +As of GitLab 13.11, we've introduced the **optional** validation of the security report artifacts based on the +[report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/tree/master/dist). +If you enable validation, GitLab validates the report artifacts before ingesting the vulnerabilities. +This prevents ingesting broken vulnerability data into the database. + +### Enable security report validation + +To enable report artifacts validation, set the `VALIDATE_SCHEMA` environment variable to `"true"` for the jobs in the `.gitlab-ci.yml` file. + +For example, the configuration below enables validation for only the `sast` job: + + ```yaml + include: + - template: Security/Dependency-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml + - template: Security/Secret-Detection.gitlab-ci.yml + + stages: + - security-scan + + dependency_scanning: + stage: security-scan + + license_scanning: + stage: security-scan + + sast: + stage: security-scan + variables: + VALIDATE_SCHEMA: "true" + + .secret-analyzer: + stage: security-scan + ``` + +## Interacting with findings and vulnerabilities + +There are a variety of locations and ways to interact with the results of the security scanning tools: + +- [Scan information in merge requests](#view-security-scan-information-in-merge-requests) +- [Project Security Dashboard](security_dashboard/#project-security-dashboard) +- [Security pipeline tab](security_dashboard/#pipeline-security) +- [Group Security Dashboard](security_dashboard/#group-security-dashboard) +- [Security Center](security_dashboard/#security-center) +- [Vulnerability Report](vulnerability_report/index.md) +- [Vulnerability Pages](vulnerabilities/index.md) +- [Dependency List](dependency_list/index.md) + +For more details about which findings or vulnerabilities you can view in each of those locations, select the respective link. Each page details the ways in which you can interact with the findings and vulnerabilities. As an example, in most cases findings start out as _detected_ status. You have the option to: + +- Change the status. +- Create an issue. +- Link it to an existing issue. +- In some cases, [apply an automatic remediation for a vulnerability](vulnerabilities/index.md#remediate-a-vulnerability-automatically). + ## Troubleshooting ### Getting error message `sast job: stage parameter should be [some stage name here]` @@ -480,7 +451,7 @@ Found errors in your .gitlab-ci.yml: ``` This error appears when the included job's `rules` configuration has been [overridden](sast/index.md#overriding-sast-jobs) -with [the deprecated `only` or `except` syntax.](../../ci/yaml/README.md#onlyexcept-basic) +with [the deprecated `only` or `except` syntax.](../../ci/yaml/README.md#only--except) To fix this issue, you must either: - [Transition your `only/except` syntax to `rules`](#transitioning-your-onlyexcept-syntax-to-rules). @@ -491,7 +462,7 @@ To fix this issue, you must either: #### Transitioning your `only/except` syntax to `rules` When overriding the template to control job execution, previous instances of -[`only` or `except`](../../ci/yaml/README.md#onlyexcept-basic) are no longer compatible +[`only` or `except`](../../ci/yaml/README.md#only--except) are no longer compatible and must be transitioned to [the `rules` syntax](../../ci/yaml/README.md#rules). If your override is aimed at limiting jobs to only run on `master`, the previous syntax diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 7c013a2a9de..c9c65e94b32 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -59,14 +59,14 @@ mirroring the packages inside your own offline network. ### Interacting with the vulnerabilities Once a vulnerability is found, you can interact with it. Read more on how to -[address the vulnerabilities](../index.md#addressing-vulnerabilities). +[address the vulnerabilities](../vulnerabilities/index.md). Please note that in some cases the reported vulnerabilities provide metadata that can contain external links exposed in the UI. These links might not be accessible within an offline environment. ### Automatic remediation for vulnerabilities -The [automatic remediation for vulnerabilities](../index.md#apply-an-automatic-remediation-for-a-vulnerability) feature is available for offline Dependency Scanning and Container Scanning, but may not work +The [automatic remediation for vulnerabilities](../vulnerabilities/index.md#remediate-a-vulnerability-automatically) feature is available for offline Dependency Scanning and Container Scanning, but may not work depending on your instance's configuration. We can only suggest solutions, which are generally more current versions that have been patched, when we are able to access up-to-date registry services hosting the latest versions of that dependency or image. diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 208fbdfa5f3..92f0d6924b3 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -66,7 +66,8 @@ scan_execution_policy: enabled: true rules: - type: pipeline - branch: master + branches: + - master actions: - scan: dast scanner_profile: Scanner Profile A @@ -76,7 +77,8 @@ scan_execution_policy: enabled: true rules: - type: pipeline - branch: main + branches: + - main actions: - scan: dast scanner_profile: Scanner Profile C @@ -108,7 +110,17 @@ This rule enforces the defined actions whenever the pipeline runs for a selected | Field | Type | Possible values | Description | |-------|------|-----------------|-------------| | `type` | `string` | `pipeline` | The rule's type. | -| `branch` | `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | +| `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | + +### `schedule` rule type + +This rule enforces the defined actions and schedules a scan on the provided date/time. + +| Field | Type | Possible values | Description | +|------------|------|-----------------|-------------| +| `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. | ### `scan` action type @@ -129,6 +141,9 @@ Note the following: - Once you associate the site profile and scanner profile by name in the policy, it is not possible to modify or delete them. If you want to modify them, you must first disable the policy by setting the `active` flag to `false`. +- When configuring policies with a scheduled DAST scan, the author of the commit in the security + policy project's repository must have access to the scanner and site profiles. Otherwise, the scan + is not scheduled successfully. Here's an example: @@ -140,17 +155,20 @@ scan_execution_policy: enabled: true rules: - type: pipeline - branch: release/* + branches: + - release/* actions: - scan: dast scanner_profile: Scanner Profile A site_profile: Site Profile B -- name: Enforce DAST in every pipeline in main branch - description: This policy enforces pipeline configuration to have a job with DAST scan for main branch +- name: Enforce DAST scan every 10 minutes + description: This policy enforces a DAST scan to run every 10 minutes enabled: true rules: - - type: pipeline - branch: main + - type: schedule + branches: + - main + cadence: */10 * * * * actions: - scan: dast scanner_profile: Scanner Profile C @@ -160,11 +178,7 @@ scan_execution_policy: In this example, the DAST scan runs with the scanner profile `Scanner Profile A` and the site profile `Site Profile B` for every pipeline executed on branches that match the `release/*` wildcard (for example, branch name `release/v1.2.1`); and the DAST scan runs with -the scanner profile `Scanner Profile C` and the site profile `Site Profile D` for every pipeline executed on `main` branch. - -NOTE: -All scanner and site profiles must be configured and created for each project that is assigned to the selected Security Policy Project. -If they are not created, the job will fail with the error message. +the scanner profile `Scanner Profile C` and the site profile `Site Profile D` every 10 minutes. ## Security Policy project selection diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index c085dafac12..0e69f3b68eb 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -45,7 +45,7 @@ GitLab, but users can also integrate their own **custom images**. ## SAST analyzer features -For an analyzer to be considered Generally Available, it is expected to minimally +For an analyzer to be considered Generally Available, it is expected to minimally support the following features: - [Customizable configuration](index.md#available-variables) diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index cbd05f6267e..886726d5d67 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -134,16 +134,16 @@ All open source (OSS) analyzers have been moved to the GitLab Free tier as of Gi Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Capability | In Free | In Ultimate | -|:-------------------------------------------------------------------------------------------------------------|:--------------------|:-------------------| -| [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | -| [Customize SAST Settings](#customizing-the-sast-settings) | **{check-circle}** | **{check-circle}** | -| View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | -| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | -| [Address vulnerabilities](../../application_security/index.md#addressing-vulnerabilities) | **{dotted-circle}** | **{check-circle}** | -| [Access to Security Dashboard](../../application_security/security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | -| [Configure SAST in the UI](#configure-sast-in-the-ui) | **{dotted-circle}** | **{check-circle}** | -| [Customize SAST Rulesets](#customize-rulesets) | **{dotted-circle}** | **{check-circle}** | +| Capability | In Free | In Ultimate | +|:---------------------------------------------------------------------------------------|:--------------------|:-------------------| +| [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | +| [Customize SAST Settings](#customizing-the-sast-settings) | **{check-circle}** | **{check-circle}** | +| View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | +| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | +| [Address vulnerabilities](../../application_security/vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Access to Security Dashboard](../../application_security/security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Configure SAST in the UI](#configure-sast-in-the-ui) | **{dotted-circle}** | **{check-circle}** | +| [Customize SAST Rulesets](#customize-rulesets) | **{dotted-circle}** | **{check-circle}** | ## Contribute your scanner @@ -222,7 +222,7 @@ the pipeline configuration, the last mention of the variable takes precedence. ### Overriding SAST jobs WARNING: -Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) +Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#only--except) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. To override a job definition, (for example, change properties like `variables` or `dependencies`), @@ -247,8 +247,8 @@ You can customize the default scanning rules provided by our SAST analyzers. Ruleset customization supports two capabilities: -1. Disabling predefined rules -1. Modifying the default behavior of a given analyzer +1. Disabling predefined rules (available for all analyzers). +1. Modifying the default behavior of a given analyzer (only available for `nodejs-scan` and `gosec`). These capabilities can be used simultaneously. @@ -464,7 +464,7 @@ Some analyzers make it possible to filter out vulnerabilities under a given thre | CI/CD variable | Default value | Description | |------------------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. You might need to exclude temporary directories used by your build tool as these can generate false positives. | +| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. You might need to exclude temporary directories used by your build tool as these can generate false positives. To exclude paths, copy and paste the default excluded paths, then **add** your own paths to be excluded. If you don't specify the default excluded paths, you will override the defaults and _only_ paths you specify will be excluded from the SAST scans. | | `SEARCH_MAX_DEPTH` | 4 | SAST searches the repository to detect the programming languages used, and selects the matching analyzers. Set the value of `SEARCH_MAX_DEPTH` to specify how many directory levels the search phase should span. After the analyzers have been selected, the _entire_ repository is analyzed. | | `SAST_BANDIT_EXCLUDED_PATHS` | | Comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html); For example: `'*/tests/*, */venv/*'` | | `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | @@ -517,7 +517,6 @@ removed, or promoted to regular features at any time. Experimental features available are: - Enable scanning of iOS and Android apps using the [MobSF analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf/). -- Enable the [semgrep analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/). #### Enable experimental features @@ -652,14 +651,15 @@ registry.gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan:2 registry.gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit:2 registry.gitlab.com/gitlab-org/security-products/analyzers/pmd-apex:2 registry.gitlab.com/gitlab-org/security-products/analyzers/security-code-scan:2 +registry.gitlab.com/gitlab-org/security-products/analyzers/semgrep:2 registry.gitlab.com/gitlab-org/security-products/analyzers/sobelow:2 registry.gitlab.com/gitlab-org/security-products/analyzers/spotbugs:2 ``` 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. Note that these scanners are [updated periodically](../index.md#maintenance-and-update-of-the-vulnerabilities-database) -with new definitions, so consider if you're able to make periodic updates yourself. +process by which external resources can be imported or temporarily accessed. These scanners are [periodically updated](../vulnerabilities/index.md#vulnerability-scanner-maintenance) +with new definitions, and you may be able to make occasional updates on your own. 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/), @@ -681,7 +681,7 @@ Support for custom certificate authorities was introduced in the following versi | `phpcs-security-audit` | [v2.8.2](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit/-/releases/v2.8.2) | | `pmd-apex` | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex/-/releases/v2.1.0) | | `security-code-scan` | [v2.7.3](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan/-/releases/v2.7.3) | -| `semgrep` | [v0.0.1](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan/-/releases/v0.0.1) | +| `semgrep` | [v0.0.1](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/releases/v0.0.1) | | `sobelow` | [v2.2.0](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow/-/releases/v2.2.0) | | `spotbugs` | [v2.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs/-/releases/v2.7.1) | @@ -710,7 +710,7 @@ documentation for instructions. ## Running SAST in SELinux -By default SAST analyzers are supported in GitLab instances hosted on SELinux. Adding a `before_script` in an [overriden SAST job](#overriding-sast-jobs) may not work as runners hosted on SELinux have restricted permissions. +By default SAST analyzers are supported in GitLab instances hosted on SELinux. Adding a `before_script` in an [overridden SAST job](#overriding-sast-jobs) may not work as runners hosted on SELinux have restricted permissions. ## Troubleshooting diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index f137ec26114..02d117b1c0a 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -118,7 +118,7 @@ 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. -Add the following to your `.gitlab-ci.yml` file: +Ensure your `.gitlab-ci.yml` file has a `stage` called `test`, and add the following to your `.gitlab-ci.yml` file: ```yaml include: @@ -133,6 +133,31 @@ The results are saved as a that you can later download and analyze. Due to implementation limitations, we always take the latest Secret Detection artifact available. +### Enable Secret Detection via an automatic merge request **(ULTIMATE SELF)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4496) in GitLab 13.11. +> - [Deployed behind a feature flag](../../../user/feature_flags.md), enabled by default. +> - Enabled on GitLab.com. +> - Recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-configure-secret-detection-via-a-merge-request). **(ULTIMATE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +There can be +[risks when disabling released features](../../../user/feature_flags.md#risks-when-disabling-released-features). +Refer to this feature's version history for more details. + +To enable Secret Detection in a project, you can create a merge request +from the Security Configuration page. + +1. In the project where you want to enable Secret Detection, go to + **Security & Compliance > Configuration**. +1. In the **Secret Detection** row, select **Configure via Merge Request**. + +This automatically creates a merge request with the changes necessary to enable Secret Detection +that you can review and merge to complete the configuration. + ### Customizing settings The Secret Detection scan settings can be changed through [CI/CD variables](#available-variables) @@ -144,7 +169,7 @@ declare a job with the same name as the SAST job to override. Place this new job inclusion and specify any additional keys under it. WARNING: -Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) +Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#only--except) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. #### GIT_DEPTH @@ -316,8 +341,8 @@ registry.gitlab.com/gitlab-org/security-products/analyzers/secrets:3 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. Note that these scanners are [updated periodically](../index.md#maintenance-and-update-of-the-vulnerabilities-database) -with new definitions, so consider if you're able to make periodic updates yourself. +process by which external resources can be imported or temporarily accessed. These scanners are [periodically updated](../vulnerabilities/index.md#vulnerability-scanner-maintenance) +with new definitions, and you may be able to make occasional updates on your own. 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/), @@ -380,3 +405,22 @@ secret_detection: variables: GIT_DEPTH: 100 ``` + +### Enable or disable Configure Secret Detection via a Merge Request + +Configure Secret Detection via a Merge Request is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:sec_secret_detection_ui_enable) +``` + +To disable it: + +```ruby +Feature.disable(:sec_secret_detection_ui_enable) +``` diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_3.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_3.png Binary files differdeleted file mode 100644 index c89179e739d..00000000000 --- a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_3.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/security_center_dashboard_link_v12_4.png b/doc/user/application_security/security_dashboard/img/security_center_dashboard_link_v12_4.png Binary files differdeleted file mode 100644 index e0e80810b08..00000000000 --- a/doc/user/application_security/security_dashboard/img/security_center_dashboard_link_v12_4.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png b/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png Binary files differindex 4223494c294..74592e2cea5 100644 --- a/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png +++ b/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 326c88f9eef..f0b3d895df5 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -73,18 +73,31 @@ CSV file containing details of the resources scanned. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235558) in GitLab 13.6. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285476) in GitLab 13.10, options to zoom in on a date range, and download the vulnerabilities chart. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285477) in GitLab 13.11, date range slider to visualise data between given dates. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285477) in GitLab 13.11, date range slider to visualize data between given dates. -At the project level, the Security Dashboard displays a chart with the number of vulnerabilities over time. -Access it by navigating to **Security & Compliance > Security Dashboard**. We display historical -data up to 365 days. The chart's data is updated daily. +A project's Security Dashboard displays a chart with the total number of vulnerabilities +over time. It updates daily with up to 365 days of historical data. By default, +it shows statistics for all vulnerability severities. + +To access the dashboard, from your project's home page go to **Security & Compliance > Security Dashboard**.  -Filter the historical data by clicking on the corresponding legend name. The image above, for example, shows -only the graph for vulnerabilities with **high** severity. +### Filter the vulnerabilities chart + +To filter the chart by vulnerability severity, select the corresponding legend name. + +In the previous example, the chart shows statistics only for vulnerabilities of medium or unknown severity. + +### Customize vulnerabilities chart display -To zoom in, select the left-most icon, then select the desired rangeby dragging across the chart. Select **Remove Selection** (**{redo}**) to reset to the original date range. +To customize the view of the vulnerability chart, you can select: + +- A specific time frame by using the time range handles (**{scroll-handle}**). +- A specific area of the chart by using the left-most icon (**{marquee-selection}**) then drag + across the chart. To reset to the original range, select **Remove Selection** (**{redo}**). + +### Download a copy of the vulnerabilities chart To download an SVG image of the chart, select **Save chart to an image** (**{download}**). @@ -137,10 +150,8 @@ the following:  -You can access the Security Center from the menu -bar at the top of the page. Under **More**, select **Security**. - - +To view the Security Center, from the navigation bar at the top of the page, select +**More > Security**. ### Adding projects to the Security Center @@ -198,4 +209,4 @@ 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. --> -Read more on how to [address the vulnerabilities](../index.md#addressing-vulnerabilities). +Read more on how to [address the vulnerabilities](../vulnerabilities/index.md). diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index e046b18b2a4..1316f1b9644 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -78,6 +78,8 @@ An asset that has the potential to be vulnerable, identified in a project by an include but are not restricted to source code, binary packages, containers, dependencies, networks, applications, and infrastructure. +Findings are all potential vulnerability items scanners identify in MRs/feature branches. Only after merging to default does a finding become a [vulnerability](#vulnerability). + ### Insignificant finding A legitimate finding that a particular customer doesn't care about. @@ -153,6 +155,8 @@ A flaw that has a negative impact on the security of its environment. Vulnerabil error or weakness, and don't describe where the error is located (see [finding](#finding)). Each vulnerability maps to a unique finding. +Vulnerabilities exist in the default branch. Findings (see [finding](#finding)) are all potential vulnerability items scanners identify in MRs/feature branches. Only after merging to default does a finding become a vulnerability. + ### Vulnerability finding When a [report finding](#report-finding) is stored to the database, it becomes a vulnerability diff --git a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_11.png b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_11.png Binary files differdeleted file mode 100644 index 05df41483c4..00000000000 --- a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_11.png +++ /dev/null diff --git a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png Binary files differnew file mode 100644 index 00000000000..1f02fd30f8e --- /dev/null +++ b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index ced4669e241..825bc64d52b 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -209,19 +209,26 @@ Feature.disable(:threat_monitoring_alerts) > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. -The policy alert list displays your policy's alert activity. You can sort the list by the -**Date and time** column, and the **Status** column. Use the selector menu in the **Status** column -to set the status for each alert: +The policy alert list displays your policy's alert activity. You can sort the list by these columns: + +- Date and time +- Events +- Status + +You can filter the list with the **Policy Name** filter and the **Status** filter at the top. Use +the selector menu in the **Status** column to set the status for each alert: - Unreviewed - In review - Resolved - Dismissed -By default, the list doesn't display resolved or dismissed alerts. To show these alerts, clear the -checkbox **Hide dismissed alerts**. +By default, the list doesn't display resolved or dismissed alerts. + + - +Clicking an alert's row opens the alert drawer, which shows more information about the alert. A user +can also create an incident from the alert and update the alert status in the alert drawer. Clicking an alert's name takes the user to the [alert details page](../../../operations/incident_management/alerts.md#alert-details-page). diff --git a/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png b/doc/user/application_security/vulnerabilities/img/create_mr_from_vulnerability_v13_4.png Binary files differindex 55694fc7926..55694fc7926 100644 --- a/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png +++ b/doc/user/application_security/vulnerabilities/img/create_mr_from_vulnerability_v13_4.png diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index b98d28f8c9f..965b856504d 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Each security vulnerability in a project's [Vulnerability Report](../vulnerability_report/index.md) has an individual page which includes: - Details of the vulnerability. -- The status of the vulnerability within the project. +- The status of the vulnerability in the project. - Available actions for the vulnerability. - Any issues related to the vulnerability. @@ -21,8 +21,10 @@ On the vulnerability's page, you can: - [Change the vulnerability's status](#change-vulnerability-status). - [Create an issue](#create-an-issue-for-a-vulnerability). - [Link issues to the vulnerability](#link-gitlab-issues-to-the-vulnerability). -- [Automatically remediate the vulnerability](#automatically-remediate-the-vulnerability), if an +- [Remediate a vulnerability automatically](#remediate-a-vulnerability-automatically), if an automatic solution is available. +- [Remediate a vulnerability manually](#remediate-a-vulnerability-manually), if a solution is + available. ## Change vulnerability status @@ -60,7 +62,7 @@ To create a GitLab issue for a vulnerability: 1. In GitLab, go to the vulnerability's page. 1. Select **Create issue**. -An issue is created in the project, prepopulated with information from the vulnerability report. +An issue is created in the project, pre-populated with information from the vulnerability report. The issue is then opened so you can take further action. ### Create a Jira issue for a vulnerability @@ -120,7 +122,76 @@ that the resolution of one issue would resolve multiple vulnerabilities. Linked issues are shown in the Vulnerability Report and the vulnerability's page. -## Automatically remediate the vulnerability +## Link to an existing issue -You can fix some vulnerabilities by applying the solution that GitLab automatically -generates for you. [Read more about the automatic remediation for vulnerabilities feature](../index.md#apply-an-automatic-remediation-for-a-vulnerability). +If you already have an open issue, you can link to it from the vulnerability. + +- The vulnerability page shows related issues, but the issue page doesn't show the vulnerability it's related to. +- An issue can only be related to one vulnerability at a time. +- Issues can be linked across groups and projects. + +To link to an existing issue: + +1. Open the vulnerability. +1. [Add a linked issue](../../project/issues/related_issues.md). + +## Remediate a vulnerability automatically + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5656) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.7. + +Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. +The following scanners are supported: + +- [Dependency Scanning](../dependency_scanning/index.md). + Automatic Patch creation is only available for Node.js projects managed with + `yarn`. +- [Container Scanning](../container_scanning/index.md). + +### Remediate a vulnerability manually + +To manually apply the patch that GitLab generated for a vulnerability: + +1. Select the **Resolve with merge request** dropdown, then select **Download patch to resolve**: + +  + +1. Ensure your local project has the same commit checked out that was used to generate the patch. +1. Run `git apply remediation.patch`. +1. Verify and commit the changes to your branch. + +### Create a merge request with the suggested patch + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9224) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. + +In some cases, you can create a merge request that automatically remediates the +vulnerability. Any vulnerability that has a +[solution](#remediate-a-vulnerability-automatically) can have a merge +request created to automatically solve the issue. + +If this action is available: + +1. Select the **Resolve with merge request** dropdown, then select **Resolve with merge request**. + +  + +A merge request is created. It applies the solution to the source branch. + +## Vulnerability scanner maintenance + +The following vulnerability scanners and their databases are regularly updated: + +| Secure scanning tool | Vulnerabilities database updates | +|:----------------------------------------------------------------|----------------------------------| +| [Container Scanning](../container_scanning/index.md) | Uses either `trivy` or `clair`. For the `trivy` scanner, a job runs on a daily basis to build a new image with the latest vulnerability database updates from the [upstream `trivy-db`](https://github.com/aquasecurity/trivy-db). For the `clair` scanner, the latest `clair-db` version is used; `clair-db` database [is updated daily according to the author](https://github.com/arminc/clair-local-scan#clair-server-or-local). | +| [Dependency Scanning](../dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for npm packages), and `gemnasium` (the GitLab tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated at least once a week. See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | +| [Dynamic Application Security Testing (DAST)](../dast/index.md) | The scanning engine is updated on a periodic basis. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/master/Dockerfile#L1). The scanning rules are downloaded at scan runtime. | +| [Static Application Security Testing (SAST)](../sast/index.md) | Relies exclusively on [the tools GitLab wraps](../sast/index.md#supported-languages-and-frameworks). The underlying analyzers are updated at least once per month if a relevant update is available. The vulnerabilities database is updated by the upstream tools. | + +You do not have to update GitLab to benefit from the latest vulnerabilities definitions. +The security tools are released as Docker images. The vendored job definitions that enable them use +major release tags according to [semantic versioning](https://semver.org/). Each new release of the +tools overrides these tags. +The Docker images are updated to match the previous GitLab releases. Although +you automatically get the latest versions of the scanning tools, +there are some [known issues](https://gitlab.com/gitlab-org/gitlab/-/issues/9725) +with this approach. diff --git a/doc/user/application_security/vulnerabilities/severities.md b/doc/user/application_security/vulnerabilities/severities.md index 40b8f418737..75366a49a55 100644 --- a/doc/user/application_security/vulnerabilities/severities.md +++ b/doc/user/application_security/vulnerabilities/severities.md @@ -50,6 +50,7 @@ the following tables: | [`pmd-apex`](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) | **{check-circle}** Yes | Integer | `1`, `2`, `3`, `4`, `5` | | [`kubesec`](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec) | **{check-circle}** Yes | String | `CriticalSeverity`, `InfoSeverity` | | [`secrets`](https://gitlab.com/gitlab-org/security-products/analyzers/secrets) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Critical` | +| [`semgrep`](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) | **{check-circle}** Yes | String | `error`, `warning`, `note`, `none` | ## Dependency Scanning @@ -61,9 +62,10 @@ the following tables: ## Container Scanning -| GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example | +| GitLab scanner | Outputs severity levels? | Native severity level type | Native severity level example | |------------------------------------------------------------------------|--------------------------|----------------------------|--------------------------------------------------------------| -| [`klar`](https://gitlab.com/gitlab-org/security-products/analyzers/klar) | **{check-circle}** Yes | String | `Negligible`, `Low`, `Medium`, `High`, `Critical`, `Defcon1` | +| [`clair`](https://gitlab.com/gitlab-org/security-products/analyzers/klar) | **{check-circle}** Yes | String | `Negligible`, `Low`, `Medium`, `High`, `Critical`, `Defcon1` | +| [`trivy`](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning)| **{check-circle}** Yes | String | `Unknown`, `Low`, `Medium`, `High`, `Critical` | ## Fuzz Testing diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index 8f7740f9bfc..012992c8a72 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -162,3 +162,26 @@ computer. NOTE: It may take several minutes for the download to start if your project contains thousands of vulnerabilities. Don't close the page until the download finishes. + +## Dismiss a vulnerability + +> The option of adding a dismissal reason was introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. + +You can dismiss a vulnerability for the entire project: + +1. Select the vulnerability in the Security Dashboard. +1. In the top-right, from the **Status** selector menu, select **Dismissed**. +1. Optional. Add a reason for the dismissal and select **Save comment**. + +To undo this action, select a different status from the same menu. + +### Dismiss multiple vulnerabilities + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35816) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. + +You can dismiss multiple vulnerabilities at once: + +1. In the list of vulnerabilities, select the checkbox for each vulnerability you want to dismiss. + To select all, select the checkbox in the table header. +1. Above the table, select a dismissal reason. +1. Select **Dismiss Selected**. diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 31accfdd9e4..5e272f2a816 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -56,7 +56,7 @@ There are several components that work in concert for the Agent to accomplish Gi You can use the same GitLab project or separate projects for configuration and manifest files, as follows: - Single GitLab project (recommended): when you use a single repository to hold both the manifest and the configuration files, these projects can be either private or public, as you prefer. -- Two GitLab projects: when you opt to use two different GitLab projects, one for manifest files, and another for configuration files, the manifests project must be private, while the configuration project can be either private or public. Our backlog contains issues for adding support for +- Two GitLab projects: when you opt to use two different GitLab projects, one for manifest files, and another for configuration files, the manifests project must be public, while the configuration project can be either private or public. Our backlog contains issues for adding support for [private manifest repositories outside of the configuration project](https://gitlab.com/gitlab-org/gitlab/-/issues/220912) and [group level agents](https://gitlab.com/gitlab-org/gitlab/-/issues/283885) in the future. @@ -100,27 +100,39 @@ To use the KAS: ### Define a configuration repository -Next, you need a GitLab repository to contain your Agent configuration. The minimal -repository layout looks like this: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the Agent manifest configuration can be added to multiple directories (or subdirectories) of its repository. + +To configure an Agent, you need: + +1. A GitLab repository to hold the configuration file. +1. Install the Agent in a cluster. + +After installed, when you update the configuration file, GitLab transmits the +information to the cluster automatically without downtime. + +In your repository, add the Agent configuration file under: ```plaintext .gitlab/agents/<agent-name>/config.yaml ``` -Your `config.yaml` file can specify multiple manifest projects in the -section `manifest_projects`: +Your `config.yaml` file specifies all configurations of the Agent, such as: + +- The manifest projects to synchronize. +- The address of the `hubble-relay` for the Network Security policy integrations. + +As an example, a minimal Agent configuration that sets up only the manifest +synchronizations is: ```yaml gitops: manifest_projects: - - id: "path-to/your-manifest-project-number1" - ... + - id: "path-to/your-manifest-project-1" + paths: + - glob: '/**/*.{yaml,yml,json}' ``` -GitLab [versions 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) also -supports manifest projects containing -multiple directories (or subdirectories) of YAML files. For more information see our -documentation on the [Kubernetes Agent configuration repository](repository.md). +All the options for the [Kubernetes Agent configuration repository](repository.md) are documented separately. ### Create an Agent record in GitLab @@ -158,8 +170,8 @@ the Agent in subsequent steps. You can create an Agent record with GraphQL: } ``` - NOTE: - GraphQL only displays the token one time after creating it. +WARNING: +GraphQL only displays the token and ids **one time** after creating it. Make sure to write down the `secret`, `clusterAgentId`, and `clusterAgentTokenId`; you'll need them later. If you are new to using the GitLab GraphQL API, refer to the [Getting started with the GraphQL API page](../../../api/graphql/getting_started.md), @@ -202,7 +214,7 @@ docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration For more advanced configurations, we recommend to use [the `kpt` based installation method](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent). -Otherwise, you can follow below for fully manual, detailed installation steps. +Otherwise, follow the manual installation steps described below. ##### Create the Kubernetes secret @@ -211,14 +223,14 @@ After generating the token, you must apply it to the Kubernetes cluster. To create your Secret, run: ```shell -kubectl create secret generic -n <YOUR_NAMESPACE> gitlab-agent-token --from-literal=token='YOUR_AGENT_TOKEN' +kubectl create secret generic -n gitlab-kubernetes-agent gitlab-kubernetes-agent-token --from-literal=token='YOUR_AGENT_TOKEN' ``` The following example file contains the Kubernetes resources required for the Agent to be installed. You can modify this example [`resources.yml` file](#example-resourcesyml-file) in the following ways: -- Replace `namespace: gitlab-agent` with `namespace: <YOUR-DESIRED-NAMESPACE>`. +- Replace `namespace: gitlab-kubernetes-agent` with `namespace: <YOUR-DESIRED-NAMESPACE>`. - You can configure `kas-address` (Kubernetes Agent Server) in several ways. The agent can use the WebSockets or gRPC protocols to connect to the Agent Server. Select the option appropriate for your cluster configuration and GitLab architecture: @@ -233,7 +245,7 @@ example [`resources.yml` file](#example-resourcesyml-file) in the following ways When using the Omnibus GitLab, specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent/`). - Specify the `grpc` scheme if both Agent and Server are installed in one cluster. In this case, you may specify `kas-address` value as - `grpc://gitlab-kas.<your-namespace>:5005`) to use gRPC directly, where `gitlab-kas` + `grpc://gitlab-kas.<your-namespace>:8150`) to use gRPC directly, where `gitlab-kas` is the name of the service created by `gitlab-kas` chart, and `your-namespace` is the namespace where the chart was installed. Encrypted gRPC is not supported yet. Follow the @@ -243,47 +255,53 @@ example [`resources.yml` file](#example-resourcesyml-file) in the following ways Check the [chart's KAS Ingress documentation](https://docs.gitlab.com/charts/charts/gitlab/kas/#ingress) to learn more about it. - In the near future, Omnibus GitLab intends to provision `gitlab-kas` under a sub-domain by default, instead of the `/-/kubernetes-agent/` path. Please follow [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5784) for details. -- If you defined your own secret name, replace `gitlab-agent-token` with your +- If you defined your own secret name, replace `gitlab-kubernetes-agent-token` with your secret name in the `secretName:` section. To apply this file, run the following command: ```shell -kubectl apply -n <YOUR-DESIRED-NAMESPACE> -f ./resources.yml +kubectl apply -n gitlab-kubernetes-agent -f ./resources.yml ``` To review your configuration, run the following command: ```shell -$ kubectl get pods -n <YOUR-DESIRED-NAMESPACE> +$ kubectl get pods -n gitlab-kubernetes-agent -NAMESPACE NAME READY STATUS RESTARTS AGE -gitlab-agent gitlab-agent-77689f7dcb-5skqk 1/1 Running 0 51s +NAMESPACE NAME READY STATUS RESTARTS AGE +gitlab-kubernetes-agent gitlab-kubernetes-agent-77689f7dcb-5skqk 1/1 Running 0 51s ``` ##### Example `resources.yml` file ```yaml +--- +apiVersion: v1 +kind: Namespace +metadata: + name: gitlab-kubernetes-agent +--- apiVersion: v1 kind: ServiceAccount metadata: - name: gitlab-agent + name: gitlab-kubernetes-agent --- apiVersion: apps/v1 kind: Deployment metadata: - name: gitlab-agent + name: gitlab-kubernetes-agent spec: replicas: 1 selector: matchLabels: - app: gitlab-agent + app: gitlab-kubernetes-agent template: metadata: labels: - app: gitlab-agent + app: gitlab-kubernetes-agent spec: - serviceAccountName: gitlab-agent + serviceAccountName: gitlab-kubernetes-agent containers: - name: agent # Make sure to specify a matching version for production @@ -291,15 +309,17 @@ spec: args: - --token-file=/config/token - --kas-address - - wss://kas.host.tld:443 # change this line for the one below if using Omnibus GitLab + - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com. # - wss://gitlab.host.tld:443/-/kubernetes-agent/ + # - wss://kas.gitlab.com # for GitLab.com users, use this KAS. + # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker. volumeMounts: - name: token-volume mountPath: /config volumes: - name: token-volume secret: - secretName: gitlab-agent-token + secretName: gitlab-kubernetes-agent-token strategy: type: RollingUpdate rollingUpdate: @@ -309,7 +329,7 @@ spec: apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: - name: gitlab-agent-write + name: gitlab-kubernetes-agent-write rules: - resources: - '*' @@ -324,20 +344,20 @@ rules: apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: - name: gitlab-agent-write-binding + name: gitlab-kubernetes-agent-write-binding roleRef: - name: gitlab-agent-write + name: gitlab-kubernetes-agent-write kind: ClusterRole apiGroup: rbac.authorization.k8s.io subjects: -- name: gitlab-agent +- name: gitlab-kubernetes-agent kind: ServiceAccount - namespace: gitlab-agent + namespace: gitlab-kubernetes-agent --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: - name: gitlab-agent-read + name: gitlab-kubernetes-agent-read rules: - resources: - '*' @@ -351,15 +371,15 @@ rules: apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: - name: gitlab-agent-read-binding + name: gitlab-kubernetes-agent-read-binding roleRef: - name: gitlab-agent-read + name: gitlab-kubernetes-agent-read kind: ClusterRole apiGroup: rbac.authorization.k8s.io subjects: -- name: gitlab-agent +- name: gitlab-kubernetes-agent kind: ServiceAccount - namespace: gitlab-agent + namespace: gitlab-kubernetes-agent ``` ### Create manifest files @@ -388,7 +408,7 @@ apiVersion: apps/v1 kind: Deployment metadata: name: nginx-deployment - namespace: gitlab-agent # Can be any namespace managed by you that the agent has access to. + namespace: gitlab-kubernetes-agent # Can be any namespace managed by you that the agent has access to. spec: selector: matchLabels: @@ -481,7 +501,7 @@ If you face any issues while using GitLab Kubernetes Agent, you can read the service logs with the following command ```shell -kubectl logs -f -l=app=gitlab-agent -n <YOUR-DESIRED-NAMESPACE> +kubectl logs -f -l=app=gitlab-kubernetes-agent -n gitlab-kubernetes-agent ``` GitLab administrators can additionally view the [Kubernetes Agent Server logs](../../../administration/clusters/kas.md#troubleshooting). @@ -520,7 +540,7 @@ It's not possible to set the `grpc` scheme due to the issue [It is not possible to configure KAS to work with `grpc` without directly editing GitLab KAS deployment](https://gitlab.com/gitlab-org/gitlab/-/issues/276888). To use `grpc` while the issue is in progress, directly edit the deployment with the `kubectl edit deployment gitlab-kas` command, and change `--listen-websocket=true` to `--listen-websocket=false`. After running that command, you should be able to use -`grpc://gitlab-kas.<YOUR-NAMESPACE>:5005`. +`grpc://gitlab-kas.<YOUR-NAMESPACE>:8150`. ### Agent logs - Decompressor is not installed for grpc-encoding @@ -542,25 +562,27 @@ is unknown to the agent. One approach to fixing it is to present the CA certific via a Kubernetes `configmap` and mount the file in the agent `/etc/ssl/certs` directory from where it will be picked up automatically. -For example, if your internal CA certifciate is `myCA.pem`: +For example, if your internal CA certificate is `myCA.pem`: ```plaintext -kubectl -n gitlab-agent create configmap ca-pemstore --from-file=myCA.pem +kubectl -n gitlab-kubernetes-agent create configmap ca-pemstore --from-file=myCA.pem ``` Then in `resources.yml`: ```yaml spec: - serviceAccountName: gitlab-agent + serviceAccountName: gitlab-kubernetes-agent containers: - name: agent image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>" args: - --token-file=/config/token - --kas-address - - wss://kas.host.tld:443 # change this line for the one below if using Omnibus GitLab + - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com. # - wss://gitlab.host.tld:443/-/kubernetes-agent/ + # - wss://kas.gitlab.com # for GitLab.com users, use this KAS. + # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker. volumeMounts: - name: token-volume mountPath: /config @@ -570,7 +592,7 @@ Then in `resources.yml`: volumes: - name: token-volume secret: - secretName: gitlab-agent-token + secretName: gitlab-kubernetes-agent-token - name: ca-pemstore-volume configMap: name: ca-pemstore @@ -590,8 +612,10 @@ Alternatively, you can mount the certificate file at a different location and in - --ca-cert-file=/tmp/myCA.pem - --token-file=/config/token - --kas-address - - wss://kas.host.tld:443 # change this line for the one below if using Omnibus GitLab + - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com. # - wss://gitlab.host.tld:443/-/kubernetes-agent/ + # - wss://kas.gitlab.com # for GitLab.com users, use this KAS. + # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker. volumeMounts: - name: token-volume mountPath: /config @@ -599,3 +623,34 @@ Alternatively, you can mount the certificate file at a different location and in mountPath: /tmp/myCA.pem subPath: myCA.pem ``` + +## Remove the GitLab Kubernetes Agent + +1. Remove an Agent record with GraphQL by deleting the `clusterAgent` and the `clusterAgentToken`. + + ```graphql + mutation deleteAgent { + clusterAgentDelete(input: { id: "<cluster-agent-id>" } ) { + errors + } + } + + mutation deleteToken { + clusterAgentTokenDelete(input: { id: "<cluster-agent-token-id>" }) { + errors + } + } + ``` + +1. Verify whether the removal occurred successfully. If the output in the Pod logs includes `unauthenticated`, it means that the agent was successfully removed: + + ```json + {"level":"warn","time":"2021-04-29T23:44:07.598Z","msg":"GetConfiguration.Recv failed","error":"rpc error: + code = Unauthenticated desc = unauthenticated"} + ``` + +1. Delete the GitLab Kubernetes Agent in your cluster: + + ```shell + kubectl delete -n gitlab-kubernetes-agent -f ./resources.yml + ``` diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index 9caa4a89daf..49e5e8c58df 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -94,3 +94,41 @@ gitops: # If 'paths' is not specified or is an empty list, the configuration below is used - glob: '/**/*.{yaml,yml,json}' ``` + +## Surface network security alerts from cluster to GitLab + +The GitLab Agent provides an [integration with Cilium](index.md#kubernetes-network-security-alerts). +To integrate, add a top-level `cilium` section to your `config.yml` file. Currently, the +only configuration option is the Hubble relay address: + +```yaml +cilium: + hubble_relay_address: "<hubble-relay-host>:<hubble-relay-port>" +``` + +If your Cilium integration was performed through GitLab Managed Apps, you can use `hubble-relay.gitlab-managed-apps.svc.cluster.local:80` as the address: + +```yaml +cilium: + hubble_relay_address: "hubble-relay.gitlab-managed-apps.svc.cluster.local:80" +``` + +## Debugging + +To debug the cluster-side component (`agentk`) of the GitLab Kubernetes Agent, set the log +level according to the available options: + +- `off` +- `warning` +- `error` +- `info` +- `debug` + +The log level defaults to `info`. You can change it by using a top-level `observability` +section in the configuration file, for example: + +```yaml +observability: + logging: + level: debug +``` diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index b11ca7aac12..212823853e4 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -4,27 +4,41 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Managed Apps **(FREE)** +# GitLab Managed Apps (DEPRECATED) **(FREE)** -GitLab provides **GitLab Managed Apps** for various -applications which can be added directly to your configured cluster. These -applications are needed for [Review Apps](../../ci/review_apps/index.md) and -[deployments](../../ci/environments/index.md) when using [Auto DevOps](../../topics/autodevops/index.md). -You can install them after you [create a cluster](../project/clusters/add_remove_clusters.md). -GitLab provides GitLab Managed Apps [using CI/CD](#install-using-gitlab-cicd). -GitLab Managed Apps with [one-click installations](#install-with-one-click) -have been deprecated, and are scheduled for removal in GitLab 14.0. +**GitLab Managed Apps** was created to help you configure applications in your +cluster directly from GitLab. You could use this feature through two different +methods: "one-click install" and "CI/CD template". Both methods are **deprecated**: -## Install using GitLab CI/CD +- The **one-click install** method was deprecated in GitLab 13.9 and **will be + removed** in GitLab 14.0. +- The **CI/CD template method** was deprecated in GitLab 13.12 and is scheduled + to be removed in GitLab 15.0. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20822) in GitLab 12.6. +Both methods were limiting as you couldn't fully customize your third-party apps installed +through GitLab Managed Apps. Therefore, we decided to deprecate this feature and provide +better [GitOps-driven alternatives](https://about.gitlab.com/direction/configure/kubernetes_management/#gitlab-managed-applications) to our users, such as [cluster integrations](integrations.md#cluster-integrations) and [cluster management project](management_project.md). + +Read the sections below according to the installation method you chose to +learn how to proceed to keep your apps up and running: + +- [One-click install method](#install-with-one-click-deprecated) +- [CI/CD template method](#install-using-gitlab-cicd-deprecated) + +## Install using GitLab CI/CD (DEPRECATED) + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20822) in GitLab 12.6. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 13.12. WARNING: -This is a _beta_ feature, and some applications might miss features to provide full integration with GitLab. +The GitLab Managed Apps CI/CD installation method was [deprecated in 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/327908). +Your applications continue to work. However, we no longer support and maintain the GitLab CI/CD template for +Managed Apps (`Managed-Cluster-Applications.gitlab-ci.yml`). +As a replacement, we are working on a [cluster management project template](https://gitlab.com/gitlab-org/gitlab/-/issues/327908), +still to be released. -This primary method for installing applications to clusters allows users to install GitLab-managed -applications using GitLab CI/CD. It also allows customization of the -install using Helm `values.yaml` files. +The CI/CD template was the primary method for installing applications to clusters via GitLab Managed Apps +and customize them through Helm. Supported applications: @@ -138,6 +152,8 @@ Note the following: ### Install Ingress using GitLab CI/CD +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 13.12. + To install Ingress, define the `.gitlab/managed-apps/config.yaml` file with: @@ -162,6 +178,8 @@ and ping at least 2 people from the ### Install cert-manager using GitLab CI/CD +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 13.12. + cert-manager is installed using GitLab CI/CD by defining configuration in `.gitlab/managed-apps/config.yaml`. @@ -206,6 +224,8 @@ least 2 people from the ### Install Sentry using GitLab CI/CD +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 13.12. + The Sentry Helm chart [recommends](https://github.com/helm/charts/blob/f6e5784f265dd459c5a77430185d0302ed372665/stable/sentry/values.yaml#L284-L285) at least 3 GB of available RAM for database migrations. @@ -275,6 +295,8 @@ least 2 people from the ### Install PostHog using GitLab CI/CD +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 13.12. + [PostHog](https://posthog.com) 🦔 is a developer-friendly, open-source product analytics platform. To install PostHog into the `gitlab-managed-apps` namespace of your cluster, @@ -325,7 +347,8 @@ If you run into issues, ### Install Prometheus using GitLab CI/CD -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25138) in GitLab 12.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25138) in GitLab 12.8. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 13.12. [Prometheus](https://prometheus.io/docs/introduction/overview/) is an open-source monitoring and alerting system for supervising your @@ -352,6 +375,8 @@ least 2 people from the [APM group](https://about.gitlab.com/handbook/product/ca ### Install GitLab Runner using GitLab CI/CD +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 13.12. + GitLab Runner is installed using GitLab CI/CD by defining configuration in `.gitlab/managed-apps/config.yaml`. @@ -390,7 +415,8 @@ least 2 people from the ### Install Cilium using GitLab CI/CD -> [Introduced](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications/-/merge_requests/22) in GitLab 12.8. +> - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications/-/merge_requests/22) in GitLab 12.8. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 13.12. [Cilium](https://cilium.io/) is a networking plugin for Kubernetes that you can use to implement support for [NetworkPolicy](https://kubernetes.io/docs/concepts/services-networking/network-policies/) @@ -505,7 +531,8 @@ least 2 people from the ### Install Falco using GitLab CI/CD -> [Introduced](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications/-/merge_requests/91) in GitLab 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications/-/merge_requests/91) in GitLab 13.1. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 13.12. GitLab Container Host Security Monitoring uses [Falco](https://falco.org/) as a runtime security tool that listens to the Linux kernel using eBPF. Falco parses system calls @@ -601,7 +628,8 @@ least 2 people from the ### Install Vault using GitLab CI/CD -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9982) in GitLab 12.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9982) in GitLab 12.9. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 13.12. [HashiCorp Vault](https://www.vaultproject.io/) is a secrets management solution which can be used to safely manage and store passwords, credentials, certificates, and more. A Vault @@ -703,7 +731,8 @@ least 2 people from the ### Install JupyterHub using GitLab CI/CD -> [Introduced](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications/-/merge_requests/40) in GitLab 12.8. +> - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications/-/merge_requests/40) in GitLab 12.8. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 13.12. JupyterHub is installed using GitLab CI/CD by defining configuration in `.gitlab/managed-apps/config.yaml` as follows: @@ -760,7 +789,8 @@ least 2 people from the ### Install Elastic Stack using GitLab CI/CD -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25138) in GitLab 12.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25138) in GitLab 12.8. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 13.12. Elastic Stack is installed using GitLab CI/CD by defining configuration in `.gitlab/managed-apps/config.yaml`. @@ -796,7 +826,8 @@ least 2 people from the [APM group](https://about.gitlab.com/handbook/product/ca ### Install Crossplane using GitLab CI/CD -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35675) in GitLab 12.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35675) in GitLab 12.9. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 13.12. Crossplane is installed using GitLab CI/CD by defining configuration in `.gitlab/managed-apps/config.yaml`. @@ -827,7 +858,8 @@ If you run into issues, ### Install Fluentd using GitLab CI/CD -> [Introduced](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications/-/merge_requests/76) in GitLab 12.10. +> - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications/-/merge_requests/76) in GitLab 12.10. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 13.12. To install Fluentd into the `gitlab-managed-apps` namespace of your cluster using GitLab CI/CD, define the following configuration in `.gitlab/managed-apps/config.yaml`: @@ -858,6 +890,8 @@ least 2 people from the ### Install Knative using GitLab CI/CD +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 13.12. + To install Knative, define the `.gitlab/managed-apps/config.yaml` file with: @@ -908,7 +942,8 @@ kubectl delete -f https://gitlab.com/gitlab-org/cluster-integration/cluster-appl ### Install AppArmor using GitLab CI/CD -> [Introduced](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications/-/merge_requests/100) in GitLab 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications/-/merge_requests/100) in GitLab 13.1. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 13.12. To install AppArmor into the `gitlab-managed-apps` namespace of your cluster using GitLab CI/CD, define the following configuration in `.gitlab/managed-apps/config.yaml`: @@ -998,13 +1033,13 @@ at least 2 people from the Logs produced by pods running **GitLab Managed Apps** can be browsed using [**Log Explorer**](../project/clusters/kubernetes_pod_logs.md). -## Install with one click +## Install with one click (DEPRECATED) WARNING: -The one-click installation method is deprecated and scheduled for removal in [GitLab 14.0](https://gitlab.com/groups/gitlab-org/-/epics/4280). -This removal does not affect installed applications to avoid breaking -changes. Following GitLab 14.0, users can take ownership of already installed applications -using our documentation. +The one-click installation method was deprecated in GitLab 13.9 and will be removed in [GitLab 14.0](https://gitlab.com/groups/gitlab-org/-/epics/4280). +The removal does not break nor uninstall any apps you have installed but removes the GitLab UI page +for installing and updating your GitLab Managed Apps. +Follow the process to [take ownership of your GitLab Managed Apps](#take-ownership-of-your-gitlab-managed-apps). Applications managed by GitLab are installed onto the `gitlab-managed-apps` namespace. This namespace: @@ -1668,3 +1703,88 @@ Spawn failed: Timeout This is due to DigitalOcean imposing a few limits with regards to creating additional block storage volumes. [Learn more about DigitalOcean Block Storage Volumes limits.](https://www.digitalocean.com/docs/volumes/#limits) + +## Take ownership of your GitLab Managed Apps + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327803) in GitLab 13.12. + +With the removal of the [One-click install method](#install-with-one-click-deprecated) in GitLab 14.0, +the **Applications** tab (under your project's **Operations > Kubernetes**) +will no longer be displayed: + + + +This tab was dedicated to installing and maintaining GitLab Managed Apps. +To continue managing your installed applications, one of the possible ways is to +install [Helm](https://helm.sh/) locally, as described below. + +### View installed applications + +To view the applications you have installed in your cluster through GitLab Managed Apps, +you need to verify the resources you have in the `gitlab-managed-apps` namespace. +On your computer, [configure `kubectl`](https://kubernetes.io/docs/reference/kubectl/overview/) +to connect to your cluster, open the terminal and run: + +```shell +kubectl get all -n gitlab-managed-apps +``` + +If there is no output or the namespace does not exist, you do not have any applications +installed through GitLab Managed Apps. If this is the case, you have nothing else to do. + +### Identify the Helm version + +Next, verify which Helm version GitLab used to install your applications. + +#### For apps installed with Helm v3 + +To list your apps installed with Helm v3, run: + +```shell +kubectl get secrets -n gitlab-managed-apps | grep 'helm.sh/release' +``` + +You can manage these applications with Helm v3 and you don't need any further steps. + +All applications not listed with the command above were installed with Helm v2. + +#### For apps installed with Helm v2 + +If you have apps installed with Helm v2, you can either: + +- A. Install Helm v3 and [upgrade your apps to Helm v3](https://helm.sh/docs/topics/v2_v3_migration/). +- B. Install Helm v2 and keep using this Helm version, which is not recommended as Helm v2 was deprecated in favor of +Helm v3. + +If you choose to keep using Helm v2 (B), follow the steps below to manage your apps: + +1. Install [Helm v2](https://v2.helm.sh/docs/install/) in your computer. +1. Start a local Tiller server: + + ```shell + export TILLER_NAMESPACE=gitlab-managed-apps + tiller -listen localhost:44134 + ``` + +1. In another tab, initialize your Helm client: + + ```shell + export HELM_HOST="localhost:44134" + helm init --client-only + ``` + +1. Now your environment is ready to manage your apps with Helm v2. For example, to list your releases: + + ```shell + helm ls + ``` + +### Cluster integrations + +Some applications were not only installed in your cluster by GitLab through Managed Apps but were also +directly integrated with GitLab so that you could benefit from seeing, controlling, or getting notified +about them through GitLab. +To keep them integrated, read the documentation for: + +- [Prometheus cluster integration](integrations.md#prometheus-cluster-integration) +- [Elastic Stack cluster integration](integrations.md#elastic-stack-cluster-integration) diff --git a/doc/user/clusters/img/applications_tab_v13_12.png b/doc/user/clusters/img/applications_tab_v13_12.png Binary files differnew file mode 100644 index 00000000000..c4f1a8862e8 --- /dev/null +++ b/doc/user/clusters/img/applications_tab_v13_12.png diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md index 74c48d1a010..a8b181f8726 100644 --- a/doc/user/clusters/integrations.md +++ b/doc/user/clusters/integrations.md @@ -10,7 +10,9 @@ GitLab provides several ways to integrate applications to your Kubernetes cluster. To enable cluster integrations, first add a Kubernetes cluster to a GitLab -[project](../project/clusters/add_remove_clusters.md) or [group](../group/clusters/index.md#group-level-kubernetes-clusters). +[project](../project/clusters/add_remove_clusters.md) or +[group](../group/clusters/index.md#group-level-kubernetes-clusters) or +[instance](../instance/clusters/index.md). ## Prometheus cluster integration @@ -20,30 +22,33 @@ You can integrate your Kubernetes cluster with [Prometheus](https://prometheus.io/) for monitoring key metrics of your apps directly from the GitLab UI. -Once enabled, you will see metrics from services available in the +[Alerts](../../operations/metrics/alerts.md) can be configured the same way as +for [external Prometheus instances](../../operations/metrics/alerts.md#external-prometheus-instances). + +Once enabled, you can see metrics from services available in the [metrics library](../project/integrations/prometheus_library/index.md). -Prerequisites: +### Prometheus Prerequisites -To benefit from this integration, you must have Prometheus -installed in your cluster with the following requirements: +To use this integration: -1. Prometheus must be installed inside the `gitlab-managed-apps` namespace. +1. Prometheus must be installed in your cluster in the `gitlab-managed-apps` namespace. 1. The `Service` resource for Prometheus must be named `prometheus-prometheus-server`. -You can use the following commands to install Prometheus to meet the requirements for cluster integrations: +You can manage your Prometheus however you like, but as an example, you can set +it up using [Helm](https://helm.sh/) as follows: ```shell -# Create the require Kubernetes namespace +# Create the required Kubernetes namespace kubectl create ns gitlab-managed-apps # Download Helm chart values that is compatible with the requirements above. -# You should substitute the tag that corresponds to the GitLab version in the url +# You should substitute the tag that corresponds to the GitLab version in the URL # - https://gitlab.com/gitlab-org/gitlab/-/raw/<tag>/vendor/prometheus/values.yaml # wget https://gitlab.com/gitlab-org/gitlab/-/raw/v13.9.0-ee/vendor/prometheus/values.yaml -# Add the Prometheus community helm repo +# Add the Prometheus community Helm chart repository helm repo add prometheus-community https://prometheus-community.github.io/helm-charts # Install Prometheus @@ -62,6 +67,65 @@ To enable the Prometheus integration for your cluster: **Operations > Kubernetes**. - For a [group-level cluster](../group/clusters/index.md), navigate to your group's **Kubernetes** page. + - For an [instance-level cluster](../instance/clusters/index.md), navigate to your instance's + **Kubernetes** page. +1. Select the **Integrations** tab. +1. Check the **Enable Prometheus integration** checkbox. +1. Click **Save changes**. +1. Go to the **Health** tab to see your cluster's metrics. + +## Elastic Stack cluster integration + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61077) in GitLab 13.12. + +You can integrate your cluster with [Elastic +Stack](https://www.elastic.co/elastic-stack) to index and [query your pod +logs](../project/clusters/kubernetes_pod_logs.md). + +### Elastic Stack Prerequisites + +To use this integration: + +1. Elasticsearch 7.x or must be installed in your cluster in the + `gitlab-managed-apps` namespace. +1. The `Service` resource must be called `elastic-stack-elasticsearch-master` + and expose the Elasticsearch API on port `9200`. +1. The logs are expected to be [Filebeat container logs](https://www.elastic.co/guide/en/beats/filebeat/7.x/filebeat-input-container.html) + following the [7.x log structure](https://www.elastic.co/guide/en/beats/filebeat/7.x/exported-fields-log.html) + and include [Kubernetes metadata](https://www.elastic.co/guide/en/beats/filebeat/7.x/add-kubernetes-metadata.html). + +You can manage your Elastic Stack however you like, but as an example, you can +use [this Elastic Stack chart](https://gitlab.com/gitlab-org/charts/elastic-stack) to get up and +running: + +```shell +# Create the required Kubernetes namespace +kubectl create namespace gitlab-managed-apps + +# Download Helm chart values that is compatible with the requirements above. +# You should substitute the tag that corresponds to the GitLab version in the URL +# - https://gitlab.com/gitlab-org/gitlab/-/raw/<tag>/vendor/elastic_stack/values.yaml +# +wget https://gitlab.com/gitlab-org/gitlab/-/raw/v13.9.0-ee/vendor/elastic_stack/values.yaml + +# Add the GitLab Helm chart repository +helm repo add gitlab https://charts.gitlab.io + +# Install Elastic Stack +helm install prometheus gitlab/elastic-stack -n gitlab-managed-apps --values values.yaml +``` + +### Enable Elastic Stack integration for your cluster + +To enable the Elastic Stack integration for your cluster: + +1. Go to the cluster's page: + - For a [project-level cluster](../project/clusters/index.md), navigate to your project's + **Operations > Kubernetes**. + - For a [group-level cluster](../group/clusters/index.md), navigate to your group's + **Kubernetes** page. + - For an [instance-level cluster](../instance/clusters/index.md), navigate to your instance's + **Kubernetes** page. 1. Select the **Integrations** tab. 1. Check the **Enable Prometheus integration** checkbox. 1. Click **Save changes**. diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index da9bacc9788..e728577e194 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -20,7 +20,7 @@ privileges. This can be useful for: -- Creating pipelines to install cluster-wide applications into your cluster, see [Install using GitLab CI/CD (beta)](applications.md#install-using-gitlab-cicd) for details. +- Creating pipelines to install cluster-wide applications into your cluster, see [Install using GitLab CI/CD (beta)](applications.md#install-using-gitlab-cicd-deprecated) for details. - Any jobs that require `cluster-admin` privileges. ## Permissions diff --git a/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_11.png b/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_11.png Binary files differindex 95e176b71b8..73a5c92670a 100644 --- a/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_11.png +++ b/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_11.png diff --git a/doc/user/compliance/compliance_dashboard/index.md b/doc/user/compliance/compliance_dashboard/index.md index 8f620fe41bb..21af6387f9d 100644 --- a/doc/user/compliance/compliance_dashboard/index.md +++ b/doc/user/compliance/compliance_dashboard/index.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36524) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.8. -The Compliance Dashboard gives you the ability to see a group's Merge Request activity +The Compliance Dashboard gives you the ability to see a group's merge request activity by providing a high-level view for all projects in the group. For example, code approved for merging into production. @@ -28,10 +28,10 @@ This feature is for people who care about the compliance status of projects with You can use the dashboard to: -- Get an overview of the latest Merge Request for each project. -- See if Merge Requests were approved and by whom. -- See Merge Request authors. -- See the latest [CI Pipeline](../../../ci/pipelines/index.md) result for each Merge Request. +- Get an overview of the latest merge request for each project. +- See if merge requests were approved and by whom. +- See merge request authors. +- See the latest [CI Pipeline](../../../ci/pipelines/index.md) result for each merge request. ## Permissions @@ -42,25 +42,25 @@ You can use the dashboard to: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217939) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. -We support a separation of duties policy between users who create and approve Merge Requests. +We support a separation of duties policy between users who create and approve merge requests. The approval status column can help you identify violations of this policy. Our criteria for the separation of duties is as follows: -- [A Merge Request author is **not** allowed to approve their Merge Request](../../project/merge_requests/merge_request_approvals.md#allowing-merge-request-authors-to-approve-their-own-merge-requests) -- [A Merge Request committer is **not** allowed to approve a Merge Request they have added commits to](../../project/merge_requests/merge_request_approvals.md#prevent-approval-of-merge-requests-by-their-committers) -- [The minimum number of approvals required to merge a Merge Request is **at least** two](../../project/merge_requests/merge_request_approvals.md#approval-rules) +- [A merge request author is **not** allowed to approve their merge request](../../project/merge_requests/approvals/settings.md#prevent-authors-from-approving-their-own-work) +- [A merge request committer is **not** allowed to approve a merge request they have added commits to](../../project/merge_requests/approvals/settings.md#prevent-committers-from-approving-their-own-work) +- [The minimum number of approvals required to merge a merge request is **at least** two](../../project/merge_requests/approvals/rules.md) -The "Approval status" column shows you, at a glance, whether a Merge Request is complying with the above. +The "Approval status" column shows you, at a glance, whether a merge request is complying with the above. This column has four states: | State | Description | |:------|:------------| -| Empty | The Merge Request approval status is unknown | -|  | The Merge Request **does not** comply with any of the above criteria | -|  | The Merge Request complies with **some** of the above criteria | -|  | The Merge Request complies with **all** of the above criteria | +| Empty | The merge request approval status is unknown | +|  | The merge request **does not** comply with any of the above criteria | +|  | The merge request complies with **some** of the above criteria | +|  | The merge request complies with **all** of the above criteria | -If you do not see the success icon in your Compliance dashboard; please review the above criteria for the Merge Requests +If you do not see the success icon in your Compliance dashboard; please review the above criteria for the merge requests project to make sure it complies with the separation of duties described above. ## Chain of Custody report **(ULTIMATE)** diff --git a/doc/user/compliance/index.md b/doc/user/compliance/index.md index d31f877c418..69deefd08a7 100644 --- a/doc/user/compliance/index.md +++ b/doc/user/compliance/index.md @@ -15,3 +15,7 @@ following compliance tools are available: - [License Compliance](license_compliance/index.md): Search your project's dependencies for their licenses. This lets you determine if the licenses of your project's dependencies are compatible with your project's license. +- [Compliance framework labels](../project/settings/index.md#compliance-frameworks): Label your projects that have unique compliance requirements. +- [Compliance pipelines](../project/settings/index.md#compliance-pipeline-configuration): Ensure that needed compliance jobs are always run for compliance-labeled projects. +- [Audit Events](../../administration/audit_events.md): Get visibility into individual actions that have taken place in your GitLab instance, group, or project. +- [Audit Reports](../../administration/audit_reports.md): Create and access reports based on the audit events that have occurred. Use pre-built GitLab reports or the API to build your own. diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 823a0561beb..43dbafb8f6f 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -180,7 +180,7 @@ directory of your project. ### Overriding the template WARNING: -Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) +Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#only--except) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. If you want to override the job definition (for example, change properties like @@ -636,7 +636,7 @@ registry.gitlab.com/gitlab-org/security-products/analyzers/license-finder:latest 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. Note that these scanners are [updated periodically](../../application_security/index.md#maintenance-and-update-of-the-vulnerabilities-database) +process by which external resources can be imported or temporarily accessed. Note that these scanners are [updated periodically](../../application_security/vulnerabilities/index.md#vulnerability-scanner-maintenance) with new definitions, so consider if you are able to make periodic updates yourself. For details on saving and transporting Docker images as a file, see Docker's documentation on @@ -766,7 +766,7 @@ Defining a non-latest Python version in ASDF_PYTHON_VERSION [doesn't have it aut 1. Define the required version by setting the `ASDF_PYTHON_VERSION` CI/CD variable. 1. Pass a custom script to the `SETUP_CMD` CI/CD variable to install the required version and dependencies. -For example: +For example: ```yaml include: diff --git a/doc/user/discussions/img/mr_review_second_comment.png b/doc/user/discussions/img/mr_review_second_comment.png Binary files differdeleted file mode 100644 index f345c52e941..00000000000 --- a/doc/user/discussions/img/mr_review_second_comment.png +++ /dev/null diff --git a/doc/user/discussions/img/mr_review_second_comment_added.png b/doc/user/discussions/img/mr_review_second_comment_added.png Binary files differdeleted file mode 100644 index 61b45431c9e..00000000000 --- a/doc/user/discussions/img/mr_review_second_comment_added.png +++ /dev/null diff --git a/doc/user/discussions/img/review_comment_quickactions.png b/doc/user/discussions/img/review_comment_quickactions.png Binary files differdeleted file mode 100644 index 276def6381f..00000000000 --- a/doc/user/discussions/img/review_comment_quickactions.png +++ /dev/null diff --git a/doc/user/discussions/img/review_preview_v13_11.png b/doc/user/discussions/img/review_preview_v13_11.png Binary files differdeleted file mode 100644 index 79e33aa0991..00000000000 --- a/doc/user/discussions/img/review_preview_v13_11.png +++ /dev/null diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index aa49f9468be..50007545a65 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -91,7 +91,7 @@ current merge request. ### Marking a comment or thread as resolved -You can mark a thread as resolved by clicking the **Resolve thread** +You can mark a thread as resolved by selecting the **Resolve thread** button at the bottom of the thread.  @@ -102,8 +102,8 @@ Alternatively, you can mark each comment as resolved individually. ### Move all unresolved threads in a merge request to an issue -To continue all open threads from a merge request in a new issue, click the -**Resolve all threads in new issue** button. +To continue all open threads from a merge request in a new issue, select +**Resolve all threads in new issue**.  @@ -283,85 +283,6 @@ To create a confidential comment, select the **Make this comment confidential**  -## Merge request reviews - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in GitLab Premium 11.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/28154) to GitLab Free in 13.1. - -When looking at a merge request diff, you are able to start a review. -This allows you to create comments inside a merge request that are **only visible to you** until published, -in order to allow you to submit them all as a single action. - -### Starting a review - -To start a review, write a comment on a diff as normal under the **Changes** tab -in a merge request, and then select **Start a review**. - - - -After a review is started, any comments that are part of this review are marked `Pending`. -All comments that are part of a review show two buttons: - -- **Finish review**: Submits all comments that are part of the review, making them visible to other users. -- **Add comment now**: Submits the specific comment as a regular comment instead of as part of the review. - - - -You can use [quick actions](../project/quick_actions.md) inside review comments. The comment shows the actions to perform after publication. - - - -To add more comments to a review, start writing a comment as normal and click the **Add to review** button. - - - -This adds the comment to the review. - - - -### Resolving/Unresolving threads - -Review comments can also resolve/unresolve [resolvable threads](#resolvable-comments-and-threads). -When replying to a comment, a checkbox is displayed that you can click to resolve or unresolve -the thread after publication. - - - -If a particular pending comment resolves or unresolves the thread, this is shown on the pending -comment itself. - - - - - -### Adding a new comment - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8225) in GitLab 13.10. - -If you have a review in progress, you will be presented with the option to **Add to review**: - - - -### Submitting a review - -If you have any comments that have not been submitted, a bar displays at the -bottom of the screen with two buttons: - -- **Pending comments**: Opens a list of comments ready to be submitted for review. -- **Submit review**: Publishes all comments. Any quick actions submitted are performed at this time. - -Alternatively, to finish the entire review from a pending comment: - -- Click the **Submit review** button on the comment. -- Use the `/submit_review` [quick action](../project/quick_actions.md) in the text of non-review comment. - - - -Submitting the review sends a single email to every notifiable user of the -merge request with all the comments associated to it. - -Replying to this email will, consequentially, create a new comment on the associated merge request. - ## Filtering notes > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26723) in GitLab 11.5. @@ -382,139 +303,6 @@ After you select one of the filters in a given issue or merge request, GitLab sa your preference, so that it persists when you visit the same page again from any device you're logged into. -## Suggest Changes - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18008) in GitLab 11.6. -> - Custom commit messages for suggestions was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9 behind a [feature flag](../feature_flags.md), disabled by default. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/297404) in GitLab 13.10. - -As a reviewer, you're able to suggest code changes with a -Markdown syntax in merge request diff threads. Then, the -merge request author (or other users with appropriate -[permission](../permissions.md)) is able to apply these -Suggestions with a click, which generates a commit in -the merge request authored by the user that applied them. - -1. Choose a line of code to be changed, add a new comment, then click - on the **Insert suggestion** icon in the toolbar: - -  - -1. In the comment, add your suggestion to the pre-populated code block: - -  - -1. Click either **Start a review** or **Add to review** to add your comment to a [review](#merge-request-reviews), or **Add comment now** to add the comment to the thread immediately. - - The Suggestion in the comment can be applied by the merge request author - directly from the merge request: - -  - -1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9, - you can opt to add a custom commit message to describe your change. If you don't - specify it, the default commit message is used. It is not supported for [batch suggestions](#batch-suggestions). - -  - -After the author applies a Suggestion, it is marked with the **Applied** label, -the thread is automatically resolved, and GitLab creates a new commit -and push the suggested change directly into the codebase in the merge request's -branch. [Developer permission](../permissions.md) is required to do so. - -### Multi-line Suggestions - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10. - -Reviewers can also suggest changes to multiple lines with a single Suggestion -within merge request diff threads by adjusting the range offsets. The -offsets are relative to the position of the diff thread, and specify the -range to be replaced by the suggestion when it is applied. - - - -In the example above, the Suggestion covers three lines above and four lines -below the commented line. When applied, it would replace from 3 lines _above_ -to 4 lines _below_ the commented line, with the suggested change. - - - -NOTE: -Suggestions covering multiple lines are limited to 100 lines _above_ and 100 -lines _below_ the commented diff line, allowing up to 200 changed lines per -suggestion. - -### Code block nested in Suggestions - -If you need to make a suggestion that involves a -[fenced code block](../markdown.md#code-spans-and-blocks), wrap your suggestion in four backticks -instead of the usual three. - - - - - -### Configure the commit message for applied Suggestions - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13086) in GitLab 12.7. - -GitLab uses a default commit message -when applying Suggestions: `Apply %{suggestions_count} suggestion(s) to %{files_count} file(s)` - -For example, consider that a user applied 3 suggestions to 2 different files, the default commit message is: **Apply 3 suggestion(s) to 2 file(s)** - -These commit messages can be customized to follow any guidelines you might have. To do so, expand the **Merge requests** -tab within your project's **General** settings and change the -**Merge suggestions** text: - - - -You can also use following variables besides static text: - -| Variable | Description | Output example | -|------------------------|-------------|----------------| -| `%{branch_name}` | The name of the branch the Suggestion(s) was(were) applied to. | `my-feature-branch` | -| `%{files_count}` | The number of file(s) to which Suggestion(s) was(were) applied.| **2** | -| `%{file_paths}` | The path(s) of the file(s) Suggestion(s) was(were) applied to. Paths are separated by commas.| `docs/index.md, docs/about.md` | -| `%{project_path}` | The project path. | `my-group/my-project` | -| `%{project_name}` | The human-readable name of the project. | **My Project** | -| `%{suggestions_count}` | The number of Suggestions applied.| **3** | -| `%{username}` | The username of the user applying Suggestion(s). | `user_1` | -| `%{user_full_name}` | The full name of the user applying Suggestion(s). | **User 1** | - -For example, to customize the commit message to output -**Addresses user_1's review**, set the custom text to -`Addresses %{username}'s review`. - -NOTE: -Custom commit messages for each applied Suggestion is -introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381). - -### Batch Suggestions - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) behind a feature flag, disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. - -You can apply multiple suggestions at once to reduce the number of commits added -to your branch to address your reviewers' requests. - -1. To start a batch of suggestions to apply with a single commit, click **Add suggestion to batch**: - -  - -1. Add as many additional suggestions to the batch as you wish: - -  - -1. To remove suggestions, click **Remove from batch**: - -  - -1. Having added all the suggestions to your liking, when ready, click **Apply suggestions**: - -  - ## Start a thread by replying to a standard comment > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30299) in GitLab 11.9 @@ -525,7 +313,7 @@ To reply to a standard (non-thread) comment, you can use the **Reply to comment* The **Reply to comment** button is only displayed if you have permissions to reply to an existing thread, or start a thread from a standard comment. -Clicking on the **Reply to comment** button brings the reply area into focus and you can type your reply. +Selecting the **Reply to comment** button brings the reply area into focus and you can type your reply.  @@ -542,9 +330,9 @@ not supported yet. You can assign an issue to a user who made a comment. -In the comment, click the **More Actions** menu and click **Assign to commenting user**. +In the comment, select the **More Actions** menu, and then select **Assign to commenting user**. - Click the button again to unassign the commenter. +Select the button again to unassign the commenter.  diff --git a/doc/user/feature_flags.md b/doc/user/feature_flags.md index 5be28de4101..e05fc582dc0 100644 --- a/doc/user/feature_flags.md +++ b/doc/user/feature_flags.md @@ -3,6 +3,7 @@ stage: none group: Development info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" description: "Understand what 'GitLab features deployed behind flags' means." +layout: 'feature_flags' --- # GitLab functionality may be limited by feature flags diff --git a/doc/user/feature_highlight.md b/doc/user/feature_highlight.md index 8d452d2caf0..e5f0369a0f6 100644 --- a/doc/user/feature_highlight.md +++ b/doc/user/feature_highlight.md @@ -6,14 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Feature highlight -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/16379) in GitLab 10.5 - Feature highlights are represented by a pulsing blue dot. Hovering over the dot -displays more information. -They are used to emphasize a certain feature and make something more visible to the user. - -You can dismiss any feature highlight permanently by clicking the "Got it" link -at the bottom of the modal window. There isn't a way to restore the feature highlight -after it has been dismissed. +displays more information. They're used to emphasize certain features and +highlight helpful information to the user. - +You can dismiss any feature highlight permanently by clicking the **Got it** link +at the bottom of the information window. You cannot restore a feature highlight +after you dismiss it. diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 6e38534b044..cdb4ca52c9c 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -98,11 +98,12 @@ Any settings or feature limits not listed here are using the defaults listed in | Artifacts maximum size (compressed) | 1G | 100M | | Artifacts [expiry time](../../ci/yaml/README.md#artifactsexpire_in) | From June 22, 2020, deleted after 30 days unless otherwise specified (artifacts created before that date have no expiry). | deleted after 30 days unless otherwise specified | | Scheduled Pipeline Cron | `*/5 * * * *` | `3-59/10 * * * *` | -| [Max jobs in active pipelines](../../administration/instance_limits.md#number-of-jobs-in-active-pipelines) | `500` for Free tier, unlimited otherwise | Unlimited +| [Max jobs in active pipelines](../../administration/instance_limits.md#number-of-jobs-in-active-pipelines) | `500` for Free tier, unlimited otherwise | Unlimited | | [Max CI/CD subscriptions to a project](../../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project) | `2` | Unlimited | | [Max pipeline schedules in projects](../../administration/instance_limits.md#number-of-pipeline-schedules) | `10` for Free tier, `50` for all paid tiers | Unlimited | | [Scheduled Job Archival](../../user/admin_area/settings/continuous_integration.md#archive-jobs) | 3 months | Never | | Max test cases per [unit test report](../../ci/unit_test_reports.md) | `500_000` | Unlimited | +| [Max registered runners](../../administration/instance_limits.md#number-of-registered-runners-per-scope) | `50` per-project and per-group for Free tier,<br/>`1_000` per-group for all paid tiers / `1_000` per-project for all paid tiers | `1_000` per-group / `1_000` per-project | ## Account and limit settings @@ -115,6 +116,7 @@ or over the repository size limit, you can [reduce your repository size with Git | ----------- | ----------- | ------------- | | [Repository size including LFS](../admin_area/settings/account_and_limit_settings.md#repository-size-limit) | 10 GB | Unlimited | | Maximum import size | 5 GB | Unlimited ([Modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to unlimited in GitLab 13.8. | +| Maximum attachment size | 10 MB | 10 MB | NOTE: `git push` and GitLab project imports are limited to 5 GB per request through Cloudflare. Git LFS and imports other than a file upload are not affected by this limit. diff --git a/doc/user/group/bulk_editing/img/bulk-editing_v13_2.png b/doc/user/group/bulk_editing/img/bulk-editing_v13_2.png Binary files differdeleted file mode 100644 index 9f28fabdf0c..00000000000 --- a/doc/user/group/bulk_editing/img/bulk-editing_v13_2.png +++ /dev/null diff --git a/doc/user/group/bulk_editing/index.md b/doc/user/group/bulk_editing/index.md index aa356bee8e3..48644b7427d 100644 --- a/doc/user/group/bulk_editing/index.md +++ b/doc/user/group/bulk_editing/index.md @@ -1,79 +1,8 @@ --- -stage: Plan -group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: '../../../user/group/index.md' --- -# Bulk editing issues, epics, and merge requests at the group level **(PREMIUM)** +This document was moved to [another location](../../../user/group/index.md). -NOTE: -Bulk editing issues and merge requests is also available at the **project level**. -For more details, see [Bulk editing issues and merge requests at the project level](../../project/bulk_editing.md). - -If you want to update attributes across multiple issues, epics, or merge requests in a group, you -can do it by bulk editing them, that is, editing them together. - -Only the items visible on the current page are selected for bulk editing (up to 20). - - - -## Bulk edit issues at the group level - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7249) in GitLab 12.1. -> - Assigning epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. -> - Editing health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in GitLab 13.2. -> - Editing iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196806) in GitLab 13.9. - -Users with permission level of [Reporter or higher](../../permissions.md) can manage issues. - -When bulk editing issues in a group, you can edit the following attributes: - -- [Epic](../epics/index.md) -- [Milestone](../../project/milestones/index.md) -- [Labels](../../project/labels.md) -- [Health status](../../project/issues/managing_issues.md#health-status) -- [Iteration](../iterations/index.md) - -To update multiple project issues at the same time: - -1. In a group, go to **{issues}** **Issues > List**. -1. Click **Edit issues**. A sidebar on the right-hand side of your screen appears with editable fields. -1. Select the checkboxes next to each issue you want to edit. -1. Select the appropriate fields and their values from the sidebar. -1. Click **Update all**. - -## Bulk edit epics - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7250) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. - -Users with permission level of [Reporter or higher](../../permissions.md) can manage epics. - -When bulk editing epics in a group, you can edit their labels. - -To update multiple epics at the same time: - -1. In a group, go to **{epic}** **Epics > List**. -1. Click **Edit epics**. A sidebar on the right-hand side of your screen appears with editable fields. -1. Check the checkboxes next to each epic you want to edit. -1. Select the appropriate fields and their values from the sidebar. -1. Click **Update all**. - -## Bulk edit merge requests at the group level - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12719) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. - -Users with permission level of [Developer or higher](../../permissions.md) can manage merge requests. - -When bulk editing merge requests in a group, you can edit the following attributes: - -- Milestone -- Labels - -To update multiple group merge requests at the same time: - -1. In a group, go to **{merge-request}** **Merge Requests**. -1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with - editable fields. -1. Select the checkboxes next to each merge request you want to edit. -1. Select the appropriate fields and their values from the sidebar. -1. Click **Update all**. +<!-- This redirect file can be deleted after <2021-08-13>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index 09e899a61ba..12d7eaf2f12 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -6,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w --- # Contribution Analytics **(PREMIUM)** -> - Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3090) for subgroups in GitLab 12.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3090) in GitLab 12.2 for subgroups. With Contribution Analytics you can get an overview of the following activity in your group: @@ -16,8 +15,7 @@ group: - Merge requests - Push events -To view the Contribution Analytics, go to your group's **Analytics > Contribution Analytics** -page. +To view the Contribution Analytics, go to your group and select **Analytics > Contribution**. ## Use cases diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md index 920421ef9bb..5a23e1559bc 100644 --- a/doc/user/group/devops_adoption/index.md +++ b/doc/user/group/devops_adoption/index.md @@ -6,33 +6,36 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Group DevOps Adoption **(ULTIMATE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321083) in GitLab 13.11. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321083) in GitLab 13.11 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). > - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. -> - Disabled on GitLab.com. -> - Not recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-group-devops-adoption). +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/323159) in GitLab 13.12. +> - Enabled on GitLab.com. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-group-devops-adoption). **(ULTIMATE SELF)** -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../../feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321083) in GitLab 13.11 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). +Prerequisites: -To access Group DevOps Adoption, navigate to your group sidebar and select **Analytics > DevOps Adoption** +- A minimum of [Reporter access](../../permissions.md) to the group. + +To access Group DevOps Adoption, go to your group and select **Analytics > DevOps Adoption**. Group DevOps Adoption shows you how individual groups and sub-groups within your organization use the following features: +- Approvals +- Deployments - Issues - Merge Requests -- Approvals -- Runners - Pipelines -- Deployments +- Runners - Scans When managing groups in the UI, you can manage your sub-groups with the **Add/Remove sub-groups** button, in the top right hand section of your Groups pages. -DevOps Adoption allows you to: +With DevOps Adoption you can: - Verify whether you are getting the return on investment that you expected from GitLab. - Identify specific sub-groups that are lagging in their adoption of GitLab so you can help them along in their DevOps journey. @@ -40,21 +43,79 @@ DevOps Adoption allows you to:  -## Enable or disable Group DevOps Adoption **(ULTIMATE)** +## Enable data processing + +Group DevOps Adoption relies on data that has been gathered by a weekly data processing task. +This task is disabled by default. + +To begin using Group DevOps Adoption, access the feature for the first time. GitLab automatically +enables the data processing for that group. The group data doesn't appear immediately, because +GitLab requires around a minute to process it. + +## What is displayed + +DevOps Adoption displays feature adoption data for the given group +and any added sub-groups for the current calendar month. +Each group appears as a separate row in the table. +For each row, a feature is considered "adopted" if it has been used in a project in the given group +during the time period (including projects in any sub-groups of the given group). + +You should expect adoption to be lower at the beginning of the month, +before you have had an opportunity to use all the features listed in the table. + +In the future [we plan to implement](https://gitlab.com/gitlab-org/gitlab/-/issues/329708) +a rolling 30-day perspective instead. + +## When is a feature considered adopted + +A feature is considered "adopted" if it has been used anywhere in the group in the specified time. +For example, if an issue was created in one project in a group, the group is considered to have +"adopted" issues in that time. + +## No penalties for common adoption patterns + +DevOps Adoption is designed not to penalize for any circumstances or practices that are common in DevOps. +Following this guideline, GitLab doesn't penalize for: + +1. Having dormant projects. It's common for groups to have a mix of active and dormant projects, + so we should not consider adoption to be low if there are relatively many dormant projects. + This means we should not measure adoption by how many projects in the group have used a feature, + only by whether a feature was used anywhere in the group. +1. GitLab adding new features over time. It's common for group feature usage to be consistent + over time, so we should not consider adoption to have decreased if GitLab adds features. + This means we should not measure adoption by percentages, only total counts. + +## Add a sub-group + +DevOps Adoption can also display data for sub-groups within the given group, +to show you differences in adoption across the group. +To add a sub-group to your Group DevOps Adoption report: + +1. Select **Add/remove sub-groups**. +1. Select the sub-group you want to add and select **Save changes**. + +The sub-group data might not appear immediately, because GitLab requires around a minute to collect +the data. + +Please note that the sub-group data might not appear immediately, +because GitLab requires a few moments to collect the data. +Generally the data will be visible in less than one minute. + +## Enable or disable Group DevOps Adoption **(ULTIMATE SELF)** Group DevOps Adoption is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. +deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. +can disable it. -To enable it: +To disable it: ```ruby -Feature.enable(:group_devops_adoption) +Feature.disable(:group_devops_adoption) ``` -To disable it: +To re-enable it: ```ruby -Feature.disable(:group_devops_adoption) +Feature.enable(:group_devops_adoption) ``` diff --git a/doc/user/group/epics/img/epic_board_v13_10.png b/doc/user/group/epics/img/epic_board_v13_10.png Binary files differindex 5a14d9288d3..85a131ea605 100644 --- a/doc/user/group/epics/img/epic_board_v13_10.png +++ b/doc/user/group/epics/img/epic_board_v13_10.png diff --git a/doc/user/group/epics/img/epic_view_roadmap_v12_9.png b/doc/user/group/epics/img/epic_view_roadmap_v12_9.png Binary files differindex 035adc5e7ac..e8224ced7e9 100644 --- a/doc/user/group/epics/img/epic_view_roadmap_v12_9.png +++ b/doc/user/group/epics/img/epic_view_roadmap_v12_9.png diff --git a/doc/user/group/epics/img/epic_view_v13.0.png b/doc/user/group/epics/img/epic_view_v13.0.png Binary files differdeleted file mode 100644 index b25a91d318a..00000000000 --- a/doc/user/group/epics/img/epic_view_v13.0.png +++ /dev/null diff --git a/doc/user/group/epics/img/new_epic_from_groups_v13.7.png b/doc/user/group/epics/img/new_epic_from_groups_v13.7.png Binary files differdeleted file mode 100644 index 3607d5c7a3f..00000000000 --- a/doc/user/group/epics/img/new_epic_from_groups_v13.7.png +++ /dev/null diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 12377b3926d..0608ff38db1 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -8,57 +8,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Epics **(PREMIUM)** > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.2. -> - Single-level Epics [were moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8. +> - Single-level epics [were moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8. -Epics let you manage your portfolio of projects more efficiently by tracking groups of [issues](../../project/issues/index.md) -that share a theme across projects and milestones. +When [issues](../../project/issues/index.md) share a theme across projects and milestones, +you can manage them by using epics. -An epic's page contains the following tabs: +You can also create child epics, and assign start and end dates, +which creates a visual roadmap for you to view progress. -- **Issues**: issues added to this epic. -- **Epics and Issues**: epics and issues added to this epic. - Appears instead of the **Issues** tab if you have access to [multi-level epics](#multi-level-child-epics). - Child epics and their issues are shown in a tree view. +Use epics: - - To reveal the child epics and issues, select the chevron (**>**) next to a parent epic. - - To see a breakdown of open and closed items, hover over the total counts. - - The number provided here includes all epics associated with this project. The number includes - epics for which users may not yet have permission. - -- [**Roadmap**](#roadmap-in-epics): a roadmap view of child epics which have start and due dates. - Appears if you have access to [multi-level epics](#multi-level-child-epics). - - - -## Use cases - -- Suppose your team is working on a large feature that involves multiple discussions throughout different issues created in distinct projects within a [Group](../index.md). With Epics, you can track all the related activities that together contribute to that single feature. -- Track when the work for the group of issues is targeted to begin, and when it's targeted to end. -- Discuss and collaborate on feature ideas and scope at a high level. - -## Manage epics - -To learn what you can do with an epic, see [Manage epics](manage_epics.md). Possible actions include: - -- [Create an epic](manage_epics.md#create-an-epic) -- [Edit an epic](manage_epics.md#edit-an-epic) -- [Bulk-edit epics](../bulk_editing/index.md#bulk-edit-epics) -- [Delete an epic](manage_epics.md#delete-an-epic) -- [Close an epic](manage_epics.md#close-an-epic) -- [Reopen a closed epic](manage_epics.md#reopen-a-closed-epic) -- [Go to an epic from an issue](manage_epics.md#go-to-an-epic-from-an-issue) -- [Search for an epic from epics list page](manage_epics.md#search-for-an-epic-from-epics-list-page) -- [Make an epic confidential](manage_epics.md#make-an-epic-confidential) -- [Manage issues assigned to an epic](manage_epics.md#manage-issues-assigned-to-an-epic) -- [Manage multi-level child epics **(ULTIMATE)**](manage_epics.md#manage-multi-level-child-epics) +- When your team is working on a large feature that involves multiple discussions + in different issues in different projects in a [group](../index.md). +- To track when the work for the group of issues is targeted to begin and end. +- To discuss and collaborate on feature ideas and scope at a high level. ## Relationships between epics and issues The possible relationships between epics and issues are: - An epic is the parent of one or more issues. -- An epic is the parent of one or more child epics. For details see [Multi-level child epics](#multi-level-child-epics). **(ULTIMATE)** +- An epic is the parent of one or more child epics. For details see [Multi-level child epics](manage_epics.md#multi-level-child-epics). ```mermaid graph TD @@ -67,72 +37,13 @@ graph TD Child_epic --> Issue2 ``` -See [Manage issues assigned to an epic](manage_epics.md#manage-issues-assigned-to-an-epic) for steps -to: - -- Add an issue to an epic -- Reorder issues -- Move an issue between epics -- Promote an issue to an epic - -## Issue health status in Epic tree **(ULTIMATE)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199184) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. -> - The health status of a closed issue [is hidden](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3 or later. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7. - -Report or respond to the health of issues and epics by setting a red, amber, or green [health status](../../project/issues/managing_issues.md#health-status), which then appears on your Epic tree. - -## Multi-level child epics **(ULTIMATE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8333) in GitLab Ultimate 11.7. - -Any epic that belongs to a group, or subgroup of the parent epic's group, is eligible to be added. -New child epics appear at the top of the list of epics in the **Epics and Issues** tab. - -When you add an epic that's already linked to a parent epic, the link to its current parent is removed. - -An epic can have multiple child epics up to the maximum depth of seven. - -See [Manage multi-level child epics](manage_epics.md#manage-multi-level-child-epics) for -steps to create, move, reorder, or delete child epics. - -## Start date and due date - -To set a **Start date** and **Due date** for an epic, select one of the following: - -- **Fixed**: enter a fixed value. -- **Inherited**: inherit a dynamic value from the epic's issues, child epics, and milestones. - -### Inherited - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones**. - -If you select **Inherited**: - -- For the **start date**: GitLab scans all child epics and issues assigned to the epic, - and sets the start date to match the earliest found start date or milestone. -- For the **due date**: GitLab sets the due date to match the latest due date or - milestone found among its child epics and issues. - -These are dynamic dates and recalculated if any of the following occur: - -- A child epic's dates change. -- Milestones are reassigned to an issue. -- A milestone's dates change. -- Issues are added to, or removed from, the epic. - -Because the epic's dates can inherit dates from its children, the start date and due date propagate from the bottom to the top. -If the start date of a child epic on the lowest level changes, that becomes the earliest possible start date for its parent epic. -The parent epic's start date then reflects this change and propagates upwards to the top epic. - ## Roadmap in epics **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7327) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.10. -If your epic contains one or more [child epics](#multi-level-child-epics) which -have a [start or due date](#start-date-and-due-date), a -[roadmap](../roadmap/index.md) view of the child epics is listed under the parent epic. +If your epic contains one or more [child epics](manage_epics.md#multi-level-child-epics) that +have a start or due date, a visual +[roadmap](../roadmap/index.md) of the child epics is listed under the parent epic.  @@ -144,45 +55,19 @@ epic's issue list. If you have access to edit an epic and an issue added to that epic, you can add the issue to or remove it from the epic. -Note that for a given group, the visibility of all projects must be the same as +For a given group, the visibility of all projects must be the same as the group, or less restrictive. That means if you have access to a group's epic, then you already have access to its projects' issues. You can also consult the [group permissions table](../../permissions.md#group-members-permissions). -## Thread - -- Comments: collaborate on that epic by posting comments in its thread. - These text fields also fully support - [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown). - -## Comment or start a thread - -Once you write your comment, you can either: - -- Click **Comment** to publish your comment. -- Click **Start thread** to start a thread within that epic's discussion. - -### Activity sort order - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214364) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. - -You can reverse the default order and interact with the activity feed sorted by most recent items -at the top. Your preference is saved via local storage and automatically applied to every issue -you view. - -To change the activity sort order, click the **Oldest first** dropdown menu and select either oldest -or newest items to be shown first. - - - -## Award emoji - -You can [award an emoji](../../award_emojis.md) to that epic or its comments. - -## Notifications +## Related topics -You can [turn on notifications](../../profile/notifications.md) to be alerted about epic events. +- [Manage epics](manage_epics.md) and multi-level child epics. +- [Turn on notifications](../../profile/notifications.md) for about epic events. +- [Award an emoji](../../award_emojis.md) to an epic or its comments. +- Collaborate on an epic by posting comments in a [thread](../../discussions/index.md). +- Use [health status](../../project/issues/managing_issues.md#health-status) to track your progress. <!-- ## Troubleshooting diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 1999e5ba214..7bb021b4b1f 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -16,28 +16,46 @@ to them. > - The New Epic form [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211533) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. > - In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/229621) and later, the New Epic button on the Epics list opens the New Epic form. -> - In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45948) and later, you can create a new epic from an empty Roadmap. +> - In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45948) and later, you can create a new epic from an empty roadmap. To create an epic in the group you're in: 1. Get to the New Epic form: - - From the **Epics** list in your group, select **New epic**. + - Go to your group and from the left sidebar select **Epics**. Then select **New epic**. - From an epic in your group, select **New epic**. - From anywhere, in the top menu, select **New...** (**{plus-square}**) **> New epic**. - In an empty [roadmap](../roadmap/index.md), select **New epic**. -  +1. Enter a title. +1. Optional. Enter a description. +1. Optional. To make the epic confidential, select the [Confidentiality checkbox](#make-an-epic-confidential). +1. Optional. Choose labels. +1. Optional. Select a start and due date, or [inherit](#start-and-due-date-inheritance) them. +1. Select **Create epic**. -1. Fill in these fields: +The newly created epic opens. - - Title - - Description - - [Confidentiality checkbox](#make-an-epic-confidential) - - Labels - - Start date - - Due date +### Start and due date inheritance -1. Select **Create epic**. You are taken to view the newly created epic. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones**. + +If you select **Inherited**: + +- For the **start date**: GitLab scans all child epics and issues assigned to the epic, + and sets the start date to match the earliest found start date or milestone. +- For the **due date**: GitLab sets the due date to match the latest due date or + milestone found among its child epics and issues. + +These are dynamic dates and recalculated if any of the following occur: + +- A child epic's dates change. +- Milestones are reassigned to an issue. +- A milestone's dates change. +- Issues are added to, or removed from, the epic. + +Because the epic's dates can inherit dates from its children, the start date and due date propagate from the bottom to the top. +If the start date of a child epic on the lowest level changes, that becomes the earliest possible start date for its parent epic. +The parent epic's start date then reflects this change and propagates upwards to the top epic. ## Edit an epic @@ -55,15 +73,26 @@ To edit an epic's title or description: 1. Make your changes. 1. Select **Save changes**. -To edit an epics' start date, due date, or labels: +To edit an epic's start date, due date, or labels: 1. Select **Edit** next to each section in the epic sidebar. 1. Select the dates or labels for your epic. -## Bulk-edit epics +## Bulk edit epics + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7250) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. -You can edit multiple epics at once. To learn how to do it, visit -[Bulk editing issues, epics, and merge requests at the group level](../bulk_editing/index.md#bulk-edit-epics). +Users with permission level of [Reporter or higher](../../permissions.md) can manage epics. + +When bulk editing epics in a group, you can edit their labels. + +To update multiple epics at the same time: + +1. In a group, go to **Epics > List**. +1. Click **Edit epics**. A sidebar on the right-hand side of your screen appears with editable fields. +1. Check the checkboxes next to each epic you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. ## Delete an epic @@ -140,6 +169,19 @@ The sort option and order is saved and used wherever you browse epics, including  +## Change activity sort order + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214364) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. + +You can reverse the default order and interact with the activity feed sorted by most recent items +at the top. Your preference is saved via local storage and automatically applied to every epic and issue +you view. + +To change the activity sort order, click the **Oldest first** dropdown menu and select either oldest +or newest items to be shown first. + + + ## Make an epic confidential > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213068) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0 behind a feature flag, disabled by default. @@ -162,6 +204,13 @@ To make an epic confidential: This section collects instructions for all the things you can do with [issues](../../project/issues/index.md) in relation to epics. +### View count of issues in an epic + +On the **Epics and Issues** tab, under each epic name, hover over the total counts. + +The number indicates all epics associated with the project, including issues +you might not have permission to. + ### Add a new issue to an epic You can add an existing issue to an epic, or create a new issue that's @@ -275,7 +324,16 @@ For an introduction to epic templates, see [GitLab Epics and Epic Template Tip]( For more on epic templates, see [Epic Templates - Repeatable sets of issues](https://about.gitlab.com/handbook/marketing/strategic-marketing/getting-started/104/). -## Manage multi-level child epics **(ULTIMATE)** +## Multi-level child epics **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8333) in GitLab Ultimate 11.7. + +You can add any epic that belongs to a group or subgroup of the parent epic's group. +New child epics appear at the top of the list of epics in the **Epics and Issues** tab. + +When you add an epic that's already linked to a parent epic, the link to its current parent is removed. + +Epics can contain multiple nested child epics, up to a total of seven levels deep. ### Add a child epic to an epic diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index e84e35607e3..14464ff1a5f 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -8,13 +8,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import groups from another instance of GitLab **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/249160) in GitLab 13.7. -> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - It's enabled on GitLab.com. - -## Overview +> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - Enabled on GitLab.com. WARNING: -This feature is [under construction](https://gitlab.com/groups/gitlab-org/-/epics/2771) and currently migrates only some of the Group data. Please see below for the full list of what is included in the migration at this time. +This feature is [under construction](https://gitlab.com/groups/gitlab-org/-/epics/2771), and migrates only some of the group data. Refer to the following information for the list of what's included in the migration. Using GitLab Group Migration, you can migrate existing top-level groups from GitLab.com or a self-managed instance. Groups can be migrated to a target instance, as a top-level group, or as a subgroup of any existing top-level group. diff --git a/doc/user/group/index.md b/doc/user/group/index.md index d070277beed..7f2e502b94b 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -216,9 +216,8 @@ There are two different ways to add a new project to a group: ### Specify who can add projects to a group -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2534) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.5. -> - Brought to [GitLab Starter](https://about.gitlab.com/pricing/) in 10.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25975) to [GitLab Free](https://about.gitlab.com/pricing/) in 11.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2534) in GitLab Premium 10.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25975) to GitLab Free in 11.10. By default, [Developers and Maintainers](../permissions.md#group-members-permissions) can create projects under a group. @@ -233,7 +232,7 @@ To change this setting globally, see [Default project creation protection](../ad ## Group activity analytics **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207164) in GitLab [Starter](https://about.gitlab.com/pricing/) 12.10 as +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207164) in GitLab 12.10 as a [beta feature](https://about.gitlab.com/handbook/product/#beta). For a group, you can view how many merge requests, issues, and members were created in the last 90 days. @@ -262,7 +261,7 @@ In GitLab 13.11, you can [replace this form with a modal window](#share-a-group- Similar to how you [share a project with a group](../project/members/share_project_with_groups.md), you can share a group with another group. Members get direct access -to the shared group. This is not valid for inherited members. +to the shared group. This includes members who inherited group membership from a parent group. To share a given group, for example, `Frontend` with another group, for example, `Engineering`: @@ -577,7 +576,8 @@ To disable group mentions: ## Enable delayed project removal **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. +> - [Inheritance and enforcement added](https://gitlab.com/gitlab-org/gitlab/-/issues/321724) in GitLab 13.11. By default, projects in a group are deleted immediately. Optionally, on [Premium](https://about.gitlab.com/pricing/) or higher tiers, @@ -591,10 +591,11 @@ To enable delayed deletion of projects: 1. Go to the group's **Settings > General** page. 1. Expand the **Permissions, LFS, 2FA** section. 1. Check **Enable delayed project removal**. +1. Optional. To prevent subgroups from changing this setting, select **Enforce for all subgroups**. 1. Select **Save changes**. NOTE: -The group setting for delayed deletion is not inherited by subgroups and has to be individually defined for each group. +In GitLab 13.11 and above the group setting for delayed project removal is inherited by subgroups. As discussed in [Cascading settings](../../development/cascading_settings.md) inheritance can be overridden, unless enforced by an ancestor. ## Prevent project forking outside group **(PREMIUM)** @@ -617,7 +618,7 @@ To enable prevent project forking: ## Group push rules **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34370) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.8. +> - [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. Group push rules allow group maintainers to set @@ -643,9 +644,6 @@ The group's new subgroups have push rules set for them based on either: and issues) of group members. **(PREMIUM)** - [Issue analytics](issues_analytics/index.md): View a bar chart of your group's number of issues per month. **(PREMIUM)** - Use GitLab as a [dependency proxy](../packages/dependency_proxy/index.md) for upstream Docker images. -- [DORA4 Project Analytics API](../../api/dora4_group_analytics.md): View deployment frequency analytics. - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291747) in GitLab Ultimate 13.9 as a - [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). **(ULTIMATE SELF)** - [Epics](epics/index.md): Track groups of issues that share a theme. **(ULTIMATE)** - [Security Dashboard](../application_security/security_dashboard/index.md): View the vulnerabilities of all the projects in a group and its subgroups. **(ULTIMATE)** diff --git a/doc/user/group/insights/img/insights_example_stacked_bar_chart_v13_11.png b/doc/user/group/insights/img/insights_example_stacked_bar_chart_v13_11.png Binary files differindex 1ef49191a13..ff18a3e86a5 100644 --- a/doc/user/group/insights/img/insights_example_stacked_bar_chart_v13_11.png +++ b/doc/user/group/insights/img/insights_example_stacked_bar_chart_v13_11.png diff --git a/doc/user/group/issues_analytics/img/issues_created_per_month_v12_8.png b/doc/user/group/issues_analytics/img/issues_created_per_month_v12_8.png Binary files differdeleted file mode 100644 index fccfa949779..00000000000 --- a/doc/user/group/issues_analytics/img/issues_created_per_month_v12_8.png +++ /dev/null diff --git a/doc/user/group/issues_analytics/img/issues_created_per_month_v12_8_a.png b/doc/user/group/issues_analytics/img/issues_created_per_month_v12_8_a.png Binary files differnew file mode 100644 index 00000000000..5994cbfa401 --- /dev/null +++ b/doc/user/group/issues_analytics/img/issues_created_per_month_v12_8_a.png diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index 97f62becdb6..20b8e4b0583 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -31,7 +31,7 @@ You can change the total number of months displayed by setting a URL parameter. For example, `https://gitlab.com/groups/gitlab-org/-/issues_analytics?months_back=15` shows a total of 15 months for the chart in the GitLab.org group. - + ## Drill into the information diff --git a/doc/user/group/roadmap/img/roadmap_filters_v13_11.png b/doc/user/group/roadmap/img/roadmap_filters_v13_11.png Binary files differindex d2a76b4edce..e45c7b2b5dd 100644 --- a/doc/user/group/roadmap/img/roadmap_filters_v13_11.png +++ b/doc/user/group/roadmap/img/roadmap_filters_v13_11.png diff --git a/doc/user/group/roadmap/img/roadmap_view_v13_2.png b/doc/user/group/roadmap/img/roadmap_view_v13_2.png Binary files differindex b4f889afaa4..94cf2258569 100644 --- a/doc/user/group/roadmap/img/roadmap_view_v13_2.png +++ b/doc/user/group/roadmap/img/roadmap_view_v13_2.png diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md index a9b1901bc8c..d62b569a795 100644 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ b/doc/user/group/saml_sso/group_managed_accounts.md @@ -104,9 +104,11 @@ This expiration date is not a requirement, and can be set to any arbitrary date. Since personal access tokens are the only token needed for programmatic access to GitLab, organizations with security requirements may want to enforce more protection to require regular rotation of these tokens. -### Setting a limit +### Set a limit -Only a GitLab administrator or an owner of a group-managed account can set a limit. When this field is left empty, the [instance-level restriction](../../admin_area/settings/account_and_limit_settings.md#limiting-lifetime-of-personal-access-tokens) on the lifetime of personal access tokens apply. +Only a GitLab administrator or an owner of a group-managed account can set a limit. When this field +is left empty, the [instance-level restriction](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-personal-access-tokens) +on the lifetime of personal access tokens apply. To set a limit on how long personal access tokens are valid for users in a group managed account: diff --git a/doc/user/group/saml_sso/img/group_saml_settings_v13_12.png b/doc/user/group/saml_sso/img/group_saml_settings_v13_12.png Binary files differnew file mode 100644 index 00000000000..2271f281655 --- /dev/null +++ b/doc/user/group/saml_sso/img/group_saml_settings_v13_12.png diff --git a/doc/user/group/saml_sso/img/group_saml_settings_v13_3.png b/doc/user/group/saml_sso/img/group_saml_settings_v13_3.png Binary files differdeleted file mode 100644 index f6450c7c1ba..00000000000 --- a/doc/user/group/saml_sso/img/group_saml_settings_v13_3.png +++ /dev/null diff --git a/doc/user/group/saml_sso/img/saml_group_links_nav_v13_6.png b/doc/user/group/saml_sso/img/saml_group_links_nav_v13_6.png Binary files differdeleted file mode 100644 index c1980b24a6d..00000000000 --- a/doc/user/group/saml_sso/img/saml_group_links_nav_v13_6.png +++ /dev/null diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index f2f28046443..1864547c57f 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -66,6 +66,9 @@ the user details need to be passed to GitLab as SAML assertions. At a minimum, the user's email address *must* be specified as an assertion named `email` or `mail`. See [the assertions list](../../../integration/saml.md#assertions) for other available claims. +NOTE: +The `username` assertion is not supported for GitLab.com SaaS integrations. + ### Metadata configuration GitLab provides metadata XML that can be used to configure your identity provider. @@ -82,21 +85,21 @@ After you set up your identity provider to work with GitLab, you must configure 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. 1. Select the access level to be applied to newly added users in the **Default membership role** field. The default access level is 'Guest'. -1. Select the **Enable SAML authentication for this group** toggle switch. +1. Select the **Enable SAML authentication for this group** checkbox. 1. Select the **Save changes** button. - + NOTE: Please note that the certificate [fingerprint algorithm](../../../integration/saml.md#notes-on-configuring-your-identity-provider) must be in SHA1. When configuring the identity provider, use a secure signature algorithm. ### SSO enforcement -- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5291) in GitLab 11.8. -- [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9255) in GitLab 11.11 with ongoing enforcement in the GitLab UI. -- [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/292811) in GitLab 13.8, with an updated timeout experience. -- [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/211962) in GitLab 13.8 with allowing group owners to not go through SSO. -- [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9152) in GitLab 13.11 with enforcing open SSO session to use Git if this setting is switched on. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5291) in GitLab 11.8. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9255) in GitLab 11.11 with ongoing enforcement in the GitLab UI. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/292811) in GitLab 13.8, with an updated timeout experience. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/211962) in GitLab 13.8 with allowing group owners to not go through SSO. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9152) in GitLab 13.11 with enforcing open SSO session to use Git if this setting is switched on. With this option enabled, users (except owners) must go through your group's GitLab single sign-on URL if they wish to access group resources through the UI. Users can't be manually added as members. @@ -322,11 +325,9 @@ Ensure your SAML identity provider sends an attribute statement named `Groups` o ``` When SAML SSO is enabled for the top-level group, `Maintainer` and `Owner` level users -see a new menu item in group **Settings -> SAML Group Links**. Each group (parent or subgroup) can specify +see a new menu item in group **Settings > SAML Group Links**. Each group (parent or subgroup) can specify one or more group links to map a SAML identity provider group name to a GitLab access level. - - To link the SAML `Freelancers` group in the attribute statement example above: 1. Enter `Freelancers` in the `SAML Group Name` field. diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 7bf54aea60e..65b3e2d095d 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -71,7 +71,7 @@ your SAML configuration differs from [the recommended SAML settings](index.md#az modify the corresponding `customappsso` settings accordingly. If a mapping is not listed in the table, use the Azure defaults. -| Azure Active Directory Attribute | customappsso Attribute | Matching precedence | +| Azure Active Directory Attribute | `customappsso` Attribute | Matching precedence | | -------------------------------- | ---------------------- | -------------------- | | `objectId` | `externalId` | 1 | | `userPrincipalName` | `emails[type eq "work"].value` | | @@ -129,11 +129,11 @@ configuration. Otherwise, the Okta SCIM app may not work properly. - For **API Token** enter the SCIM token obtained from the GitLab SCIM configuration page 1. Click 'Test API Credentials' to verify configuration. 1. Click **Save** to apply the settings. -1. After saving the API integration details, new settings tabs will appear on the left. Choose **To App**. +1. After saving the API integration details, new settings tabs appear on the left. Choose **To App**. 1. Click **Edit**. 1. Check the box to **Enable** for both **Create Users** and **Deactivate Users**. 1. Click **Save**. -1. Assign users in the **Assignments** tab. Assigned users will be created and +1. Assign users in the **Assignments** tab. Assigned users are created and managed in your GitLab group. #### Okta Known Issues @@ -212,7 +212,7 @@ Ensure that the user has been added to the SCIM app. If you receive "User is not linked to a SAML account", then most likely the user already exists in GitLab. Have the user follow the [User access and linking setup](#user-access-and-linking-setup) instructions. -The **Identity** (`extern_uid`) value stored by GitLab is updated by SCIM whenever `id` or `externalId` changes. Users won't be able to sign in unless the GitLab Identity (`extern_uid`) value matches the `NameId` sent by SAML. +The **Identity** (`extern_uid`) value stored by GitLab is updated by SCIM whenever `id` or `externalId` changes. Users cannot sign in unless the GitLab Identity (`extern_uid`) value matches the `NameId` sent by SAML. 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. @@ -242,9 +242,9 @@ 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 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'll need to know the desired value that matches the `NameId` as well as the current `externalId`. + To look up a user, you need to know the desired value that matches the `NameId` as well as the current `externalId`. -It is important not to update these to incorrect values, since this will cause users to be unable to sign in. It is also important not to assign a value to the wrong user, as this would cause users to get signed into the wrong account. +It is important not to update these to incorrect values, since this causes users to be unable to sign in. It is also important not to assign a value to the wrong user, as this causes users to get signed into the wrong account. ### I need to change my SCIM app diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index bb7c1e26544..5d375e2abd9 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -29,7 +29,7 @@ To enable GitLab import/export: Note the following: -- Exports are stored in a temporary [shared directory](../../../development/shared_files.md) and are deleted every 24 hours by a specific worker. +- Exports are stored in a temporary directory and are deleted every 24 hours by a specific worker. - To preserve group-level relationships from imported projects, run the Group Import/Export first, to allow projects to be imported into the desired group structure. - Imported groups are given a `private` visibility level, unless imported into a parent group. @@ -71,7 +71,7 @@ For more details on the specific data persisted in a group export, see the  1. After the export is generated, you should receive an e-mail with a link to the [exported contents](#exported-contents) - in a compressed tar archive, with contents in JSON format. + in a compressed tar archive, with contents in NDJSON format. 1. Alternatively, you can come back to the project settings and download the file from there by clicking **Download export**, or generate a new file by clicking **Regenerate export**. @@ -109,6 +109,14 @@ on an existing group's page. ## Version history +### 14.0+ + +In GitLab 14.0, the JSON format is no longer supported for project and group exports. To allow for a +transitional period, you can still import any JSON exports. The new format for imports and exports +is NDJSON. + +### 13.0+ + GitLab can import bundles that were exported from a different GitLab deployment. This ability is limited to two previous GitLab [minor](../../../policy/maintenance.md#versioning) releases, which is similar to our process for [Security Releases](../../../policy/maintenance.md#security-releases). diff --git a/doc/user/group/value_stream_analytics/img/delete_value_stream_v13_12.png b/doc/user/group/value_stream_analytics/img/delete_value_stream_v13_12.png Binary files differnew file mode 100644 index 00000000000..c02f259ae8c --- /dev/null +++ b/doc/user/group/value_stream_analytics/img/delete_value_stream_v13_12.png diff --git a/doc/user/group/value_stream_analytics/img/delete_value_stream_v13_4.png b/doc/user/group/value_stream_analytics/img/delete_value_stream_v13_4.png Binary files differdeleted file mode 100644 index c97fcb76343..00000000000 --- a/doc/user/group/value_stream_analytics/img/delete_value_stream_v13_4.png +++ /dev/null diff --git a/doc/user/group/value_stream_analytics/img/extended_value_stream_form_v13_10.png b/doc/user/group/value_stream_analytics/img/extended_value_stream_form_v13_10.png Binary files differdeleted file mode 100644 index e2752ad1157..00000000000 --- a/doc/user/group/value_stream_analytics/img/extended_value_stream_form_v13_10.png +++ /dev/null diff --git a/doc/user/group/value_stream_analytics/img/label_based_stage_vsm_v12_9.png b/doc/user/group/value_stream_analytics/img/label_based_stage_vsm_v12_9.png Binary files differdeleted file mode 100644 index 84ce33aece5..00000000000 --- a/doc/user/group/value_stream_analytics/img/label_based_stage_vsm_v12_9.png +++ /dev/null diff --git a/doc/user/group/value_stream_analytics/img/new_value_stream_v13_12.png b/doc/user/group/value_stream_analytics/img/new_value_stream_v13_12.png Binary files differnew file mode 100644 index 00000000000..b2b6ce04a14 --- /dev/null +++ b/doc/user/group/value_stream_analytics/img/new_value_stream_v13_12.png diff --git a/doc/user/group/value_stream_analytics/img/new_value_stream_v13_3.png b/doc/user/group/value_stream_analytics/img/new_value_stream_v13_3.png Binary files differdeleted file mode 100644 index bc8502e85a6..00000000000 --- a/doc/user/group/value_stream_analytics/img/new_value_stream_v13_3.png +++ /dev/null diff --git a/doc/user/group/value_stream_analytics/img/new_vsm_stage_v12_9.png b/doc/user/group/value_stream_analytics/img/new_vsm_stage_v12_9.png Binary files differdeleted file mode 100644 index dbef25d33ed..00000000000 --- a/doc/user/group/value_stream_analytics/img/new_vsm_stage_v12_9.png +++ /dev/null diff --git a/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13_12.png b/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13_12.png Binary files differnew file mode 100644 index 00000000000..ee0d007a778 --- /dev/null +++ b/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13_12.png diff --git a/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13_3.png b/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13_3.png Binary files differdeleted file mode 100644 index 506765f63cb..00000000000 --- a/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13_3.png +++ /dev/null diff --git a/doc/user/group/value_stream_analytics/img/vsa_label_based_stage_v14_0.png b/doc/user/group/value_stream_analytics/img/vsa_label_based_stage_v14_0.png Binary files differnew file mode 100644 index 00000000000..1f47670462c --- /dev/null +++ b/doc/user/group/value_stream_analytics/img/vsa_label_based_stage_v14_0.png diff --git a/doc/user/group/value_stream_analytics/img/vsa_overview_stage_v13_11.png b/doc/user/group/value_stream_analytics/img/vsa_overview_stage_v13_11.png Binary files differnew file mode 100644 index 00000000000..7d47003972c --- /dev/null +++ b/doc/user/group/value_stream_analytics/img/vsa_overview_stage_v13_11.png diff --git a/doc/user/group/value_stream_analytics/img/vsa_stage_table_v13_12.png b/doc/user/group/value_stream_analytics/img/vsa_stage_table_v13_12.png Binary files differnew file mode 100644 index 00000000000..24d485306be --- /dev/null +++ b/doc/user/group/value_stream_analytics/img/vsa_stage_table_v13_12.png diff --git a/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_0.png b/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_0.png Binary files differdeleted file mode 100644 index 799a81584a0..00000000000 --- a/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_0.png +++ /dev/null diff --git a/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_12.png b/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_12.png Binary files differnew file mode 100644 index 00000000000..63bae51afef --- /dev/null +++ b/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_12.png diff --git a/doc/user/group/value_stream_analytics/img/vsm_stage_list_v12_9.png b/doc/user/group/value_stream_analytics/img/vsm_stage_list_v12_9.png Binary files differdeleted file mode 100644 index 3b50dd48543..00000000000 --- a/doc/user/group/value_stream_analytics/img/vsm_stage_list_v12_9.png +++ /dev/null diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 6a512d78696..4b473c9217d 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -59,7 +59,7 @@ To filter results: 1. Select a parameter to filter by. 1. Select a value from the autocompleted results, or type to refine the results. - + ### Date ranges @@ -71,14 +71,28 @@ GitLab provides the ability to filter analytics based on a date range. To filter 1. Optionally select a project. 1. Select a date range using the available date pickers. -## How Time metrics are measured +## How metrics are measured The "Time" metrics near the top of the page are measured as follows: - **Lead time**: median time from issue created to issue closed. -- **Cycle time**: median time from first commit to issue closed. (You can associate a commit with an issue by [crosslinking in the commit message](../../project/issues/crosslinking_issues.md#from-commit-messages).) +- **Cycle time**: median time from first commit to issue closed. (You can associate a commit with an + issue by [crosslinking in the commit message](../../project/issues/crosslinking_issues.md#from-commit-messages).) - +The "Recent Activity" metrics near the top of the page are measured as follows: + +- **New Issues:** the number of issues created in the date range. +- **Deploys:** the number of deployments to production (1) in the date range. +- **Deployment Frequency:** the average number of deployments to production (1) per day in the date range. + +(1) To give a more accurate representation of deployments that actually completed successfully, +the calculation for these two metrics changed in GitLab 13.9 from using the time a deployment was +created to the time a deployment finished. If you were referencing this metric prior to 13.9, please +keep this slight change in mind. + +You can learn more about these metrics in our [analytics definitions](../../analytics/index.md). + + ## How the stages are measured @@ -109,8 +123,8 @@ How this works, behind the scenes: we need for the stages, like issue creation date, merge request merge time, etc. -To sum up, anything that doesn't follow [GitLab flow](../../../topics/gitlab_flow.md) will not be tracked and the -Value Stream Analytics dashboard will not present any data for: +To sum up, anything that doesn't follow [GitLab flow](../../../topics/gitlab_flow.md) is not tracked and the +Value Stream Analytics dashboard does not present any data for: - Merge requests that do not close an issue. - Issues not labeled with a label present in the Issue Board or for issues not assigned a milestone. @@ -118,7 +132,8 @@ Value Stream Analytics dashboard will not present any data for: ## How the production environment is identified -Value Stream Analytics identifies production environments by looking for project [environments](../../../ci/yaml/README.md#environment) with a name matching any of these patterns: +Value Stream Analytics identifies production environments by looking for project +[environments](../../../ci/yaml/README.md#environment) with a name matching any of these patterns: - `prod` or `prod/*` - `production` or `production/*` @@ -176,7 +191,7 @@ A few notes: cycles, calculate their median time and the result is what the dashboard of Value Stream Analytics is showing. -## Customizable Stages +## Custom value streams > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12196) in GitLab 12.9. @@ -184,14 +199,13 @@ The default stages are designed to work straight out of the box, but they might all teams. Different teams use different approaches to building software, so some teams might want to customize their Value Stream Analytics. -GitLab allows users to create multiple value streams, hide default stages and create custom stages that align better to their development workflow. +GitLab allows users to create multiple value streams, hide default stages and create custom stages +that align better to their development workflow. ### Stage path > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210315) in GitLab 13.0. -> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](../../../administration/feature_flags.md). **(FREE SELF)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323982) in GitLab 13.12.  @@ -212,98 +226,62 @@ Hovering over a stage item displays a popover with the following information: - Start event description for the given stage - End event description +- Median time items took to complete the stage +- Number of items that completed the stage -Horizontal path navigation is enabled by default. If you have a self-managed instance, an -administrator can [open a Rails console](../../../administration/troubleshooting/navigating_gitlab_via_rails_console.md) -and disable it with the following command: - -```ruby -Feature.disable(:value_stream_analytics_path_navigation) -``` - -### Adding a stage - -In the following example we're creating a new stage that measures and tracks issues from creation -time until they are closed. - -1. Navigate to your group's **Analytics > Value Stream**. -1. Click the **Add a stage** button. -1. Fill in the new stage form: - - Name: Issue start to finish. - - Start event: Issue created. - - End event: Issue closed. -1. Click the **Add stage** button. - - - -The new stage is persisted and it will always show up on the Value Stream Analytics page for your -group. - -If you want to alter or delete the stage, you can easily do that for customized stages by: - -1. Hovering over the stage. -1. Clicking the vertical ellipsis (**{ellipsis_v}**) button that appears. - - - -Creating a custom stage requires specifying two events: - -- A start. -- An end. - -Be careful to choose a start event that occurs *before* your end event. For example, consider a -stage that: +### Stream overview -- Started when an issue is added to a board. -- Ended when the issue is created. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321438) in GitLab 13.11. -This stage would not work because the end event has already happened when the start event occurs. -To prevent such invalid stages, the UI prohibits incompatible start and end events. After you select -the start event, the stop event dropdown will only list the compatible events. + -### Re-ordering stages +The stream overview provides access to key metrics and charts summarizing all the stages in the value stream +based on selected filters. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196698) in GitLab 12.10. +Shown metrics and charts includes: -Once a custom stage has been added, you can "drag and drop" stages to rearrange their order. These changes are automatically saved to the system. +- [Lead time](#how-metrics-are-measured) +- [Cycle time](#how-metrics-are-measured) +- [Days to completion chart](#days-to-completion-chart) +- [Tasks by type chart](#type-of-work---tasks-by-type-chart) -### Label based stages +### Stage table -The pre-defined start and end events can cover many use cases involving both issues and merge requests. - -For supporting more complex workflows, use stages based on group labels. These events are based on -labels being added or removed. In particular, [scoped labels](../../project/labels.md#scoped-labels) -are useful for complex workflows. +> Sorting the stage table [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301082) in GitLab 13.12. -In this example, we'd like to measure more accurate code review times. The workflow is the following: + -- When the code review starts, the reviewer adds `workflow::code_review_start` label to the merge request. -- When the code review is finished, the reviewer adds `workflow::code_review_complete` label to the merge request. +The stage table shows a list of related workflow items for the selected stage. This can include: -Creating a new stage called "Code Review": +- CI/CD jobs +- Issues +- Merge requests +- Pipelines - +A little badge next to the workflow items table header shows the number of workflow items that +completed the selected stage. -### Hiding unused stages +The stage table also includes the **Time** column, which shows how long it takes each item to pass +through the selected value stream stage. -Sometimes certain default stages are not relevant to a team. In this case, you can easily hide stages -so they no longer appear in the list. To hide stages: +The stage table is not displayed on the stream [Overview](#stream-overview). +The workflow item column (first column) is ordered by end event. -1. Add a custom stage to activate customizability. -1. Hover over the default stage you want to hide. -1. Click the vertical ellipsis (**{ellipsis_v}**) button that appears and select **Hide stage**. +To sort the stage table by a table column, select the table header. +You can sort in ascending or descending order. To find items that spent the most time in a stage, +potentially causing bottlenecks in your value stream, sort the table by the **Time** column. +From there, select individual items to drill in and investigate how delays are happening. +To see which items the stage most recently, sort by the work item column on the left. -To recover a default stage that was previously hidden: - -1. Click **Add a stage** button. -1. In the top right corner open the **Recover hidden stage** dropdown. -1. Select a stage. +The table displays up to 20 items at a time. If there are more than 20 items, you can use the +**Prev** and **Next** buttons to navigate through the pages. ### Creating a value stream > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221202) in GitLab 13.3 -A default value stream is readily available for each group. You can create additional value streams based on the different areas of work that you would like to measure. +A default value stream is readily available for each group. You can create additional value streams +based on the different areas of work that you would like to measure. Once created, a new value stream includes the [seven stages](#default-stages) that follow [GitLab workflow](../../../topics/gitlab_flow.md) @@ -317,7 +295,7 @@ To create a value stream: - You can [customize the stages](#creating-a-value-stream-with-stages) 1. Click the **Create Value Stream** button. - + #### Creating a value stream with stages @@ -333,17 +311,52 @@ add stages as desired. To create a value stream with stages: -1. Navigate to your group's **Analytics > Value Stream**. -1. Find and select the Value Stream dropdown. Select **Create new Value Stream**. +1. Go to your group and select **Analytics > Value Stream**. +1. Select the Value Stream dropdown and select **Create new Value Stream**. 1. Select either **Create from default template** or **Create from no template**. - - Default stages in the value stream can be hidden or re-ordered + - Default stages in the value stream can be hidden or re-ordered. +  - - New stages can be added by clicking the 'Add another stage' button + + - New stages can be added by clicking the 'Add another stage' button. - The name, start and end events for the stage can be selected +  1. Select the **Create Value Stream** button to save the value stream. - +#### Label-based stages + +The pre-defined start and end events can cover many use cases involving both issues and merge requests. + +In more complex workflows, use stages based on group labels. These events are based on +added or removed labels. In particular, [scoped labels](../../project/labels.md#scoped-labels) +are useful for complex workflows. + +In this example, we'd like to measure times for deployment from a staging environment to production. The workflow is the following: + +- When the code is deployed to staging, the `workflow::staging` label is added to the merge request. +- When the code is deployed to production, the `workflow::production` label is added to the merge request. + + + +### Editing a value stream + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267537) in GitLab 13.10. + +After you create a value stream, you can customize it to suit your purposes. To edit a value stream: + +1. Go to your group and select **Analytics > Value Stream**. +1. Find and select the relevant value stream from the value stream dropdown. +1. Next to the value stream dropdown, select **Edit**. + The edit form is populated with the value stream details. +1. Optional: + - Rename the value stream. + - Hide or re-order default stages. + - Remove existing custom stages. + - Add new stages by selecting the 'Add another stage' button + - Select the start and end events for the stage. +1. Optional. To undo any modifications, select **Restore value stream defaults**. +1. Select **Save Value Stream**. ### Deleting a value stream @@ -356,14 +369,15 @@ To delete a custom value stream: 1. Click the **Delete (name of value stream)**. 1. Click the **Delete** button to confirm. - + ## Days to completion chart > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21631) in GitLab 12.6. > - [Chart median line removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235455) in GitLab 13.4. +> - [Totals replaced with averages](https://gitlab.com/gitlab-org/gitlab/-/issues/262070) in GitLab 13.12. -This chart visually depicts the total number of days it takes for cycles to be completed. (Totals are being replaced with averages in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/262070).) +This chart visually depicts the average number of days it takes for cycles to be completed. This chart uses the global page filters for displaying data based on the selected group, projects, and time frame. In addition, specific stages can be selected diff --git a/doc/user/img/activity_followed_users_v13_9.png b/doc/user/img/activity_followed_users_v13_9.png Binary files differdeleted file mode 100644 index 3c0a9de74b4..00000000000 --- a/doc/user/img/activity_followed_users_v13_9.png +++ /dev/null diff --git a/doc/user/img/feature_highlight_example.png b/doc/user/img/feature_highlight_example.png Binary files differdeleted file mode 100644 index 32ca05a6087..00000000000 --- a/doc/user/img/feature_highlight_example.png +++ /dev/null diff --git a/doc/user/img/snippet_intro_v13_11.png b/doc/user/img/snippet_intro_v13_11.png Binary files differindex aa2ad5fd43a..4b6818341b7 100644 --- a/doc/user/img/snippet_intro_v13_11.png +++ b/doc/user/img/snippet_intro_v13_11.png diff --git a/doc/user/img/todos_icon.png b/doc/user/img/todos_icon.png Binary files differdeleted file mode 100644 index 9fee4337a75..00000000000 --- a/doc/user/img/todos_icon.png +++ /dev/null diff --git a/doc/user/img/todos_index.png b/doc/user/img/todos_index.png Binary files differdeleted file mode 100644 index 99c1575d157..00000000000 --- a/doc/user/img/todos_index.png +++ /dev/null diff --git a/doc/user/img/todos_index_v13_11.png b/doc/user/img/todos_index_v13_11.png Binary files differnew file mode 100644 index 00000000000..eedb3045d39 --- /dev/null +++ b/doc/user/img/todos_index_v13_11.png diff --git a/doc/user/index.md b/doc/user/index.md index 872dbd09c7d..ab159cecdef 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -56,7 +56,7 @@ GitLab is a Git-based platform that integrates a great number of essential tools With GitLab Enterprise Edition, you can also: - Improve collaboration with: - - [Merge Request Approvals](project/merge_requests/merge_request_approvals.md). + - [Merge Request Approvals](project/merge_requests/approvals/index.md). - [Multiple Assignees for Issues](project/issues/multiple_assignees_for_issues.md). - [Multiple Issue Boards](project/issue_board.md#multiple-issue-boards). - Create formal relationships between issues with [linked issues](project/issues/related_issues.md). @@ -86,10 +86,11 @@ There are several types of users in GitLab: ## User activity You can follow or unfollow other users from their [user profiles](profile/index.md#access-your-user-profile). -To see their activity in the top-level Activity view, select Follow or Unfollow, and select -the Followed Users tab: +To view a user's activity in a top-level Activity view: - +1. From a user's profile, select **Follow**. +1. In the GitLab menu, select **Activity**. +1. Select the **Followed users** tab. ## Projects @@ -119,7 +120,7 @@ to enjoy the best of GitLab. user type (guest, reporter, developer, maintainer, owner). - [Feature highlight](feature_highlight.md): Learn more about the little blue dots around the app that explain certain features. -- [Abuse reports](abuse_reports.md): Report abuse from users to GitLab administrators. +- [Abuse reports](report_abuse.md): Report abuse from users to GitLab administrators. ## Groups @@ -177,7 +178,7 @@ pages and accomplish tasks faster. ## Integrations -[Integrate GitLab](../integration/README.md) with your preferred tool, +[Integrate GitLab](../integration/index.md) with your preferred tool, such as Trello, Jira, etc. ## Webhooks diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 0c257f2fb70..cbd5bf1553a 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -1092,7 +1092,7 @@ Markdown is fine in GitLab. </dd> </dl> -#### Details and summary +#### Collapsible section To see the second Markdown example rendered in HTML, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#details-and-summary). diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 9df4aeb404a..53d191cbcfe 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -186,6 +186,10 @@ To authenticate to the Package Registry, you need one of the following: scope set to `read_package_registry`, `write_package_registry`, or both. - A [CI job token](#publish-a-conan-package-by-using-cicd). +NOTE: +Packages from private and internal projects are hidden if you are not +authenticated. If you try to search or download a package from a private or internal project without authenticating, you will receive the error `unable to find the package in remote` in the Conan client. + ### Add your credentials to the GitLab remote Associate your token with the GitLab remote, so that you don't have to diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index bc96d3c937c..6d7b009bb09 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -698,6 +698,13 @@ You can, however, remove the Container Registry for a project: The **Packages & Registries > Container Registry** entry is removed from the project's sidebar. +## Manifest lists and garbage collection + +Manifest lists are commonly used for creating multi-architecture images. If you rely on manifest +lists, you should tag all the individual manifests referenced by a list in their respective +repositories, and not just the manifest list itself. This ensures that those manifests aren't +garbage collected, as long as they have at least one tag pointing to them. + ## Troubleshooting the GitLab Container Registry ### Docker connection error @@ -729,20 +736,78 @@ As a workaround, you should include the architecture in the tag name of individu ### The cleanup policy doesn't delete any tags -In GitLab 13.6 and earlier, when you run the cleanup policy, -you may expect it to delete tags and it does not. +There can be different reasons behind this: + +- In GitLab 13.6 and earlier, when you run the cleanup policy you may expect it to delete tags and + it does not. This occurs when the cleanup policy is saved without editing the value in the + **Remove tags matching** field. This field has a grayed out `.*` value as a placeholder. Unless + `.*` (or another regex pattern) is entered explicitly into the field, a `nil` value is submitted. + This value prevents the saved cleanup policy from matching any tags. As a workaround, edit the + cleanup policy. In the **Remove tags matching** field, enter `.*` and save. This value indicates + that all tags should be removed. + +- If you are on GitLab self-managed instances and you have 1000+ tags in a container repository, you + might run into a [Container Registry token expiration issue](https://gitlab.com/gitlab-org/gitlab/-/issues/288814), + with `error authorizing context: invalid token` in the logs. + + To fix this, there are two workarounds: + + - If you are on GitLab 13.9 or later, you can [set limits for the cleanup policy](#set-cleanup-limits-to-conserve-resources). + This limits the cleanup execution in time, and avoids the expired token error. + + - Extend the expiration delay of the Container Registry authentication tokens. This defaults to 5 + minutes. You can set a custom value by running + `ApplicationSetting.last.update(container_registry_token_expire_delay: <integer>)` in the Rails + console, where `<integer>` is the desired number of minutes. For reference, 15 minutes is the + value currently in use for GitLab.com. Be aware that by extending this value you increase the + time required to revoke permissions. -This issue occurs when the cleanup policy was saved without -editing the value in the **Remove tags matching** field. +If the previous fixes didn't work or you are on earlier versions of GitLab, you can generate a list +of the tags that you want to delete, and then use that list to delete the tags. To do this, follow +these steps: -This field had a grayed out `.*` value as a placeholder. -Unless `.*` (or other regex pattern) was entered explicitly into the -field, a `nil` value was submitted. This value prevents the -saved cleanup policy from matching any tags. +1. Run the following shell script. The command just before the `for` loop ensures that + `list_o_tags.out` is always reinitialized when starting the loop. After running this command, all + the tags' names will be in the `list_o_tags.out` file: + + ```shell + # Get a list of all tags in a certain container repository while considering [pagination](../../../api/README.md#pagination) + echo -n "" > list_o_tags.out; for i in {1..N}; do curl --header 'PRIVATE-TOKEN: <PAT>' "https://gitlab.example.com/api/v4/projects/<Project_id>/registry/repositories/<container_repo_id>/tags?per_page=100&page=${i}" | jq '.[].name' | sed 's:^.\(.*\).$:\1:' >> list_o_tags.out; done + ``` + +1. Remove from the `list_o_tags.out` file any tags that you want to keep. Here are some example + `sed` commands for this. Note that these commands are simply examples. You may change them to + best suit your needs: + + ```shell + # Remove the `latest` tag from the file + sed -i '/latest/d' list_o_tags.out -As a workaround, edit the cleanup policy. In the **Remove tags matching** -field, enter `.*` and save. This value indicates that all tags should -be removed. + # Remove the first N tags from the file + sed -i '1,Nd' list_o_tags.out + + # Remove the tags starting with `Av` from the file + sed -i '/^Av/d' list_o_tags.out + + # Remove the tags ending with `_v3` from the file + sed -i '/_v3$/d' list_o_tags.out + ``` + + If you are running macOS, you must add `.bak` to the commands. For example: + + ```shell + sed -i .bak '/latest/d' list_o_tags.out + ``` + +1. Double-check the `list_o_tags.out` file to make sure it contains only the tags that you want to + delete. + +1. Run this shell script to delete the tags in the `list_o_tags.out` file: + + ```shell + # loop over list_o_tags.out to delete a single tag at a time + while read -r LINE || [[ -n $LINE ]]; do echo ${LINE}; curl --request DELETE --header 'PRIVATE-TOKEN: <PAT>' "https://gitlab.example.com/api/v4/projects/<Project_id>/registry/repositories/<container_repo_id>/tags/${LINE}"; sleep 0.1; echo; done < list_o_tags.out > delete.logs + ``` ### Troubleshoot as a GitLab server admin diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 57d6245dd96..e20ac57e64f 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -69,22 +69,6 @@ Example response: } ``` -Example request using a deploy token: - -```shell -curl --header "DEPLOY-TOKEN: <deploy_token>" \ - --upload-file path/to/file.txt \ - "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt?status=hidden" -``` - -Example response: - -```json -{ - "message":"201 Created" -} -``` - ## Download package file Download a package file. diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index 74072aa95e1..b871a08c133 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -12,22 +12,17 @@ packages, which can be easily consumed as a dependency in downstream projects. The Package Registry supports the following formats: -<div class="row"> -<div class="col-md-9"> -<table align="left" style="width:50%"> -<tr style="background:#dfdfdf"><th>Package type</th><th>GitLab version</th></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/composer_repository/index.html">Composer</a></td><td>13.2+</td></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/conan_repository/index.html">Conan</a></td><td>12.6+</td></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/go_proxy/index.html">Go</a></td><td>13.1+</td></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/maven_repository/index.html">Maven</a></td><td>11.3+</td></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/npm_registry/index.html">npm</a></td><td>11.7+</td></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/nuget_repository/index.html">NuGet</a></td><td>12.8+</td></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/pypi_repository/index.html">PyPI</a></td><td>12.10+</td></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/generic_packages/index.html">Generic packages</a></td><td>13.5+</td></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/rubygems_registry/index.html">RubyGems</a></td><td>13.10+</td></tr> -</table> -</div> -</div> +| Package type | GitLab version | +| ------------ | -------------- | +| [Composer](composer_repository/index.md) | 13.2+ | +| [Conan](conan_repository/index.md) | 12.6+ | +| [Go](go_proxy/index.md) | 13.1+ | +| [Maven](maven_repository/index.md) | 11.3+ | +| [npm](npm_registry/index.md) | 11.7+ | +| [NuGet](nuget_repository/index.md) | 12.8+ | +| [PyPI](pypi_repository/index.md) | 12.10+ | +| [Generic packages](generic_packages/index.md) | 13.5+ | +| [Ruby gems](rubygems_registry/index.md) | 13.10+ | You can also use the [API](../../api/packages.md) to administer the Package Registry. diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index d4dc9f0ae78..ba7b55dc47d 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -625,7 +625,7 @@ In the UI: 1. For your group, go to **Settings > Packages & 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 of packages you want to allow. +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. Your changes are automatically saved. diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index b6312002184..ace432b305f 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -14,6 +14,9 @@ packages whenever you need to use them as a dependency. Only [scoped](https://docs.npmjs.com/misc/scope/) packages are supported. +For documentation of the specific API endpoints that the npm package manager +client uses, see the [npm API documentation](../../../api/packages/npm.md). + ## Build an npm package This section covers how to install npm or Yarn and build a package for your @@ -43,7 +46,7 @@ The npm version is shown in the output: ### Install Yarn As an alternative to npm, you can install Yarn in your local environment by following the -instructions at [yarnpkg.com](https://classic.yarnpkg.com/en/docs/install). +instructions at [classic.yarnpkg.com](https://classic.yarnpkg.com/en/docs/install). When installation is complete, verify you can use Yarn in your terminal by running: @@ -305,6 +308,46 @@ See the [Publish npm packages to the GitLab Package Registry using semantic-release](../../../ci/examples/semantic-release.md) step-by-step guide and demo project for a complete example. +## Configure the GitLab npm registry with Yarn 2 + +You can get started with Yarn 2 by following the documentation at +[https://yarnpkg.com/getting-started/install](https://yarnpkg.com/getting-started/install). + +To publish and install with the project-level npm endpoint, set the following configuration in +`.yarnrc.yml`: + +```yaml +npmScopes: + foo: + npmRegistryServer: "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/" + npmPublishRegistry: "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/" + +npmRegistries: + //gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/: + npmAlwaysAuth: true + npmAuthToken: "<your_token>" +``` + +For the instance-level npm endpoint, use this Yarn 2 configuration in `.yarnrc.yml`: + +```yaml +npmScopes: + foo: + npmRegistryServer: "https://gitlab.example.com/api/v4/packages/npm/" + +npmRegistries: + //gitlab.example.com/api/v4/packages/npm/: + npmAlwaysAuth: true + npmAuthToken: "<your_token>" +``` + +In this configuration: + +- Replace `<your_token>` with your personal access token or deploy token. +- Replace `<your_project_id>` with your project's ID, which you can find on the project's home page. +- Replace `gitlab.example.com` with your domain name. +- Your scope is `foo`, without `@`. + ## Publishing packages with the same name or version You cannot publish a package if a package of the same name and version already exists. diff --git a/doc/user/packages/rubygems_registry/index.md b/doc/user/packages/rubygems_registry/index.md index aa50bc6c2bc..e4d297ac1d8 100644 --- a/doc/user/packages/rubygems_registry/index.md +++ b/doc/user/packages/rubygems_registry/index.md @@ -44,7 +44,7 @@ Feature.enable(:rubygem_packages, Project.find(1)) Feature.disable(:rubygem_packages, Project.find(2)) ``` -## Create a Ruby Gem +## Create a Ruby gem If you need help creating a Ruby gem, see the [RubyGems documentation](https://guides.rubygems.org/make-your-own-gem/). @@ -80,10 +80,19 @@ you can use `CI_JOB_TOKEN` instead of a personal access token or deploy token. For example: ```yaml -image: ruby:latest +# assuming a my_gem.gemspec file is present in the repository with the version currently set to 0.0.1 +image: ruby run: + before_script: + - mkdir ~/.gem + - echo "---" > ~/.gem/credentials + - | + echo "https://gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/rubygems: '${CI_JOB_TOKEN}'" >> ~/.gem/credentials + - chmod 0600 ~/.gem/credentials # rubygems requires 0600 permissions on the credentials file script: + - gem build my_gem + - gem push my_gem-0.0.1.gem --host https://gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/rubygems ``` You can also use `CI_JOB_TOKEN` in a `~/.gem/credentials` file that you check in to diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 7405c3aade8..245efc0e908 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -202,7 +202,7 @@ The following table depicts the various user permission levels in a project. 1. Actions are limited only to records owned (referenced) by user. 1. When [Share Group Lock](group/index.md#prevent-a-project-from-being-shared-with-groups) is enabled the project can't be shared with other groups. It does not affect group with group sharing. 1. For information on eligible approvers for merge requests, see - [Eligible approvers](project/merge_requests/merge_request_approvals.md#eligible-approvers). + [Eligible approvers](project/merge_requests/approvals/rules.md#eligible-approvers). 1. Applies only to comments on [Design Management](project/issues/design_management.md) designs. 1. Users can only view events based on their individual actions. 1. Project access tokens are supported for self-managed instances on Free and above. They are also @@ -427,8 +427,8 @@ with the permissions described on the documentation on [auditor users permission >[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40942) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. -Administrators can add members with a "minimal access" role to a parent group. Such users don't -automatically have access to projects and subgroups underneath. To support such access, administrators must explicitly add these "minimal access" users to the specific subgroups/projects. +Owners can add members with a "minimal access" role to a parent group. Such users don't +automatically have access to projects and subgroups underneath. To support such access, owners must explicitly add these "minimal access" users to the specific subgroups/projects. Users with minimal access can list the group in the UI and through the API. However, they cannot see details such as projects or subgroups. They do not have access to the group's page or list any of its subgroups or projects. diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index a33b6742d61..361353a0f8c 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -53,7 +53,7 @@ There are two options for deleting users: - **Delete user and contributions** When using the **Delete user** option, not all associated records are deleted with the user. -Here's a list of things that will **not** be deleted: +Here's a list of things that are **not** deleted: - Issues that the user created. - Merge requests that the user created. @@ -61,20 +61,20 @@ Here's a list of things that will **not** be deleted: - Abuse reports that the user reported. - Award emoji that the user created. -Instead of being deleted, these records will be moved to a system-wide +Instead of being deleted, these records are moved to a system-wide user with the username "Ghost User", whose sole purpose is to act as a container -for such records. Any commits made by a deleted user will still display the +for such records. Any commits made by a deleted user still display the username of the original user. When using the **Delete user and contributions** option, **all** associated records are removed. This includes all of the items mentioned above including issues, merge requests, notes/comments, and more. Consider -[blocking a user](../../admin_area/blocking_unblocking_users.md) +[blocking a user](../../admin_area/moderate_users.md#blocking-a-user) or using the **Delete user** option instead. -When a user is deleted from an [abuse report](../../admin_area/abuse_reports.md) +When a user is deleted from an [abuse report](../../admin_area/review_abuse_reports.md) or spam log, these associated -records are not ghosted and will be removed, along with any groups the user +records are not ghosted and are removed, along with any groups the user is a sole owner of. Administrators can also request this behavior when deleting users from the [API](../../../api/users.md#user-deletion) or the Admin Area. diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 23e5bf2d143..c763226015e 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -51,10 +51,11 @@ To enable 2FA: 1. Install a compatible application, like: - [Authy](https://authy.com/) - [Duo Mobile](https://duo.com/product/multi-factor-authentication-mfa/duo-mobile-app) - - [LastPass](https://lastpass.com/auth/) + - [LastPass Authenticator](https://lastpass.com/auth/) - [Authenticator](https://mattrubin.me/authenticator/) - [andOTP](https://github.com/andOTP/andOTP) - [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en) + - [Microsoft Authenticator](https://www.microsoft.com/en-us/account/authenticator) - [SailOTP](https://openrepos.net/content/seiichiro0185/sailotp) 1. In the application, add a new entry in one of two ways: - Scan the code presented in GitLab with your device's camera to add the diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 4e4cdf5dc36..17c24a6b63f 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -135,9 +135,7 @@ If you select the **Busy** checkbox, remember to clear it when you become availa > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259649) in GitLab 13.6. > - It was [deployed behind a feature flag](../feature_flags.md), disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/281073) in GitLab 13.8. -> - It's enabled on GitLab.com. -> - It's not recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-busy-status-feature). +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/329163) in GitLab 13.12. To indicate to others that you are busy, you can set an indicator. @@ -173,23 +171,6 @@ To set the busy status indicator, either: | --- | --- | |  |  | -### Disable busy status feature - -The busy status feature is deployed behind a feature flag and is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) can disable it for your instance from the [rails console](../../administration/feature_flags.md#start-the-gitlab-rails-console). - -To disable it: - -```ruby -Feature.disable(:set_user_availability_status) -``` - -To enable it: - -```ruby -Feature.enable(:set_user_availability_status) -``` - ## Change the email displayed on your commits > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21598) in GitLab 11.4. diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index d32971a7618..7b63a5bfef9 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -8,112 +8,148 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Personal access tokens > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3749) in GitLab 8.8. -> - [Notifications about expiring tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) added in GitLab 12.6. -> - [Notifications about expired tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/214721) added in GitLab 13.3. +> - [Notifications for expiring tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) added in GitLab 12.6. > - [Token lifetime limits](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) added in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. +> - [Additional notifications for expiring tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/214721) added in GitLab 13.3. -If you're unable to use [OAuth2](../../api/oauth2.md), you can use a personal access token to authenticate with the [GitLab API](../../api/README.md#personalproject-access-tokens). +If you're unable to use [OAuth2](../../api/oauth2.md), you can use a personal access token to authenticate with the [GitLab API](../../api/README.md#personalproject-access-tokens). You can also use a personal access token with Git to authenticate over HTTP. -You can also use personal access tokens with Git to authenticate over HTTP. Personal access tokens are required when [Two-Factor Authentication (2FA)](account/two_factor_authentication.md) is enabled. In both cases, you can authenticate with a token in place of your password. +In both cases, you authenticate with a personal access token in place of your password. -Personal access tokens expire on the date you define, at midnight UTC. - -- GitLab runs a check at 01:00 AM UTC every day to identify personal access tokens that expire in under seven days. The owners of these tokens are notified by email. -- GitLab runs a check at 02:00 AM UTC every day to identify personal access tokens that expired on the current date. The owners of these tokens are notified by email. -- In GitLab Ultimate, administrators may [limit the lifetime of personal access tokens](../admin_area/settings/account_and_limit_settings.md#limiting-lifetime-of-personal-access-tokens). -- In GitLab Ultimate, administrators may [toggle enforcement of personal access token expiration](../admin_area/settings/account_and_limit_settings.md#optional-non-enforcement-of-personal-access-token-expiration). +Personal access tokens are required when [Two-Factor Authentication (2FA)](account/two_factor_authentication.md) is enabled. -For examples of how you can use a personal access token to authenticate with the API, see the following section from our [API Docs](../../api/README.md#personalproject-access-tokens). +For examples of how you can use a personal access token to authenticate with the API, see the [API documentation](../../api/README.md#personalproject-access-tokens). -GitLab also offers [impersonation tokens](../../api/README.md#impersonation-tokens) which are created by administrators via the API. They're a great fit for automated authentication as a specific user. +Alternately, GitLab administrators can use the API to create [impersonation tokens](../../api/README.md#impersonation-tokens). +Use impersonation tokens to automate authentication as a specific user. -## Creating a personal access token +## Create a personal access token -You can create as many personal access tokens as you like from your GitLab -profile. +You can create as many personal access tokens as you like. -1. Sign in to GitLab. 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. 1. In the left sidebar, select **Access Tokens**. -1. Choose a name and optional expiry date for the token. -1. Choose the [desired scopes](#limiting-scopes-of-a-personal-access-token). +1. Enter a name and optional expiry date for the token. +1. Select the [desired scopes](#personal-access-token-scopes). 1. Select **Create personal access token**. -1. Save the personal access token somewhere safe. If you navigate away or refresh - your page, and you did not save the token, you must create a new one. -### Revoking a personal access token +Save the personal access token somewhere safe. After you leave the page, +you no longer have access to the token. -At any time, you can revoke any personal access token by clicking the -respective **Revoke** button under the **Active Personal Access Token** area. +## Revoke a personal access token -### Token activity +At any time, you can revoke a personal access token. + +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Access Tokens**. +1. In the **Active personal access tokens** area, next to the key, select **Revoke**. -You can see when a token was last used from the **Personal Access Tokens** page. Updates to the token usage is fixed at once per 24 hours. Requests to [API resources](../../api/api_resources.md) and the [GraphQL API](../../api/graphql/index.md) update a token's usage. +## View the last time a token was used -## Limiting scopes of a personal access token +Token usage is updated once every 24 hours. It is updated each time the token is used to request +[API resources](../../api/api_resources.md) and the [GraphQL API](../../api/graphql/index.md). -Personal access tokens can be created with one or more scopes that allow various -actions that a given token can perform. The available scopes are depicted in -the following table. +To view the last time a token was used: -| Scope | Introduced in | Description | +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Access Tokens**. +1. In the **Active personal access tokens** area, next to the key, view the **Last Used** date. + +## Personal access token scopes + +A personal access token can perform actions based on the assigned scopes. + +| Scope | Introduced in | Access | | ------------------ | ------------- | ----------- | -| `read_user` | [GitLab 8.15](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5951) | Allows access to the read-only endpoints under `/users`. Essentially, any of the `GET` requests in the [Users API](../../api/users.md) are allowed. | -| `api` | [GitLab 8.15](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5951) | Grants complete read/write access to the API, including all groups and projects, the container registry, and the package registry. | -| `read_api` | [GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28944) | Grants read access to the API, including all groups and projects, the container registry, and the package registry. | -| `read_registry` | [GitLab 9.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11845) | Allows to read (pull) [container registry](../packages/container_registry/index.md) images if a project is private and authorization is required. | -| `write_registry` | [GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28958) | Allows to write (push) [container registry](../packages/container_registry/index.md) images if a project is private and authorization is required. | -| `sudo` | [GitLab 10.2](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14838) | Allows performing API actions as any user in the system (if the authenticated user is an administrator). | -| `read_repository` | [GitLab 10.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17894) | Allows read-only access (pull) to the repository through `git clone`. | -| `write_repository` | [GitLab 11.11](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26021) | Allows read-write access (pull, push) to the repository through `git clone`. Required for accessing Git repositories over HTTP when 2FA is enabled. | - -## Programmatically creating a personal access token - -You can programmatically create a predetermined personal access token for use in -automation or tests. You need sufficient access to run a -[Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session) -for your GitLab instance. - -To create a token belonging to a user with username `automation-bot`, run the -following in the Rails console (`sudo gitlab-rails console`): - -```ruby -user = User.find_by_username('automation-bot') -token = user.personal_access_tokens.create(scopes: [:read_user, :read_repository], name: 'Automation token') -token.set_token('token-string-here123') -token.save! -``` +| `api` | [8.15](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5951) | Read-write for the complete API, including all groups and projects, the Container Registry, and the Package Registry. | +| `read_user` | [8.15](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5951) | Read-only for endpoints under `/users`. Essentially, access to any of the `GET` requests in the [Users API](../../api/users.md). | +| `read_api` | [12.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28944) | Read-only for the complete API, including all groups and projects, the Container Registry, and the Package Registry. | +| `read_repository` | [10.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17894) | Read-only (pull) for the repository through `git clone`. | +| `write_repository` | [11.11](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26021) | Read-write (pull, push) for the repository through `git clone`. Required for accessing Git repositories over HTTP when 2FA is enabled. | +| `read_registry` | [9.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11845) | Read-only (pull) for [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. | +| `write_registry` | [12.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28958) | Read-write (push) for [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. | +| `sudo` | [10.2](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14838) | API actions as any user in the system (if the authenticated user is an administrator). | + +## When personal access tokens expire -This can be shortened into a single-line shell command using the +Personal access tokens expire on the date you define, at midnight UTC. + +- GitLab runs a check at 01:00 AM UTC every day to identify personal access tokens that expire in the next seven days. The owners of these tokens are notified by email. +- GitLab runs a check at 02:00 AM UTC every day to identify personal access tokens that expire on the current date. The owners of these tokens are notified by email. +- In GitLab Ultimate, administrators can + [limit the lifetime of personal access tokens](../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-personal-access-tokens). +- In GitLab Ultimate, administrators can choose whether or not to + [enforce personal access token expiration](../admin_area/settings/account_and_limit_settings.md#do-not-enforce-personal-access-token-expiration). + +## Create a personal access token programmatically **(FREE SELF)** + +You can create a predetermined personal access token +as part of your tests or automation. + +Prerequisite: + +- You need sufficient access to run a + [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session) + for your GitLab instance. + +To create a personal access token programmatically: + +1. Open a Rails console: + + ```shell + sudo gitlab-rails console + ``` + +1. Run the following commands to reference the username, the token, and the scopes. + + The token must be 20 characters long. The scopes must be valid and are visible + [in the source code](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/auth.rb). + + For example, to create a token that belongs to a user with username `automation-bot`: + + ```ruby + user = User.find_by_username('automation-bot') + token = user.personal_access_tokens.create(scopes: [:read_user, :read_repository], name: 'Automation token') + token.set_token('token-string-here123') + token.save! + ``` + +This code can be shortened into a single-line shell command by using the [Rails runner](../../administration/troubleshooting/debug.md#using-the-rails-runner): ```shell sudo gitlab-rails runner "token = User.find_by_username('automation-bot').personal_access_tokens.create(scopes: [:read_user, :read_repository], name: 'Automation token'); token.set_token('token-string-here123'); token.save!" ``` -NOTE: -The token string must be 20 characters in length to be -recognized as a valid personal access token. +## Revoke a personal access token programmatically **(FREE SELF)** -The list of valid scopes and what they do can be found -[in the source code](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/auth.rb). +You can programmatically revoke a personal access token +as part of your tests or automation. -## Programmatically revoking a personal access token +Prerequisite: -You can programmatically revoke a personal access token. You need -sufficient access to run a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session) -for your GitLab instance. +- You need sufficient access to run a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session) + for your GitLab instance. -To revoke a known token `token-string-here123`, run the following in the Rails -console (`sudo gitlab-rails console`): +To revoke a token programmatically: -```ruby -token = PersonalAccessToken.find_by_token('token-string-here123') -token.revoke! -``` +1. Open a Rails console: + + ```shell + sudo gitlab-rails console + ``` + +1. To revoke a token of `token-string-here123`, run the following commands: + + ```ruby + token = PersonalAccessToken.find_by_token('token-string-here123') + token.revoke! + ``` -This can be shortened into a single-line shell command using the +This code can be shortened into a single-line shell command using the [Rails runner](../../administration/troubleshooting/debug.md#using-the-rails-runner): ```shell diff --git a/doc/user/project/bulk_editing.md b/doc/user/project/bulk_editing.md index 76ae4cf596b..d9e268251b7 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -1,67 +1,8 @@ --- -stage: Plan -group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'issues/managing_issues.md' --- -# Bulk editing issues and merge requests at the project level +This document was moved to [another location](issues/managing_issues.md). -NOTE: -Bulk editing issues, epics, and merge requests is also available at the **group level**. -For more details, see -[Bulk editing issues, epics, and merge requests at the group level](../group/bulk_editing/index.md). - -If you want to update attributes across multiple issues or merge requests, you can do it -by bulk editing them, that is, editing them together. - -Only the items visible on the current page are selected for bulk editing (up to 20). - - - -## Bulk edit issues at the project level - -> - Assigning epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. -> - Editing health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in GitLab 13.2. -> - Editing iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196806) in GitLab 13.9. - -Users with permission level of [Reporter or higher](../permissions.md) can manage issues. - -When bulk editing issues in a project, you can edit the following attributes: - -- Status (open/closed) -- Assignee -- [Epic](../group/epics/index.md) -- [Milestone](milestones/index.md) -- [Labels](labels.md) -- [Health status](issues/managing_issues.md#health-status) -- Notification subscription -- [Iteration](../group/iterations/index.md) - -To update multiple project issues at the same time: - -1. In a project, go to **{issues}** **Issues > List**. -1. Click **Edit issues**. A sidebar on the right-hand side of your screen appears with editable fields. -1. Select the checkboxes next to each issue you want to edit. -1. Select the appropriate fields and their values from the sidebar. -1. Click **Update all**. - -## Bulk edit merge requests at the project level - -Users with permission level of [Developer or higher](../permissions.md) can manage merge requests. - -When bulk editing merge requests in a project, you can edit the following attributes: - -- Status (open/closed) -- Assignee -- Milestone -- Labels -- Subscriptions - -To update multiple project merge requests at the same time: - -1. In a project, go to **{merge-request}** **Merge Requests**. -1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with - editable fields. -1. Select the checkboxes next to each merge request you want to edit. -1. Select the appropriate fields and their values from the sidebar. -1. Click **Update all**. +<!-- This redirect file can be deleted after <2021-08-12>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index e329ec4f903..c0fb8f5848f 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -41,9 +41,9 @@ For example, the following policy document allows assuming a role whose name sta } ``` -### Administration settings +### Configure Amazon authentication -Generate an access key for the IAM user, and configure GitLab with the credentials: +To configure Amazon authentication in GitLab, generate an access key for the IAM user in the Amazon AWS console, and following the steps below. 1. Navigate to **Admin Area > Settings > General** and expand the **Amazon EKS** section. 1. Check **Enable Amazon EKS integration**. @@ -232,7 +232,7 @@ sequenceDiagram First, GitLab must obtain an initial set of credentials to communicate with the AWS API. These credentials can be retrieved in one of two ways: -- Statically through the [Administration settings](#administration-settings). +- Statically through the [Configure Amazon authentication](#configure-amazon-authentication). - Dynamically via an IAM instance profile ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291015) in GitLab 13.7). After GitLab retrieves the AWS credentials, it makes an @@ -272,7 +272,7 @@ arn:aws:iam::123456789012:role/gitlab-eks-provision' #### Access denied: User `arn:aws:iam::x` is not authorized to perform: `sts:AssumeRole` on resource: `arn:aws:iam::y` This error occurs when the credentials defined in the -[Administration settings](#administration-settings) cannot assume the role defined by the +[Configure Amazon authentication](#configure-amazon-authentication) cannot assume the role defined by the Provision Role ARN. Check that: 1. The initial set of AWS credentials [has the AssumeRole policy](#additional-requirements-for-self-managed-instances). @@ -290,6 +290,10 @@ because GitLab has successfully assumed your provided role, but the role has insufficient permissions to retrieve the resources needed for the form. Make sure you've assigned the role the correct permissions. +### Key Pairs are not loaded + +GitLab loads the key pairs from the **Cluster Region** specified. Ensure that key pair exists in that region. + #### `ROLLBACK_FAILED` during cluster creation The creation process halted because GitLab encountered an error when creating diff --git a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md index d64ebfd9385..fa4a5fb61d0 100644 --- a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md @@ -77,5 +77,5 @@ necessary components with GMAv2 and the cluster management project. **Related documentation links:** -- [GitLab Managed Apps v1 (GMAv1)](../../../../clusters/applications.md#install-with-one-click) +- [GitLab Managed Apps v1 (GMAv1)](../../../../clusters/applications.md#install-with-one-click-deprecated) - [GitLab Managed Apps v2 (GMAv2)](../../../../clusters/management_project.md) diff --git a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md index 14db98c7ce7..bf419c69885 100644 --- a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md @@ -52,7 +52,7 @@ Each method has benefits and drawbacks: | | YAML method | UI method (Ultimate only) | |--|:------------|:-------------------------------| -| **Benefits** | A change control process is possible by requiring [MR Approvals](../../../merge_requests/merge_request_approvals.md). All changes are fully tracked and audited in the same way that Git tracks the history of any file in its repository. | The UI provides a simple rules editor for users who are less familiar with the YAML syntax of NetworkPolicies. This view is a live representation of the policies currently deployed in the Kubernetes cluster. The UI also allows for multiple network policies to be created per environment. | +| **Benefits** | A change control process is possible by requiring [MR Approvals](../../../merge_requests/approvals/index.md). All changes are fully tracked and audited in the same way that Git tracks the history of any file in its repository. | The UI provides a simple rules editor for users who are less familiar with the YAML syntax of NetworkPolicies. This view is a live representation of the policies currently deployed in the Kubernetes cluster. The UI also allows for multiple network policies to be created per environment. | | **Drawbacks** | Only one network policy can be deployed per environment (although that policy can be as detailed as needed). Also, if changes were made in Kubernetes directly rather than through the `auto-deploy-values.yaml` file, the YAML file's contents don't represent the actual state of policies deployed in Kubernetes. | Policy changes aren't audited and a change control process isn't available. | Users are encouraged to choose one of the two methods to manage their policies. If users attempt to @@ -149,5 +149,5 @@ necessary components with GMAv2 and the cluster management project. **Related documentation links:** -- [GitLab Managed Apps v1 (GMAv1)](../../../../clusters/applications.md#install-with-one-click) +- [GitLab Managed Apps v1 (GMAv1)](../../../../clusters/applications.md#install-with-one-click-deprecated) - [GitLab Managed Apps v2 (GMAv2)](../../../../clusters/management_project.md) diff --git a/doc/user/project/clusters/securing.md b/doc/user/project/clusters/securing.md deleted file mode 100644 index d734db6bac9..00000000000 --- a/doc/user/project/clusters/securing.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'protect/index.md' ---- - -This document was moved to [another location](protect/index.md). - -<!-- This redirect file can be deleted after <2021-04-01>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index f9423c0be2d..5d6fb8252bb 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -86,7 +86,7 @@ Put the following code in the file: service: gitlab-example provider: name: aws - runtime: nodejs10.x + runtime: nodejs14.x functions: hello: diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 3135aa78719..ea7bcce99c1 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -22,19 +22,19 @@ The GitLab Code Owners feature defines who owns specific files or paths in a repository, allowing other users to understand who is responsible for each file or path. +As an alternative to using Code Owners for approvals, you can instead +[configure rules](merge_requests/approvals/rules.md). + ## Why is this useful? Code Owners allows for a version controlled, single source of truth file outlining the exact GitLab users or groups that -own certain files or paths in a repository. Code Owners can be -used in the merge request approval process which can streamline -the process of finding the right reviewers and approvers for a given -merge request. - -In larger organizations or popular open source projects, Code Owners -can help you understand who to contact if you have -a question that may not be related to code review or a merge request -approval. +own certain files or paths in a repository. In larger organizations +or popular open source projects, Code Owners can help you understand +who to contact if you have a question about a specific portion of +the codebase. Code Owners can also streamline the merge request approval +process, identifying the most relevant reviewers and approvers for a +given change. ## How to set up Code Owners @@ -76,7 +76,7 @@ The user that would show for `README.md` would be `@user2`. After you've added Code Owners to a project, you can configure it to be used for merge request approvals: -- As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers). +- As [merge request eligible approvers](merge_requests/approvals/rules.md#code-owners-as-eligible-approvers). - As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** Developer or higher [permissions](../permissions.md) are required to @@ -87,9 +87,9 @@ After it's set, Code Owners are displayed in merge request widgets:  While you can use the `CODEOWNERS` file in addition to Merge Request -[Approval Rules](merge_requests/merge_request_approvals.md#approval-rules), +[Approval Rules](merge_requests/approvals/rules.md), you can also use it as the sole driver of merge request approvals -without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules): +without using [Approval Rules](merge_requests/approvals/rules.md): 1. Create the file in one of the three locations specified above. 1. Set the code owners as required approvers for @@ -143,6 +143,10 @@ But you have the option to [invite](members/share_project_with_groups.md) the Subgroup Y to the Project A so that their members also become eligible Code Owners: +NOTE: +If you do not invite Subgroup Y to Project A, but make them Code Owners, their approval +of the merge request becomes optional. +  After being invited, any member (`@user`) of the group or subgroup can be set diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 368417ac00b..804c013d317 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -8,7 +8,13 @@ type: howto, reference # Deploy Boards **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. -> - [Moved](<https://gitlab.com/gitlab-org/gitlab/-/issues/212320>) to GitLab Free in 13.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to GitLab Free in 13.8. +> - In GitLab 13.5 and earlier, apps that consist of multiple deployments are shown as +> duplicates on the deploy board. This is [fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/8463) +> in GitLab 13.6. +> - In GitLab 13.11 and earlier, environments in folders do not show deploy boards. +> This is [fixed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60525) in +> GitLab 13.12. GitLab Deploy Boards offer a consolidated view of the current health and status of each CI [environment](../../ci/environments/index.md) running on [Kubernetes](https://kubernetes.io), displaying the status @@ -46,10 +52,6 @@ knowledge. In particular, you should be familiar with: - [Kubernetes namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) - [Kubernetes canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments) -In GitLab 13.5 and earlier, apps that consist of multiple deployments are shown as -duplicates on the deploy board. This is [fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/8463) -in GitLab 13.6. - ## Use cases Since the Deploy Board is a visual representation of the Kubernetes pods for a diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index a45c3d26f1a..a6b54474a9e 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -151,6 +151,24 @@ Adding a public deploy key does not immediately expose any repository to it. Pub deploy keys enable access from other systems, but access is not given to any project until a project maintainer chooses to make use of it. +## How to disable deploy keys + +[Project maintainers and owners](../../permissions.md#project-members-permissions) +can remove or disable a deploy key for a project repository: + +1. Navigate to the project's **Settings > Repository** page. +1. Expand the **Deploy keys** section. +1. Select the **{remove}** or **{cancel}** button. + +NOTE: +If anything relies on the removed deploy key, it will stop working once removed. + +If the key is **publicly accessible**, it will be removed from the project, but still available under **Publicly accessible deploy keys**. + +If the key is **privately accessible** and only in use by this project, it will deleted. + +If the key is **privately accessible** and in use by other projects, it will be removed from the project, but still available under **Privately accessible deploy keys**. + ## Troubleshooting ### Deploy key cannot push to a protected branch @@ -158,7 +176,7 @@ until a project maintainer chooses to make use of it. If the owner of this deploy key doesn't have access to a [protected branch](../protected_branches.md), then this deploy key doesn't have access to the branch either. In addition to this, choosing the **No one** value in -[the "Allowed to push" section](../protected_branches.md#configuring-protected-branches) +[the "Allowed to push" section](../protected_branches.md#configure-a-protected-branch) means that no users **and** no services using deploy keys can push to that selected branch. Refer to [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30769) for more information. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 842f167f6ec..e2fa63ce519 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -130,20 +130,12 @@ To pull packages in the GitLab package registry, you must: 1. For the [package type of your choice](../../packages/index.md), follow the authentication instructions for deploy tokens. -Example request publishing a generic package using a deploy token: +Example request publishing a NuGet package using a deploy token: ```shell -curl --header "DEPLOY-TOKEN: <deploy_token>" \ - --upload-file path/to/file.txt \ - "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt?status=hidden" -``` - -Example response: +nuget source Add -Name GitLab -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName deploy-token-username -Password 12345678asdf -```json -{ - "message":"201 Created" -} +nuget push mypkg.nupkg -Source GitLab ``` ### Push or upload packages diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index b51a1b79a13..576de63d00d 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -15,7 +15,7 @@ Although branching strategies usually work well enough for source code and plain text because different versions can be merged together, they do not work for binary files. -When file locking is setup, lockable files are **read only** by default. +When file locking is setup, lockable files are **read-only** by default. When a file is locked, only the user who locked the file may modify it. This user is said to "hold the lock" or have "taken the lock", since only one user diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index c914c90c923..2e5713e10be 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -49,3 +49,21 @@ file is in your default branch (usually `master`). NOTE: The Web IDE does not support `.gitattribute` files, but it's [planned for a future release](https://gitlab.com/gitlab-org/gitlab/-/issues/22014). + +## Configure maximum file size for highlighting + +You can configure the maximum size of the file to be highlighted. + +The file size is measured in kilobytes, and is set to a default of `512 KB`. Any file _over_ the file size is rendered in plain text. + +1. Open the [`gitlab.yml`](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/config/gitlab.yml.example) configuration file. + +1. Add this section, replacing `maximum_text_highlight_size_kilobytes` with the value you want. + + ```yaml + gitlab: + extra: + ## Maximum file size for syntax highlighting + ## https://docs.gitlab.com/ee/user/project/highlighting.html + maximum_text_highlight_size_kilobytes: 512 + ``` diff --git a/doc/user/project/img/bulk-editing_v13_2.png b/doc/user/project/img/bulk-editing_v13_2.png Binary files differdeleted file mode 100644 index 871cb02c01f..00000000000 --- a/doc/user/project/img/bulk-editing_v13_2.png +++ /dev/null diff --git a/doc/user/project/img/protected_branches_list_v12_3.png b/doc/user/project/img/protected_branches_list_v12_3.png Binary files differdeleted file mode 100644 index 995a294b85c..00000000000 --- a/doc/user/project/img/protected_branches_list_v12_3.png +++ /dev/null diff --git a/doc/user/project/img/protected_branches_page_v12_3.png b/doc/user/project/img/protected_branches_page_v12_3.png Binary files differdeleted file mode 100644 index 60aa3c4d251..00000000000 --- a/doc/user/project/img/protected_branches_page_v12_3.png +++ /dev/null diff --git a/doc/user/project/img/time_tracking_report_v13_12.png b/doc/user/project/img/time_tracking_report_v13_12.png Binary files differnew file mode 100644 index 00000000000..2132ca01cf4 --- /dev/null +++ b/doc/user/project/img/time_tracking_report_v13_12.png diff --git a/doc/user/project/img/time_tracking_sidebar_v13_12.png b/doc/user/project/img/time_tracking_sidebar_v13_12.png Binary files differnew file mode 100644 index 00000000000..e25282bc551 --- /dev/null +++ b/doc/user/project/img/time_tracking_sidebar_v13_12.png diff --git a/doc/user/project/img/time_tracking_sidebar_v8_16.png b/doc/user/project/img/time_tracking_sidebar_v8_16.png Binary files differdeleted file mode 100644 index 22124afed6f..00000000000 --- a/doc/user/project/img/time_tracking_sidebar_v8_16.png +++ /dev/null diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 6f274dd12a2..e77932c6427 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -14,26 +14,27 @@ Server (aka Stash). If you are trying to import projects from Bitbucket Server, Import your projects from Bitbucket Cloud to GitLab with minimal effort. -## Overview - -- At its current state, the Bitbucket importer can import: - - the repository description (GitLab 7.7+) - - the Git repository data (GitLab 7.7+) - - the issues (GitLab 7.7+) - - the issue comments (GitLab 8.15+) - - the pull requests (GitLab 8.4+) - - the pull request comments (GitLab 8.15+) - - the milestones (GitLab 8.15+) - - the wiki (GitLab 8.15+) -- References to pull requests and issues are preserved (GitLab 8.7+) -- Repository public access is retained. If a repository is private in Bitbucket - it will be created as private in GitLab as well. +The Bitbucket importer can import: + +- Repository description (GitLab 7.7+) +- Git repository data (GitLab 7.7+) +- Issues (GitLab 7.7+) +- Issue comments (GitLab 8.15+) +- Pull requests (GitLab 8.4+) +- Pull request comments (GitLab 8.15+) +- Milestones (GitLab 8.15+) +- Wiki (GitLab 8.15+) + +When importing: + +- References to pull requests and issues are preserved (GitLab 8.7+). +- Repository public access is retained. If a repository is private in Bitbucket, it's created as + private in GitLab as well. ## Requirements -The [Bitbucket Cloud integration](../../../integration/bitbucket.md) must be first enabled in order to be -able to import your projects from Bitbucket Cloud. Ask your GitLab administrator -to enable this if not already. +To import your projects from Bitbucket Cloud, the [Bitbucket Cloud integration](../../../integration/bitbucket.md) +must be enabled. Ask your GitLab administrator to enable this if it isn't already enabled. ## How it works diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index bb2256c9464..1e79107d76f 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -15,51 +15,49 @@ Use the [Bitbucket Cloud importer](bitbucket.md) for that. Import your projects from Bitbucket Server to GitLab with minimal effort. -## Overview +The Bitbucket importer can import: -- In its current state, the Bitbucket importer can import: - - the repository description (GitLab 11.2+) - - the Git repository data (GitLab 11.2+) - - the pull requests (GitLab 11.2+) - - the pull request comments (GitLab 11.2+) -- Repository public access is retained. If a repository is private in Bitbucket - it will be created as private in GitLab as well. +- Repository description (GitLab 11.2+) +- Git repository data (GitLab 11.2+) +- Pull requests (GitLab 11.2+) +- Pull request comments (GitLab 11.2+) + +When importing, repository public access is retained. If a repository is private in Bitbucket, it's +created as private in GitLab as well. ## Limitations -1. Currently GitLab doesn't allow comments on arbitrary lines of code, so any - Bitbucket comments out of bounds will be inserted as comments in the merge - request. -1. Bitbucket Server allows multiple levels of threading. GitLab import - will collapse this into one thread and quote part of the original comment. -1. Declined pull requests have unreachable commits, which prevents the GitLab - importer from generating a proper diff. These pull requests will show up as - empty changes. -1. Attachments in Markdown are currently not imported. -1. Task lists are not imported. -1. Emoji reactions are not imported -1. Project filtering does not support fuzzy search (only `starts with` or `full - match strings` are currently supported) +- GitLab doesn't allow comments on arbitrary lines of code, so any Bitbucket comments out of bounds + are inserted as comments in the merge request. +- Bitbucket Server allows multiple levels of threading. GitLab import collapses this into one thread + and quote part of the original comment. +- Declined pull requests have unreachable commits, which prevents the GitLab importer from + generating a proper diff. These pull requests show up as empty changes. +- Attachments in Markdown are not imported. +- Task lists are not imported. +- Emoji reactions are not imported. +- Project filtering does not support fuzzy search (only `starts with` or `full match strings` are + supported). ## How it works The Bitbucket Server importer works as follows: -1. The user will be prompted to enter the URL, username, and password (or personal access token) to log in to Bitbucket. +1. The user is prompted to enter the URL, username, and password (or personal access token) to log in to Bitbucket. These credentials are preserved only as long as the importer is running. -1. The importer will attempt to list all the current repositories on the Bitbucket Server. -1. Upon selection, the importer will clone the repository and import pull requests and comments. +1. The importer attempts to list all the current repositories on the Bitbucket Server. +1. Upon selection, the importer clones the repository and import pull requests and comments. ### User assignment When issues/pull requests are being imported, the Bitbucket importer tries to find the author's e-mail address with a confirmed e-mail address in the GitLab user database. If no such user is available, the project creator is set as -the author. The importer will append a note in the comment to mark the original +the author. The importer appends a note in the comment to mark the original creator. -The importer will create any new namespaces (groups) if they don't exist or in -the case the namespace is taken, the repository will be imported under the user's +The importer creates any new namespaces (groups) if they don't exist or in +the case the namespace is taken, the repository is imported under the user's namespace that started the import process. #### User assignment by username @@ -104,7 +102,7 @@ To disable it: Feature.disable(:bitbucket_server_user_mapping_by_username) ``` -## Importing your Bitbucket repositories +## Import your Bitbucket repositories 1. Sign in to GitLab and go to your dashboard. 1. Click on **New project**. @@ -118,7 +116,7 @@ Feature.disable(:bitbucket_server_user_mapping_by_username)  1. Click on the projects that you'd like to import or **Import all projects**. - You can also filter projects by name and select the namespace under which each project will be + You can also filter projects by name and select the namespace under which each project is imported.  diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 1371ca57bc9..09505d94a8c 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -8,12 +8,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import your project from FogBugz to GitLab It only takes a few simple steps to import your project from FogBugz. -The importer will import all of your cases and comments with original case -numbers and timestamps. You will also have the opportunity to map FogBugz -users to GitLab users. +The importer imports all your cases and comments with original case +numbers and timestamps. You can also map FogBugz users to GitLab users. -1. From your GitLab dashboard click 'New project' -1. Click on the 'FogBugz' button +Follow these steps to import your project from FogBugz: + +1. From your GitLab dashboard, select **New project**. + +1. Select the **FogBugz** button.  @@ -25,11 +27,11 @@ users to GitLab users.  -1. Select the projects you wish to import by clicking the Import buttons +1. Select the projects you wish to import by selecting the **Import** buttons.  -1. Once the import has finished click the link to take you to the project +1. Once the import finishes, click the link to go to the project dashboard. Follow the directions to push your existing repository.  diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md index bac10cb0948..5a4b16d57f5 100644 --- a/doc/user/project/import/gemnasium.md +++ b/doc/user/project/import/gemnasium.md @@ -1,117 +1,8 @@ --- -type: reference, howto -stage: Manage -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 +redirect_to: 'index.md' --- -# Gemnasium **(ULTIMATE)** +This document was deleted. -This guide describes how to migrate from Gemnasium.com to your own GitLab -instance or GitLab.com. - -## Why is Gemnasium.com closed? - -Gemnasium was [acquired by GitLab](https://about.gitlab.com/press/releases/2018-01-30-gemnasium-acquisition.html) -in January 2018. Since May 15, 2018, the services provided by Gemnasium are no longer available. -The team behind Gemnasium has joined GitLab as the new Security Products team -and is working on a [wide range of tools](../../application_security/index.md), -including: - -- [Dependency Scanning](../../application_security/dependency_scanning/index.md) -- [SAST](../../application_security/sast/index.md) -- [DAST](../../application_security/dast/index.md) -- [Container Scanning](../../application_security/container_scanning/index.md) - -If you want to continue monitoring your dependencies, see the -[Migrating to GitLab](#migrating-to-gitlab) section below. - -## What happened to my account? - -Your account has been automatically closed on May 15th, 2018. If you had a paid -subscription at that time, your card will be refunded on a -<!-- vale gitlab.Spelling = NO --> pro rata temporis <!-- vale gitlab.Spelling = YES --> basis. -You may contact `gemnasium@gitlab.com` regarding your closed account. - -## Will my account/data be transferred to GitLab Inc.? - -All accounts and data have been deleted on May 15th, 2018. GitLab Inc. -doesn't know anything about your private data, nor your projects, and therefore -if they were vulnerable or not. GitLab Inc. takes personal information very seriously. - -## What happened to my badge? - -To avoid broken 404 images, all badges pointing to Gemnasium.com will be a -placeholder, inviting you to migrate to GitLab (and pointing to this page). - -## Migrating to GitLab - -Gemnasium has been ported and integrated directly into GitLab CI/CD. -You can still benefit from our dependency monitoring features, and it requires -some steps to migrate your projects. There is no automatic import since GitLab -doesn't know anything about any projects which existed on Gemnasium.com. -Security features are free for public (open-source) projects hosted on GitLab.com. - -### If your project is hosted on GitLab (`https://gitlab.com` / self-managed) - -You're almost set! If you're already using -[Auto DevOps](../../../topics/autodevops/), you are already covered. -Otherwise, you must configure your `.gitlab-ci.yml` according to the -[dependency scanning page](../../application_security/dependency_scanning/index.md). - -### If your project is hosted on GitHub (`https://github.com` / GitHub Enterprise) - -Since [GitLab 10.6 comes with GitHub integration](https://about.gitlab.com/solutions/github/), -GitLab users can now create a CI/CD project in GitLab connected to an external -GitHub.com or GitHub Enterprise repository. This will automatically prompt -GitLab CI/CD to run whenever code is pushed to GitHub and post CI/CD results -back to both GitLab and GitHub when completed. - -<!-- vale gitlab.Spelling = NO --> - -1. Create a new project, and select **CI/CD for external repo**: - -  - <!-- vale gitlab.Spelling = YES --> - -1. Use the **GitHub** button to connect your repositories. - -  - -1. Select the project(s) to be set up with GitLab CI/CD and choose **Connect**. - -  - - After the configuration is done, you may click on your new - project on GitLab. - -  - - Your project is now mirrored on GitLab, where the runners will be able to access - your source code and run your tests. - - Optional step: If you set this up on GitLab.com, make sure the project is - public (in the project settings) if your GitHub project is public, since - the security feature is available only for [GitLab Ultimate](https://about.gitlab.com/pricing/). - -1. To set up the dependency scanning job, corresponding to what Gemnasium was - doing, you must create a `.gitlab-ci.yml` file, or update it according to - the [dependency scanning docs](../../application_security/dependency_scanning/index.md). - The mirroring is pull-only by default, so you may create or update the file on - GitHub: - -  - -1. Once your file has been committed, a new pipeline will be automatically - triggered if your file is valid: - -  - -1. The result of the job will be visible directly from the pipeline view: - -  - -NOTE: -If you don't commit very often to your project, you may want to use -[scheduled pipelines](../../../ci/pipelines/schedules.md) to run the job on a regular -basis. +<!-- This redirect file can be deleted after <2021-08-15>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
\ No newline at end of file diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 26e5a86b808..41141902468 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -9,20 +9,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w Import your projects from Gitea to GitLab with minimal effort. -## Overview - NOTE: This requires Gitea `v1.0.0` or newer. -- At its current state, Gitea importer can import: - - the repository description (GitLab 8.15+) - - the Git repository data (GitLab 8.15+) - - the issues (GitLab 8.15+) - - the pull requests (GitLab 8.15+) - - the milestones (GitLab 8.15+) - - the labels (GitLab 8.15+) -- Repository public access is retained. If a repository is private in Gitea - it will be created as private in GitLab as well. +The Gitea importer can import: + +- Repository description (GitLab 8.15+) +- Git repository data (GitLab 8.15+) +- Issues (GitLab 8.15+) +- Pull requests (GitLab 8.15+) +- Milestones (GitLab 8.15+) +- Labels (GitLab 8.15+) + +When importing, repository public access is retained. If a repository is private in Gitea, it's +created as private in GitLab as well. ## How it works @@ -31,23 +31,23 @@ to users in your GitLab instance. This means that the project creator (most of the times the current user that started the import process) is set as the author, but a reference on the issue about the original Gitea author is kept. -The importer will create any new namespaces (groups) if they don't exist or in -the case the namespace is taken, the repository will be imported under the user's +The importer creates any new namespaces (groups) if they don't exist or in +the case the namespace is taken, the repository is imported under the user's namespace that started the import process. -## Importing your Gitea repositories +## Import your Gitea repositories The importer page is visible when you create a new project.  -Click on the **Gitea** link and the import authorization process will start. +Click the **Gitea** link and the import authorization process starts.  ### Authorize access to your repositories using a personal access token -With this method, you will perform a one-off authorization with Gitea to grant +With this method, you perform a one-off authorization with Gitea to grant GitLab access your repositories: 1. Go to `https://your-gitea-instance/user/settings/applications` (replace @@ -58,27 +58,27 @@ GitLab access your repositories: 1. Copy the token hash. 1. Go back to GitLab and provide the token to the Gitea importer. 1. Hit the **List Your Gitea Repositories** button and wait while GitLab reads - your repositories' information. Once done, you'll be taken to the importer + your repositories' information. Once done, you are taken to the importer page to select the repositories to import. ### Select which repositories to import -After you've authorized access to your Gitea repositories, you will be +After you've authorized access to your Gitea repositories, you are redirected to the Gitea importer page. From there, you can see the import statuses of your Gitea repositories. -- Those that are being imported will show a _started_ status, -- those already successfully imported will be green with a _done_ status, -- whereas those that are not yet imported will have an **Import** button on the +- Those that are being imported show a _started_ status, +- those already successfully imported are green with a _done_ status, +- whereas those that are not yet imported have an **Import** button on the right side of the table. You also can: - Import all your Gitea projects in one go by hitting **Import all projects** in - the upper left corner + the upper left corner. - Filter projects by name. If filter is applied, hitting **Import all projects** - will only import matched projects + only imports matched projects.  diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index eb426a9f126..c8b973b673e 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -10,8 +10,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w Using the importer, you can import your GitHub repositories to GitLab.com or to your self-managed GitLab instance. -## Overview - The following aspects of a project are imported: - Repository description (GitLab.com & 7.7+) @@ -37,12 +35,12 @@ The namespace is a user or group in GitLab, such as `gitlab.com/janedoe` or `git This process does not migrate or import any types of groups or organizations from GitHub to GitLab. -### Use cases +## Use cases The steps you take depend on whether you are importing from GitHub.com or GitHub Enterprise, as well as whether you are importing to GitLab.com or self-managed GitLab instance. - If you're importing to GitLab.com, you can alternatively import GitHub repositories - using a [personal access token](#using-a-github-token). We do not recommend + 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. - If you're importing to a self-managed GitLab instance, you can alternatively use the @@ -62,9 +60,16 @@ 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 publicly visible - [primary email address](https://docs.github.com/en/rest/reference/users#get-a-user) - on their profile that matches their GitLab account's primary or secondary email address. +- Have a GitHub account with a [public-facing email address](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address) + that matches their GitLab account's email address. + + NOTE: + GitLab content imports that use GitHub accounts require that the GitHub public-facing + email address is populated so that all comments and contributions are properly mapped + to the same user in GitLab. GitHub Enterprise (on premise) does not require this field + to be populated to use the product, so you may need to add it on existing GitHub Enterprise + accounts for imported content to be properly mapped to the user in the new system. + Refer to GitHub documentation for instructions on how to add that address. If a user referenced in the project is not found in the GitLab database, the project creator (typically the user that initiated the import process) is set as the author/assignee, but a note on the issue mentioning the original @@ -86,7 +91,7 @@ For an overview of the import process, see the video [Migrating from GitHub to G ## Import your GitHub repository into GitLab -### Using the GitHub integration +### Use the GitHub integration Before you begin, ensure that any GitHub users who you want to map to GitLab users have either: @@ -105,9 +110,9 @@ If you are using a self-managed GitLab instance or if you are importing from Git 1. Select the **Import project** tab and then select **GitHub**. 1. Select the first button to **List your GitHub repositories**. You are redirected to a page on [GitHub](https://github.com) to authorize the GitLab application. 1. Click **Authorize GitlabHQ**. You are redirected back to the GitLab Import page and all of your GitHub repositories are listed. -1. Continue on to [selecting which repositories to import](#selecting-which-repositories-to-import). +1. Continue on to [selecting which repositories to import](#select-which-repositories-to-import). -### Using a GitHub token +### Use a GitHub token NOTE: Using a personal access token to import projects is not recommended. If you are a GitLab.com user, @@ -115,7 +120,7 @@ you can use a personal access token to import your project from GitHub, but this associate all user activity (such as issues and pull requests) with matching GitLab users. If you are an administrator of a self-managed GitLab instance or if you are importing from GitHub Enterprise, you cannot use a personal access token. -The [GitHub integration method (above)](#using-the-github-integration) is recommended for all users. +The [GitHub integration method (above)](#use-the-github-integration) is recommended for all users. Read more in the [How it works](#how-it-works) section. If you are not using the GitHub integration, you can still perform an authorization with GitHub to grant GitLab access your repositories: @@ -129,7 +134,7 @@ If you are not using the GitHub integration, you can still perform an authorizat 1. Hit the **List Your GitHub Repositories** button and wait while GitLab reads your repositories' information. Once done, you'll be taken to the importer page to select the repositories to import. -### Selecting which repositories to import +### Select which repositories to import After you have authorized access to your GitHub repositories, you are redirected to the GitHub importer page and your GitHub repositories are listed. @@ -155,7 +160,7 @@ Additionally, you can configure GitLab to send pipeline status updates back GitH If you import your project using [CI/CD for external repository](../../../ci/ci_cd_for_external_repos/index.md), then both of the above are automatically configured. **(PREMIUM)** -## Improving the speed of imports on self-managed instances +## Improve the speed of imports on self-managed instances NOTE: Administrator access to the GitLab server is required. diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index add457c217e..9e63b1cb617 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -19,10 +19,10 @@ you'll need to follow the instructions for [exporting a project](../settings/imp  -Go to the **Import Projects** tab, then click on **GitLab.com**, and you will be redirected to GitLab.com -for permission to access your projects. After accepting, you'll be automatically redirected to the importer. +Go to the **Import Projects** tab, then click on **GitLab.com**, and you are redirected to GitLab.com +for permission to access your projects. After accepting, you are automatically redirected to the importer.  -To import a project, click "Import". The importer will import your repository and issues. -Once the importer is done, a new GitLab project will be created with your imported data. +To import a project, click "Import". The importer imports your repository and issues. +Once the importer is done, a new GitLab project is created with your imported data. diff --git a/doc/user/project/import/img/gemnasium/connect_github_v13_5.png b/doc/user/project/import/img/gemnasium/connect_github_v13_5.png Binary files differdeleted file mode 100644 index 575d257a213..00000000000 --- a/doc/user/project/import/img/gemnasium/connect_github_v13_5.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/create_project_v13_5.png b/doc/user/project/import/img/gemnasium/create_project_v13_5.png Binary files differdeleted file mode 100644 index 37467bc3fed..00000000000 --- a/doc/user/project/import/img/gemnasium/create_project_v13_5.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/edit_gitlab-ci.png b/doc/user/project/import/img/gemnasium/edit_gitlab-ci.png Binary files differdeleted file mode 100644 index 8336c803b83..00000000000 --- a/doc/user/project/import/img/gemnasium/edit_gitlab-ci.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/pipeline.png b/doc/user/project/import/img/gemnasium/pipeline.png Binary files differdeleted file mode 100644 index ae4d5295ffa..00000000000 --- a/doc/user/project/import/img/gemnasium/pipeline.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/project_connected.png b/doc/user/project/import/img/gemnasium/project_connected.png Binary files differdeleted file mode 100644 index 332d2230ef8..00000000000 --- a/doc/user/project/import/img/gemnasium/project_connected.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/select_project_v13_5.png b/doc/user/project/import/img/gemnasium/select_project_v13_5.png Binary files differdeleted file mode 100644 index 30575954811..00000000000 --- a/doc/user/project/import/img/gemnasium/select_project_v13_5.png +++ /dev/null diff --git a/doc/user/project/import/img/jira/import_issues_from_jira_form_v13_2.png b/doc/user/project/import/img/jira/import_issues_from_jira_form_v13_2.png Binary files differindex 8a94d33d47b..dca60b2bc5c 100644 --- a/doc/user/project/import/img/jira/import_issues_from_jira_form_v13_2.png +++ b/doc/user/project/import/img/jira/import_issues_from_jira_form_v13_2.png diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index f6ed53763dd..3728a486070 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -5,50 +5,52 @@ 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 projects to a GitLab instance - -1. [From Bitbucket Cloud](bitbucket.md) -1. [From Bitbucket Server (also known as Stash)](bitbucket_server.md) -1. [From ClearCase](clearcase.md) -1. [From CVS](cvs.md) -1. [From FogBugz](fogbugz.md) -1. [From GitHub.com or GitHub Enterprise](github.md) -1. [From GitLab.com](gitlab_com.md) -1. [From Gitea](gitea.md) -1. [From Perforce](perforce.md) -1. [From SVN](svn.md) -1. [From TFVC](tfvc.md) -1. [From repository by URL](repo_by_url.md) -1. [By uploading a manifest file (AOSP)](manifest.md) -1. [From Gemnasium](gemnasium.md) -1. [From Phabricator](phabricator.md) -1. [From Jira (issues only)](jira.md) - -In addition to the specific migration documentation above, you can import any -Git repository via HTTP from the New Project page. Be aware that if the -repository is too large the import can timeout. - -There is also the option of [connecting your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)** +# Migrate projects to a GitLab instance + +See these documents to migrate to GitLab: + +- [From Bitbucket Cloud](bitbucket.md) +- [From Bitbucket Server (also known as Stash)](bitbucket_server.md) +- [From ClearCase](clearcase.md) +- [From CVS](cvs.md) +- [From FogBugz](fogbugz.md) +- [From GitHub.com or GitHub Enterprise](github.md) +- [From GitLab.com](gitlab_com.md) +- [From Gitea](gitea.md) +- [From Perforce](perforce.md) +- [From SVN](svn.md) +- [From TFVC](tfvc.md) +- [From repository by URL](repo_by_url.md) +- [By uploading a manifest file (AOSP)](manifest.md) +- [From Phabricator](phabricator.md) +- [From Jira (issues only)](jira.md) + +You can also import any Git repository through HTTP from the **New Project** page. Note that if the +repository is too large, the import can timeout. + +You can also [connect your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)** ## LFS authentication When importing a project that contains LFS objects, if the project has an [`.lfsconfig`](https://github.com/git-lfs/git-lfs/blob/master/docs/man/git-lfs-config.5.ronn) file with a URL host (`lfs.url`) different from the repository URL host, LFS files are not downloaded. -## Migrating from self-managed GitLab to GitLab.com +## Migrate from self-managed GitLab to GitLab.com -If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md). Issues and merge requests can't be imported. - -If you want to retain all metadata like issues and merge requests, you can use -the [import/export feature](../settings/import_export.md) to export projects from self-managed GitLab and import those projects into GitLab.com. - -All GitLab user associations (such as comment author) will be changed to the user importing the project. For more information, please see [the import notes](../settings/import_export.md#important-notes). - -If you need to migrate all data over, you can leverage our [API](../../../api/README.md) to migrate from self-managed to GitLab.com. -The order of assets to migrate from a self-managed instance to GitLab.com is the following: +If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md). +However, you can't import issues and merge requests this way. To retain all metadata like issues and +merge requests, use the [import/export feature](../settings/import_export.md) +to export projects from self-managed GitLab and import those projects into GitLab.com. All GitLab +user associations (such as comment author) are changed to the user importing the project. For more +information, see [the import notes](../settings/import_export.md#important-notes). NOTE: -When migrating to GitLab.com, users would need to be manually created unless [SCIM](../../../user/group/saml_sso/scim_setup.md) is going to be used. Creating users with the API is limited to self-managed instances as it requires administrator access. +When migrating to GitLab.com, you must create users manually unless [SCIM](../../../user/group/saml_sso/scim_setup.md) +will be used. Creating users with the API is limited to self-managed instances as it requires +administrator access. + +To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/README.md). +Migrate the assets in this order: 1. [Groups](../../../api/groups.md) 1. [Projects](../../../api/projects.md) @@ -56,43 +58,43 @@ When migrating to GitLab.com, users would need to be manually created unless [SC Keep in mind the limitations of the [import/export feature](../settings/import_export.md#exported-contents). -You will still need to migrate your Container Registry over a series of -Docker pulls and pushes and re-run any CI pipelines to retrieve any build artifacts. +You must still migrate your [Container Registry](../../packages/container_registry/) +over a series of Docker pulls and pushes. Re-run any CI pipelines to retrieve any build artifacts. -## Migrating from GitLab.com to self-managed GitLab +## Migrate from GitLab.com to self-managed GitLab -The process is essentially the same as for [migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). The main difference is that users can be created on the self-managed GitLab instance by an administrator through the UI or the [users API](../../../api/users.md#user-creation). +The process is essentially the same as [migrating from self-managed GitLab to GitLab.com](#migrate-from-self-managed-gitlab-to-gitlabcom). +The main difference is that an administrator can create users on the self-managed GitLab instance +through the UI or the [users API](../../../api/users.md#user-creation). -## Migrating between two self-managed GitLab instances +## Migrate between two self-managed GitLab instances -The best method for migrating from one GitLab instance to another, -perhaps from an old server to a new server for example, is to -[back up the instance](../../../raketasks/backup_restore.md), -then restore it on the new server. +To migrate from an existing self-managed GitLab instance to a new self-managed GitLab instance, it's +best to [back up](../../../raketasks/backup_restore.md) +the existing instance and restore it on the new instance. For example, this is useful when migrating +a self-managed instance from an old server to a new server. -In the event of merging two GitLab instances together (for example, both instances have existing data on them and one can't be wiped), -refer to the instructions in [Migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). +To instead merge two self-managed GitLab instances together, use the instructions in +[Migrate from self-managed GitLab to GitLab.com](#migrate-from-self-managed-gitlab-to-gitlabcom). +This method is useful when both self-managed instances have existing data that must be preserved. -Additionally, you can migrate users using the [Users API](../../../api/users.md) with an administrator user. +Also note that administrators can use the [Users API](../../../api/users.md) +to migrate users. ## Project aliases **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in GitLab Premium 12.1. -When migrating repositories to GitLab and they are being accessed by other systems, -it's very useful to be able to access them using the same name especially when -they are a lot. It reduces the risk of changing significant number of Git URLs in -a large number of systems. - -GitLab provides a functionality to help with this. In GitLab, repositories are -usually accessed with a namespace and project name. It is also possible to access -them via a project alias. This feature is only available on Git over SSH. +GitLab repositories are usually accessed with a namespace and a project name. When migrating +frequently accessed repositories to GitLab, however, you can use project aliases to access those +repositories with the original name. Accessing repositories through a project alias reduces the risk +associated with migrating such repositories. -A project alias can be only created via API and only by GitLab administrators. -Follow the [Project Aliases API documentation](../../../api/project_aliases.md) for -more details. +This feature is only available on Git over SSH. Also, only GitLab administrators can create project +aliases, and they can only do so through the API. For more information, see the +[Project Aliases API documentation](../../../api/project_aliases.md). -After an alias has been created for a project (such as an alias `gitlab` for the -project `https://gitlab.com/gitlab-org/gitlab`), you can clone the repository -with the alias (e.g `git clone git@gitlab.com:gitlab.git` instead of -`git clone git@gitlab.com:gitlab-org/gitlab.git`). +After an administrator creates an alias for a project, you can use the alias to clone the +repository. For example, if an administrator creates the alias `gitlab` for the project +`https://gitlab.com/gitlab-org/gitlab`, you can clone the project with +`git clone git@gitlab.com:gitlab.git` instead of `git clone git@gitlab.com:gitlab-org/gitlab.git`. diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index 5fb737cf74a..4273f90c1e7 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -54,13 +54,13 @@ Make sure you have the integration set up before trying to import Jira issues. > New import form [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216145) in GitLab 13.2. -To import Jira issues to a GitLab project, follow the steps below. - NOTE: Importing Jira issues is done as an asynchronous background job, which may result in delays based on import queues load, system load, or other factors. Importing large projects may take several minutes depending on the size of the import. +To import Jira issues to a GitLab project: + 1. On the **{issues}** **Issues** page, click **Import Issues** (**{import}**) **> Import from Jira**.  diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index 6ef91a54987..94eba319a17 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -29,7 +29,7 @@ A manifest must be an XML file. There must be one `remote` tag with a `review` attribute that contains a URL to a Git server, and each `project` tag must have a `name` and `path` attribute. GitLab will then build the URL to the repository by combining the URL from the `remote` tag with a project name. -A path attribute will be used to represent the project path in GitLab. +A path attribute is used to represent the project path in GitLab. Below is a valid example of a manifest file: @@ -42,23 +42,23 @@ Below is a valid example of a manifest file: </manifest> ``` -As a result, the following projects will be created: +As a result, the following projects are created: | GitLab | Import URL | |:------------------------------------------------|:------------------------------------------------------------| | `https://gitlab.com/YOUR_GROUP/build/make` | <https://android.googlesource.com/platform/build> | | `https://gitlab.com/YOUR_GROUP/build/blueprint` | <https://android.googlesource.com/platform/build/blueprint> | -## Importing the repositories +## Import the repositories -You can start the import with: +To start the import: -1. From your GitLab dashboard click **New project** -1. Switch to the **Import project** tab -1. Click on the **Manifest file** button -1. Provide GitLab with a manifest XML file -1. Select a group you want to import to (you need to create a group first if you don't have one) -1. Click **List available repositories**. At this point, you will be redirected +1. From your GitLab dashboard click **New project**. +1. Switch to the **Import project** tab. +1. Click on the **Manifest file** button. +1. Provide GitLab with a manifest XML file. +1. Select a group you want to import to (you need to create a group first if you don't have one). +1. Click **List available repositories**. At this point, you are redirected to the import status page with projects list based on the manifest file. 1. Check the list and click **Import all repositories** to start the import. diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index 91fd7b8928b..30a63a72cf9 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -20,7 +20,7 @@ GitLab allows you to import all tasks from a Phabricator instance into GitLab issues. The import creates a single project with the repository disabled. -Currently, only the following basic fields are imported: +Only the following basic fields are imported: - Title - Description @@ -34,6 +34,6 @@ The assignee and author of a user are deducted from a Task's owner and author: If a user with the same username has access to the namespace of the project being imported into, then the user will be linked. -## Enabling this feature +## Enable this feature Enable Phabricator as an [import source](../../admin_area/settings/visibility_and_access_controls.md#import-sources) in the Admin Area. diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index a816dca59bc..e39976e00f6 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -11,18 +11,16 @@ 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. -## Overview - There are two approaches to SVN to Git migration: -1. [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 to manage migration risks. +- [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. -1. [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. +- [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. ## Smooth migration with a Git/SVN mirror using SubGit @@ -38,15 +36,15 @@ directly in a file system level. 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 will be available at `/opt/subgit-VERSION/bin/subgit`. + command is available at `/opt/subgit-VERSION/bin/subgit`. ### SubGit configuration The first step to mirror you SVN repository in GitLab is to create a new empty -project which will be used as a mirror. For Omnibus installations the path to -the repository will be located at +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 will be +installations from source, the default repository directory is `/home/git/repositories/USER/REPO.git`. For convenience, assign this path to a variable: @@ -54,7 +52,7 @@ variable: GIT_REPO_PATH=/var/opt/gitlab/git-data/repositories/USER/REPOS.git ``` -SubGit will keep this repository in sync with a remote SVN project. For +SubGit keeps this repository in sync with a remote SVN project. For convenience, assign your remote SVN project URL to a variable: ```shell @@ -89,9 +87,9 @@ initial translation of existing SVN revisions into the Git repository: subgit install $GIT_REPO_PATH ``` -After the initial translation is completed, the Git repository and the SVN -project will be kept in sync by `subgit` - new Git commits will be translated to -SVN revisions and new SVN revisions will be translated to Git commits. Mirror +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. If you would prefer to perform one-time cut over migration with `subgit`, use @@ -134,12 +132,12 @@ 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 will not be attributed +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 will want to ensure they complete this step. If you choose to map authors -you will be required to map every author that is present on changes in the SVN -repository. If you don't, the conversion will fail and you will have to update -the author file accordingly. The following command will search through the +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 @@ -159,7 +157,7 @@ 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 will take some time. +running the `svn2git` command. The conversion process takes some time. ```shell svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt @@ -167,13 +165,13 @@ 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, etc. See +`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, where you will eventually push your converted code. +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 will push all commits, +repository as a Git remote and push all the changes. This pushes all commits, branches and tags. ```shell diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md index 0d347a16697..705df686fe0 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts --- -# Migrating from TFVC to Git +# Migrate from TFVC to Git Team Foundation Server (TFS), renamed [Azure DevOps Server](https://azure.microsoft.com/en-us/services/devops/server/) in 2019, is a set of tools developed by Microsoft which also includes @@ -46,12 +46,8 @@ Advantages of migrating to Git/GitLab: Migration options from TFVC to Git depend on your operating system. -- If you're migrating on Microsoft Windows: - - Use the [`git-tfs`](https://github.com/git-tfs/git-tfs) -tool. - Read the [Migrate TFS to Git](https://github.com/git-tfs/git-tfs/blob/master/doc/usecases/migrate_tfs_to_git.md) guide for details. - -- If you're on a Unix-based system: - - Follow the procedures described with this [TFVC to Git migration tool](https://github.com/turbo/gtfotfs). +- If you're migrating on Microsoft Windows, use the [`git-tfs`](https://github.com/git-tfs/git-tfs) + tool. See [Migrate TFS to Git](https://github.com/git-tfs/git-tfs/blob/master/doc/usecases/migrate_tfs_to_git.md) + for details. +- If you're on a Unix-based system, follow the procedures described with this + [TFVC to Git migration tool](https://github.com/turbo/gtfotfs). diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 7e5801a2382..d9283f623d4 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -45,7 +45,7 @@ Projects include the following [features](https://about.gitlab.com/features/): - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (Issue Boards) for a project. - [Merge Requests](merge_requests/index.md): Apply a branching strategy and get reviewed by your team. - - [Merge Request Approvals](merge_requests/merge_request_approvals.md): Ask for approval before + - [Merge Request Approvals](merge_requests/approvals/index.md): Ask for approval before implementing a change. - [Fix merge conflicts from the UI](merge_requests/resolve_conflicts.md): View Git diffs from the GitLab UI. - [Review Apps](../../ci/review_apps/index.md): By branch, preview the results diff --git a/doc/user/project/insights/img/insights_sidebar_link_v12_8.png b/doc/user/project/insights/img/insights_sidebar_link_v12_8.png Binary files differdeleted file mode 100644 index b07ecc5286a..00000000000 --- a/doc/user/project/insights/img/insights_sidebar_link_v12_8.png +++ /dev/null diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 72897a1a26e..436df07d673 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -20,9 +20,7 @@ This feature is [also available at the group level](../../group/insights/index.m ## View your project's Insights You can access your project's Insights by clicking the **Analytics > Insights** -link in the left sidebar: - - +link in the left sidebar. ## Configure your Insights diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 7e14515d98e..e8427e36015 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -4,33 +4,55 @@ group: Ecosystem 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 --- -# Bugzilla Service **(FREE)** +# Bugzilla service **(FREE)** -Navigate to the [Integrations page](overview.md#accessing-integrations), -select the **Bugzilla** service and fill in the required details as described -in the table below. +[Bugzilla](https://www.bugzilla.org/) is a web-based general-purpose bug tracking system and testing +tool. -| Field | Description | -| ----- | ----------- | -| `project_url` | The URL to the project in Bugzilla which is being linked to this GitLab project. Note that the `project_url` requires PRODUCT_NAME to be updated with the product/project name in Bugzilla. | -| `issues_url` | The URL to the issue in Bugzilla project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | -| `new_issue_url` | This is the URL to create a new issue in Bugzilla for the project linked to this GitLab project. Note that the `new_issue_url` requires PRODUCT_NAME to be updated with the product/project name in Bugzilla. | +You can configure Bugzilla as an +[external issue tracker](../../../integration/external-issue-tracker.md) in GitLab. -Once you have configured and enabled Bugzilla, you see the Bugzilla link on the GitLab project pages that takes you to the appropriate Bugzilla project. +To enable the Bugzilla integration in a project: -## Referencing issues in Bugzilla +1. Go to the [Integrations page](overview.md#accessing-integrations). +1. Select **Bugzilla**. +1. Select the checkbox under **Enable integration**. +1. Fill in the required fields: -Issues in Bugzilla can be referenced in two alternative ways: + - **Project URL**: The URL to the project in Bugzilla. + For example, for a product named "Fire Tanuki": + `https://bugzilla.example.org/describecomponents.cgi?product=Fire+Tanuki`. + - **Issue URL**: The URL to view an issue in the Bugzilla project. + The URL must contain `:id`. GitLab replaces `:id` with the issue number (for example, + `https://bugzilla.example.org/show_bug.cgi?id=:id`, which becomes + `https://bugzilla.example.org/show_bug.cgi?id=123`). + - **New issue URL**: The URL to create a new issue in the linked Bugzilla project. + For example, for a project named "My Cool App": + `https://bugzilla.example.org/enter_bug.cgi#h=dupes%7CMy+Cool+App`. -- `#<ID>` where `<ID>` is a number (example `#143`). -- `<PROJECT>-<ID>` where `<PROJECT>` starts with a capital letter which is - then followed by capital letters, numbers or underscores, and `<ID>` is - a number (example `API_32-143`). +1. Select **Save changes** or optionally select **Test settings**. -We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker, the internal issue is linked. +After you configure and enable Bugzilla, a link appears on the GitLab +project pages. This link takes you to the appropriate Bugzilla project. -Please note that `<PROJECT>` part is ignored and links always point to the -address specified in `issues_url`. +You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. +Learn more about the steps and consequences of disabling GitLab issues in +[Sharing and permissions](../settings/index.md#sharing-and-permissions). + +## Reference Bugzilla issues in GitLab + +You can reference issues in Bugzilla using: + +- `#<ID>`, where `<ID>` is a number (for example, `#143`). +- `<PROJECT>-<ID>` (for example `API_32-143`) where: + - `<PROJECT>` starts with a capital letter, followed by capital letters, numbers, or underscores. + - `<ID>` is a number. + +The `<PROJECT>` part is ignored in links, which always point to the address specified in **Issue URL**. + +We suggest using the longer format (`<PROJECT>-<ID>`) if you have both internal and external issue +trackers enabled. If you use the shorter format, and an issue with the same ID exists in the +internal issue tracker, the internal issue is linked. ## Troubleshooting diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 9cc4e980212..19beafd6663 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -4,35 +4,43 @@ group: Ecosystem 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 --- -# Custom Issue Tracker service **(FREE)** +# Custom issue tracker service **(FREE)** -To enable the Custom Issue Tracker integration in a project: +Use a custom issue tracker that is not in the integration list. -1. Go to **Settings > Integrations**. -1. Click **Custom Issue Tracker** -1. Fill in the tracker's details, such as title, description, and URLs. - You can edit these fields later as well. +To enable a custom issue tracker in a project: - These are some of the required fields: +1. Go to the [Integrations page](overview.md#accessing-integrations). +1. Select **Custom issue tracker**. +1. Select the checkbox under **Enable integration**. +1. Fill in the required fields: - | Field | Description | - | --------------- | ----------- | - | **Project URL** | The URL to the project in the custom issue tracker. | - | **Issues URL** | The URL to the issue in the issue tracker project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. For example, `https://customissuetracker.com/project-name/:id`. | - | **New issue URL** | Currently unused. Planned to be changed in a future release. | + - **Project URL**: The URL to view all the issues in the custom issue tracker. + - **Issue URL**: The URL to view an issue in the custom issue tracker. The URL must contain `:id`. + GitLab replaces `:id` with the issue number (for example, + `https://customissuetracker.com/project-name/:id`, which becomes `https://customissuetracker.com/project-name/123`). + - **New issue URL**: + <!-- The line below was originally added in January 2018: https://gitlab.com/gitlab-org/gitlab/-/commit/778b231f3a5dd42ebe195d4719a26bf675093350 --> + **This URL is not used and removal is planned in a future release.** + Enter any URL here. + For more information, see [issue 327503](https://gitlab.com/gitlab-org/gitlab/-/issues/327503). -1. Click **Test settings and save changes**. +1. Select **Save changes** or optionally select **Test settings**. -After you configure and enable the Custom Issue Tracker service, you see a link on the GitLab -project pages that takes you to that custom issue tracker. +After you configure and enable the custom issue tracker service, a link appears on the GitLab +project pages. This link takes you to the custom issue tracker. -## Referencing issues +## Reference issues in a custom issue tracker -Issues are referenced with `<ANYTHING>-<ID>` (for example, `PROJECT-143`), where `<ANYTHING>` can be any string in CAPS, and `<ID>` -is a number used in the target project of the custom integration. +You can reference issues in a custom issue tracker using: -`<ANYTHING>` is a placeholder to differentiate against GitLab issues, which are referenced with `#<ID>`. You can use a project name or project key to replace it for example. +- `#<ID>`, where `<ID>` is a number (for example, `#143`). +- `<PROJECT>-<ID>` (for example `API_32-143`) where: + - `<PROJECT>` starts with a capital letter, followed by capital letters, numbers, or underscores. + - `<ID>` is a number. -When building the hyperlink, the `<ANYTHING>` part is ignored, and links always point to the address -specified in `issues_url`, so in the example above, `PROJECT-143` would refer to -`https://customissuetracker.com/project-name/143`. +The `<PROJECT>` part is ignored in links, which always point to the address specified in **Issue URL**. + +We suggest using the longer format (`<PROJECT>-<ID>`) if you have both internal and external issue +trackers enabled. If you use the shorter format, and an issue with the same ID exists in the +internal issue tracker, the internal issue is linked. diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index d63599d02bc..5b0059673ad 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -6,31 +6,49 @@ info: To determine the technical writer assigned to the Stage/Group associated w # IBM Engineering Workflow Management (EWM) Integration **(FREE)** -This service allows you to navigate from GitLab to EWM work items mentioned in merge request descriptions and commit messages. Each work item reference is automatically converted to a link back to the work item. +This service allows you to go from GitLab to EWM work items mentioned in merge request +descriptions and commit messages. +Each work item reference is automatically converted to a link to the work item. -NOTE: -This IBM product was [formerly named Rational Team Concert](https://jazz.net/blog/index.php/2019/04/23/renaming-the-ibm-continuous-engineering-portfolio/)(RTC). This integration is also compatible with all versions of RTC and EWM. +This IBM product was [formerly named Rational Team Concert](https://jazz.net/blog/index.php/2019/04/23/renaming-the-ibm-continuous-engineering-portfolio/)(RTC). This integration is compatible with all versions of RTC and EWM. -1. From a GitLab project, navigate to **Settings > Integrations**, and then click **EWM**. -1. Enter the information listed below. +To enable the EWM integration, in a project: - | Field | Description | - | ----- | ----------- | - | `project_url` | URL of the EWM project area to link to the GitLab project. To obtain your project area URL, navigate to the path `/ccm/web/projects` and copy the listed project's URL. For example, `https://example.com/ccm/web/Example%20Project` | - | `issues_url` | URL to the work item editor in the EWM project area. The format is `<your-server-url>/resource/itemName/com.ibm.team.workitem.WorkItem/:id`. For example, `https://example.com/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/:id` | - | `new_issue_url` | URL to create a new work item in the EWM project area. Append the following fragment to your project area URL: `#action=com.ibm.team.workitem.newWorkItem`. For example, `https://example.com/ccm/web/projects/JKE%20Banking#action=com.ibm.team.workitem.newWorkItem` | +1. Go to the [Integrations page](overview.md#accessing-integrations). +1. Select **EWM**. +1. Select the checkbox under **Enable integration**. +1. Fill in the required fields: + + - **Project URL**: The URL to the EWM project area. + + To obtain your project area URL, navigate to the + path `/ccm/web/projects` and copy the listed project's URL. For example, `https://example.com/ccm/web/Example%20Project`. + - **Issue URL**: The URL to the work item editor in the EWM project area. + + The format is `<your-server-url>/resource/itemName/com.ibm.team.workitem.WorkItem/:id`. + GitLab replaces `:id` with the issue number + (for example, `https://example.com/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/:id`, + which becomes `https://example.com/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/123`). + - **New issue URL**: URL to create a new work item in the EWM project area. + + Append the following fragment to your project area URL: `#action=com.ibm.team.workitem.newWorkItem`. + For example, `https://example.com/ccm/web/projects/JKE%20Banking#action=com.ibm.team.workitem.newWorkItem`. + +1. Select **Save changes** or optionally select **Test settings**. ## Reference EWM work items in commit messages -You can use any of the keywords supported by the EWM Git Integration Toolkit to refer to work items. Work items can be referenced using the format: `<keyword> <id>`. +To refer to work items, you can use any keywords supported by the EWM Git Integration Toolkit. +Use the format: `<keyword> <id>`. You can use the following keywords: - `bug` -- `task` - `defect` - `rtcwi` -- `workitem` +- `task` - `work item` +- `workitem` -For more details, see the EWM documentation page [Creating links from commit comments](https://www.ibm.com/support/knowledgecenter/SSYMRC_7.0.0/com.ibm.team.connector.cq.doc/topics/t_creating_links_through_comments.html), which recommends against using the additionally-supported keyword `#` because of incompatibility with GitLab. +Avoid using the keyword `#`. Learn more in the EWM documentation page +[Creating links from commit comments](https://www.ibm.com/docs/en/elm/7.0.0?topic=commits-creating-links-from-commit-comments). diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index d0efebd4da7..0668e5dd88f 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -4,32 +4,50 @@ group: Ecosystem 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 --- -# Hangouts Chat service **(FREE)** +# Google Chat integration **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/43756) in GitLab 11.2. -The Hangouts Chat service sends notifications from GitLab to the room for which the webhook was created. +Integrate your project to send notifications from GitLab to a +room of your choice in [Google Chat](https://chat.google.com/) (former Google +Hangouts). -## On Hangouts Chat +## How it works -1. Open the chat room in which you want to see the notifications. -1. From the chat room menu, select **Configure Webhooks**. -1. Click on **ADD WEBHOOK** and fill in the name of the bot to post the messages. Optionally define an avatar. -1. Click **SAVE** and copy the **Webhook URL** of your webhook. +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. -See also [the Hangouts Chat documentation for configuring incoming webhooks](https://developers.google.com/hangouts/chat/how-tos/webhooks) +After that, enable the integration in GitLab and choose the events you want to +be notified about in your Google Chat room. -## On GitLab +For every selected event in your project, GitLab acts like a bot sending +notifications to Google Chat: -When you have the **Webhook URL** for your Hangouts Chat room webhook, you can set up the GitLab service. + -1. Navigate to the [Integrations page](overview.md#accessing-integrations) in your project's settings, i.e. **Project > Settings > Integrations**. -1. Select the **Hangouts Chat** integration to configure it. -1. Ensure that the **Active** toggle is enabled. -1. Check the checkboxes corresponding to the GitLab events you want to receive. -1. Paste the **Webhook URL** that you copied from the Hangouts Chat configuration step. -1. Configure the remaining options and click `Save changes`. +## In Google Chat -Your Hangouts Chat room now starts receiving GitLab event notifications as configured. +Select a room and create a webhook: - +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**. +1. Enter the name for your webhook, for example "GitLab integration". +1. (Optional) Add an avatar for your bot. +1. Select **Save**. +1. Copy the webhook URL. + +For further details, see [the Google Chat documentation for configuring webhooks](https://developers.google.com/hangouts/chat/how-tos/webhooks). + +## In GitLab + +Enable the Google Chat 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. +1. Enter the webhook URL you copied from Google Chat. +1. Select the events you want to be notified about in your Google Chat room. +1. (Optional) Select **Test settings** to verify the connection. +1. Select **Save changes**. + +To test the integration, make a change based on the events you selected and +see the notification in your Google Chat room. diff --git a/doc/user/project/integrations/img/emails_on_push_service.png b/doc/user/project/integrations/img/emails_on_push_service.png Binary files differdeleted file mode 100644 index 43cef167369..00000000000 --- a/doc/user/project/integrations/img/emails_on_push_service.png +++ /dev/null diff --git a/doc/user/project/integrations/img/google_chat_integration_v13_11.png b/doc/user/project/integrations/img/google_chat_integration_v13_11.png Binary files differnew file mode 100644 index 00000000000..b2df55816d5 --- /dev/null +++ b/doc/user/project/integrations/img/google_chat_integration_v13_11.png diff --git a/doc/user/project/integrations/img/hangouts_chat_configuration.png b/doc/user/project/integrations/img/hangouts_chat_configuration.png Binary files differdeleted file mode 100644 index 1104f20ce2f..00000000000 --- a/doc/user/project/integrations/img/hangouts_chat_configuration.png +++ /dev/null diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 0a32119d572..18ff6e324e3 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -48,10 +48,16 @@ notification. You do not need to add the hash sign (`#`). Then fill in the integration configuration: -| Field | Description | -| ----- | ----------- | -| **Webhook** | The incoming webhook URL on Mattermost, similar to: `http://mattermost.example/hooks/5xo…`. | -| **Username** | (Optional) The username to show on messages sent to Mattermost. Fill this in to change the username of the bot. | -| **Notify only broken pipelines** | If you enable the **Pipeline** event and you want to be notified about failed pipelines only. | -| **Branches to be notified** | Select which branches to send notifications for. | -| **Labels to be notified** | (Optional) Labels that the issue or merge request must have to trigger a notification. Leave blank to get notifications for all issues and merge requests. | +- **Webhook**: The incoming webhook URL on Mattermost, similar to + `http://mattermost.example/hooks/5xo…`. +- **Username**: (Optional) The username shown in messages sent to Mattermost. + To change the bot's username, provide a value. +- **Notify only broken pipelines**: If you enable the **Pipeline** event, and you want + notifications about failed pipelines only. +- **Branches to be notified**: The branches to send notifications for. +- **Labels to be notified**: (Optional) Labels required for the issue or merge request + to trigger a notification. Leave blank to notify for all issues and merge requests. +- **Labels to be notified behavior**: When you use the **Labels to be notified** filter, + messages are sent when an issue or merge request contains _any_ of the labels specified + in the filter. You can also choose to trigger messages only when the issue or merge request + contains _all_ the labels defined in the filter. diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index ef1f492bfbf..5bd4062b125 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -39,9 +39,9 @@ Click on the service links to see further configuration instructions and details | [Emails on push](emails_on_push.md) | Send commits and diff of each push by email. | **{dotted-circle}** No | | [EWM](ewm.md) | Use IBM Engineering Workflow Management as the issue tracker. | **{dotted-circle}** No | | [External wiki](../wiki/index.md#link-an-external-wiki) | Link an external wiki. | **{dotted-circle}** No | -| Flowdock | Use Flowdock with GitLab. | **{dotted-circle}** No | +| [Flowdock](../../../api/services.md#flowdock) | Send notifications from GitLab to Flowdock flows. | **{dotted-circle}** No | | [GitHub](github.md) | Obtain statuses for commits and pull requests. | **{dotted-circle}** No | -| [Hangouts Chat](hangouts_chat.md) | Receive events notifications. | **{dotted-circle}** No | +| [Google Chat](hangouts_chat.md) | Send notifications from your GitLab project to a room in Google Chat.| **{dotted-circle}** No | | [Irker (IRC gateway)](irker.md) | Send IRC messages. | **{dotted-circle}** No | | [Jenkins](../../../integration/jenkins.md) | Run CI/CD pipelines with Jenkins. | **{check-circle}** Yes | | JetBrains TeamCity CI | Run CI/CD pipelines with TeamCity. | **{check-circle}** Yes | diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index 0eaa9cae7c0..b35ebacbd31 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -31,7 +31,7 @@ Cloudwatch exporter retrieves and parses the specified Cloudwatch metrics, and translates them into a Prometheus monitoring endpoint. The only supported AWS resource is the Elastic Load Balancer, whose Cloudwatch -metrics are [documented here](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-cloudwatch-metrics.html). +metrics are listed in [this AWS documentation](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-cloudwatch-metrics.html). You can [download a sample Cloudwatch Exporter configuration file](../samples/cloudwatch.yml) that's configured for basic AWS ELB monitoring. diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 6820412808f..b2bf8e5731a 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -6,25 +6,32 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Webex Teams service **(FREE)** -You can configure GitLab to send notifications to a Webex Teams space. +You can configure GitLab to send notifications to a Webex Teams space: + +1. Create a webhook for the space. +1. Add the webhook to GitLab. ## Create a webhook for the space 1. Go to the [Incoming Webhooks app page](https://apphub.webex.com/messaging/applications/incoming-webhooks-cisco-systems-38054). -1. Click **Connect** and log in to Webex Teams, if required. +1. Select **Connect** and log in to Webex Teams, if required. 1. Enter a name for the webhook and select the space to receive the notifications. -1. Click **ADD**. +1. Select **ADD**. 1. Copy the **Webhook URL**. ## Configure settings in GitLab -Once you have a webhook URL for your Webex Teams space, you can configure GitLab to send notifications. +Once you have a webhook URL for your Webex Teams space, you can configure GitLab to send +notifications: -1. Navigate to **Project > Settings > Integrations**. +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. + - **Settings > Integrations** in the Admin Area (**{admin}**) to enable an instance-level integration. 1. Select the **Webex Teams** integration. 1. Ensure that the **Active** toggle is enabled. 1. Select the checkboxes corresponding to the GitLab events you want to receive in Webex Teams. 1. Paste the **Webhook** URL for the Webex Teams space. 1. Configure the remaining options and then click **Test settings and save changes**. -The Webex Teams space now begins to receive all applicable GitLab events. +The Webex Teams space begins to receive all applicable GitLab events. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 56a339e02d2..d74a2bec1f6 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1368,6 +1368,7 @@ X-Gitlab-Event: Deployment Hook { "object_kind": "deployment", "status": "success", + "status_changed_at":"2021-04-28 21:50:00 +0200", "deployable_id": 796, "deployable_url": "http://10.126.0.2:3000/root/test-deployment-webhooks/-/jobs/796", "environment": "staging", diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index f9f61de9d6b..f39c34ccc0a 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -4,40 +4,38 @@ group: Ecosystem 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 --- -# YouTrack Service **(FREE)** +# YouTrack service **(FREE)** -JetBrains [YouTrack](https://www.jetbrains.com/help/youtrack/standalone/YouTrack-Documentation.html) is a web-based issue tracking and project management platform. +JetBrains [YouTrack](https://www.jetbrains.com/youtrack/) is a web-based issue tracking and project +management platform. -You can configure YouTrack as an [External Issue Tracker](../../../integration/external-issue-tracker.md) in GitLab. +You can configure YouTrack as an +[external issue tracker](../../../integration/external-issue-tracker.md) in GitLab. -## Enable the YouTrack integration +To enable the YouTrack integration in a project: -To enable YouTrack integration in a project: +1. Go to the [Integrations page](overview.md#accessing-integrations). +1. Select **YouTrack**. +1. Select the checkbox under **Enable integration**. +1. Fill in the required fields: + - **Project URL**: The URL to the project in YouTrack. + - **Issue URL**: The URL to view an issue in the YouTrack project. + The URL must contain `:id`. GitLab replaces `:id` with the issue number. +1. Select **Save changes** or optionally select **Test settings**. -1. Navigate to the project's **Settings > [Integrations](overview.md#accessing-integrations)** page. -1. Click the **YouTrack** service, ensure it's active, and enter the required details on the page as described in the table below. +After you configure and enable YouTrack, a link appears on the GitLab +project pages. This link takes you to the appropriate YouTrack project. - | Field | Description | - |:----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| - | **Project URL** | URL to the project in YouTrack which is being linked to this GitLab project. | - | **Issues URL** | URL to the issue in YouTrack project that is linked to this GitLab project. Note that the **Issues URL** requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | +You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. +Learn more about the steps and consequences of disabling GitLab issues in +[Sharing and permissions](../settings/index.md#sharing-and-permissions). -1. Click the **Save changes** button. +## Reference YouTrack issues in GitLab -Once you have configured and enabled YouTrack, you see the YouTrack link on the GitLab project pages that takes you to the appropriate YouTrack project. +You can reference issues in YouTrack using `<PROJECT>-<ID>` (for example `YT-101`, `Api_32-143` or `gl-030`) where: -## Disable the internal issue tracker +- `<PROJECT>` starts with a letter and is followed by letters, numbers, or underscores. +- `<ID>` is a number. -To disable the internal issue tracker in a project: - -1. Navigate to the project's **Settings > General** page. -1. Expand the [permissions section](../settings/index.md#sharing-and-permissions) and switch the **Issues** toggle to disabled. - -## Referencing YouTrack issues in GitLab - -Issues in YouTrack can be referenced as `<PROJECT>-<ID>`. `<PROJECT>` -must start with a letter and is followed by letters, numbers, or underscores. -`<ID>` is a number. An example reference is `YT-101`, `Api_32-143` or `gl-030`. - -References to `<PROJECT>-<ID>` in merge requests, commits, or comments are automatically linked to the YouTrack issue URL. -For more information, see the [External Issue Tracker](../../../integration/external-issue-tracker.md) documentation. +References to `<PROJECT>-<ID>` in merge requests, commits, or comments are automatically linked +to the YouTrack issue URL. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 5ddf98d4560..e1b6956f873 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -343,11 +343,10 @@ As in other list types, click the trash icon to remove a list. ### Iteration lists **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250479) in GitLab 13.11. -> - [Deployed behind the `board_new_lists` and `iteration_board_lists` feature flags](../feature_flags.md), disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57439) in GitLab 13.11. +> - [Deployed behind the `board_new_list` and `iteration_board_lists` feature flags](../feature_flags.md), enabled by default. > - Enabled on GitLab.com. > - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to disable the feature flags: [`board_new_lists`](#enable-or-disable-new-add-list-form) and [`iteration_board_lists`](#enable-or-disable-iteration-lists-in-boards). **(PREMIUM SELF)** +> - For GitLab self-managed instances, GitLab administrators can opt to disable the feature flags: [`board_new_list`](#enable-or-disable-new-add-list-form) and [`iteration_board_lists`](#enable-or-disable-iteration-lists-in-boards). **(PREMIUM SELF)** There can be [risks when disabling released features](../feature_flags.md#risks-when-disabling-released-features). diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index f5eb8dd5a4d..2a003e68a73 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -31,7 +31,7 @@ to be enabled: - For self-managed instances, a GitLab administrator must have [enabled LFS globally](../../../administration/lfs/index.md). - For both GitLab.com and self-managed instances: LFS must be enabled for the project itself. - If enabled globally, LFS will be enabled by default to all projects. To enable LFS on the + If enabled globally, LFS is enabled by default to all projects. To enable LFS on the project level, navigate to your project's **Settings > General**, expand **Visibility, project features, permissions** and enable **Git Large File Storage**. @@ -56,7 +56,7 @@ Support for [PDF](https://gitlab.com/gitlab-org/gitlab/issues/32811) is planned - From GitLab 13.1, Design filenames are limited to 255 characters. - Design Management data [isn't deleted when a project is destroyed](https://gitlab.com/gitlab-org/gitlab/-/issues/13429) yet. -- Design Management data [won't be deleted](https://gitlab.com/gitlab-org/gitlab/-/issues/13427) +- Design Management data [isn't deleted](https://gitlab.com/gitlab-org/gitlab/-/issues/13427) when an issue is deleted. - From GitLab 12.7, Design Management data [can be replicated](../../../administration/geo/replication/datatypes.md#limitations-on-replicationverification) by Geo but [not verified](https://gitlab.com/gitlab-org/gitlab/-/issues/32467). @@ -102,19 +102,19 @@ the clipboard by simultaneously clicking <kbd>Control</kbd> + <kbd>Command</kbd> Copy-and-pasting has some limitations: -- You can paste only one image at a time. When copy/pasting multiple files, only the first one will be uploaded. -- All images will be converted to `png` format under the hood, so when you want to copy/paste `gif` file, it will result in broken animation. -- If you are pasting a screenshot from the clipboard, it will be renamed to `design_<timestamp>.png` +- You can paste only one image at a time. When copy/pasting multiple files, only the first one is uploaded. +- All images are converted to `png` format under the hood, so when you want to copy/paste `gif` file, it results in broken animation. +- If you are pasting a screenshot from the clipboard, it is renamed to `design_<timestamp>.png` - Copy/pasting designs is not supported on Internet Explorer. -Designs with the same filename as an existing uploaded design will create a new version -of the design, and will replace the previous version. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9, dropping a design on an existing uploaded design will also create a new version, +Designs with the same filename as an existing uploaded design create a new version +of the design, and replaces the previous version. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9, dropping a design on an existing uploaded design also creates a new version, provided the filenames are the same. ### Skipped designs -Designs with the same filename as an existing uploaded design _and_ whose content has not changed will be skipped. -This means that no new version of the design will be created. When designs are skipped, you will be made aware via a warning +Designs with the same filename as an existing uploaded design _and_ whose content has not changed are skipped. +This means that no new version of the design is created. When designs are skipped, you are made aware via a warning message on the Issue. ## Viewing designs @@ -198,7 +198,7 @@ Different discussions have different pin numbers:  -From GitLab 12.5 on, new discussions will be outputted to the issue activity, +From GitLab 12.5 on, new discussions are outputted to the issue activity, so that everyone involved can participate in the discussion. ## Resolve Design threads @@ -214,13 +214,13 @@ There are two ways to resolve/unresolve a Design thread:  1. Design threads can also be resolved or unresolved in their threads by using a checkbox. - When replying to a comment, you will see a checkbox that you can click in order to resolve or unresolve + When replying to a comment, there is a checkbox that you can click in order to resolve or unresolve the thread once published:  -Note that your resolved comment pins will disappear from the Design to free up space for new discussions. -However, if you need to revisit or find a resolved discussion, all of your resolved threads will be +Note that your resolved comment pins disappear from the Design to free up space for new discussions. +However, if you need to revisit or find a resolved discussion, all of your resolved threads are available in the **Resolved Comment** area at the bottom of the right sidebar. ## Add to dos for designs @@ -247,7 +247,7 @@ somewhere with: See https://gitlab.com/your-group/your-project/-/issues/123/designs/homescreen.png ``` -This will be rendered as: +This is rendered as: > See [#123[homescreen.png]](https://gitlab.com/your-group/your-project/-/issues/123/designs/homescreen.png) diff --git a/doc/user/project/issues/img/create_issue_from_group_level_issue_tracker.png b/doc/user/project/issues/img/create_issue_from_group_level_issue_tracker.png Binary files differdeleted file mode 100644 index 8996490ae63..00000000000 --- a/doc/user/project/issues/img/create_issue_from_group_level_issue_tracker.png +++ /dev/null diff --git a/doc/user/project/issues/img/delete_issue.png b/doc/user/project/issues/img/delete_issue.png Binary files differdeleted file mode 100644 index 87ea65956fc..00000000000 --- a/doc/user/project/issues/img/delete_issue.png +++ /dev/null diff --git a/doc/user/project/issues/img/delete_issue_v13_11.png b/doc/user/project/issues/img/delete_issue_v13_11.png Binary files differnew file mode 100644 index 00000000000..d9905012eab --- /dev/null +++ b/doc/user/project/issues/img/delete_issue_v13_11.png diff --git a/doc/user/project/issues/img/issue_weight.png b/doc/user/project/issues/img/issue_weight.png Binary files differdeleted file mode 100644 index 3800b5940b8..00000000000 --- a/doc/user/project/issues/img/issue_weight.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..842c154ea49 --- /dev/null +++ b/doc/user/project/issues/img/issue_weight_v13_11.png diff --git a/doc/user/project/issues/img/merge_request_closes_issue.png b/doc/user/project/issues/img/merge_request_closes_issue.png Binary files differdeleted file mode 100644 index 6fd27738843..00000000000 --- a/doc/user/project/issues/img/merge_request_closes_issue.png +++ /dev/null diff --git a/doc/user/project/issues/img/merge_request_closes_issue_v13_11.png b/doc/user/project/issues/img/merge_request_closes_issue_v13_11.png Binary files differnew file mode 100644 index 00000000000..26b42239c12 --- /dev/null +++ b/doc/user/project/issues/img/merge_request_closes_issue_v13_11.png diff --git a/doc/user/project/issues/img/select_project_from_group_level_issue_tracker.png b/doc/user/project/issues/img/select_project_from_group_level_issue_tracker.png Binary files differdeleted file mode 100644 index 97d93620b2a..00000000000 --- a/doc/user/project/issues/img/select_project_from_group_level_issue_tracker.png +++ /dev/null diff --git a/doc/user/project/issues/img/select_project_from_group_level_issue_tracker_v13_11.png b/doc/user/project/issues/img/select_project_from_group_level_issue_tracker_v13_11.png Binary files differnew file mode 100644 index 00000000000..4612ae254d4 --- /dev/null +++ b/doc/user/project/issues/img/select_project_from_group_level_issue_tracker_v13_11.png diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 2963555869c..3af6c528db9 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -67,7 +67,7 @@ To access additional actions, select the vertical ellipsis - To create a new issue in the same project, select **New issue** in the dropdown menu. -- If you are not the issue author, you can [submit an abuse report](../../abuse_reports.md). +- If you are not the issue author, you can [submit an abuse report](../../report_abuse.md). Select **Report abuse** in the dropdown menu. ### To Do @@ -101,7 +101,7 @@ assigned to them if they created the issue themselves. Often, multiple people work on the same issue together. This can be difficult to track in large teams where there is shared ownership of an issue. -In [GitLab Starter](https://about.gitlab.com/pricing/), you can +To help with this, you can use GitLab to [assign multiple people](multiple_assignees_for_issues.md) to an issue. ### Epic **(PREMIUM)** diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index b10debf9888..8f17f399cb0 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -7,22 +7,22 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Issue weight **(PREMIUM)** -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. When you have a lot of issues, it can be hard to get an overview. -By adding a weight to each issue, you can get a better idea of how much time, -value or complexity a given issue has or costs. +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. (The database stores a 4-byte value, so the -upper bound is essentially limitless). +upper bound is essentially limitless.) You can remove weight from an issue as well. This value appears on the right sidebar of an individual issue, as well as -in the issues page next to a distinctive balance scale icon. +in the issues page next to a weight icon (**{weight}**). As an added bonus, you can see the total sum of all issues on the milestone page. - + diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index dafc0e6ba02..9e8a75743a7 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -62,28 +62,31 @@ When you're creating a new issue, these are the fields you can fill in: - Checkbox to make the issue confidential - Assignee - Weight -- Epic **(PREMIUM)** +- [Epic](../../group/epics/index.md) - Due date - Milestone - Labels -### New issue from the group-level Issue Tracker +### New issue from the group-level issue tracker -Go to the Group dashboard and click **Issues** in the sidebar to visit the Issue Tracker -for all projects in your Group. Select the project you'd like to add an issue for -using the dropdown button at the top-right of the page. +To visit the issue tracker for all projects in your group: - +1. Go to the group dashboard. +1. In the left sidebar, select **Issues**. +1. In the top-right, select the **Select project to create issue** button. +1. Select the project you'd like to create an issue for. The button now reflects the selected + project. +1. Select the button to create an issue in the selected project. + + The project you selected most recently becomes the default for your next visit. This should save you a lot of time and clicks, if you mostly create issues for the same project. - - ### New issue via Service Desk Enable [Service Desk](../service_desk.md) for your project and offer email support. -By doing so, when your customer sends a new email, a new issue can be created in +Now, when your customer sends a new email, a new issue can be created in the appropriate project and followed up from there. ### New issue via email @@ -119,21 +122,16 @@ older format is still supported, allowing existing aliases or contacts to contin To link directly to the new issue page with prefilled fields, use query string parameters in a URL. You can embed a URL in an external -HTML page, or create issues with certain +HTML page to create issues with certain fields prefilled. -The title, description, description template, and confidential fields can be prefilled -using this method. You cannot pre-fill both the description and description template -fields in the same URL because a description template also populates the description -field. - | Field | URL Parameter Name | Notes | |----------------------|-----------------------|-------------------------------------------------------| | title | `issue[title]` | | -| description | `issue[description]` | | -| description template | `issuable_template` | | -| issue type | `issue[issue_type]` | Either `incident` or `issue` | -| confidential | `issue[confidential]` | Parameter value must be `true` to set to confidential | +| description | `issue[description]` | Cannot be used at the same time as `issuable_template`. | +| description template | `issuable_template` | Cannot be used at the same time as `issue[description]`. | +| issue type | `issue[issue_type]` | Either `incident` or `issue`. | +| confidential | `issue[confidential]` | Parameter value must be `true` to set to confidential. | Follow these examples to form your new issue URL with prefilled fields. @@ -144,6 +142,58 @@ Follow these examples to form your new issue URL with prefilled fields. - For a new issue in the GitLab Community Edition project with a pre-filled title, a pre-filled description, and the confidential flag set, the URL would be `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea&issue[confidential]=true` +## Bulk edit issues at the project level + +> - Assigning epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. +> - Editing health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in GitLab 13.2. +> - Editing iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196806) in GitLab 13.9. + +Users with permission level of [Reporter or higher](../../permissions.md) can manage issues. + +When bulk editing issues in a project, you can edit the following attributes: + +- Status (open/closed) +- Assignee +- [Epic](../../group/epics/index.md) +- [Milestone](../milestones/index.md) +- [Labels](../labels.md) +- [Health status](#health-status) +- Notification subscription +- [Iteration](../../group/iterations/index.md) + +To update multiple project issues at the same time: + +1. In a project, go to **Issues > List**. +1. Click **Edit issues**. A sidebar on the right-hand side of your screen appears with editable fields. +1. Select the checkboxes next to each issue you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. + +## Bulk edit issues at the group level + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7249) in GitLab 12.1. +> - Assigning epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. +> - Editing health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in GitLab 13.2. +> - Editing iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196806) in GitLab 13.9. + +Users with permission level of [Reporter or higher](../../permissions.md) can manage issues. + +When bulk editing issues in a group, you can edit the following attributes: + +- [Epic](../../group/epics/index.md) +- [Milestone](../milestones/index.md) +- [Labels](../labels.md) +- [Health status](#health-status) +- [Iteration](../../group/iterations/index.md) + +To update multiple project issues at the same time: + +1. In a group, go to **Issues > List**. +1. Click **Edit issues**. A sidebar on the right-hand side of your screen appears with editable fields. +1. Select the checkboxes next to each issue you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. + ## Moving issues Moving an issue copies it to the target project, and closes it in the originating project. @@ -207,7 +257,7 @@ description, issues `#4` and `#6` are closed automatically when the MR is merged Using `Related to` flags `#5` as a [related issue](related_issues.md), but is not closed automatically. - + If the issue is in a different repository than the MR, add the full URL for the issue(s): @@ -278,12 +328,10 @@ of your installation. ## Deleting issues -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2982) in GitLab 8.6. - Users with [project owner permission](../../permissions.md) can delete an issue by -editing it and clicking on the delete button. +editing it and selecting **Delete issue**. - + ## Promote an issue to an epic **(PREMIUM)** @@ -321,7 +369,7 @@ in a comment or description field. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 13.3. Assignees in the sidebar are updated in real time. This feature is **disabled by default**. -To enable it, you need to enable [ActionCable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html). +To enable it, you need to enable [Action Cable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html). ## Similar issues @@ -354,5 +402,4 @@ This marks issues as progressing as planned or needs attention to keep on schedu After an issue is closed, its health status can't be edited and the **Edit** button becomes disabled until the issue is reopened. -You can then see issue statuses in the issues list and the -[epic tree](../../group/epics/index.md#issue-health-status-in-epic-tree). +You can then see issue statuses in the issues list and the epic tree. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index fd5045f2e93..0cb5b5d993e 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Labels +# Labels **(FREE)** As your count of issues, merge requests, and epics grows in GitLab, it's more and more challenging to keep track of those items. Especially as your organization grows from just a few people to diff --git a/doc/user/project/members/img/add_user_give_permissions_v13_8.png b/doc/user/project/members/img/add_user_give_permissions_v13_8.png Binary files differdeleted file mode 100644 index 1916d056a52..00000000000 --- a/doc/user/project/members/img/add_user_give_permissions_v13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_import_members_from_another_project_v13_8.png b/doc/user/project/members/img/add_user_import_members_from_another_project_v13_8.png Binary files differdeleted file mode 100644 index a6dddec3fb7..00000000000 --- a/doc/user/project/members/img/add_user_import_members_from_another_project_v13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_imported_members_v13_9.png b/doc/user/project/members/img/add_user_imported_members_v13_9.png Binary files differdeleted file mode 100644 index e40240df2b2..00000000000 --- a/doc/user/project/members/img/add_user_imported_members_v13_9.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_list_members_v13_9.png b/doc/user/project/members/img/add_user_list_members_v13_9.png Binary files differdeleted file mode 100644 index 7a07ea01d14..00000000000 --- a/doc/user/project/members/img/add_user_list_members_v13_9.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_search_people_v13_8.png b/doc/user/project/members/img/add_user_search_people_v13_8.png Binary files differdeleted file mode 100644 index e9aa58512ab..00000000000 --- a/doc/user/project/members/img/add_user_search_people_v13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/other_group_sees_shared_project_v13_8.png b/doc/user/project/members/img/other_group_sees_shared_project_v13_8.png Binary files differdeleted file mode 100644 index aa2aaf071e1..00000000000 --- a/doc/user/project/members/img/other_group_sees_shared_project_v13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/project_groups_tab_v13_9.png b/doc/user/project/members/img/project_groups_tab_v13_9.png Binary files differdeleted file mode 100644 index d1b6a640341..00000000000 --- a/doc/user/project/members/img/project_groups_tab_v13_9.png +++ /dev/null diff --git a/doc/user/project/members/img/share_project_with_groups_tab_v13_9.png b/doc/user/project/members/img/share_project_with_groups_tab_v13_9.png Binary files differdeleted file mode 100644 index 99be996c03e..00000000000 --- a/doc/user/project/members/img/share_project_with_groups_tab_v13_9.png +++ /dev/null diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 2993849e0e6..7dc1a9c612f 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -6,19 +6,75 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Members of a project -You can manage the groups and users and their access levels in all of your -projects. You can also personalize the access level you give each user, -per-project. +Members are the users and groups who have access to your project. -You should have Maintainer or Owner [permissions](../../permissions.md) to add -or import a new user to your project. +Each member gets a role, which determines what they can do in the project. -To view, edit, add, and remove project's members, go to your -project's **Members**. +## Add users to a project + +Add users to a project so they become members and have permission +to perform actions. + +Prerequisite: + +- You must have maintainer or owner [permissions](../../permissions.md). + +To add a user to a project: + +1. Go to your project and select **Members**. +1. On the **Invite member** tab, under **GitLab member of Email address**, type the username or email address. +1. Select a [role](../../permissions.md). +1. Optional. Choose an expiration date. On that date, the user can no longer access the project. +1. Select **Invite**. + +If the user has a GitLab account, they are added to the members list. +If you used an email address, the user receives an email. + +## Add groups to a project + +When you assign a group to a project, each user in the group gets access to the project, +based on the role they're assigned in the group. However, the user's access is also +limited by the maximum role you choose when you invite the group. + +Prerequisite: + +- You must have maintainer or owner [permissions](../../permissions.md). + +To add groups to a project: + +1. Go to your project and select **Members**. +1. On the **Invite group** tab, under **Select a group to invite**, choose a group. +1. Select the highest max [role](../../permissions.md) for users in the group. +1. Optional. Choose an expiration date. On that date, the user can no longer access the project. +1. Select **Invite**. + +The members of the group are not displayed on the **Members** tab. +The **Members** tab shows: + +- Members who are directly assigned to the project. +- If the project was created in a group [namespace](../../group/index.md#namespaces), members of that group. + +## Import users from another project + +You can import another project's users to your own project. Users +retain the same permissions as the project you import them from. + +Prerequisite: + +- You must have maintainer or owner [permissions](../../permissions.md). + +To import users: + +1. Go to your project and select **Members**. +1. On the **Invite member** tab, at the bottom of the panel, select **Import**. +1. Select the project. You can view only the projects for which you're a maintainer. +1. Select **Import project members**. + +A success message is displayed and the new members are now displayed in the list. ## Inherited membership -When your project belongs to the group, group members inherit the membership and permission +When your project belongs to a group, group members inherit the membership and permission level for the project from the group.  @@ -70,43 +126,6 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last  -## Add a user - -Right next to **People**, start typing the name or username of the user you -want to add. - - - -Select the user and the [permission level](../../permissions.md) -that you'd like to give the user. You can add more than one user at a time. -The Owner role can only be assigned at the group level. - - - -Once done, select **Add users to project** and they are immediately added to -your project with the permissions you gave them above. - - - -From there on, you can either remove an existing user or change their access -level to the project. - -## Import users from another project - -You can import another project's users in your own project by hitting the -**Import members** button on the upper right corner of the **Members** menu. - -In the dropdown menu, you can see only the projects you are Maintainer on. - - - -Select the one you want and hit **Import project members**. A flash message -displays, notifying you that the import was successful, and the new members -are now in the project's members list. Notice that the permissions that they -had on the project you imported from are retained. - - - ## Invite people using their e-mail address NOTE: @@ -235,8 +254,7 @@ requests they are currently assigned or leave the assignments as they are. To remove a member from a project: -1. In a project, go to **{users}** **Members**. -1. Click the **Delete** **{remove}** button next to a project member you want to remove. - A **Remove member** modal appears. -1. (Optional) Select the **Also unassign this user from related issues and merge requests** checkbox. -1. Click **Remove member**. +1. Go to your project and select **Members**. +1. Next to the project member you want to remove, select **Remove member** **{remove}**. +1. Optional. In the confirmation box, select the **Also unassign this user from related issues and merge requests** checkbox. +1. Select **Remove member**. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 8338c17f4ba..085e4db0b94 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -4,7 +4,7 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Share Projects with other Groups +# Share projects with other groups You can share projects with other [groups](../../group/index.md). This makes it possible to add a group of users to a project with a single action. @@ -28,22 +28,14 @@ This is where the group sharing feature can be of use. To share 'Project Acme' with the 'Engineering' group: 1. For 'Project Acme' use the left navigation menu to go to **Members**. - -  - 1. Select the **Invite group** tab. 1. Add the 'Engineering' group with the maximum access level of your choice. 1. Optionally, select an expiring date. 1. Click **Invite**. 1. After sharing 'Project Acme' with 'Engineering': - The group is listed in the **Groups** tab. - -  - - The project is listed on the group dashboard. -  - Note that you can only share a project with: - groups for which you have an explicitly defined membership diff --git a/doc/user/project/merge_requests/img/approvals_premium_mr_widget_v13_3.png b/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_v13_3.png Binary files differindex 306bf57354d..306bf57354d 100644 --- a/doc/user/project/merge_requests/img/approvals_premium_mr_widget_v13_3.png +++ b/doc/user/project/merge_requests/approvals/img/approvals_premium_mr_widget_v13_3.png diff --git a/doc/user/project/merge_requests/img/mr_approvals_by_code_owners_v12_7.png b/doc/user/project/merge_requests/approvals/img/mr_approvals_by_code_owners_v12_7.png Binary files differindex 669148a41d8..669148a41d8 100644 --- a/doc/user/project/merge_requests/img/mr_approvals_by_code_owners_v12_7.png +++ b/doc/user/project/merge_requests/approvals/img/mr_approvals_by_code_owners_v12_7.png diff --git a/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png b/doc/user/project/merge_requests/approvals/img/scoped_to_protected_branch_v13_10.png Binary files differindex a6636f0bc7f..a6636f0bc7f 100644 --- a/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png +++ b/doc/user/project/merge_requests/approvals/img/scoped_to_protected_branch_v13_10.png diff --git a/doc/user/project/merge_requests/img/update_approval_rule_v13_10.png b/doc/user/project/merge_requests/approvals/img/update_approval_rule_v13_10.png Binary files differindex c5596b965ff..c5596b965ff 100644 --- a/doc/user/project/merge_requests/img/update_approval_rule_v13_10.png +++ b/doc/user/project/merge_requests/approvals/img/update_approval_rule_v13_10.png diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md new file mode 100644 index 00000000000..ac48e44da52 --- /dev/null +++ b/doc/user/project/merge_requests/approvals/index.md @@ -0,0 +1,145 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: reference, concepts +disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html' +--- + +# Merge request approvals **(FREE)** + +> Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0. + +You can configure your merge requests so that they must be approved before +they can be merged. You can do this by creating [rules](rules.md) or by specifying +a list of users who act as [code owners](../../code_owners.md) for specific files. + +You can configure merge request approvals for each project. In higher GitLab tiers, +Administrators of self-managed GitLab instances can configure approvals +[for the entire instance](../../../admin_area/merge_requests_approvals.md). + +## How approvals work + +With [merge request approval rules](rules.md), you can set the minimum number of +required approvals before work can merge into your project. You can also extend these +rules to define what types of users can approve work. Some examples of rules you can create include: + +- Users with specific permissions can always approve work. +- [Code owners](../../code_owners.md) can approve work for files they own. +- Users with specific permissions can approve work, + [even if they don't have merge rights](rules.md#merge-request-approval-segregation-of-duties) + to the repository. +- Users with specific permissions can be allowed or denied the ability + to [override approval rules on a specific merge request](rules.md#edit-or-override-merge-request-approval-rules). + +You can also configure additional [settings for merge request approvals](settings.md) +for more control of the level of oversight and security your project needs, including: + +- [Prevent users from overriding a merge request approval rule.](settings.md#prevent-overrides-of-default-approvals) +- [Reset approvals when new code is pushed.](settings.md#reset-approvals-on-push) +- Allow (or disallow) [authors and committers](settings.md) to approve their own merge requests. +- [Require password authentication when approving.](settings.md#require-authentication-for-approvals) +- [Require security team approval.](settings.md#security-approvals-in-merge-requests) + +You can configure your merge request approval rules and settings through the GitLab +user interface or [with the API](../../../../api/merge_request_approvals.md). + +## Approve a merge request + +When an [eligible approver](rules.md#eligible-approvers) visits an open merge request, +GitLab displays one of these buttons after the body of the merge request: + +- **Approve**: The merge request doesn't yet have the required number of approvals. +- **Approve additionally**: The merge request has the required number of approvals. +- **Revoke approval**: The user viewing the merge request has already approved + the merge request. + +Eligible approvers can also use the `/approve` +[quick action](../../../project/quick_actions.md) when adding a comment to +a merge request. + +After a merge request receives the [number and type of approvals](rules.md) you configure, it can merge +unless it's blocked for another reason. Merge requests can be blocked by other problems, +such as merge conflicts, [pending discussions](../../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved), +or a [failed CI/CD pipeline](../merge_when_pipeline_succeeds.md). + +To prevent merge request authors from approving their own merge requests, +enable [**Prevent author approval**](settings.md#prevent-authors-from-approving-their-own-work) +in your project's settings. + +If you enable [approval rule overrides](settings.md#prevent-overrides-of-default-approvals), +merge requests created before a change to default approval rules are not affected. +The only exceptions are changes to the [target branch](rules.md#approvals-for-protected-branches) +of the rule. + +## Optional approvals + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27426) in GitLab 13.2. + +GitLab allows all users with Developer or greater [permissions](../../../permissions.md) +to approve merge requests. Approvals in GitLab Free are optional, and don't prevent +a merge request from merging without approval. + +## Required approvals **(PREMIUM)** + +> Moved to [GitLab Premium](https://about.gitlab.com/pricing/) in 13.9. + +Required approvals enforce code reviews by the number and type of users you specify. +Without the approvals, the work cannot merge. Required approvals enable multiple use cases: + +- Enforce review of all code that gets merged into a repository. +- Specify reviewers for a given proposed code change, and a minimum number + of reviewers, through [Approval rules](rules.md). +- Specify categories of reviewers, such as backend, frontend, quality assurance, or + database, for all proposed code changes. +- Use the [code owners of changed files](rules.md#code-owners-as-eligible-approvers), + to determine who should review the work. +- [Require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests) + before merging code that could introduce a vulnerability. **(ULTIMATE)** + +## Notify external services **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab Ultimate 13.10. +> - [Deployed behind a feature flag](../../../feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../../../api/merge_request_approvals.md#enable-or-disable-external-project-level-mr-approvals). **(ULTIMATE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +You can create an external approval rule to integrate approvals with third-party tools. +When users create, change, or close merge requests, GitLab sends a notification. +The users of the third-party tools can then approve merge requests from outside of GitLab. + +With this integration, you can integrate with third-party workflow tools, like +[ServiceNow](https://www.servicenow.co.uk/), or the custom tool of your choice. +You can modify your external approval rules +[by using the REST API](../../../../api/merge_request_approvals.md#external-project-level-mr-approvals). + +The lack of an external approval doesn't block the merging of a merge request. + +When [approval rule overrides](settings.md#prevent-overrides-of-default-approvals) are allowed, +changes to default approval rules will **not** be applied to existing +merge requests, except for changes to the [target branch](rules.md#approvals-for-protected-branches) +of the rule. + +To learn more about use cases, feature discovery, and development timelines, +see the [External API approval rules epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). + +## Related links + +- [Merge request approvals API](../../../../api/merge_request_approvals.md) +- [Instance-level approval rules](../../../admin_area/merge_requests_approvals.md) for self-managed installations + +<!-- ## 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. --> diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md new file mode 100644 index 00000000000..32f0160771f --- /dev/null +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -0,0 +1,232 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: reference, concepts +--- + +# Merge request approval rules + +Approval rules define how many [approvals](index.md) a merge request must receive before it can +be merged, and which users should do the approving. You can define approval rules: + +- [As project defaults](#add-an-approval-rule). +- [Per merge request](#edit-or-override-merge-request-approval-rules). +- [At the instance level](../../../admin_area/merge_requests_approvals.md) + +If you don't define a [default approval rule](#add-an-approval-rule), +any user can approve a merge request. Even if you don't define a rule, you can still +enforce a [minimum number of required approvers](settings.md) in the project's settings. + +You can define a single rule to approve merge requests from among the available +rules, or you can select [multiple approval rules](#add-multiple-approval-rules). + +Merge requests that target a different project, such as from a fork to the upstream project, +use the default approval rules from the target (upstream) project, not the source (fork). + +## Add an approval rule + +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. 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` + creates a required rule. +1. To add users or groups as approvers, search for users or groups that are + [eligible to approve](#eligible-approvers), and select **Add**. GitLab suggests approvers based on + previous authors of the files changed by the merge request. + + NOTE: + On GitLab.com, you can add a group as an approver if you're a member of that group or the + group is public. + +1. Select **Add approval rule**. + +Users of GitLab Premium and higher tiers can create [additional approval rules](#add-multiple-approval-rules). + +Your configuration for approval rule overrides determines if the new rule is applied +to existing merge requests: + +- If [approval rule overrides](settings.md#prevent-overrides-of-default-approvals) are allowed, + changes to these default rules are not applied to existing merge requests, except for + changes to the [target branch](#approvals-for-protected-branches) of the rule. +- If approval rule overrides are not allowed, all changes to default rules + are applied to existing merge requests. Any approval rules that were previously + manually [overridden](#edit-or-override-merge-request-approval-rules) during the + period when approval rule overrides where allowed, are not modified. + +## Edit an approval rule + +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. (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: + - *To add users or groups as approvers,* search for users or groups that are + [eligible to approve](#eligible-approvers), and select **Add**. + + NOTE: + On GitLab.com, you can add a group as an approver if you're a member of that group or the + group is public. + + - *To remove users or groups,* identify the group or user to remove, and + select **{remove}** **Remove**. +1. Select **Update approval rule**. + +## Add multiple approval rules **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in GitLab Premium 11.10. + +In GitLab Premium and higher tiers, you can enforce multiple approval rules on a +merge request, and multiple default approval rules for a project. If your tier +supports multiple default rules: + +- When [adding](#add-an-approval-rule) or [editing](#edit-an-approval-rule) an approval rule + for a project, GitLab displays the **Add approval rule** button even after a rule is defined. +- When editing or overriding multiple approval rules + [on a merge request](#edit-or-override-merge-request-approval-rules), GitLab + displays the **Add approval rule** button even after a rule is defined. + +When an [eligible approver](#eligible-approvers) approves a merge request, it +reduces the number of approvals left (the **Approvals** column) for all rules that the approver belongs to: + + + +## Eligible approvers + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in GitLab 13.3, when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget. + +To be eligible as an approver for a project, a user must be a member of one or +more of these: + +- The project. +- The project's immediate parent [group](#group-approvers). +- A group that has access to the project via a [share](../../members/share_project_with_groups.md). +- A [group added as approvers](#group-approvers). + +The following users can approve merge requests if they have Developer or +higher [permissions](../../../permissions.md): + +- Users added as approvers at the project or merge request level. +- Users who are [Code owners](#code-owners-as-eligible-approvers) of the files + changed in the merge request. + +To show who has participated in the merge request review, the Approvals widget in +a merge request displays a **Commented by** column. This column lists eligible approvers +who commented on the merge request. It helps authors and reviewers identify who to +contact with questions about the merge request's content. + +If the number of required approvals is greater than the number of assigned approvers, +approvals from other users with Developer [permissions](../../../permissions.md) or higher +in the project counts toward meeting the required number of approvals, even if the +users were not explicitly listed in the approval rules. + +### Group approvers + +You can add a group of users as approvers, but those users count as approvers only if +they have direct membership to the group. In the future, group approvers may be +restricted to only groups [with share access to the project](https://gitlab.com/gitlab-org/gitlab/-/issues/2048). + +A user's membership in an approvers group affects their individual ability to +approve in these ways: + +- A user already part of a group approver who is later added as an individual approver + counts as one approver, and not two. +- Merge request authors do not count as eligible approvers on their own merge requests by default. + To change this behavior, disable the + [**Prevent author approval**](settings.md#prevent-authors-from-approving-their-own-work) + project setting. +- Committers to merge requests can approve a merge request. To change this behavior, enable the + [**Prevent committers approval**](settings.md#prevent-committers-from-approving-their-own-work) + project setting. + +### Code owners as eligible approvers + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in GitLab 11.5. +> - Moved to GitLab Premium in 13.9. + +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 **Any eligible user** and select the number of approvals required: + +  + +You can also +[require code owner approval](../../protected_branches.md#protected-branches-approval-by-code-owners) +for protected branches. **(PREMIUM)** + +## Merge request approval segregation of duties + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. +> - Moved to GitLab Premium in 13.9. + +You may need to grant users with [Reporter permissions](../../../permissions.md#project-members-permissions), +permission to approve merge requests before they can merge to a protected branch. +Some users (like managers) may not need permission to push or merge code, but still need +oversight on proposed work. To enable approval permissions for these users without +granting them push access: + +1. [Create a new group](../../../group/index.md#create-a-group). +1. [Add the user to the group](../../../group/index.md#add-users-to-a-group), + and select the Reporter role for the user. +1. [Share the project with your group](../../members/share_project_with_groups.md#sharing-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**. +1. [Add the group](../../../group/index.md#create-a-group) to the permission list. + +  + +### Edit or override merge request approval rules + +By default, the merge request author (or a user with sufficient [permissions](../../../permissions.md)) +can edit the approval rule listed in a merge request. When editing an approval rule +on a merge request, you can either add or remove approvers: + +1. In the merge request, find the **Approval rules section**. +1. When creating a new merge request, scroll to the **Approval Rules** section, + and add or remove your desired approval rules before selecting **Create merge request**. +1. When viewing an existing merge request: + 1. Select **Edit**. + 1. Scroll to the **Approval Rules** section. + 1. Add or remove your desired approval rules. + 1. Select **Save changes**. + +Administrators can change the [merge request approvals settings](settings.md#prevent-overrides-of-default-approvals) +to prevent users from overriding approval rules for merge requests. + +## Configure optional approval rules + +Merge request approvals can be optional for projects where approvals are +appreciated, but not required. To make an approval rule optional: + +- When you [create or edit a rule](#edit-an-approval-rule), set **Approvals required** to `0`. +- Use the [Merge requests approvals API](../../../../api/merge_request_approvals.md#update-merge-request-level-rule) + to set the `approvals_required` attribute to `0`. + +## Approvals for protected branches **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in GitLab Premium 12.8. + +Approval rules are often relevant only to specific branches, like your +[default branch](../../repository/branches/default.md). To configure an +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. Select a **Target branch**: + - To protect all branches, select **Any branch**. + - To select a specific branch, select it from the list: + +  +1. To enable this configuration, read + [Code Owner's approvals for protected branches](../../protected_branches.md#protected-branches-approval-by-code-owners). diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md new file mode 100644 index 00000000000..8769f6a7470 --- /dev/null +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -0,0 +1,125 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: reference, concepts +--- + +# Merge request approval settings + +You can configure the settings for [merge request approvals](index.md) to +ensure the approval rules meet your use case. You can also configure +[approval rules](rules.md), which define the number and type of users who must +approve work before it's merged. Merge request approval settings define how +those rules are applied as a merge request moves toward completion. + +## Edit merge request approval settings + +To view or edit merge request approval settings: + +1. Go to your project and select **Settings > General**. +1. Expand **Merge request (MR) approvals**. + +In this section of general settings, you can configure the settings described +on this page. + +## Prevent overrides of default approvals + +By default, users can override the approval rules you [create for a project](rules.md) +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 users from modifying MR approval rules in merge requests** checkbox. +1. Select **Save changes**. + +TODO This change affects all open merge requests. + +## Reset approvals on push + +By default, an approval on a merge request remains in place, even if you add more changes +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 **Require new approvals when new commits are added to an MR** checkbox. +1. Select **Save changes**. + +Approvals aren't reset when a merge request is [rebased from the UI](../fast_forward_merge.md) +However, approvals are reset if the target branch is changed. + +## Prevent authors from approving their own work **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in GitLab 11.3. +> - Moved to GitLab Premium in 13.9. + +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 MR approval by the author** checkbox. +1. Select **Save changes**. + +Authors can edit the approval rule in an individual merge request and override +this setting, unless you configure one of these options: + +- [Prevent overrides of default approvals](#prevent-overrides-of-default-approvals) at + the project level. +- *(Self-managed instances only)* Prevent overrides of default approvals + [at the instance level](../../../admin_area/merge_requests_approvals.md). When configured + at the instance level, you can't edit this setting at the project or individual + merge request levels. + +## Prevent committers from approving their own work **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in GitLab 11.10. +> - Moved to GitLab Premium in 13.9. + +By default, users who commit to a merge request can still approve it. At both +the project level or [instance level](../../../admin_area/merge_requests_approvals.md) +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 MR approvals from users who make commits to the MR** checkbox. + 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. +1. Select **Save changes**. + +Even with this configuration, [code owners](../../code_owners.md) who contribute +to a merge request can approve merge requests that affect files they own. + +To learn more about the [differences between authors and committers](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History), +read the official Git documentation for an explanation. + +## Require authentication for approvals + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 12.0. +> - Moved to GitLab Premium in 13.9. + +You can force potential approvers to first authenticate with a password. This +permission enables an electronic signature for approvals, such as the one defined by +[Code of Federal Regulations (CFR) Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)): + +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 for approvals** checkbox. +1. Select **Save changes**. + +## Security approvals in merge requests **(ULTIMATE)** + +You can require that a member of your security team approves a merge request if a +merge request could introduce a vulnerability. To learn more, see +[Security approvals in merge requests](../../../application_security/index.md#security-approvals-in-merge-requests). + +## Related links + +- [Instance-level merge request approval settings](../../../admin_area/merge_requests_approvals.md) +- [Compliance Dashboard](../../../compliance/compliance_dashboard/index.md) +- [Merge request approvals API](../../../../api/merge_request_approvals.md) diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 76913351283..b33919c7fbe 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -64,7 +64,7 @@ using Docker-in-Docker. 1. First, set up GitLab Runner with a [Docker-in-Docker build](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). -1. Configure the default Browser Performance Testing CI job as follows in your `.gitlab-ci.yml` file: +1. Configure the default Browser Performance Testing CI/CD job as follows in your `.gitlab-ci.yml` file: ```yaml include: @@ -75,17 +75,19 @@ using Docker-in-Docker. URL: https://example.com ``` -NOTE: -For versions before 12.4, see the information for [older GitLab versions](#gitlab-versions-123-and-older). -If you are using a Kubernetes cluster, use [`template: Jobs/Browser-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Browser-Performance-Testing.gitlab-ci.yml) -instead. +WARNING: +In GitLab 14.0 and later, the job [is scheduled to be renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/225914) +from `performance` to `browser_performance`. -The above example creates a `performance` job in your CI/CD pipeline and runs -sitespeed.io against the webpage you defined in `URL` to gather key metrics. +The above example: -The example uses a CI/CD template that is included in all GitLab installations since -12.4, but it doesn't work with Kubernetes clusters. If you are using GitLab 12.3 -or older, you must [add the configuration manually](#gitlab-versions-123-and-older) +- Creates a `performance` job in your CI/CD pipeline and runs sitespeed.io against the webpage you + defined in `URL` to gather key metrics. +- Uses a template that doesn't work with Kubernetes clusters. If you are using a Kubernetes cluster, + use [`template: Jobs/Browser-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Browser-Performance-Testing.gitlab-ci.yml) + instead. +- Uses a CI/CD template that is included in all GitLab installations since 12.4. If you are using + GitLab 12.3 or earlier, you must [add the configuration manually](#gitlab-versions-132-and-earlier). The template uses the [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance), and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance) @@ -181,63 +183,62 @@ performance: URL: environment_url.txt ``` -### GitLab versions 12.3 and older +### GitLab versions 13.2 and earlier -Browser Performance Testing has gone through several changes since it's introduction. +Browser Performance Testing has gone through several changes since its introduction. In this section we detail these changes and how you can run the test based on your GitLab version: +- In 13.2 the feature was renamed from `Performance` to `Browser Performance` with additional + template CI/CD variables. - In GitLab 12.4 [a job template was made available](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml). -- In 13.2 the feature was renamed from `Performance` to `Browser Performance` with -additional template CI/CD variables. The job name in the template is still `performance` -for compatibility reasons, but may be renamed to match in a future iteration. - For 11.5 to 12.3 no template is available and the job has to be defined manually as follows: -```yaml -performance: - stage: performance - image: docker:git - variables: - URL: https://example.com - SITESPEED_VERSION: 14.1.0 - SITESPEED_OPTIONS: '' - services: - - docker:stable-dind - script: - - mkdir gitlab-exporter - - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/1.1.0/index.js - - mkdir sitespeed-results - - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:$SITESPEED_VERSION --plugins.add ./gitlab-exporter --outputFolder sitespeed-results $URL $SITESPEED_OPTIONS - - mv sitespeed-results/data/performance.json performance.json - artifacts: - paths: - - performance.json - - sitespeed-results/ - reports: - performance: performance.json -``` + ```yaml + performance: + stage: performance + image: docker:git + variables: + URL: https://example.com + SITESPEED_VERSION: 14.1.0 + SITESPEED_OPTIONS: '' + services: + - docker:stable-dind + script: + - mkdir gitlab-exporter + - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/1.1.0/index.js + - mkdir sitespeed-results + - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:$SITESPEED_VERSION --plugins.add ./gitlab-exporter --outputFolder sitespeed-results $URL $SITESPEED_OPTIONS + - mv sitespeed-results/data/performance.json performance.json + artifacts: + paths: + - performance.json + - sitespeed-results/ + reports: + performance: performance.json + ``` - For 11.4 and earlier the job should be defined as follows: -```yaml -performance: - stage: performance - image: docker:git - variables: - URL: https://example.com - services: - - docker:stable-dind - script: - - mkdir gitlab-exporter - - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/1.1.0/index.js - - mkdir sitespeed-results - - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:6.3.1 --plugins.add ./gitlab-exporter --outputFolder sitespeed-results $URL - - mv sitespeed-results/data/performance.json performance.json - artifacts: - paths: - - performance.json - - sitespeed-results/ -``` + ```yaml + performance: + stage: performance + image: docker:git + variables: + URL: https://example.com + services: + - docker:stable-dind + script: + - mkdir gitlab-exporter + - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/1.1.0/index.js + - mkdir sitespeed-results + - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:6.3.1 --plugins.add ./gitlab-exporter --outputFolder sitespeed-results $URL + - mv sitespeed-results/data/performance.json performance.json + artifacts: + paths: + - performance.json + - sitespeed-results/ + ``` Upgrading to the latest version and using the templates is recommended, to ensure you receive the latest updates, including updates to the sitespeed.io versions. diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md new file mode 100644 index 00000000000..adcf4518209 --- /dev/null +++ b/doc/user/project/merge_requests/changes.md @@ -0,0 +1,151 @@ +--- +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: index, reference +--- + +# Changes tab in merge requests + +The **Changes** tab on a [merge request](index.md), below the main merge request details and next to the discussion tab, +shows the changes to files between branches or commits. This view of changes to a +file is also known as a **diff**. By default, the diff view compares the file in the +merge request branch and the file in the target branch. + +The diff view includes the following: + +- The file's name and path. +- The number of lines added and deleted. +- Buttons for the following options: + - Toggle comments for this file; useful for inline reviews. + - Edit the file in the merge request's branch. + - Show full file, in case you want to look at the changes in context with the rest of the file. + - View file at the current commit. + - Preview the changes with [Review Apps](../../../ci/review_apps/index.md). +- The changed lines, with the specific changes highlighted. + + + +## Merge request diff file navigation + +When reviewing changes in the **Changes** tab, the diff can be navigated using +the file tree or file list. As you scroll through large diffs with many +changes, you can quickly jump to any changed file using the file tree or file +list. + + + +## Collapsed files in the Changes view + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232820) in GitLab 13.4. + +When you review changes in the **Changes** tab, files with a large number of changes are collapsed +to improve performance. When files are collapsed, a warning appears at the top of the changes. +Select **Expand file** on any file to view the changes for that file. + +## File-by-file diff navigation + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229848) in GitLab 13.7. + +For larger merge requests, consider reviewing one file at a time. To enable this feature: + +1. In the top-right corner, select your avatar. +1. Select **Preferences**. +1. Scroll to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**. +1. Select **Save changes**. + +After you enable this setting, GitLab displays only one file at a time in the **Changes** tab when you review merge requests. You can select **Prev** and **Next** to view other changed files. + + + +In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) and later, if you want to change +this behavior, you can do so from your **User preferences** (as explained above) or directly in a +merge request: + +1. Go to the merge request's **Changes** tab. +1. Select the cog icon (**{settings}**) to reveal the merge request's settings dropdown. +1. Select or clear the checkbox **Show one file at a time** to change the setting accordingly. + +This change overrides the choice you made in your user preferences and persists until you clear your +browser's cookies or change this behavior again. + +## Merge requests commit navigation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. + +To seamlessly navigate among commits in a merge request: + +1. Select the **Commits** tab. +1. Select a commit to open it in the single-commit view. +1. Navigate through the commits by either: + + - Selecting **Prev** and **Next** buttons below the tab buttons. + - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. + + + +## Incrementally expand merge request diffs + +By default, the diff shows only the parts of a file which are changed. +To view more unchanged lines above or below a change select the +**Expand up** or **Expand down** icons. You can also select **Show unchanged lines** +to expand the entire file. + + + +In GitLab [versions 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/205401), when viewing a +merge request's **Changes** tab, if a certain file was only renamed, you can expand it to see the +entire content by selecting **Show file contents**. + +## Ignore whitespace changes in Merge Request diff view + +If you select the **Hide whitespace changes** button, you can see the diff +without whitespace changes (if there are any). This is also working when on a +specific commit page. + + + +NOTE: +You can append `?w=1` while on the diffs page of a merge request to ignore any +whitespace changes. + +## Mark files as viewed + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9. +> - Deployed behind a feature flag, enabled by default. +> - Enabled on GitLab.com. +> - Recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-file-views). **(FREE SELF)** + +When reviewing a merge request with many files multiple times, it may be useful to the reviewer +to focus on new changes and ignore the files that they have already reviewed and don't want to +see anymore unless they are changed again. + +To mark a file as viewed: + +1. Go to the merge request's **Diffs** tab. +1. On the right-top of the file, locate the **Viewed** checkbox. +1. Select it to mark the file as viewed. + +Once checked, the file remains marked for that reviewer unless there are newly introduced +changes to its content or the checkbox is unchecked. + +### Enable or disable file views **(FREE SELF)** + +The file view feature is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to enable it for your instance. + +To enable it: + +```ruby +Feature.enable(:local_file_reviews) +``` + +To disable it: + +```ruby +Feature.disable(:local_file_reviews) +``` diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index f531cd52af1..eaeef12444e 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -16,7 +16,7 @@ with a **Cherry-pick** button in merge requests and commit details. After the merge request has been merged, a **Cherry-pick** button displays to cherry-pick the changes introduced by that merge request. - + After you click that button, a modal displays a [branch filter search box](../repository/branches/index.md#branch-filter-search-box) @@ -32,7 +32,7 @@ where you can choose to either: 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. - + Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) includes cherry-picked merge commits. diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 0fe1b9801cc..284d66dd591 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -53,20 +53,21 @@ See also the Code Climate list of [Supported Languages for Maintainability](http > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.11. > - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 13.12. Changes to files in merge requests can cause Code Quality to fall if merged. In these cases, an indicator is displayed (**{information-o}** **Code Quality**) on the file in the merge request's diff view. For example:  -To enable this feature, a GitLab administrator can run the following in a +To disable this feature, a GitLab administrator can run the following in a [Rails console](../../../administration/operations/rails_console.md): ```ruby # For the instance -Feature.enable(:codequality_mr_diff) +Feature.disable(:codequality_mr_diff) # For a single project -Feature.enable(:codequality_mr_diff, Project.find(<project id>)) +Feature.disable(:codequality_mr_diff, Project.find(<project id>)) ``` ## Use cases @@ -519,7 +520,7 @@ to change the default configuration, **not** a `.codequality.yml` file. If you u the wrong filename, the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template) is still used. -### No Code Quality report is displayed in a Merge Request +### No Code Quality report is displayed in a merge request This can be due to multiple reasons: @@ -531,7 +532,7 @@ This can be due to multiple reasons: nothing is displayed. - The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD setting can cause the Code Quality artifact(s) to expire faster than desired. -- The widgets use the pipeline of the latest commit to the target branch. If commits are made to the default branch that do not run the code quality job, this may cause the Merge Request widget to have no base report for comparison. +- The widgets use the pipeline of the latest commit to the target branch. If commits are made to the default branch that do not run the code quality job, this may cause the merge request widget to have no base report for comparison. - If you use the [`REPORT_STDOUT` environment variable](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables), no report file is generated and nothing displays in the merge request. - Large `gl-code-quality-report.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). As a work-around, try removing [properties](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types) diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 3a5a581198b..ce1dac0a96b 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -3,14 +3,14 @@ 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: howto -description: "How to create Merge Requests in GitLab." +description: "How to create merge requests in GitLab." disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html' --- # How to create a merge request **(FREE)** Before creating a merge request, read through an -[introduction to Merge Requests](getting_started.md) +[introduction to merge requests](getting_started.md) to familiarize yourself with the concept, the terminology, and to learn what you can do with them. @@ -21,16 +21,16 @@ or through the [GitLab UI](#new-merge-request-from-a-new-branch-created-through- This document describes the several ways to create a merge request. When you start a new merge request, regardless of the method, -you are taken to the [**New Merge Request** page](#new-merge-request-page) +you are taken to the [**New merge request** page](#new-merge-request-page) to fill it with information about the merge request. If you push a new branch to GitLab, also regardless of the method, -you can click the [**Create Merge Request**](#create-merge-request-button) +you can click the [**Create merge request**](#create-merge-request-button) button and start a merge request from there. -## New Merge Request page +## New merge request page -On the **New Merge Request** page, start by filling in the title and description +On the **New merge request** page, start by filling in the title and description for the merge request. If commits already exist on the branch, GitLab suggests a merge request title for you: @@ -43,31 +43,31 @@ merge request title for you: The title is the only field that is mandatory in all cases. From there, you can fill it with information (title, description, -assignee(s), milestone, labels, approvers) and click **Create Merge Request**. +assignee(s), milestone, labels, approvers) and click **Create merge request**. From that initial screen, you can also see all the commits, pipelines, and file changes pushed to your branch before submitting the merge request. - + NOTE: You can push one or more times to your branch in GitLab before creating the merge request. -## Create Merge Request button +## Create merge request button Once you have pushed a new branch to GitLab, visit your repository in GitLab and to see a call-to-action at the top of your screen -from which you can click the button **Create Merge Request**. +from which you can click the button **Create merge request**. - + You can also see the **Create merge request** button in the top-right of the: - **Project** page. - **Repository > Files** page. -- **Merge Requests** page. +- **Merge requests** page. In this case, GitLab uses the most recent branch you pushed changes to as the source branch, and the default branch in the current @@ -90,7 +90,7 @@ Once you have added, edited, or uploaded the file: 1. Click **Commit changes**. If you chose to start a merge request, you are taken to the -[**New Merge Request** page](#new-merge-request-page), from +[**New merge request** page](#new-merge-request-page), from which you can fill it in with information and submit the merge request. The merge request targets the default branch of the repository. @@ -103,8 +103,8 @@ navigate to your project's **Repository > Branches** and click **New branch**. A new branch is created and you can start editing files. -Once committed and pushed, you can click on the [**Create Merge Request**](#create-merge-request-button) -button to open the [**New Merge Request** page](#new-merge-request-page). +Once committed and pushed, you can click on the [**Create merge request**](#create-merge-request-button) +button to open the [**New merge request** page](#new-merge-request-page). A new merge request is started using the current branch as the source, and the default branch in the current project as the target. @@ -140,7 +140,7 @@ remote: To create a merge request for docs-new-merge-request, visit: remote: https://gitlab-instance.com/my-group/my-project/merge_requests/new?merge_request%5Bsource_branch%5D=my-new-branch ``` -Copy that link and paste it in your browser, and the [**New Merge Request page**](#new-merge-request-page) +Copy that link and paste it in your browser, and the [**New merge request page**](#new-merge-request-page) is displayed. There is also a number of [flags you can add to commands when pushing through the command line](../push_options.md) to reduce the need for editing merge requests manually through the UI. @@ -148,20 +148,20 @@ There is also a number of [flags you can add to commands when pushing through th If you didn't push your branch to GitLab through the command line (for example, you used a Git CLI application to push your changes), you can create a merge request through the GitLab UI by clicking -the [**Create Merge Request**](#create-merge-request-button) button. +the [**Create merge request**](#create-merge-request-button) button. ## New merge request from an issue You can also [create a new merge request directly from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue). -## New merge request from the Merge Requests page +## New merge request from the merge requests page You can start creating a new merge request by clicking the -**New merge request** button on the **Merge Requests** page in a project. +**New merge request** button on the **merge requests** page in a project. Then choose the source project and branch that contain your changes, and the target project and branch where you want to merge the changes into. Click on **Compare branches and continue** to go to the -[**New Merge Request** page](#new-merge-request-page) and fill in the details. +[**New merge request** page](#new-merge-request-page) and fill in the details. ## New merge request from a fork @@ -169,7 +169,7 @@ After forking a project and applying your local changes, complete the following create a merge request from your fork to contribute back to the main project: 1. Go to **Projects > Your Projects** and select your fork of the repository. -1. In the left menu, go to **Merge Requests**, and click **New Merge Request**. +1. In the left menu, go to **Merge requests**, and click **New merge request**. 1. In the **Source branch** drop-down list box, select your branch in your forked repository as the source branch. 1. In the **Target branch** drop-down list box, select the branch from the upstream repository as the target branch. You can set a [default target project](#set-the-default-target-project) to @@ -247,6 +247,6 @@ apply the patches. The target branch can be specified using the [`/target_branch` quick action](../quick_actions.md). If the source branch already exists, the patches are applied on top of it. -## Reviewing and managing Merge Requests +## Reviewing and managing merge requests -Once you have submitted a merge request, it can be [reviewed and managed](reviewing_and_managing_merge_requests.md) through GitLab. +Once you have submitted a merge request, it can be [reviewed and managed](reviews/index.md) through GitLab. diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index f973d9220f2..5556e54f875 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -4,13 +4,13 @@ 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 --- -# Export Merge Requests to CSV **(FREE)** +# Export merge requests to CSV **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3619) in GitLab 13.6. -Exporting Merge Requests CSV enables you and your team to export all the data collected from merge requests into a comma-separated values (CSV) file, which stores tabular data in plain text. +Exporting merge requests CSV enables you and your team to export all the data collected from merge requests into a comma-separated values (CSV) file, which stores tabular data in plain text. -To export Merge Requests to CSV, navigate to your **Merge Requests** from the sidebar of a project and click **Export to CSV**. +To export merge requests to CSV, navigate to your **Merge requests** from the sidebar of a project and click **Export to CSV**. ## CSV Output diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index a030961e219..57850ad7304 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -66,7 +66,7 @@ when you mark a merge request as ready, notifications are triggered to When viewing or searching in your project's merge requests list, you can include or exclude draft merge requests: -1. In your project, select **Merge Requests** from the left sidebar. +1. Go to your project and select **Merge requests**. 1. In the navigation bar, click **Open**, **Merged**, **Closed**, or **All** to filter by merge request status. 1. Click the search box to display a list of filters and select **Draft**, or diff --git a/doc/user/project/merge_requests/fail_fast_testing.md b/doc/user/project/merge_requests/fail_fast_testing.md index 80bdbce8d2c..68a63aebb90 100644 --- a/doc/user/project/merge_requests/fail_fast_testing.md +++ b/doc/user/project/merge_requests/fail_fast_testing.md @@ -42,14 +42,14 @@ This template requires: - A project built in Rails that uses RSpec for testing. - CI/CD configured to: - Use a Docker image with Ruby available. - - Use [Pipelines for Merge Requests](../../../ci/merge_request_pipelines/index.md#configuring-pipelines-for-merge-requests) + - Use [Pipelines for merge requests](../../../ci/merge_request_pipelines/index.md#configuring-pipelines-for-merge-requests) - [Pipelines for Merged Results](../../../ci/merge_request_pipelines/pipelines_for_merged_results/index.md#enable-pipelines-for-merged-results) enabled in the project settings. - A Docker image with Ruby available. The template uses `image: ruby:2.6` by default, but you [can override](../../../ci/yaml/includes.md#overriding-external-template-values) this. ## Configuring Fast RSpec Failure -We'll use the following plain RSpec configuration as a starting point. It installs all the +We use the following plain RSpec configuration as a starting point. It installs all the project gems and executes `rspec`, on merge request pipelines only. ```yaml @@ -86,13 +86,13 @@ For illustrative purposes, let's say our Rails app spec suite consists of 100 sp If no Ruby files are changed: -- `rspec-rails-modified-paths-specs` will not run any tests. -- `rspec-complete` will run the full suite of 1000 tests. +- `rspec-rails-modified-paths-specs` does not run any tests. +- `rspec-complete` runs the full suite of 1000 tests. If one Ruby model is changed, for example `app/models/example.rb`, then `rspec-rails-modified-paths-specs` -will run the 100 tests for `example.rb`: +runs the 100 tests for `example.rb`: - If all of these 100 tests pass, then the full `rspec-complete` suite of 1000 tests is allowed to run. -- If any of these 100 tests fail, they will fail quickly, and `rspec-complete` will not run any tests. +- If any of these 100 tests fail, they fail quickly, and `rspec-complete` does not run any tests. The final case saves resources and time as the full 1000 test suite does not run. diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 1bb333dcb14..459b8fa56ff 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -3,12 +3,12 @@ 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: index, reference -description: "Getting started with Merge Requests." +description: "Getting started with merge requests." --- -# Getting started with Merge Requests **(FREE)** +# Getting started with merge requests **(FREE)** -A Merge Request (**MR**) is the basis of GitLab as a code +A merge request (**MR**) is the basis of GitLab as a code collaboration and version control. When working in a Git-based platform, you can use branching @@ -25,7 +25,7 @@ avoiding changes to be pushed directly to the default branch without prior reviews, tests, and approvals. When you create a new feature branch, change the files, and push -it to GitLab, you have the option to create a **Merge Request**, +it to GitLab, you have the option to create a **merge request**, which is essentially a _request_ to merge one branch into another. The branch you added your changes into is called _source branch_ @@ -56,7 +56,7 @@ request's page at the top-right side: - [Assign](#assignee) the merge request to a colleague for review. With [multiple assignees](#multiple-assignees), you can assign it to more than one person at a time. - Set a [milestone](../milestones/index.md) to track time-sensitive changes. - Add [labels](../labels.md) to help contextualize and filter your merge requests over time. -- Require [approval](merge_request_approvals.md) from your team. **(PREMIUM)** +- [Require approval](approvals/index.md#required-approvals) from your team. **(PREMIUM)** - [Close issues automatically](#merge-requests-to-close-issues) when they are merged. - Enable the [delete source branch when merge request is accepted](#deleting-the-source-branch) option to keep your repository clean. - Enable the [squash commits when merge request is accepted](squash_and_merge.md) option to combine all the commits into one before merging, thus keep a clean commit history in your repository. @@ -65,24 +65,24 @@ request's page at the top-right side: After you have created the merge request, you can also: - [Discuss](../../discussions/index.md) your implementation with your team in the merge request thread. -- [Perform inline code reviews](reviewing_and_managing_merge_requests.md#perform-inline-code-reviews). +- [Perform inline code reviews](reviews/index.md#perform-inline-code-reviews). - Add [merge request dependencies](merge_request_dependencies.md) to restrict it to be merged only when other merge requests have been merged. **(PREMIUM)** -- Preview continuous integration [pipelines on the merge request widget](reviewing_and_managing_merge_requests.md#pipeline-status-in-merge-requests-widgets). -- Preview how your changes look directly on your deployed application with [Review Apps](reviewing_and_managing_merge_requests.md#live-preview-with-review-apps). +- Preview continuous integration [pipelines on the merge request widget](reviews/index.md#pipeline-status-in-merge-requests-widgets). +- Preview how your changes look directly on your deployed application with [Review Apps](reviews/index.md#live-preview-with-review-apps). - [Allow collaboration on merge requests across forks](allow_collaboration.md). -- Perform a [Review](../../discussions/index.md#merge-request-reviews) to create multiple comments on a diff and publish them when you're ready. -- Add [code suggestions](../../discussions/index.md#suggest-changes) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI. +- Perform a [Review](reviews/index.md) to create multiple comments on a diff and publish them when you're ready. +- Add [code suggestions](reviews/suggestions.md) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI. - Add a time estimation and the time spent with that merge request with [Time Tracking](../time_tracking.md#time-tracking). Many of these can be set when pushing changes from the command line, with [Git push options](../push_options.md). -See also other [features associated to merge requests](reviewing_and_managing_merge_requests.md#associated-features). +See also other [features associated to merge requests](reviews/index.md#associated-features). ### Assignee Choose an assignee to designate someone as the person responsible -for the first [review of the merge request](reviewing_and_managing_merge_requests.md). +for the first [review of the merge request](reviews/index.md). Open the drop down box to search for the user you wish to assign, and the merge request is added to their [assigned merge request list](../../search/index.md#issues-and-merge-requests). @@ -122,7 +122,7 @@ Requesting a code review is an important part of contributing code. However, dec your code and asking for a review are no easy tasks. Using the "assignee" field for both authors and reviewers makes it hard for others to determine who's doing what on a merge request. -The Merge Request Reviewers feature enables you to request a review of your work, and +The merge request Reviewers feature enables you to request a review of your work, and see the status of the review. Reviewers help distinguish the roles of the users involved in the merge request. In comparison to an **Assignee**, who is directly responsible for creating or merging a merge request, a **Reviewer** is a team member @@ -138,7 +138,7 @@ When selected, GitLab creates a [to-do list item](../../todos.md) for each revie > - [Feature flag 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](merge_request_approvals.md#approval-rules) +displays the name of the matching [approval rule](approvals/rules.md) below the name of each suggested reviewer. [Code Owners](../code_owners.md) are displayed as `Codeowner` without group detail. This example shows reviewers and approval rules when creating a new merge request: @@ -234,7 +234,7 @@ The feature today works only on merge. Clicking the **Remove source branch** but after the merge request was merged will not automatically retarget a merge request. This improvement is [tracked as a follow-up](https://gitlab.com/gitlab-org/gitlab/-/issues/321559). -## Recommendations and best practices for Merge Requests +## Recommendations and best practices for merge requests - When working locally in your branch, add multiple commits and only push when you're done, so GitLab runs only one pipeline for all the commits pushed diff --git a/doc/user/project/merge_requests/img/approve.png b/doc/user/project/merge_requests/img/approve.png Binary files differdeleted file mode 100644 index e2641f48c7a..00000000000 --- a/doc/user/project/merge_requests/img/approve.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/approve_additionally.png b/doc/user/project/merge_requests/img/approve_additionally.png Binary files differdeleted file mode 100644 index bab0cd4e041..00000000000 --- a/doc/user/project/merge_requests/img/approve_additionally.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/group_merge_requests_list_view.png b/doc/user/project/merge_requests/img/group_merge_requests_list_view.png Binary files differdeleted file mode 100644 index 7d0756505db..00000000000 --- a/doc/user/project/merge_requests/img/group_merge_requests_list_view.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/remove_approval.png b/doc/user/project/merge_requests/img/remove_approval.png Binary files differdeleted file mode 100644 index b178d26cf85..00000000000 --- a/doc/user/project/merge_requests/img/remove_approval.png +++ /dev/null diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 1fed30dc589..f587ab34d11 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -8,7 +8,6 @@ type: index, reference # Merge requests **(FREE)** Merge requests (MRs) are the way you check source code changes into a branch. - When you open a merge request, you can visualize and collaborate on the code changes before merge. Merge requests include: @@ -18,6 +17,11 @@ Merge requests include: - A comment section for discussion threads. - The list of commits. +Merge requests contain tabs at the top of the page to help you navigate to +important parts of the merge request: **Overview**, **Commits**, **Pipelines**, and **Changes**. + + + To get started, read the [introduction to merge requests](getting_started.md). ## Merge request workflows @@ -29,10 +33,10 @@ For a software developer working in a team: 1. You work on the implementation optimizing code with [Code Quality reports](code_quality.md). 1. You verify your changes with [Unit test reports](../../../ci/unit_test_reports.md) in GitLab CI/CD. 1. You avoid using dependencies whose license is not compatible with your project with [License Compliance reports](../../compliance/license_compliance/index.md). -1. You request the [approval](merge_request_approvals.md) from your manager. +1. You request the [approval](approvals/index.md) from your manager. 1. Your manager: 1. Pushes a commit with their final review. - 1. [Approves the merge request](merge_request_approvals.md). + 1. [Approves the merge request](approvals/index.md). 1. Sets it to [merge when pipeline succeeds](merge_when_pipeline_succeeds.md). 1. Your changes get deployed to production with [manual actions](../../../ci/yaml/README.md#whenmanual) for GitLab CI/CD. 1. Your implementations were successfully shipped to your customer. @@ -43,35 +47,13 @@ For a web developer writing a webpage for your company's website: 1. You gather feedback from your reviewers. 1. You preview your changes with [Review Apps](../../../ci/review_apps/index.md). 1. You request your web designers for their implementation. -1. You request the [approval](merge_request_approvals.md) from your manager. +1. You request the [approval](approvals/index.md) from your manager. 1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/). 1. Your production team [cherry picks](cherry_pick_changes.md) the merge commit into production. -## Merge request navigation tabs at the top - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33813) in GitLab 12.6. This positioning is experimental. - -In GitLab 12.5 and earlier, navigation tabs in merge requests (**Discussion**, -**Commits**, **Pipelines**, and **Changes**) were located after the merge request -widget. - -To facilitate navigation without scrolling, and based on user feedback, the tabs are -now located at the top of the merge request tab. A new **Overview** tab was added, -and next to **Overview** are **Commits**, **Pipelines**, and **Changes**. - - - -This change is behind a feature flag that is enabled by default. For -self-managed instances, it can be disabled through the Rails console by a GitLab -administrator with the following command: - -```ruby -Feature.disable(:mr_tabs_position) -``` - ## Related topics - [Create a merge request](creating_merge_requests.md) -- [Review and manage merge requests](reviewing_and_managing_merge_requests.md) +- [Review and manage merge requests](reviews/index.md) - [Authorization for merge requests](authorization_for_merge_requests.md) - [Testing and reports](testing_and_reports_in_merge_requests.md) diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 835350ade44..38d6ba062e4 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -1,416 +1,8 @@ --- -stage: Create -group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, concepts +redirect_to: 'approvals/index.md' --- -# Merge Request Approvals **(FREE)** +This document was moved to [another location](approvals/index.md). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/580) in GitLab Enterprise Edition 7.2. Available in GitLab Free and higher tiers. -> - Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0. - -Code review is an essential practice of every successful project. Approving a -merge request is an important part of the review -process, as it clearly communicates the ability to merge the change. -A [merge request approvals API](../../../api/merge_request_approvals.md) is also available. - -## Optional Approvals - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27426) in GitLab 13.2. - -Any user with Developer or greater [permissions](../../permissions.md) can approve a merge request in GitLab Free and higher tiers. -This provides a consistent mechanism for reviewers to approve merge requests, and ensures -maintainers know a change is ready to merge. Approvals in Free are optional, and do -not prevent a merge request from being merged when there is no approval. - -## External approvals **(ULTIMATE)** - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab Ultimate 13.10. -> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../../api/merge_request_approvals.md#enable-or-disable-external-project-level-mr-approvals). **(ULTIMATE SELF)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -When you create an external approval rule, the following merge request actions sends information -about a merge request to a third party service: - -- Create -- Change -- Close - -This action enables use-cases such as: - -- Integration with 3rd party workflow tools, such as [ServiceNow](https://www.servicenow.co.uk/). -- Integration with custom tools designed to approve merge requests from outside of GitLab. - -You can find more information about use-cases, development timelines and the feature discovery in -the [External API approval rules epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). - -The intention for this feature is to allow those 3rd party tools to approve a merge request similarly to how users current do. - -NOTE: -The lack of an external approval does not block the merging of a merge request. - -You can modify external approval rules through the [REST API](../../../api/merge_request_approvals.md#external-project-level-mr-approvals). - -## Required Approvals **(PREMIUM)** - -> - [Introduced](https://about.gitlab.com/releases/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only) in GitLab Enterprise Edition 7.12. -> - Moved to GitLab Premium in 13.9. - -Required approvals enable enforced code review by requiring specified people -to approve a merge request before it can be merged. - -Required approvals enable multiple use cases: - -- Enforcing review of all code that gets merged into a repository. -- Specifying reviewers for a given proposed code change, as well as a minimum number - of reviewers, through [Approval rules](#approval-rules). -- Specifying categories of reviewers, such as backend, frontend, quality assurance, - database, and so on, for all proposed code changes. -- Designating [Code Owners as eligible approvers](#code-owners-as-eligible-approvers), - determined by the files changed in a merge request. -- [Requiring approval from a security team](#security-approvals-in-merge-requests) - before merging code that could introduce a vulnerability.**(ULTIMATE)** - -### Approval Rules - -Approval rules define how many approvals a merge request must receive before it can -be merged, and optionally which users should do the approving. Approvals can be defined: - -- [As project defaults](#adding--editing-a-default-approval-rule). -- [Per merge request](#editing--overriding-approval-rules-per-merge-request). - -If no approval rules are defined, any user can approve a merge request. However, the default -minimum number of required approvers can still be set in the -[settings for merge request approvals](#approval-settings). - -You can opt to define one single rule to approve a merge request among the available rules -or choose more than one with [multiple approval rules](#multiple-approval-rules). - -NOTE: -On GitLab.com, you can add a group as an approver if you're a member of that group or the -group is public. - -#### Eligible Approvers - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in GitLab 13.3, when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget. - -The following users can approve merge requests: - -- Users who have been added as approvers at the project or merge request levels with - developer or higher [permissions](../../permissions.md). -- [Code owners](#code-owners-as-eligible-approvers) of the files changed by the merge request - that have developer or higher [permissions](../../permissions.md). - -An individual user can be added as an approver for a project if they are a member of: - -- The project. -- The project's immediate parent group. -- A group that has access to the project via a [share](../members/share_project_with_groups.md). - -A group of users can also be added as approvers, though they only count as approvers if -they have direct membership to the group. In the future, group approvers may be -[restricted to only groups with share access to the project](https://gitlab.com/gitlab-org/gitlab/-/issues/2048). - -If a user is added as an individual approver and is also part of a group approver, -then that user is just counted once. The merge request author, and users who have committed -to the merge request, do not count as eligible approvers, -if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) (enabled by default) -and [**Prevent committers approval**](#prevent-approval-of-merge-requests-by-their-committers) (disabled by default) -are enabled on the project settings. - -When an eligible approver comments on a merge request, it displays in the -**Commented by** column of the Approvals widget. It indicates who participated in -the merge request review. Authors and reviewers can also identify who they should reach out -to if they have any questions about the content of the merge request. - -##### Implicit Approvers - -If the number of required approvals is greater than the number of assigned approvers, -approvals from other users counts towards meeting the requirement. These would be -users with developer [permissions](../../permissions.md) or higher in the project who -were not explicitly listed in the approval rules. - -##### Code Owners as eligible approvers - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in GitLab 11.5. -> - Moved to GitLab Premium in 13.9. - -If you add [Code Owners](../code_owners.md) to your repository, the owners to the -corresponding files become eligible approvers, together with members with Developer -or higher [permissions](../../permissions.md). - -To enable this merge request approval rule: - -1. Navigate to your project's **Settings > General** and expand - **Merge request (MR) approvals**. -1. Locate **Any eligible user** and choose the number of approvals required. - - - -Once set, merge requests can only be merged once approved by the -number of approvals you've set. GitLab accepts approvals from -users with Developer or higher permissions, as well as by Code Owners, -indistinguishably. - -Alternatively, you can **require** -[Code Owner's approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** - -#### Merge Request approval segregation of duties - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. -> - Moved to Premium in 13.9. - -Managers or operators with [Reporter permissions](../../permissions.md#project-members-permissions) -to a project sometimes need to be required approvers of a merge request, -before a merge to a protected branch begins. These approvers aren't allowed -to push or merge code to any branches. - -To enable this access: - -1. [Create a new group](../../group/index.md#create-a-group), and then - [add the user to the group](../../group/index.md#add-users-to-a-group), - ensuring you select the Reporter role for the user. -1. [Share the project with your group](../members/share_project_with_groups.md#sharing-a-project-with-a-group-of-users), - based on the Reporter role. -1. Navigate to your project's **Settings > General**, and in the - **Merge request (MR) approvals** section, click **Expand**. -1. Select **Add approval rule** or **Update approval rule**. -1. [Add the group](../../group/index.md#create-a-group) to the permission list. - - - -#### Adding / editing a default approval rule - -To add or edit the default merge request approval rule: - -1. Navigate to your project's **Settings > General** and expand **Merge request (MR) approvals**. - -1. Click **Add approval rule**, or **Edit**. - - Add or change the **Rule name**. - - Set the number of required approvals in **Approvals required**. The minimum value is `0`. - - (Optional) Search for users or groups that are [eligible to approve](#eligible-approvers) - merge requests and click the **Add** button to add them as approvers. Before typing - in the search field, approvers are suggested based on the previous authors of - the files being changed by the merge request. - - (Optional) Click the **{remove}** **Remove** button next to a group or user to delete it from - the rule. -1. Click **Add approval rule** or **Update approval rule**. - -When [approval rule overrides](#prevent-overriding-default-approvals) are allowed, -changes to these default rules are not applied to existing merge -requests, except for changes to the [target branch](#scoped-to-protected-branch) of -the rule. - -When approval rule overrides are not allowed, all changes to these default rules -are applied to existing merge requests. Any approval rules that had previously been -manually [overridden](#editing--overriding-approval-rules-per-merge-request) during a -period when approval rule overrides where allowed, are not modified. - -NOTE: -If a merge request targets a different project, such as from a fork to the upstream project, -the default approval rules are taken from the target (upstream) project, not the -source (fork). - -##### Editing / overriding approval rules per merge request - -> Introduced in GitLab Enterprise Edition 9.4. - -By default, the merge request approval rule listed in each merge request (MR) can be -edited by the MR author or a user with sufficient [permissions](../../permissions.md). -This ability can be disabled in the [merge request approvals settings](#prevent-overriding-default-approvals). - -One possible scenario would be to add more approvers than were defined in the default -settings. - -When creating or editing a merge request, find the **Approval rules** section, then follow -the same steps as [Adding / editing a default approval rule](#adding--editing-a-default-approval-rule). - -#### Set up an optional approval rule - -MR approvals can be configured to be optional, which can help if you're working -on a team where approvals are appreciated, but not required. - -To configure an approval to be optional, set the number of required approvals in **Approvals required** to `0`. - -You can also set an optional approval rule through the [Merge requests approvals API](../../../api/merge_request_approvals.md#update-merge-request-level-rule), by setting the `approvals_required` attribute to `0`. - -#### Multiple approval rules **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. - -In GitLab Premium, it is possible to have multiple approval rules per merge request, -as well as multiple default approval rules per project. - -Adding or editing multiple default rules is identical to -[adding or editing a single default approval rule](#adding--editing-a-default-approval-rule), -except the **Add approval rule** button is available to add more rules, even after -a rule is already defined. - -Similarly, editing or overriding multiple approval rules per merge request is identical -to [editing or overriding approval rules per merge request](#editing--overriding-approval-rules-per-merge-request), -except the **Add approval rule** button is available to add more rules, even after -a rule is already defined. - -When an [eligible approver](#eligible-approvers) approves a merge request, it -reduces the number of approvals left for all rules that the approver belongs to. - - - -#### Scoped to protected branch **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. - -Approval rules are often only relevant to specific branches, like `master`. -When configuring [**Default Approval Rules**](#adding--editing-a-default-approval-rule) -these can be scoped to all the protected branches at once by navigating to your project's -**Settings**, expanding **Merge request (MR) approvals**, and selecting **Any branch** from -the **Target branch** dropdown. - -Alternatively, you can select a very specific protected branch from the **Target branch** dropdown: - - - -To enable this configuration, see [Code Owner's approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). - -### Adding or removing an approval - -When an [eligible approver](#eligible-approvers) visits an open merge request, -one of the following is possible: - -- If the required number of approvals has _not_ been yet met, they can approve - it by clicking the displayed **Approve** button. - -  - -- If the required number of approvals has already been met, they can still - approve it by clicking the displayed **Approve additionally** button. - -  - -- **They have already approved this merge request**: They can remove their approval. - -  - -When [approval rule overrides](#prevent-overriding-default-approvals) are allowed, -changes to default approval rules will **not** be applied to existing -merge requests, except for changes to the [target branch](#scoped-to-protected-branch) -of the rule. - -NOTE: -The merge request author is not allowed to approve their own merge request if -[**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) -is enabled in the project settings. - -After the approval rules have been met, the merge request can be merged if there is nothing -else blocking it. Note that the merge request could still be blocked by other conditions, -such as merge conflicts, [pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved), -or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md). - -### Approval settings - -The settings for Merge Request Approvals are found by going to -**Settings > General** and expanding **Merge request (MR) approvals**. - -#### Prevent overriding default approvals - -Regardless of the approval rules you choose for your project, users can edit them in every merge -request, overriding the rules you set as [default](#adding--editing-a-default-approval-rule). -To prevent that from happening: - -1. Select the **Prevent users from modifying MR approval rules in merge requests.** checkbox. -1. Click **Save changes**. - -#### Resetting approvals on push - -You can force all approvals on a merge request to be removed when new commits are -pushed to the source branch of the merge request. If disabled, approvals persist -even if there are changes added to the merge request. To enable this feature: - -1. Check the **Require new approvals when new commits are added to an MR.** - checkbox. -1. Click **Save changes**. - -NOTE: -Approvals do not get reset when [rebasing a merge request](fast_forward_merge.md) -from the UI. However, approvals are reset if the target branch is changed. - -#### Allowing merge request authors to approve their own merge requests **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in GitLab 11.3. -> - Moved to GitLab Premium in 13.9. - -By default, projects are configured to prevent merge requests from being approved by -their own authors. To change this setting: - -1. Go to your project's **Settings > General**, expand **Merge request (MR) approvals**. -1. Uncheck the **Prevent MR approval by the author.** checkbox. -1. Click **Save changes**. - -Note that users can edit the approval rules in every merge request and override pre-defined settings unless it's set [**not to allow** overrides](#prevent-overriding-default-approvals). - -You can prevent authors from approving their own merge requests -[at the instance level](../../admin_area/merge_requests_approvals.md). When enabled, -this setting is disabled on the project level, and not editable. - -#### Prevent approval of merge requests by their committers **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in GitLab 11.10. -> - Moved to GitLab Premium in 13.9. - -You can prevent users who have committed to a merge request from approving it, -though code authors can still approve. You can enable this feature -[at the instance level](../../admin_area/merge_requests_approvals.md), which -disables changes to this feature at the project level. If you prefer to manage -this feature at the project level, you can: - -1. Check the **Prevent MR approvals from users who make commits to the MR.** checkbox. - If this check box is disabled, this feature has been disabled - [at the instance level](../../admin_area/merge_requests_approvals.md). -1. Click **Save changes**. - -Read the official Git documentation for an explanation of the -[differences between authors and committers](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History). - -#### Require authentication when approving a merge request - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 12.0. -> - Moved to GitLab Premium in 13.9. - -NOTE: -To require authentication when approving a merge request, you must enable -**Password authentication enabled for web interface** under [sign-in restrictions](../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). -in the Admin Area. - -You can force the approver to enter a password in order to authenticate before adding -the approval. This enables an Electronic Signature for approvals such as the one defined -by [CFR Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)). -To enable this feature: - -1. Check the **Require user password for approvals.** checkbox. -1. Click **Save changes**. - -### Security approvals in merge requests **(ULTIMATE)** - -Merge Request Approvals can be configured to require approval from a member -of your security team when a vulnerability would be introduced by a merge request. - -For more information, see -[Security approvals in merge requests](../../application_security/index.md#security-approvals-in-merge-requests). - -<!-- ## 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. --> +<!-- This redirect file can be deleted after <2021-07-27>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index fc5cc4d958b..4534ce194bf 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -5,10 +5,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Merge Request dependencies **(PREMIUM)** +# Merge request dependencies **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9688) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17291) from "Cross-project dependencies" to "Merge Requests dependencies" in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17291) from "Cross-project dependencies" to "Merge request dependencies" in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. > - Intra-project MR dependencies were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16799) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. Merge request dependencies allows a required order of merging 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 58f2c310375..b1da336aae9 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -67,7 +67,7 @@ You should be careful to configure CI/CD so that pipelines run for every merge r ### Limitations 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/README.md#onlyexcept-advanced) +is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/README.md#only--except) or [`rules`](../../../ci/yaml/README.md#rules) are used and they don't generate any pipelines. You should ensure that [there is always a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54226) diff --git a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md index aba75403a2a..0475996cb9b 100644 --- a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md +++ b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md @@ -1,452 +1,8 @@ --- -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: index, reference +redirect_to: 'reviews/index.md' --- -# Reviewing and managing merge requests **(FREE)** +This document was moved to [another location](reviews/index.md). -Merge requests are the primary method of making changes to files in a GitLab project. -Changes are proposed by [creating and submitting a merge request](creating_merge_requests.md), -which is then reviewed, and accepted (or rejected). - -## View project merge requests - -View all the merge requests in a project by navigating to **Project > Merge Requests**. - -When you access your project's merge requests, GitLab displays them in a list. -Use the tabs to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists). - - - -## View merge requests for all projects in a group - -View merge requests in all projects in the group, including all projects of all descendant subgroups of the group. Navigate to **Group > Merge Requests** to view these merge requests. This view also has the open and closed merge requests tabs. - -You can [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists) from here. - - - -## Cached merge request count - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299542) in GitLab 13.11. -> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-cached-merge-request-count). - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -In a group, the sidebar displays the total count of open merge requests and this value is cached if higher -than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. - -### Enable or disable cached merge request count **(FREE SELF)** - -Cached merge request count in the left sidebar is under development but ready for production use. It is -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable it. - -To disable it: - -```ruby -Feature.disable(:cached_sidebar_merge_requests_count) -``` - -To enable it: - -```ruby -Feature.enable(:cached_sidebar_merge_requests_count) -``` - -## Semi-linear history merge requests - -A merge commit is created for every merge, but the branch is only merged if -a fast-forward merge is possible. This ensures that if the merge request build -succeeded, the target branch build also succeeds after the merge. - -Navigate to a project's settings, select the **Merge commit with semi-linear history** -option under **Merge Requests: Merge method** and save your changes. - -## View changes between file versions - -The **Changes** tab, below the main merge request details and next to the discussion tab, -shows the changes to files between branches or commits. This view of changes to a -file is also known as a **diff**. By default, the diff view compares the file in the -merge request branch and the file in the target branch. - -The diff view includes the following: - -- The file's name and path. -- The number of lines added and deleted. -- Buttons for the following options: - - Toggle comments for this file; useful for inline reviews. - - Edit the file in the merge request's branch. - - Show full file, in case you want to look at the changes in context with the rest of the file. - - View file at the current commit. - - Preview the changes with [Review Apps](../../../ci/review_apps/index.md). -- The changed lines, with the specific changes highlighted. - - - -### Merge request diff file navigation - -When reviewing changes in the **Changes** tab the diff can be navigated using -the file tree or file list. As you scroll through large diffs with many -changes, you can quickly jump to any changed file using the file tree or file -list. - - - -### Collapsed files in the Changes view - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232820) in GitLab 13.4. - -When you review changes in the **Changes** tab, files with a large number of changes are collapsed -to improve performance. When files are collapsed, a warning appears at the top of the changes. -Click **Expand file** on any file to view the changes for that file. - -### File-by-file diff navigation - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229848) in GitLab 13.7. - -For larger merge requests, consider reviewing one file at a time. To enable this feature: - -1. In the top-right corner, select your avatar. -1. Select **Preferences**. -1. Scroll to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**. -1. Select **Save changes**. - -After you enable this setting, GitLab displays only one file at a time in the **Changes** tab when you review merge requests. You can click **Prev** and **Next** to view other changed files. - - - -In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) and later, if you want to change -this behavior, you can do so from your **User preferences** (as explained above) or directly in a -merge request: - -1. Go to the merge request's **Changes** tab. -1. Select the cog icon (**{settings}**) to reveal the merge request's settings dropdown. -1. Select or deselect the checkbox **Show one file at a time** to change the setting accordingly. - -This change overrides the choice you made in your user preferences and persists until you clear your -browser's cookies or change this behavior again. - -### Merge requests commit navigation - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. - -To seamlessly navigate among commits in a merge request: - -1. Select the **Commits** tab. -1. Select a commit to open it in the single-commit view. -1. Navigate through the commits by either: - - - Selecting **Prev** and **Next** buttons below the tab buttons. - - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. - - - -### Incrementally expand merge request diffs - -By default, the diff shows only the parts of a file which are changed. -To view more unchanged lines above or below a change click on the -**Expand up** or **Expand down** icons. You can also click on **Show unchanged lines** -to expand the entire file. - - - -In GitLab [versions 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/205401), when viewing a -merge request's **Changes** tab, if a certain file was only renamed, you can expand it to see the -entire content by clicking **Show file contents**. - -### Ignore whitespace changes in Merge Request diff view - -If you click the **Hide whitespace changes** button, you can see the diff -without whitespace changes (if there are any). This is also working when on a -specific commit page. - - - -NOTE: -You can append `?w=1` while on the diffs page of a merge request to ignore any -whitespace changes. - -## Mark files as viewed - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9. -> - It's deployed behind a feature flag, enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-file-views). **(FREE SELF)** - -When reviewing a merge request with many files multiple times, it may be useful to the reviewer -to focus on new changes and ignore the files that they have already reviewed and don't want to -see anymore unless they are changed again. - -To mark a file as viewed: - -1. Go to the merge request's **Diffs** tab. -1. On the right-top of the file, locate the **Viewed** checkbox. -1. Check it to mark the file as viewed. - -Once checked, the file remains marked for that reviewer unless there are newly introduced -changes to its content or the checkbox is unchecked. - -### Enable or disable file views **(FREE SELF)** - -The file view feature is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to enable it for your instance. - -To enable it: - -```ruby -Feature.enable(:local_file_reviews) -``` - -To disable it: - -```ruby -Feature.disable(:local_file_reviews) -``` - -## Perform inline code reviews - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13950) in GitLab 11.5. - -In a merge request, you can leave comments in any part of the file being changed. -In the Merge Request Diff UI, you can: - -- **Comment on a single line**: Click the **{comment}** **comment** icon in the - gutter to expand the diff lines and display a comment box. -- [**Comment on multiple lines**](#commenting-on-multiple-lines). - -### Commenting on multiple lines - -> - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49875) click-and-drag features in GitLab 13.8. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299121) in GitLab 13.9. - -When commenting on a diff, you can select which lines of code your comment refers -to by either: - - - -- Clicking and dragging the **{comment}** **comment** icon in the gutter to highlight - lines in the diff. GitLab expands the diff lines and displays a comment box. -- After starting a comment by clicking the **{comment}** **comment** icon in the - gutter, select the first line number your comment refers to in the **Commenting on lines** - select box. New comments default to single-line comments, unless you select - a different starting line. - -Multiline comments display the comment's line numbers above the body of the comment: - - - -## Pipeline status in merge requests widgets - -If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, -you can see: - -- Both pre-merge and post-merge pipelines and the environment information if any. -- Which deployments are in progress. - -If an application is successfully deployed to an -[environment](../../../ci/environments/index.md), the deployed environment and the link to the -Review App are both shown. - -NOTE: -When the pipeline fails in a merge request but it can still be merged, -the **Merge** button is colored red. - -### Post-merge pipeline status - -When a merge request is merged, you can see the post-merge pipeline status of -the branch the merge request was merged into. For example, when a merge request -is merged into the [default branch](../repository/branches/default.md) and then triggers a deployment to the staging -environment. - -Ongoing deployments are shown, and the state (deploying or deployed) -for environments. If it's the first time the branch is deployed, the link -returns a `404` error until done. During the deployment, the stop button is -disabled. If the pipeline fails to deploy, the deployment information is hidden. - - - -For more information, [read about pipelines](../../../ci/pipelines/index.md). - -### Merge when pipeline succeeds (MWPS) - -Set a merge request that looks ready to merge to -[merge automatically when CI pipeline succeeds](merge_when_pipeline_succeeds.md). - -### Live preview with Review Apps - -If you configured [Review Apps](https://about.gitlab.com/stages-devops-lifecycle/review-apps/) for your project, -you can preview the changes submitted to a feature branch through a merge request -on a per-branch basis. You don't need to checkout the branch, install, and preview locally. -All your changes are available to preview by anyone with the Review Apps link. - -With GitLab [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the -merge request widget takes you directly to the pages changed, making it easier and -faster to preview proposed modifications. - -[Read more about Review Apps](../../../ci/review_apps/index.md). - -## Associated features - -These features are associated with merge requests: - -- [Bulk editing merge requests](../../project/bulk_editing.md): - Update the attributes of multiple merge requests simultaneously. -- [Cherry-pick changes](cherry_pick_changes.md): - Cherry-pick any commit in the UI by clicking the **Cherry-pick** button in a merged merge requests or a commit. -- [Fast-forward merge requests](fast_forward_merge.md): - For a linear Git history and a way to accept merge requests without creating merge commits -- [Find the merge request that introduced a change](versions.md): - When viewing the commit details page, GitLab links to the merge request(s) containing that commit. -- [Merge requests versions](versions.md): - Select and compare the different versions of merge request diffs -- [Resolve conflicts](resolve_conflicts.md): - GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. -- [Revert changes](revert_changes.md): - Revert changes from any commit from a merge request. - -## Troubleshooting - -Sometimes things don't go as expected in a merge request. Here are some -troubleshooting steps. - -### Merge request cannot retrieve the pipeline status - -This can occur if Sidekiq doesn't pick up the changes fast enough. - -#### Sidekiq - -Sidekiq didn't process the CI state change fast enough. Please wait a few -seconds and the status should update automatically. - -#### Bug - -Merge Request pipeline statuses can't be retrieved when the following occurs: - -1. A Merge Request is created -1. The Merge Request is closed -1. Changes are made in the project -1. The Merge Request is reopened - -To enable the pipeline status to be properly retrieved, close and reopen the -Merge Request again. - -## Tips - -Here are some tips to help you be more efficient with merge requests in -the command line. - -### Copy the branch name for local checkout - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23767) in GitLab 13.4. - -The merge request sidebar contains the branch reference for the source branch -used to contribute changes for this merge request. - -To copy the branch reference into your clipboard, click the **Copy branch name** button -(**{copy-to-clipboard}**) in the right sidebar. Use it to checkout the branch locally -via command line by running `git checkout <branch-name>`. - -### Checkout merge requests locally through the `head` ref - -A merge request contains all the history from a repository, plus the additional -commits added to the branch associated with the merge request. Here's a few -ways to checkout a merge request locally. - -You can checkout a merge request locally even if the source -project is a fork (even a private fork) of the target project. - -This relies on the merge request `head` ref (`refs/merge-requests/:iid/head`) -that is available for each merge request. It allows checking out a merge -request via its ID instead of its branch. - -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223156) in GitLab -13.4, 14 days after a merge request gets closed or merged, the merge request -`head` ref is deleted. This means that the merge request is not available -for local checkout via the merge request `head` ref anymore. The merge request -can still be re-opened. If the merge request's branch -exists, you can still check out the branch, as it isn't affected. - -#### Checkout locally by adding a Git alias - -Add the following alias to your `~/.gitconfig`: - -```plaintext -[alias] - mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' - -``` - -Now you can check out a particular merge request from any repository and any -remote. For example, to check out the merge request with ID 5 as shown in GitLab -from the `origin` remote, do: - -```shell -git mr origin 5 -``` - -This fetches the merge request into a local `mr-origin-5` branch and check -it out. - -#### Checkout locally by modifying `.git/config` for a given repository - -Locate the section for your GitLab remote in the `.git/config` file. It looks -like this: - -```plaintext -[remote "origin"] - url = https://gitlab.com/gitlab-org/gitlab-foss.git - fetch = +refs/heads/*:refs/remotes/origin/* -``` - -You can open the file with: - -```shell -git config -e -``` - -Now add the following line to the above section: - -```plaintext -fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* -``` - -In the end, it should look like this: - -```plaintext -[remote "origin"] - url = https://gitlab.com/gitlab-org/gitlab-foss.git - fetch = +refs/heads/*:refs/remotes/origin/* - fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* -``` - -Now you can fetch all the merge requests: - -```shell -git fetch origin - -... -From https://gitlab.com/gitlab-org/gitlab-foss.git - * [new ref] refs/merge-requests/1/head -> origin/merge-requests/1 - * [new ref] refs/merge-requests/2/head -> origin/merge-requests/2 -... -``` - -And to check out a particular merge request: - -```shell -git checkout origin/merge-requests/1 -``` - -All the above can be done with the [`git-mr`](https://gitlab.com/glensc/git-mr) script. +<!-- This redirect file can be deleted after <2021-08-03>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/discussions/img/add_another_suggestion_to_batch_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/add_another_suggestion_to_batch_v13_1.jpg Binary files differindex e8aa4b7c730..e8aa4b7c730 100644 --- a/doc/user/discussions/img/add_another_suggestion_to_batch_v13_1.jpg +++ b/doc/user/project/merge_requests/reviews/img/add_another_suggestion_to_batch_v13_1.jpg diff --git a/doc/user/discussions/img/add_first_suggestion_to_batch_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/add_first_suggestion_to_batch_v13_1.jpg Binary files differindex d15f5d53e55..d15f5d53e55 100644 --- a/doc/user/discussions/img/add_first_suggestion_to_batch_v13_1.jpg +++ b/doc/user/project/merge_requests/reviews/img/add_first_suggestion_to_batch_v13_1.jpg diff --git a/doc/user/discussions/img/apply_batch_of_suggestions_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/apply_batch_of_suggestions_v13_1.jpg Binary files differindex 3e1e9c20af9..3e1e9c20af9 100644 --- a/doc/user/discussions/img/apply_batch_of_suggestions_v13_1.jpg +++ b/doc/user/project/merge_requests/reviews/img/apply_batch_of_suggestions_v13_1.jpg diff --git a/doc/user/discussions/img/apply_suggestion_v13_9.png b/doc/user/project/merge_requests/reviews/img/apply_suggestion_v13_9.png Binary files differindex e27fa629672..e27fa629672 100644 --- a/doc/user/discussions/img/apply_suggestion_v13_9.png +++ b/doc/user/project/merge_requests/reviews/img/apply_suggestion_v13_9.png diff --git a/doc/user/project/merge_requests/img/comment-on-any-diff-line_v13_10.png b/doc/user/project/merge_requests/reviews/img/comment-on-any-diff-line_v13_10.png Binary files differindex a31fea85be9..a31fea85be9 100644 --- a/doc/user/project/merge_requests/img/comment-on-any-diff-line_v13_10.png +++ b/doc/user/project/merge_requests/reviews/img/comment-on-any-diff-line_v13_10.png diff --git a/doc/user/discussions/img/custom_commit_v13_9.png b/doc/user/project/merge_requests/reviews/img/custom_commit_v13_9.png Binary files differindex 170c04542dd..170c04542dd 100644 --- a/doc/user/discussions/img/custom_commit_v13_9.png +++ b/doc/user/project/merge_requests/reviews/img/custom_commit_v13_9.png diff --git a/doc/user/discussions/img/make_suggestion_v13_9.png b/doc/user/project/merge_requests/reviews/img/make_suggestion_v13_9.png Binary files differindex 92d5ba5ddda..92d5ba5ddda 100644 --- a/doc/user/discussions/img/make_suggestion_v13_9.png +++ b/doc/user/project/merge_requests/reviews/img/make_suggestion_v13_9.png diff --git a/doc/user/project/merge_requests/img/merge_request_pipeline.png b/doc/user/project/merge_requests/reviews/img/merge_request_pipeline.png Binary files differindex ce1d6bab536..ce1d6bab536 100644 --- a/doc/user/project/merge_requests/img/merge_request_pipeline.png +++ b/doc/user/project/merge_requests/reviews/img/merge_request_pipeline.png diff --git a/doc/user/discussions/img/mr_review_new_comment_v13_11.png b/doc/user/project/merge_requests/reviews/img/mr_review_new_comment_v13_11.png Binary files differindex 6b4899bf67f..6b4899bf67f 100644 --- a/doc/user/discussions/img/mr_review_new_comment_v13_11.png +++ b/doc/user/project/merge_requests/reviews/img/mr_review_new_comment_v13_11.png diff --git a/doc/user/discussions/img/mr_review_resolve.png b/doc/user/project/merge_requests/reviews/img/mr_review_resolve.png Binary files differindex ced33682459..ced33682459 100644 --- a/doc/user/discussions/img/mr_review_resolve.png +++ b/doc/user/project/merge_requests/reviews/img/mr_review_resolve.png diff --git a/doc/user/discussions/img/mr_review_resolve2.png b/doc/user/project/merge_requests/reviews/img/mr_review_resolve2.png Binary files differindex 2f0be3b6d06..2f0be3b6d06 100644 --- a/doc/user/discussions/img/mr_review_resolve2.png +++ b/doc/user/project/merge_requests/reviews/img/mr_review_resolve2.png diff --git a/doc/user/discussions/img/mr_review_start.png b/doc/user/project/merge_requests/reviews/img/mr_review_start.png Binary files differindex 08b4c6bb82b..08b4c6bb82b 100644 --- a/doc/user/discussions/img/mr_review_start.png +++ b/doc/user/project/merge_requests/reviews/img/mr_review_start.png diff --git a/doc/user/discussions/img/mr_review_unresolve.png b/doc/user/project/merge_requests/reviews/img/mr_review_unresolve.png Binary files differindex 4bef38f7808..4bef38f7808 100644 --- a/doc/user/discussions/img/mr_review_unresolve.png +++ b/doc/user/project/merge_requests/reviews/img/mr_review_unresolve.png diff --git a/doc/user/discussions/img/multi-line-suggestion-preview.png b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview.png Binary files differindex 476c50b9098..476c50b9098 100644 --- a/doc/user/discussions/img/multi-line-suggestion-preview.png +++ b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview.png diff --git a/doc/user/discussions/img/multi-line-suggestion-syntax.png b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-syntax.png Binary files differindex 80424d1f056..80424d1f056 100644 --- a/doc/user/discussions/img/multi-line-suggestion-syntax.png +++ b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-syntax.png diff --git a/doc/user/project/merge_requests/img/multiline-comment-saved.png b/doc/user/project/merge_requests/reviews/img/multiline-comment-saved.png Binary files differindex cceab36e62b..cceab36e62b 100644 --- a/doc/user/project/merge_requests/img/multiline-comment-saved.png +++ b/doc/user/project/merge_requests/reviews/img/multiline-comment-saved.png diff --git a/doc/user/discussions/img/pending_review_comment.png b/doc/user/project/merge_requests/reviews/img/pending_review_comment.png Binary files differindex 70a66b3f4f0..70a66b3f4f0 100644 --- a/doc/user/discussions/img/pending_review_comment.png +++ b/doc/user/project/merge_requests/reviews/img/pending_review_comment.png diff --git a/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png b/doc/user/project/merge_requests/reviews/img/project_merge_requests_list_view_v13_5.png Binary files differindex 625d47b1142..625d47b1142 100644 --- a/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png +++ b/doc/user/project/merge_requests/reviews/img/project_merge_requests_list_view_v13_5.png diff --git a/doc/user/discussions/img/remove_suggestion_from_batch_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/remove_suggestion_from_batch_v13_1.jpg Binary files differindex fa8331effdb..fa8331effdb 100644 --- a/doc/user/discussions/img/remove_suggestion_from_batch_v13_1.jpg +++ b/doc/user/project/merge_requests/reviews/img/remove_suggestion_from_batch_v13_1.jpg diff --git a/doc/user/discussions/img/suggestion_button_v13_9.png b/doc/user/project/merge_requests/reviews/img/suggestion_button_v13_9.png Binary files differindex 58e0508d8cf..58e0508d8cf 100644 --- a/doc/user/discussions/img/suggestion_button_v13_9.png +++ b/doc/user/project/merge_requests/reviews/img/suggestion_button_v13_9.png diff --git a/doc/user/discussions/img/suggestion_code_block_editor_v12_8.png b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_editor_v12_8.png Binary files differindex 927b4f812a5..927b4f812a5 100644 --- a/doc/user/discussions/img/suggestion_code_block_editor_v12_8.png +++ b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_editor_v12_8.png diff --git a/doc/user/discussions/img/suggestion_code_block_output_v12_8.png b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_output_v12_8.png Binary files differindex 6f29107146d..6f29107146d 100644 --- a/doc/user/discussions/img/suggestion_code_block_output_v12_8.png +++ b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_output_v12_8.png diff --git a/doc/user/discussions/img/suggestions_custom_commit_messages_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v13_1.jpg Binary files differindex a4c9df0ebb9..a4c9df0ebb9 100644 --- a/doc/user/discussions/img/suggestions_custom_commit_messages_v13_1.jpg +++ b/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v13_1.jpg diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md new file mode 100644 index 00000000000..e98a230c0de --- /dev/null +++ b/doc/user/project/merge_requests/reviews/index.md @@ -0,0 +1,417 @@ +--- +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: index, reference +--- + +# Review and manage merge requests **(FREE)** + +[Merge requests](../index.md) are the primary method of making changes to files in a +GitLab project. [Create and submit a merge request](../creating_merge_requests.md) +to propose changes. Your team makes [suggestions](suggestions.md) and leaves +[comments](../../../discussions/index.md). When your work is reviewed, your team +members can choose to accept or reject it. + +## View merge requests + +You can view merge requests for a specific project, or for all projects in a group: + +- **Specific project**: Go to your project and select **Merge requests**. +- **All projects in a group**: Go to your group and select **Merge requests**. + If your group contains subgroups, this view also displays merge requests from the subgroup projects. + GitLab displays a count of open merge requests in the left sidebar, but + [caches the value](#cached-merge-request-count) for groups with a large number of + open merge requests. + +GitLab displays open merge requests, with tabs to filter the list by open and closed status: + + + +You can [search and filter](../../../search/index.md#filtering-issue-and-merge-request-lists), +the results, or select a merge request to begin a review. + +## Bulk edit merge requests at the project level + +Users with permission level of [Developer or higher](../../../permissions.md) can manage merge requests. + +When bulk editing merge requests in a project, you can edit the following attributes: + +- Status (open/closed) +- Assignee +- Milestone +- Labels +- Subscriptions + +To update multiple project merge requests at the same time: + +1. In a project, go to **Merge requests**. +1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with + editable fields. +1. Select the checkboxes next to each merge request you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. + +## Bulk edit merge requests at the group level + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12719) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. + +Users with permission level of [Developer or higher](../../../permissions.md) can manage merge requests. + +When bulk editing merge requests in a group, you can edit the following attributes: + +- Milestone +- Labels + +To update multiple group merge requests at the same time: + +1. In a group, go to **Merge requests**. +1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with + editable fields. +1. Select the checkboxes next to each merge request you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. + +## Review a merge request + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in GitLab Premium 11.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/28154) to GitLab Free in 13.1. + +When you review a merge request, you can create comments that are visible only +to you. When you're ready, you can publish them together in a single action. +To start your review: + +1. Go to the merge request you want to review, and select the **Changes** tab. + To learn more about navigating the diffs displayed in this tab, read + [Changes tab in merge requests](../changes.md). +1. Select a line of code. In GitLab version 13.2 and later, you can [highlight a set of lines](#comment-on-multiple-lines). +1. Write your first comment, and select **Start a review** below your comment: +  +1. Continue adding comments to lines of code, and select the appropriate button after + you write a comment: + - **Add to review**: Keep this comment private and add to the current review. + These review comments are marked **Pending** and are visible only to you. + - **Add comment now**: Submits the specific comment as a regular comment instead of as part of the review. +1. (Optional) You can use [quick actions](../../quick_actions.md) inside review comments. + The comment shows the actions to perform after publication, but does not perform them + until you submit your review. +1. When your review is complete, you can [submit the review](#submit-a-review). Your comments + are now visible, and any quick actions included your comments are performed. + +### Submit a review + +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. +- When creating a review comment, select **Submit review**. +- Scroll to the bottom of the screen and select **Submit review**. + +When you submit your review, GitLab: + +- Publishes the comments in your review. +- 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. + +### Resolving/Unresolving threads + +Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolvable-comments-and-threads). +When replying to a comment, a checkbox is displayed to resolve or unresolve +the thread after publication. + + + +If a particular pending comment resolves or unresolves the thread, this is shown on the pending +comment itself. + + + + + +### Adding a new comment + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8225) in GitLab 13.10. + +If you have a review in progress, you will be presented with the option to **Add to review**: + + + +## Semi-linear history merge requests + +A merge commit is created for every merge, but the branch is only merged if +a fast-forward merge is possible. This ensures that if the merge request build +succeeded, the target branch build also succeeds after the merge. + +1. Go to your project and select **Settings > General**. +1. Expand **Merge requests**. +1. In the **Merge method** section, select **Merge commit with semi-linear history**. +1. Select **Save changes**. + +## Perform inline code reviews + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13950) in GitLab 11.5. + +In a merge request, you can leave comments in any part of the file being changed. +In the merge request Diff UI, you can: + +- **Comment on a single line**: Select the **{comment}** **comment** icon in the + gutter to expand the diff lines and display a comment box. +- [**Comment on multiple lines**](#comment-on-multiple-lines). + +### Comment on multiple lines + +> - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49875) click-and-drag features in GitLab 13.8. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299121) in GitLab 13.9. + +When commenting on a diff, you can select which lines of code your comment refers +to by either: + + + +- Dragging the **{comment}** **comment** icon in the gutter to highlight + lines in the diff. GitLab expands the diff lines and displays a comment box. +- After starting a comment by selecting the **{comment}** **comment** icon in the + gutter, select the first line number your comment refers to in the **Commenting on lines** + select box. New comments default to single-line comments, unless you select + a different starting line. + +Multiline comments display the comment's line numbers above the body of the comment: + + + +## Pipeline status in merge requests widgets + +If you've set up [GitLab CI/CD](../../../../ci/README.md) in your project, +you can see: + +- Both pre-merge and post-merge pipelines and the environment information if any. +- Which deployments are in progress. + +If an application is successfully deployed to an +[environment](../../../../ci/environments/index.md), the deployed environment and the link to the +Review App are both shown. + +NOTE: +When the pipeline fails in a merge request but it can still be merged, +the **Merge** button is colored red. + +### Post-merge pipeline status + +When a merge request is merged, you can see the post-merge pipeline status of +the branch the merge request was merged into. For example, when a merge request +is merged into the [default branch](../../repository/branches/default.md) and then triggers a deployment to the staging +environment. + +Ongoing deployments are shown, and the state (deploying or deployed) +for environments. If it's the first time the branch is deployed, the link +returns a `404` error until done. During the deployment, the stop button is +disabled. If the pipeline fails to deploy, the deployment information is hidden. + + + +For more information, [read about pipelines](../../../../ci/pipelines/index.md). + +### Merge when pipeline succeeds (MWPS) + +Set a merge request that looks ready to merge to +[merge automatically when CI pipeline succeeds](../merge_when_pipeline_succeeds.md). + +### Live preview with Review Apps + +If you configured [Review Apps](https://about.gitlab.com/stages-devops-lifecycle/review-apps/) for your project, +you can preview the changes submitted to a feature branch through a merge request +on a per-branch basis. You don't need to checkout the branch, install, and preview locally. +All your changes are available to preview by anyone with the Review Apps link. + +With GitLab [Route Maps](../../../../ci/review_apps/index.md#route-maps) set, the +merge request widget takes you directly to the pages changed, making it easier and +faster to preview proposed modifications. + +[Read more about Review Apps](../../../../ci/review_apps/index.md). + +## Associated features + +These features are associated with merge requests: + +- [Bulk editing merge requests](../../../project/bulk_editing.md): + Update the attributes of multiple merge requests simultaneously. +- [Cherry-pick changes](../cherry_pick_changes.md): + Cherry-pick any commit in the UI by selecting the **Cherry-pick** button in a merged merge requests or a commit. +- [Fast-forward merge requests](../fast_forward_merge.md): + For a linear Git history and a way to accept merge requests without creating merge commits +- [Find the merge request that introduced a change](../versions.md): + When viewing the commit details page, GitLab links to the merge request(s) containing that commit. +- [Merge requests versions](../versions.md): + Select and compare the different versions of merge request diffs +- [Resolve conflicts](../resolve_conflicts.md): + GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. +- [Revert changes](../revert_changes.md): + Revert changes from any commit from a merge request. + +## Troubleshooting + +Sometimes things don't go as expected in a merge request. Here are some +troubleshooting steps. + +### Merge request cannot retrieve the pipeline status + +This can occur if Sidekiq doesn't pick up the changes fast enough. + +#### Sidekiq + +Sidekiq didn't process the CI state change fast enough. Please wait a few +seconds and the status should update automatically. + +#### Bug + +Merge request pipeline statuses can't be retrieved when the following occurs: + +1. A merge request is created +1. The merge request is closed +1. Changes are made in the project +1. The merge request is reopened + +To enable the pipeline status to be properly retrieved, close and reopen the +merge request again. + +## Tips + +Here are some tips to help you be more efficient with merge requests in +the command line. + +### Copy the branch name for local checkout + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23767) in GitLab 13.4. + +The merge request sidebar contains the branch reference for the source branch +used to contribute changes for this merge request. + +To copy the branch reference into your clipboard, select the **Copy branch name** button +(**{copy-to-clipboard}**) in the right sidebar. Use it to checkout the branch locally +from the command line by running `git checkout <branch-name>`. + +### Checkout merge requests locally through the `head` ref + +A merge request contains all the history from a repository, plus the additional +commits added to the branch associated with the merge request. Here's a few +ways to check out a merge request locally. + +You can check out a merge request locally even if the source +project is a fork (even a private fork) of the target project. + +This relies on the merge request `head` ref (`refs/merge-requests/:iid/head`) +that is available for each merge request. It allows checking out a merge +request by using its ID instead of its branch. + +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223156) in GitLab +13.4, 14 days after a merge request gets closed or merged, the merge request +`head` ref is deleted. This means that the merge request isn't available +for local checkout from the merge request `head` ref anymore. The merge request +can still be re-opened. If the merge request's branch +exists, you can still check out the branch, as it isn't affected. + +#### Checkout locally by adding a Git alias + +Add the following alias to your `~/.gitconfig`: + +```plaintext +[alias] + mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' - +``` + +Now you can check out a particular merge request from any repository and any +remote. For example, to check out the merge request with ID 5 as shown in GitLab +from the `origin` remote, do: + +```shell +git mr origin 5 +``` + +This fetches the merge request into a local `mr-origin-5` branch and check +it out. + +#### Checkout locally by modifying `.git/config` for a given repository + +Locate the section for your GitLab remote in the `.git/config` file. It looks +like this: + +```plaintext +[remote "origin"] + url = https://gitlab.com/gitlab-org/gitlab-foss.git + fetch = +refs/heads/*:refs/remotes/origin/* +``` + +You can open the file with: + +```shell +git config -e +``` + +Now add the following line to the above section: + +```plaintext +fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* +``` + +In the end, it should look like this: + +```plaintext +[remote "origin"] + url = https://gitlab.com/gitlab-org/gitlab-foss.git + fetch = +refs/heads/*:refs/remotes/origin/* + fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* +``` + +Now you can fetch all the merge requests: + +```shell +git fetch origin + +... +From https://gitlab.com/gitlab-org/gitlab-foss.git + * [new ref] refs/merge-requests/1/head -> origin/merge-requests/1 + * [new ref] refs/merge-requests/2/head -> origin/merge-requests/2 +... +``` + +And to check out a particular merge request: + +```shell +git checkout origin/merge-requests/1 +``` + +All the above can be done with the [`git-mr`](https://gitlab.com/glensc/git-mr) script. + +## Cached merge request count + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299542) in GitLab 13.11. +> - It's [deployed behind a feature flag](../../../feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-cached-merge-request-count). + +WARNING: +This feature might not be available to you. Refer to the previous **version history** note for details. + +In a group, the sidebar displays the total count of open merge requests. This value is cached if it's greater than +than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. + +### Enable or disable cached merge request count **(FREE SELF)** + +Cached merge request count in the left sidebar is under development but ready for production use. It is +deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../../administration/feature_flags.md) +can disable it. + +To disable it: + +```ruby +Feature.disable(:cached_sidebar_merge_requests_count) +``` + +To enable it: + +```ruby +Feature.enable(:cached_sidebar_merge_requests_count) +``` diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md new file mode 100644 index 00000000000..0c8dd384b88 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -0,0 +1,142 @@ +--- +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: index, reference +--- + +# Suggest changes **(FREE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18008) in GitLab 11.6. +> - Custom commit messages for suggestions was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9 behind a [feature flag](../../../feature_flags.md), disabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/297404) in GitLab 13.10. + +As a reviewer, you're able to suggest code changes with a Markdown syntax in merge request +diff threads. Then, the merge request author (or other users with appropriate +[permission](../../../permissions.md)) is able to apply these suggestions with a click, +which generates a commit in the merge request authored by the user that applied them. + +1. Choose a line of code to be changed, add a new comment, then select + the **Insert suggestion** icon in the toolbar: + +  + +1. In the comment, add your suggestion to the pre-populated code block: + +  + +1. Select either **Start a review** or **Add to review** to add your comment to a + [review](index.md), or **Add comment now** to add the comment to the thread immediately. + + The suggestion in the comment can be applied by the merge request author + directly from the merge request: + +  + +1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9, + you can opt to add a custom commit message to describe your change. If you don't + specify it, the default commit message is used. It is not supported for [batch suggestions](#batch-suggestions). + +  + +After the author applies a suggestion, it's marked with the **Applied** label, +the thread is automatically resolved, and GitLab creates a new commit +and pushes the suggested change directly into the codebase in the merge request's +branch. [Developer permission](../../../permissions.md) is required to do so. + +## Multi-line suggestions + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10. + +Reviewers can also suggest changes to multiple lines with a single suggestion +within merge request diff threads by adjusting the range offsets. The +offsets are relative to the position of the diff thread, and specify the +range to be replaced by the suggestion when it is applied. + + + +In the previous example, the suggestion covers three lines above and four lines +below the commented line. When applied, it would replace from 3 lines _above_ +to 4 lines _below_ the commented line, with the suggested change. + + + +NOTE: +Suggestions for multiple lines are limited to 100 lines _above_ and 100 +lines _below_ the commented diff line. This allows for up to 200 changed lines per +suggestion. + +## Code block nested in suggestions + +If you need to make a suggestion that involves a +[fenced code block](../../../markdown.md#code-spans-and-blocks), wrap your suggestion in four backticks +instead of the usual three. + + + + + +## Configure the commit message for applied suggestions + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13086) in GitLab 12.7. + +GitLab uses a default commit message +when applying suggestions: `Apply %{suggestions_count} suggestion(s) to %{files_count} file(s)` + +For example, consider that a user applied 3 suggestions to 2 different files, the +default commit message is: **Apply 3 suggestion(s) to 2 file(s)** + +These commit messages can be customized to follow any guidelines you might have. +To do so, expand the **Merge requests** tab within your project's **General** +settings and change the **Merge suggestions** text: + + + +You can also use following variables besides static text: + +| Variable | Description | Output example | +|------------------------|-------------|----------------| +| `%{branch_name}` | The name of the branch the suggestion(s) was(were) applied to. | `my-feature-branch` | +| `%{files_count}` | The number of file(s) to which suggestion(s) was(were) applied.| **2** | +| `%{file_paths}` | The path(s) of the file(s) suggestion(s) was(were) applied to. Paths are separated by commas.| `docs/index.md, docs/about.md` | +| `%{project_path}` | The project path. | `my-group/my-project` | +| `%{project_name}` | The human-readable name of the project. | **My Project** | +| `%{suggestions_count}` | The number of suggestions applied.| **3** | +| `%{username}` | The username of the user applying suggestion(s). | `user_1` | +| `%{user_full_name}` | The full name of the user applying suggestion(s). | **User 1** | + +For example, to customize the commit message to output +**Addresses user_1's review**, set the custom text to +`Addresses %{username}'s review`. + +NOTE: +Custom commit messages for each applied suggestion is +introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381). + +## Batch suggestions + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) behind a feature flag, disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. + +You can apply multiple suggestions at once to reduce the number of commits added +to your branch to address your reviewers' requests. + +1. To start a batch of suggestions to apply with a single commit, select **Add suggestion to batch**: + +  + +1. Add as many additional suggestions to the batch as you wish: + +  + +1. To remove suggestions, select **Remove from batch**: + +  + +1. Having added all the suggestions to your liking, when ready, select **Apply suggestions**: + +  + +WARNING: +Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions. diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 147171e8488..c25ee1a8a94 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -23,7 +23,7 @@ MR is merged. Collecting the coverage information is done via GitLab CI/CD's [artifacts reports feature](../../../ci/yaml/README.md#artifactsreports). You can specify one or more coverage reports to collect, including wildcard paths. -GitLab will then take the coverage information in all the files and combine it +GitLab then takes the coverage information in all the files and combines it together. For the coverage analysis to work, you have to provide a properly formatted @@ -41,24 +41,24 @@ Other coverage analysis frameworks support the format out of the box, for exampl - [Coverage.py](https://coverage.readthedocs.io/en/coverage-5.0.4/cmd.html#xml-reporting) (Python) Once configured, if you create a merge request that triggers a pipeline which collects -coverage reports, the coverage will be shown in the diff view. This includes reports -from any job in any stage in the pipeline. The coverage will be displayed for each line: +coverage reports, the coverage is shown in the diff view. This includes reports +from any job in any stage in the pipeline. The coverage displays for each line: - `covered` (green): lines which have been checked at least once by tests - `no test coverage` (orange): lines which are loaded but never executed - no coverage information: lines which are non-instrumented or not loaded -Hovering over the coverage bar will provide further information, such as the number +Hovering over the coverage bar provides further information, such as the number of times the line was checked by tests. NOTE: A limit of 100 `<source>` nodes for Cobertura format XML files applies. If your Cobertura report exceeds -100 nodes, there can be mismatches or no matches in the Merge Request diff view. +100 nodes, there can be mismatches or no matches in the merge request diff view. ### Artifact expiration By default, the [pipeline artifact](../../../ci/pipelines/pipeline_artifacts.md#storage) used -to draw the visualization on the Merge Request expires **one week** after creation. +to draw the visualization on the merge request expires **one week** after creation. ### Automatic class path correction @@ -69,8 +69,8 @@ For the coverage report to properly match the files displayed on a merge request must contain the full path relative to the project root. But in some coverage analysis frameworks, the generated Cobertura XML has the `filename` path relative to the class package directory instead. -To make an intelligent guess on the project root relative `class` path, the Cobertura XML parser will attempt to build the -full path by doing following: +To make an intelligent guess on the project root relative `class` path, the Cobertura XML parser attempts to build the +full path by doing the following: 1. Extract a portion of the `source` paths from the `sources` element and combine them with the class `filename` path. 1. Check if the candidate path exists in the project. @@ -82,6 +82,14 @@ to the project root: ```shell Auth/User.cs Lib/Utils/User.cs +src/main/java +``` + +In the Cobertura XML, the `filename` attribute in the `class` element assumes the value is a +relative path to project's root. + +```xml +<class name="packet.name" filename="src/main/java" line-rate="0.0" branch-rate="0.0" complexity="5"> ``` And the `sources` from Cobertura XML with paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`: @@ -93,16 +101,16 @@ And the `sources` from Cobertura XML with paths in the format of `<CI_BUILDS_DIR </sources> ``` -The parser will extract `Auth` and `Lib/Utils` from the sources and use these as basis to determine the class path relative to +The parser extracts `Auth` and `Lib/Utils` from the sources and use these as basis to determine the class path relative to the project root, combining these extracted sources and the class filename. -If for example there is a `class` element with the `filename` value of `User.cs`, the parser will take the first candidate path -that matches which is `Auth/User.cs`. +If for example there is a `class` element with the `filename` value of `User.cs`, the parser takes the first candidate path +that matches, which is `Auth/User.cs`. -For each `class` element, the parser will attempt to look for a match for each extracted `source` path up to `100` iterations. If it reaches this limit without finding a matching path in the file tree, the class will not be included in the final coverage report. +For each `class` element, the parser attempts to look for a match for each extracted `source` path up to `100` iterations. If it reaches this limit without finding a matching path in the file tree, the class will not be included in the final coverage report. NOTE: -The automatic class path correction only works on `source` paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`. If `source` will be ignored if the path does not follow this pattern. The parser will assume that +The automatic class path correction only works on `source` paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`. If `source` will be ignored if the path does not follow this pattern. The parser assumes that the `filename` of a `class` element contains the full path relative to the project root. ## Example test coverage configurations @@ -153,7 +161,7 @@ coverage-jdk11: stage: visualize image: registry.gitlab.com/haynes/jacoco2cobertura:1.0.7 script: - # convert report from jacoco to cobertura + # convert report from jacoco to cobertura, use relative project path - 'python /opt/cover2cover.py target/site/jacoco/jacoco.xml src/main/java > target/site/cobertura.xml' # read the <source></source> tag and prepend the path to every filename attribute - 'python /opt/source2filename.py target/site/cobertura.xml' @@ -193,7 +201,7 @@ coverage-jdk11: stage: visualize image: registry.gitlab.com/haynes/jacoco2cobertura:1.0.7 script: - # convert report from jacoco to cobertura + # convert report from jacoco to cobertura, use relative project path - 'python /opt/cover2cover.py build/jacoco/jacoco.xml src/main/java > build/cobertura.xml' # read the <source></source> tag and prepend the path to every filename attribute - 'python /opt/source2filename.py build/cobertura.xml' diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 2c77957c98d..676af4b2881 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -49,11 +49,11 @@ This only applies to commits that are in the most recent version of a merge request - if commits were in a merge request, then rebased out of that merge request, they aren't linked. -## `HEAD` comparison mode for Merge Requests +## `HEAD` comparison mode for merge requests > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27008) in GitLab 12.10. -Merge Requests, particularly the **Changes** tab, is where source code +Merge requests, particularly the **Changes** tab, is where source code is reviewed and discussed. In circumstances where the target branch was merged into the source branch of the merge request, the changes in the source and target branch can be shown mixed together making it hard to diff --git a/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png b/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png Binary files differindex a865221c5d7..ffe1328b7d3 100644 --- a/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png +++ b/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png diff --git a/doc/user/project/milestones/img/milestones_project_milestone_page.png b/doc/user/project/milestones/img/milestones_project_milestone_page.png Binary files differdeleted file mode 100644 index 1faaf0b3979..00000000000 --- a/doc/user/project/milestones/img/milestones_project_milestone_page.png +++ /dev/null diff --git a/doc/user/project/milestones/img/milestones_project_milestone_page_sidebar_v13_11.png b/doc/user/project/milestones/img/milestones_project_milestone_page_sidebar_v13_11.png Binary files differnew file mode 100644 index 00000000000..3bdec8e219a --- /dev/null +++ b/doc/user/project/milestones/img/milestones_project_milestone_page_sidebar_v13_11.png diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index fe34dca4959..2399774c96d 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -38,7 +38,7 @@ You can assign **group milestones** to any issue or merge request of any project To view the group milestone list, in a group, go to **{issues}** **Issues > Milestones**. You can also view all milestones you have access to in the dashboard milestones list. -To view both project milestones and group milestones you have access to, click **More > Milestones** +To view both project milestones and group milestones you have access to, select **More > Milestones** on the top navigation bar. For information about project and group milestones API, see: @@ -47,9 +47,9 @@ For information about project and group milestones API, see: - [Group Milestones API](../../../api/group_milestones.md) NOTE: -If you're in a group and click **Issues > Milestones**, GitLab displays group milestones +If you're in a group and select **Issues > Milestones**, GitLab displays group milestones and the milestones of projects in this group. -If you're in a project and click **Issues > Milestones**, GitLab displays only this project's milestones. +If you're in a project and select **Issues > Milestones**, GitLab displays only this project's milestones. ## Creating milestones @@ -58,23 +58,23 @@ A permission level of [Developer or higher](../../permissions.md) is required to ### New project milestone -To create a **project milestone**: +To create a project milestone: 1. In a project, go to **{issues}** **Issues > Milestones**. -1. Click **New milestone**. +1. Select **New milestone**. 1. Enter the title, an optional description, an optional start date, and an optional due date. -1. Click **New milestone**. +1. Select **New milestone**.  ### New group milestone -To create a **group milestone**: +To create a group milestone: 1. In a group, go to **{issues}** **Issues > Milestones**. -1. Click **New milestone**. +1. Select **New milestone**. 1. Enter the title, an optional description, an optional start date, and an optional due date. -1. Click **New milestone**. +1. Select **New milestone**.  @@ -86,10 +86,10 @@ A permission level of [Developer or higher](../../permissions.md) is required to To edit a milestone: 1. In a project or group, go to **{issues}** **Issues > Milestones**. -1. Click a milestone's title. -1. Click **Edit**. +1. Select a milestone's title. +1. Select **Edit**. -You can delete a milestone by clicking the **Delete** button. +You can delete a milestone by selecting the **Delete** button. ### Promoting project milestones to group milestones @@ -182,7 +182,7 @@ The milestone sidebar on the milestone view shows the following: - 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 diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 3c3de26d7dd..18acb360f5a 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -129,7 +129,7 @@ See this document for a [step-by-step guide](getting_started/pages_from_scratch. Remember that GitLab Pages are by default branch/tag agnostic and their deployment relies solely on what you specify in `.gitlab-ci.yml`. You can limit -the `pages` job with the [`only` parameter](../../../ci/yaml/README.md#onlyexcept-basic), +the `pages` job with the [`only` parameter](../../../ci/yaml/README.md#only--except), whenever a new commit is pushed to a branch used specifically for your pages. @@ -273,6 +273,10 @@ Sure. All you need to do is download the artifacts archive from the job page. Yes. GitLab Pages doesn't care whether you set your project's visibility level to private, internal or public. +### Can I create a personal or a group website + +Yes. See the documentation about [GitLab Pages domain names, URLs, and base URLs](getting_started_part_one.md). + ### Do I need to create a user/group website before creating a project website? No, you don't. You can create your project first and access it under @@ -297,3 +301,27 @@ Files listed under the public directory can be accessed through the Pages URL fo A 404 can also be related to incorrect permissions. If [Pages Access Control](pages_access_control.md) is enabled, and a user navigates to the Pages URL and receives a 404 response, it is possible that the user does not have permission to view the site. To fix this, verify that the user is a member of the project. + +For Geo instances, 404 errors on Pages occur after promoting a secondary to a primary. +Find more details in the [Pages administration documentation](../../../administration/pages/index.md#404-error-after-promoting-a-geo-secondary-to-a-primary-node) + +### Cannot play media content on Safari + +Safari requires the web server to support the [Range request header](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/CreatingVideoforSafarioniPhone/CreatingVideoforSafarioniPhone.html#//apple_ref/doc/uid/TP40006514-SW6) +in order to play your media content. For GitLab Pages to serve +HTTP Range requests, you should use the following two variables in your `.gitlab-ci.yaml` file: + +```yaml +pages: + stage: deploy + variables: + FF_USE_FASTZIP: "true" + ARTIFACT_COMPRESSION_LEVEL: "fastest" + script: + - echo "Deploying pages" + artifacts: + paths: + - public +``` + +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/README.md#artifact-and-cache-settings). diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index c66f9038ed2..673a756f18d 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -7,46 +7,45 @@ type: reference, howto # Protected branches **(FREE)** -[Permissions](../permissions.md) in GitLab are fundamentally defined around the +In GitLab, [permissions](../permissions.md) are fundamentally defined around the idea of having read or write permission to the repository and branches. To impose further restrictions on certain branches, they can be protected. -## Overview +The default branch for your repository is protected by default. -By default, a protected branch does these things: +## Who can access a protected branch -- It prevents its creation, if not already created, from everybody except users - with Maintainer permission. -- It prevents pushes from everybody except users with **Allowed** permission. -- It prevents **anyone** from force pushing to the branch. -- It prevents **anyone** from deleting the branch. +When a branch is protected, the default behavior enforces +these restrictions on the branch. -**Permissions:** +| Action | Who can do it | +|--------------------------|---------------| +| Protect a branch | Maintainers only. | +| Push to the branch | GitLab administrators and anyone with **Allowed** permission. (*) | +| Force push to the branch | No one. | +| Delete the branch | No one. | -- GitLab administrators are allowed to push to the protected branches. -- Users with [Developer permissions](../permissions.md) are allowed to - create a project in a group, but might not be allowed to initially - push to the [default branch](repository/branches/default.md). +(*) Users with developer permissions can create a project in a group, +but might not be allowed to initially push to the [default branch](repository/branches/default.md). -The default branch protection level is set in the [Admin Area](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection). +### Set the branch protection default level -See the [Changelog](#changelog) section for changes over time. +The default branch protection level is set in the [Admin Area](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection). -## Configuring protected branches +## Configure a protected branch -To protect a branch, you need to have at least Maintainer permission level. -The default branch for your repository is protected by default. +Prerequisite: -1. In your project, go to **Settings > Repository**. -1. Scroll to find the **Protected branches** section. -1. From the **Branch** dropdown menu, select the branch you want to protect and - click **Protect**. In the screenshot below, we chose the `develop` branch. +- You must have at least maintainer permissions. -  +To protect a branch: -1. Once done, the protected branch displays in the **Protected branches** list. +1. Go to your project and select **Settings > Repository**. +1. Expand **Protected branches**. +1. From the **Branch** dropdown menu, select the branch you want to protect. +1. Select **Protect**. -  +The protected branch displays in the **Protected branches** list. ## Using the Allowed to merge and Allowed to push settings @@ -141,7 +140,7 @@ all matching branches:  -## Creating a protected branch +## Create a protected branch > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) in GitLab 11.9. @@ -161,7 +160,7 @@ To create a new branch through the user interface: base the new branch on. Only existing protected branches and commits that are already in protected branches are accepted. -## Deleting a protected branch +## Delete a protected branch From time to time, you may need to delete or clean up protected branches. User with [Maintainer permissions](../permissions.md) and greater can manually delete protected diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 3c5cc668986..728c682b009 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -68,8 +68,8 @@ time as pushing changes: | `merge_request.description="<description>"` | Set the description of the merge request. Ex: `git push -o merge_request.description="The description I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/64320) | | `merge_request.label="<label>"` | Add labels to the merge request. If the label does not exist, it is created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | | `merge_request.unlabel="<label>"` | Remove labels from the merge request. For example, for two labels: `git push -o merge_request.unlabel="label1" -o merge_request.unlabel="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31831) | -| `merge_request.assign="<user>"` | Assign users to the merge request. For example, for two users: `git push -o merge_request.assign="user1" -o merge_request.assign="user2"`. | [12.9](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/XXXXX) | -| `merge_request.unassign="<user>"` | Remove assigned users from the merge request. For example, for two users: `git push -o merge_request.unassign="user1" -o merge_request.unassign="user2"`. | [12.9](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/XXXXX) | +| `merge_request.assign="<user>"` | Assign users to the merge request. For example, for two users: `git push -o merge_request.assign="user1" -o merge_request.assign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904) | +| `merge_request.unassign="<user>"` | Remove assigned users from the merge request. For example, for two users: `git push -o merge_request.unassign="user1" -o merge_request.unassign="user2"`. | [13.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25904) | If you use a push option that requires text with spaces in it, you need to enclose it in quotes (`"`). You can omit the quotes if there are no spaces. Some examples: diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 06ad71713d7..1ea21b1f269 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -86,7 +86,7 @@ by using a `release` node in the job definition. The release is created only if the job processes without error. If the Rails API returns an error during release creation, the release job fails. -### Schedule a future release +### Upcoming releases > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38105) in GitLab 12.1. @@ -271,10 +271,15 @@ Release note descriptions are unrelated. Description supports [Markdown](../../m ### Release assets -You can add the following types of assets to each release: +A release contains the following types of assets: - [Source code](#source-code) -- [Links](#links) +- [Permanent links to release assets](#permanent-links-to-release-assets) + +#### Source code + +GitLab automatically generates `zip`, `tar.gz`, `tar.bz2`, and `tar` +archived source code from the given Git tag. These are read-only assets. #### Permanent links to release assets @@ -285,9 +290,21 @@ GitLab always redirects this URL to the actual asset location, so even if the assets move to a different location, you can continue to use the same URL. This is defined during [link creation](../../../api/releases/links.md#create-a-link) or [updating](../../../api/releases/links.md#update-a-link). -Each asset has a name, a URL of the *actual* asset location, and optionally, a -`filepath` parameter, which, if you specify it, creates a URL pointing -to the asset for the Release. The format of the URL is: +Each asset has a `name`, a `url` of the *actual* asset location, and optionally, +`filepath` and `link_type` parameters. + +A `filepath` creates a URL pointing to the asset for the Release. + +The `link_type` parameter accepts one of the following four values: + +- `runbook` +- `package` +- `image` +- `other` (default) + +This field has no effect on the URL and it's only used for visual purposes in the Releases page of your project. + +The format of the URL is: ```plaintext https://host/namespace/project/releases/:release/downloads/:filepath @@ -300,7 +317,8 @@ namespace and `gitlab-runner` project on `gitlab.com`, for example: { "name": "linux amd64", "filepath": "/binaries/gitlab-runner-linux-amd64", - "url": "https://gitlab-runner-downloads.s3.amazonaws.com/v11.9.0-rc2/binaries/gitlab-runner-linux-amd64" + "url": "https://gitlab-runner-downloads.s3.amazonaws.com/v11.9.0-rc2/binaries/gitlab-runner-linux-amd64", + "link_type": "other" } ``` @@ -312,11 +330,6 @@ https://gitlab.com/gitlab-org/gitlab-runner/releases/v11.9.0-rc2/downloads/binar The physical location of the asset can change at any time and the direct link remains unchanged. -### Source code - -GitLab automatically generates `zip`, `tar.gz`, `tar.bz2` and `tar` -archived source code from the given Git tag. These are read-only assets. - ### Links A link is any URL which can point to whatever you like: documentation, built diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index 1363d883e76..deacf119d38 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: concepts, howto --- -# Default branch +# Default branch **(FREE)** When you create a new [project](../../index.md), GitLab creates a default branch in the repository. A default branch has special configuration options not shared @@ -60,7 +60,6 @@ GitLab administrators can configure a new default branch name at the > - It's deployed behind a feature flag, enabled by default. > - It cannot be enabled or disabled per-project. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-custom-initial-branch-name). GitLab [administrators](../../../permissions.md) of self-managed instances can customize the initial branch for projects hosted on that instance. Individual @@ -75,26 +74,7 @@ Projects created on this instance after you change the setting use the custom branch name, unless a group-level or subgroup-level configuration overrides it. -#### Enable or disable custom initial branch name **(FREE SELF)** - -Setting the default initial branch name is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../../administration/feature_flags.md) -can opt to disable it for your instance. - -To disable it: - -```ruby -Feature.disable(:global_default_branch_name) -``` - -To enable it: - -```ruby -Feature.enable(:global_default_branch_name) -``` - -### Group-level custom initial branch name **(FREE)** +### Group-level custom initial branch name > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221014) in GitLab 13.6. diff --git a/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png b/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png Binary files differdeleted file mode 100644 index fdda3858c3b..00000000000 --- a/doc/user/project/repository/branches/img/branch_filter_search_box_v13_10.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/branch_filter_search_box_v13_12.png b/doc/user/project/repository/branches/img/branch_filter_search_box_v13_12.png Binary files differnew file mode 100644 index 00000000000..a1cf9f10122 --- /dev/null +++ b/doc/user/project/repository/branches/img/branch_filter_search_box_v13_12.png diff --git a/doc/user/project/repository/branches/img/compare_branches_v13_10.png b/doc/user/project/repository/branches/img/compare_branches_v13_10.png Binary files differdeleted file mode 100644 index 2b9a5751938..00000000000 --- a/doc/user/project/repository/branches/img/compare_branches_v13_10.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/compare_branches_v13_12.png b/doc/user/project/repository/branches/img/compare_branches_v13_12.png Binary files differnew file mode 100644 index 00000000000..29627406729 --- /dev/null +++ b/doc/user/project/repository/branches/img/compare_branches_v13_12.png diff --git a/doc/user/project/repository/branches/img/repository_filter_search_box_v13_10.png b/doc/user/project/repository/branches/img/repository_filter_search_box_v13_10.png Binary files differdeleted file mode 100644 index fdda3858c3b..00000000000 --- a/doc/user/project/repository/branches/img/repository_filter_search_box_v13_10.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/repository_filter_search_box_v13_12.png b/doc/user/project/repository/branches/img/repository_filter_search_box_v13_12.png Binary files differnew file mode 100644 index 00000000000..230abf0d875 --- /dev/null +++ b/doc/user/project/repository/branches/img/repository_filter_search_box_v13_12.png diff --git a/doc/user/project/repository/branches/img/swap_revisions_after_v13_12.png b/doc/user/project/repository/branches/img/swap_revisions_after_v13_12.png Binary files differnew file mode 100644 index 00000000000..7eb10d10938 --- /dev/null +++ b/doc/user/project/repository/branches/img/swap_revisions_after_v13_12.png diff --git a/doc/user/project/repository/branches/img/swap_revisions_before_v13_12.png b/doc/user/project/repository/branches/img/swap_revisions_before_v13_12.png Binary files differnew file mode 100644 index 00000000000..f92c4279871 --- /dev/null +++ b/doc/user/project/repository/branches/img/swap_revisions_before_v13_12.png diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index f2562ef89e3..91858ff9a65 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -19,7 +19,7 @@ After pushing your changes to a new branch, you can: - [Discuss](../../../discussions/index.md) your implementation with your team - Preview changes submitted to a new branch with [Review Apps](../../../../ci/review_apps/index.md). -You can also request [approval](../../merge_requests/merge_request_approvals.md) +You can also request [approval](../../merge_requests/approvals/index.md) from your managers. For more information on managing branches using the GitLab UI, see: @@ -40,7 +40,7 @@ You can also manage branches using the See also: - [Branches API](../../../../api/branches.md), for information on operating on repository branches using the GitLab API. -- [GitLab Flow](../../../../university/training/gitlab_flow.md) documentation. +- [GitLab Flow](../../../../topics/gitlab_flow.md) documentation. - [Getting started with Git](../../../../topics/git/index.md) and GitLab. ## Compare @@ -53,7 +53,7 @@ To compare branches in a repository: 1. Select branches to compare using the [branch filter search box](#branch-filter-search-box). 1. Click **Compare** to view the changes inline: -  +  ## Delete merged branches @@ -74,7 +74,7 @@ automatically when a merge request was merged. This feature allows you to search and select a repository quickly when [comparing branches](#compare). - + Search results appear in the following order: @@ -85,7 +85,7 @@ Search results appear in the following order: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22166) in GitLab 11.5. - + This feature allows you to search and select branches quickly. Search results appear in the following order: @@ -97,6 +97,16 @@ Sometimes when you have hundreds of branches you may want a more flexible matchi - `^feature` matches only branch names that begin with 'feature'. - `feature$` matches only branch names that end with 'feature'. +## Swap revisions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60491) in GitLab 13.12. + + + +The Swap revisions feature allows you to swap the Source and Target revisions. When the Swap revisions button is clicked, the selected revisions for Source and Target will be swapped. + + + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png b/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png Binary files differdeleted file mode 100644 index f48cf176ba1..00000000000 --- a/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_2.png +++ /dev/null diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 70c5ef63dd4..ed5bcc1f85a 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -208,7 +208,7 @@ The repository graph displays the history of the repository network visually, in Find it under your project's **Repository > Graph**. -## Repository Languages +## Repository languages For the default branch of each repository, GitLab determines what programming languages were used and displays this on the project's pages. If this information is missing, it's @@ -226,6 +226,10 @@ detected, add the following to `.gitattributes` in the root of your repository. *.proto linguist-detectable=true ``` +Sometimes this feature can use excessive CPU. +[Read about troubleshooting this](#repository-languages-excessive-cpu-use) +and also more about customizing this feature using `.gitattributes`. + ## Locked files **(PREMIUM)** Use [File Locking](../file_lock.md) to @@ -268,7 +272,7 @@ All projects can be cloned into Visual Studio Code. To do that: When VS Code has successfully cloned your project, it opens the folder. -## Download Source Code +## Download source code > - Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/24704) in GitLab 11.11. > - Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. @@ -310,14 +314,40 @@ When [renaming a user](../../profile/index.md#change-your-username), - The redirects are available as long as the original path is not claimed by another group, user or project. -<!-- ## Troubleshooting +## Troubleshooting + +### Repository Languages: excessive CPU use + +GitLab uses a Ruby gem to scan all the files in the repository to determine what languages are used. +[Sometimes this can use excessive CPU](https://gitlab.com/gitlab-org/gitaly/-/issues/1565) if +a file type needs to be parsed by the gem to determine what sort of file it is. +The gem contains a [heuristics configuration file](https://github.com/github/linguist/blob/master/lib/linguist/heuristics.yml) +that defines what file extensions need to be parsed. + +Excessive CPU use has been reported for files with the extension `.txt` and XML files with +a file extension that is not defined by the gem. + +The workaround is to specify what language to assign to specific file extensions. +The same approach should also allow misidentified file types to be fixed. + +1. Identify which language to specify. The gem contains a [configuration file for known data types](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml). + The entry for `Text` files, for example: + + ```yaml + Text: + type: prose + wrap: true + aliases: + - fundamental + - plain text + extensions: + - ".txt" + ``` + +1. Add or modify `.gitattributes` in the root of your repository: -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. + ```plaintext + *.txt linguist-language=Text + ``` -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. --> + `*.txt` files have an entry in the heuristics file. The example above prevents parsing of these files. diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 980c5417da6..3bbe9e6cb66 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -22,7 +22,7 @@ There are two kinds of repository mirroring supported by GitLab: When the mirror repository is updated, all new branches, tags, and commits are visible in the project's activity feed. -Users with at least [Developer access](../../permissions.md) to the project can also force an +Users with [Maintainer access](../../permissions.md) to the project can also force an immediate update, unless: - The mirror is already being updated. @@ -65,7 +65,10 @@ For an existing project, you can set up push mirroring as follows:  When push mirroring is enabled, only push commits directly to the mirrored repository to prevent the -mirror diverging. The mirrored repository receives all changes when: +mirror diverging. + +Unlike [pull mirroring](#how-it-works), the mirrored repository is not periodically auto-synced. +The mirrored repository receives all changes only when: - Commits are pushed to GitLab. - A [forced update](#forcing-an-update) is initiated. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index b6bde46b26a..4e8e3f1bbce 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -58,6 +58,9 @@ to display, add a file to your repository. ## Highlight lines +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56159) in GitLab 13.10 for GitLab SaaS instances. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56159) in GitLab 13.11 for self-managed instances. + Web Editor enables you to highlight a single line by adding specially formatted hash information to the URL's file path segment. For example, the file path segment `MY_FILE.js#L3` instructs the Web Editor to highlight line 3. diff --git a/doc/user/project/requirements/img/requirements_archived_list_view_v13_1.png b/doc/user/project/requirements/img/requirements_archived_list_view_v13_1.png Binary files differindex 04cb011ff89..f839a391074 100644 --- a/doc/user/project/requirements/img/requirements_archived_list_view_v13_1.png +++ b/doc/user/project/requirements/img/requirements_archived_list_view_v13_1.png diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 6fa1b0aa368..f5fa6e37d1c 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -37,26 +37,34 @@ Note the following: for how you can export a project through the UI. - Imports from a newer version of GitLab are not supported. The Importing GitLab version must be greater than or equal to the Exporting GitLab version. -- Imports will fail unless the import and export GitLab instances are +- Imports fail unless the import and export GitLab instances are compatible as described in the [Version history](#version-history). -- Exports are generated in your configured `shared_path`, a temporary [shared directory](../../../development/shared_files.md) +- Exports are generated in your configured `shared_path`, a temporary shared directory, and are moved to your configured `uploads_directory`. Every 24 hours, a specific worker deletes these export files. - Group members are exported as project members, as long as the user has maintainer or administrator access to the group where the exported project lives. -- Project members with owner access will be imported as maintainers. +- Project members with owner access are imported as maintainers. - Imported users can be mapped by their primary email on self-managed instances, if an administrative user (not an owner) does the import. Otherwise, a supplementary comment is left to mention that the original author and - the MRs, notes, or issues will be owned by the importer. + the MRs, notes, or issues are owned by the importer. + - For project migration imports performed over GitLab.com Groups, preserving author information is + possible through a [professional services engagement](https://about.gitlab.com/services/migration/). - If an imported project contains merge requests originating from forks, - then new branches associated with such merge requests will be created + then new branches associated with such merge requests are created within a project during the import/export. Thus, the number of branches in the exported project could be bigger than in the original project. - Deploy keys allowed to push to protected branches are not exported. Therefore, - you will need to recreate this association by first enabling these deploy keys in your + you need to recreate this association by first enabling these deploy keys in your imported project and then updating your protected branches accordingly. ## Version history +### 14.0+ + +In GitLab 14.0, the JSON format is no longer supported for project and group exports. To allow for a +transitional period, you can still import any JSON exports. The new format for imports and exports +is NDJSON. + ### 13.0+ Starting with GitLab 13.0, GitLab can import bundles that were exported from a different GitLab deployment. @@ -95,7 +103,7 @@ Prior to 13.0 this was a defined compatibility table: Projects can be exported and imported only between versions of GitLab with matching Import/Export versions. For example, 8.10.3 and 8.11 have the same Import/Export version (0.1.3) -and the exports between them will be compatible. +and the exports between them are compatible. ## Between CE and EE @@ -106,7 +114,7 @@ If you're exporting a project from the Enterprise Edition to the Community Editi ## Exported contents -The following items will be exported: +The following items are exported: - Project and wiki repositories - Project uploads @@ -120,7 +128,7 @@ The following items will be exported: - Push Rules - Awards -The following items will **not** be exported: +The following items are **not** exported: - Build traces and artifacts - Container registry images @@ -171,7 +179,7 @@ To export a project and its data, follow these steps:  1. Click on **Import project** to begin importing. Your newly imported project - page will appear soon. + page appears shortly. NOTE: If use of the `Internal` visibility level diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 6d37d26f6e8..d3177aa7585 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -32,38 +32,19 @@ Adjust your project's name, description, avatar, [default branch](../repository/ The project description also partially supports [standard Markdown](../../markdown.md#standard-markdown-and-extensions-in-gitlab). You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and [line-breaks](../../markdown.md#line-breaks) to add more context to the project description. -#### Compliance framework **(PREMIUM)** - -You can select a framework label to identify that your project has certain compliance requirements or needs additional oversight. Available labels include: - -- GDPR (General Data Protection Regulation) -- HIPAA (Health Insurance Portability and Accountability Act) -- PCI-DSS (Payment Card Industry-Data Security Standard) -- SOC 2 (Service Organization Control 2) -- SOX (Sarbanes-Oxley) - -NOTE: -Compliance framework labels do not affect your project settings. - -#### Custom compliance frameworks +#### Compliance frameworks **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9. -> - [Deployed behind a feature flag](../../feature_flags.md). -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287779) in GitLab 13.11. -> - Enabled on GitLab.com. -> - Recommended for production use. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/287779) in GitLab 13.12. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +You can create a framework label to identify that your project has certain compliance requirements or needs additional oversight. -GitLab 13.9 introduces custom compliance frameworks at the group-level. A group owner can create a compliance framework label -and assign it to any number of projects within that group or subgroups. When this feature is enabled, projects can only -be assigned compliance framework labels that already exist within that group. +Group owners can create, edit and delete compliance frameworks by going to **Settings** > **General** and expanding the **Compliance frameworks** section. +Compliance frameworks created can then be assigned to any number of projects via the project settings page inside the group or subgroups. -If existing [Compliance frameworks](#compliance-framework) are not sufficient, project and group owners -can now create their own. - -New compliance framework labels can be created and updated using GraphQL. +NOTE: +Attempting to create compliance frameworks on subgroups via GraphQL will cause the framework to be created on the root ancestor if the user has the correct permissions. +The web UI presents a read-only view to discourage this behavior. #### Compliance pipeline configuration **(ULTIMATE)** @@ -79,7 +60,7 @@ This feature might not be available to you. Check the **version history** note a Group owners can use the compliance pipeline configuration to define compliance requirements such as scans or tests, and enforce them in individual projects. -The [custom compliance framework](#custom-compliance-frameworks) feature allows group owners to specify the location +The [custom compliance framework](#compliance-frameworks) feature allows group owners to specify the location of a compliance pipeline configuration stored and managed in a dedicated project, distinct from a developer's project. When you set up the compliance pipeline configuration field, use the @@ -96,7 +77,9 @@ The user running the pipeline in the project should at least have Reporter acces Example `.compliance-gitlab-ci.yml` ```yaml -stages: # Allows compliance team to control the ordering and interweaving of stages/jobs +# Allows compliance team to control the ordering and interweaving of stages/jobs. +# Stages without jobs defined will remain hidden. +stages: - pre-compliance - build - test @@ -209,11 +192,12 @@ Set up your project's merge request settings: - Set up the merge request method (merge commit, [fast-forward merge](../merge_requests/fast_forward_merge.md)). - Add merge request [description templates](../description_templates.md#description-templates). -- Enable [merge request approvals](../merge_requests/merge_request_approvals.md). +- Enable [merge request approvals](../merge_requests/approvals/index.md). - Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). - Enable [merge only when all threads are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved). -- Enable [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch) -- Configure [suggested changes commit messages](../../discussions/index.md#configure-the-commit-message-for-applied-suggestions) +- Enable [require an associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). +- Enable [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch). +- Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). - Configure [the default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. ### Service Desk @@ -375,6 +359,24 @@ to remove a fork relationship. ## Operations settings +### Alerts + +Configure [alert integrations](../../../operations/incident_management/integrations.md#configuration) to triage and manage critical problems in your application as [alerts](../../../operations/incident_management/alerts.md). + +### Incidents + +#### Alert integration + +Automatically [create](../../../operations/incident_management/incidents.md#create-incidents-automatically), [notify on](../../../operations/incident_management/paging.md#email-notifications), and [resolve](../../../operations/incident_management/incidents.md#automatically-close-incidents-via-recovery-alerts) incidents based on GitLab alerts. + +#### PagerDuty integration + +[Create incidents in GitLab for each PagerDuty incident](../../../operations/incident_management/incidents.md#create-incidents-via-the-pagerduty-webhook). + +#### Incident settings + +[Manage Service Level Agreements for incidents](../../../operations/incident_management/incidents.md#service-level-agreement-countdown-timer) with an SLA countdown timer. + ### Error Tracking Configure Error Tracking to discover and view [Sentry errors within GitLab](../../../operations/error_tracking.md). @@ -387,22 +389,3 @@ Add the URL of a Jaeger server to allow your users to [easily access the Jaeger [Add Storage credentials](../../../operations/incident_management/status_page.md#sync-incidents-to-the-status-page) to enable the syncing of public Issues to a [deployed status page](../../../operations/incident_management/status_page.md#create-a-status-page-project). - -### Enable or disable custom compliance frameworks **(PREMIUM)** - -Enabling or disabling custom compliance frameworks is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:ff_custom_compliance_frameworks, Group.find(<group id>)) -``` - -To disable it: - -```ruby -Feature.disable(:ff_custom_compliance_frameworks, Group.find(<group id>)) -``` diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 78e7ded9784..df76c4682f3 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -20,13 +20,14 @@ Time Tracking allows you to: - Record the time spent working on an issue or a merge request. - Add an estimate of the amount of time needed to complete an issue or a merge request. +- View a breakdown of time spent working on an issue or a merge request. You don't have to indicate an estimate to enter the time spent, and vice versa. Data about time tracking is shown on the issue/merge request sidebar, as shown below. - + ## How to enter data @@ -56,7 +57,7 @@ To remove an estimation entirely, use `/remove_estimate`. ### Time spent -To enter time spent, write `/spend`, followed by the time. For example, if you need +To enter time spent, write `/spend`, followed by the time. For example, if you need to log 1 month, 2 weeks, 3 days, 4 hours and 5 minutes, you would write `/spend 1mo 2w 3d 4h 5m`. Time units that we support are listed at the bottom of this help page. @@ -68,13 +69,26 @@ days from the total time spent. You can't go below 0 minutes of time spent, so GitLab automatically resets the time spent if you remove a larger amount of time compared to the time that was entered already. -You can log time in the past by providing a date after the time. +You can log time in the past by providing a date after the time. For example, if you want to log 1 hour of time spent on the 31 January 2021, you would write `/spend 1h 2021-01-31`. If you supply a date in the future, the command fails and no time is logged. To remove all the time spent at once, use `/remove_time_spent`. +## View a time tracking report + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271409) in GitLab 13.12. + +You can view a breakdown of time spent on an issue or merge request. + +To view a time tracking report, go to an issue or a merge request and select **Time tracking report** +in the right sidebar. + + + +The breakdown of spent time is limited to a maximum of 100 entries. + ## Configuration The following time units are available: @@ -98,4 +112,9 @@ With this option enabled, `75h` is displayed instead of `1w 4d 3h`. ## Other interesting links -- [Time Tracking landing page in the GitLab handbook](https://about.gitlab.com/solutions/time-tracking/) +- [Time Tracking solutions page](https://about.gitlab.com/solutions/time-tracking/) +- Time Tracking GraphQL references: + - [Connection](../../api/graphql/reference/index.md#timelogconnection) + - [Edge](../../api/graphql/reference/index.md#timelogedge) + - [Fields](../../api/graphql/reference/index.md#timelog) + - [Group Timelogs](../../api/graphql/reference/index.md#grouptimelogs) diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index a69141ac04d..22915efef94 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -182,6 +182,8 @@ GitLab tracks wiki creation, deletion, and update events. These events are displ [group](../../group/index.md#view-group-activity), and [project](../working_with_projects.md#project-activity) activity pages. +Commits to wikis are not counted in [repository analytics](../../analytics/repository_analytics.md). + ## Customize sidebar > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by selecting the **Edit sidebar** button. diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 43df1cce70f..ddca0b64f81 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -41,7 +41,8 @@ For a list of words that can't be used as project names see To create a new blank project on the **New project** page: -1. On the **Blank project** tab, provide the following information: +1. Click **Create blank project** +1. Provide the following information: - The name of your project in the **Project name** field. You can't use special characters, but you can use spaces, hyphens, underscores, or even emoji. When adding the name, the **Project slug** auto populates. @@ -86,7 +87,8 @@ Built-in templates are project templates that are: To use a built-in template on the **New project** page: -1. On the **Create from template** tab, select the **Built-in** tab. +1. Click **Create from template** +1. Select the **Built-in** tab. 1. From the list of available built-in templates, click the: - **Preview** button to look at the template source itself. - **Use template** button to start creating the project. @@ -99,7 +101,8 @@ GitLab is developing Enterprise templates to help you streamline audit managemen To create a new project with an Enterprise template, on the **New project** page: -1. On the **Create from template** tab, select the **Built-in** tab. +1. Click **Create from template** +1. Select the **Built-in** tab. 1. From the list of available built-in Enterprise templates, click the: - **Preview** button to look at the template source itself. - **Use template** button to start creating the project. @@ -123,11 +126,12 @@ quickly starting projects. Custom projects are available at the [instance-level](../../user/admin_area/custom_project_templates.md) from the **Instance** tab, or at the [group-level](../../user/group/custom_project_templates.md) -from the **Group** tab, under the **Create from template** tab. +from the **Group** tab, on the **Create from template** page. To use a custom project template on the **New project** page: -1. On the **Create from template** tab, select the **Instance** tab or the **Group** tab. +1. Click **Create from template** +1. Select the **Instance** tab or the **Group** tab. 1. From the list of available custom templates, click the: - **Preview** button to look at the template source itself. - **Use template** button to start creating the project. diff --git a/doc/user/report_abuse.md b/doc/user/report_abuse.md new file mode 100644 index 00000000000..2b585315326 --- /dev/null +++ b/doc/user/report_abuse.md @@ -0,0 +1,68 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Report abuse **(FREE)** + +You can report abuse from other GitLab users to GitLab administrators. + +A GitLab administrator [can then choose](admin_area/review_abuse_reports.md) to: + +- Remove the user, which deletes them from the instance. +- Block the user, which denies them access to the instance. +- Or remove the report, which retains the user's access to the instance. + +You can report a user through their: + +- [Profile](#reporting-abuse-through-a-users-profile) +- [Comments](#reporting-abuse-through-a-users-comment) +- [Issues and Merge requests](#reporting-abuse-through-a-users-issue-or-merge-request) + +## Reporting abuse through a user's profile + +To report abuse from a user's profile page: + +1. Click on the exclamation point report abuse button at the top right of the + user's profile. +1. Complete an abuse report. +1. Click the **Send report** button. + +## Reporting abuse through a user's comment + +To report abuse from a user's comment: + +1. Click on the vertical ellipsis (⋮) more actions button to open the dropdown. +1. Select **Report as abuse**. +1. Complete an abuse report. +1. Click the **Send report** button. + +NOTE: +A URL to the reported user's comment is pre-filled in the abuse report's +**Message** field. + +## Reporting abuse through a user's issue or merge request + +The **Report abuse** button is displayed at the top right of the issue or merge request: + +- When **Report abuse** is selected from the menu that appears when the + **Close issue** or **Close merge request** button is clicked, for users that + have permission to close the issue or merge request. +- When viewing the issue or merge request, for users that don't have permission + to close the issue or merge request. + +With the **Report abuse** button displayed, to submit an abuse report: + +1. Click the **Report abuse** button. +1. Submit an abuse report. +1. Click the **Send report** button. + +NOTE: +A URL to the reported user's issue or merge request is pre-filled +in the abuse report's **Message** field. + +## Managing abuse reports + +Admins are able to view and resolve abuse reports. +For more information, see [abuse reports administration documentation](admin_area/review_abuse_reports.md). diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index 2a3ee09b40b..6673611267d 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -15,7 +15,7 @@ To display a window in GitLab that lists its keyboard shortcuts, use one of the following methods: - Press <kbd>?</kbd>. -- In the Help menu in the top right of the appication, select **Keyboard shortcuts**. +- In the Help menu in the top right of the application, select **Keyboard shortcuts**. In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/22113), you can disable keyboard shortcuts by using the **Keyboard shortcuts** toggle diff --git a/doc/user/todos.md b/doc/user/todos.md index 57ab7d4d888..695532abf9f 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -20,11 +20,12 @@ Your *To-Do List* offers a chronological list of items waiting for your input The To-Do List supports tracking [actions](#what-triggers-a-to-do-item) related to the following: -- Issues -- Merge Requests -- Epics **(ULTIMATE)** +- [Issues](project/issues/index.md) +- [Merge requests](project/merge_requests/index.md) +- [Epics](group/epics/index.md) +- [Designs](project/issues/design_management.md) - + You can access your To-Do List by clicking the To-Do List icon (**{task-done}**) next to the search bar in the top navigation. If the to-do item count is: @@ -33,15 +34,13 @@ next to the search bar in the top navigation. If the to-do item count is: - *100 or more*, the number displays as 99+. The exact number displays in the To-Do List. - - ## What triggers a to-do item A to-do item appears on your To-Do List when: - An issue or merge request is assigned to you. - You're `@mentioned` in the description or comment of an issue or merge request - (or epic **(ULTIMATE)**). + (or epic). - You are `@mentioned` in a comment on a: - Commit - Design @@ -54,7 +53,7 @@ A to-do item appears on your To-Do List when: - [In GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/12136) and later, a merge request is removed from a [merge train](../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md), - and you're the user that added it. **(PREMIUM)** + and you're the user that added it. When several trigger actions occur for the same user on the same object (for example, an issue), GitLab displays only the first action as a single to do @@ -93,18 +92,18 @@ for filtering purposes; otherwise, they appear as normal. ### Manually creating a to-do item -You can also add the following to your To-Do List by clicking the **Add a to do** button on an: +You can also add the following to your To-Do List by clicking the **Add a to do** button on: -- [Issue](project/issues/index.md) -- [Merge Request](project/merge_requests/index.md) -- [Epic](group/epics/index.md) **(ULTIMATE)** -- [Design](project/issues/design_management.md) +- [Issues](project/issues/index.md) +- [Merge requests](project/merge_requests/index.md) +- [Epics](group/epics/index.md) +- [Designs](project/issues/design_management.md)  ## Marking a to-do item as done -Any action to an issue or merge request (or epic **(PREMIUM)**) marks its +Any action to an issue, merge request, or epic marks its corresponding to-do item as done. Actions that dismiss to-do items include: @@ -119,8 +118,8 @@ action. If you close the issue or merge request, your to-do item is marked as done. To prevent other users from closing issues without you being notified, if -someone else closes, merges, or takes action on an issue or merge request (or -epic **(ULTIMATE)**), your to-do item remains pending. +someone else closes, merges, or takes action on an issue, merge request, or +epic, your to-do item remains pending. There's just one to-do item for each of these, so mentioning a user many times in an issue only triggers one to-do item. @@ -132,7 +131,7 @@ your To-Do List.  You can also mark a to-do item as done by clicking the **Mark as done** button -in the sidebar of an issue or merge request (or epic **(ULTIMATE)**). +in the sidebar of an issue, merge request, or epic.  @@ -148,7 +147,7 @@ You can use the following types of filters with your To-Do List: | Project | Filter by project. | | Group | Filter by group. | | Author | Filter by the author that triggered the to do. | -| Type | Filter by issue, merge request, design, or epic. **(ULTIMATE)** | +| Type | Filter by issue, merge request, design, or epic. | | Action | Filter by the action that triggered the to do. | You can also filter by more than one of these at the same time. The previously diff --git a/doc/user/upgrade_email_bypass.md b/doc/user/upgrade_email_bypass.md index 199c1a47e04..7d2f2395815 100644 --- a/doc/user/upgrade_email_bypass.md +++ b/doc/user/upgrade_email_bypass.md @@ -73,7 +73,7 @@ Your account has been blocked. Fatal: Could not read from remote repository Your primary email address is not confirmed. ``` -You can assure your users that they have not been [Blocked](admin_area/blocking_unblocking_users.md) by an administrator. +You can assure your users that they have not been [Blocked](admin_area/moderate_users.md#blocking-and-unblocking-users) by an administrator. When affected users see this message, they must confirm their email address before they can commit code. ## What do I need to know as an administrator of a GitLab self-managed Instance? |
