diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2023-02-20 16:49:51 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2023-02-20 16:49:51 +0300 |
| commit | 71786ddc8e28fbd3cb3fcc4b3ff15e5962a1c82e (patch) | |
| tree | 6a2d93ef3fb2d353bb7739e4b57e6541f51cdd71 /doc/user | |
| parent | a7253423e3403b8c08f8a161e5937e1488f5f407 (diff) | |
Add latest changes from gitlab-org/gitlab@15-9-stable-eev15.9.0-rc42
Diffstat (limited to 'doc/user')
295 files changed, 4318 insertions, 2032 deletions
diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index a65c0c86649..a1fae7e8712 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -60,7 +60,7 @@ to activate it in the GitLab instance. 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. -The optimal size for the logo is 640x360px, but any image can be used (below 1MB) +The optimal size for the logo is 128 x 128 pixels, but any image can be used (below 1 MB) and it is resized automatically. The logo image appears between the title and the description, on the left of the sign-up page. diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index df53ef0696f..5fee0c42a77 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -54,10 +54,10 @@ When a PAT is revoked from the credentials inventory, the instance notifies the > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/243833) in GitLab 14.8. -The **Revoke** button next to a project access token can be selected to revoke that particular project access token. This will both: +The **Revoke** button next to a project access token can be selected to revoke that particular project access token. This both: -- Revoke the token project access token. -- Enqueue a background worker to delete the project bot user. +- Revokes the token project access token. +- Enqueues a background worker to delete the project bot user.  diff --git a/doc/user/admin_area/geo_sites.md b/doc/user/admin_area/geo_sites.md index f3be036fd38..9fe36188dd0 100644 --- a/doc/user/admin_area/geo_sites.md +++ b/doc/user/admin_area/geo_sites.md @@ -52,7 +52,7 @@ How long the backfill takes is dependent on the maximum concurrency, but higher values place more strain on the **primary** site. The limits are configurable. If your **primary** site has lots of surplus capacity, you can increase the values to complete backfill in a shorter time. If it's -under heavy load and backfill reduces its availability for normal requests, +under heavy load and backfill reduces its availability for standard requests, you can decrease them. ## Set up the internal URLs diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 559aae63da5..0375232334f 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -160,11 +160,11 @@ You can impersonate a user in the following ways: 1. On the left sidebar, select **Overview > Users**. 1. From the list of users, select a user. 1. Select **Impersonate**. -- With the API, using [impersonation tokens](../../api/index.md#impersonation-tokens). +- With the API, using [impersonation tokens](../../api/rest/index.md#impersonation-tokens). All impersonation activities are [captured with audit events](../../administration/audit_events.md#user-impersonation). -By default, impersonation is enabled. GitLab can be configured to [disable impersonation](../../api/index.md#disable-impersonation). +By default, impersonation is enabled. GitLab can be configured to [disable impersonation](../../api/rest/index.md#disable-impersonation).  diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index 3d96eaf793f..a273798c8eb 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -17,7 +17,7 @@ pending approval state because an administrator has enabled any of the following - [Require administrator approval for new sign-ups](settings/sign_up_restrictions.md#require-administrator-approval-for-new-sign-ups) setting. - [User cap](settings/sign_up_restrictions.md#user-cap). -- [Block auto-created users (OmniAuth)](../../integration/omniauth.md#configure-initial-settings) +- [Block auto-created users (OmniAuth)](../../integration/omniauth.md#configure-common-settings) - [Block auto-created users (LDAP)](../../administration/auth/ldap/index.md#basic-configuration-settings) When a user registers for an account while this setting is enabled: @@ -69,7 +69,7 @@ GitLab administrators can block and unblock users. ### Block a user -In order to completely prevent access of a user to the GitLab instance, +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), @@ -129,7 +129,7 @@ GitLab administrators can deactivate and activate users. > [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, +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](#block-and-unblock-users), @@ -220,7 +220,6 @@ Users can also be activated using the [GitLab API](../../api/users.md#activate-u FLAG: On self-managed GitLab, by default this feature is available. -To hide the feature, ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `ban_user_feature_flag`. On GitLab.com, this feature is available to GitLab.com administrators only. GitLab administrators can ban and unban users. Banned users are blocked, and their issues and merge requests are hidden. 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 7f678344955..35a4c0aeea7 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -86,6 +86,9 @@ To modify the maximum file size for imports in GitLab: 1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. 1. Increase or decrease by changing the value in **Maximum import size (MB)**. +This setting applies only to repositories +[imported from a GitLab export file](../../project/settings/import_export.md#import-a-project-and-its-data). + If you choose a size larger than the configured value for the web server, you may receive errors. See the [troubleshooting section](#troubleshooting) for more details. diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 7c869c9b8fe..aa171fe4536 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -44,17 +44,17 @@ Any time a new project is created, the shared runners are available. As an administrator you can set either a global or namespace-specific limit on the number of [CI/CD minutes](../../../ci/pipelines/cicd_minutes.md) you can use. -## Enable a specific runner for multiple projects +## Enable a project runner for multiple projects -If you have already registered a [specific runner](../../../ci/runners/runners_scope.md#specific-runners) +If you have already registered a [project runner](../../../ci/runners/runners_scope.md#project-runners) you can assign that runner to other projects. -To enable a specific runner for more than one project: +To enable a project runner for more than one project: 1. On the top bar, select **Main menu > Admin**. 1. From the left sidebar, select **CI/CD > Runners**. 1. Select the runner you want to edit. -1. In the top right, select **Edit** (**{pencil}**). +1. In the upper right, select **Edit** (**{pencil}**). 1. Under **Restrict projects for this runner**, search for a project. 1. To the left of the project, select **Enable**. 1. Repeat this process for each additional project. @@ -91,7 +91,7 @@ can be set at: For the setting on GitLab.com, see [Artifacts maximum size](../../gitlab_com/index.md#gitlab-cicd). -The value is in MB and the default is 100MB per job. To change it at the: +The value is in MB and the default is 100 MB per job. To change it at the: - Instance level: @@ -247,7 +247,7 @@ To enable or disable the banner: > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/352316) from GitLab Premium to GitLab Ultimate in 15.0. NOTE: -An alternative [compliance solution](../../group/compliance_frameworks.md#configure-a-compliance-pipeline) +An alternative [compliance solution](../../group/compliance_frameworks.md#compliance-pipelines) is available. We recommend this alternative solution because it provides greater flexibility, allowing required pipelines to be assigned to specific compliance framework labels. @@ -336,6 +336,8 @@ To set the maximum file size: GitLab administrators can adjust who is allowed to register runners, by showing and hiding areas of the UI. +When the registration sections are hidden in the UI, members of the project or group must contact administrators to enable runner registration in the group or project. If you plan to prevent registration, ensure users have access to the runners they need to run jobs. + By default, all members of a project and group are able to register runners. To restrict all users in an instance from registering runners: @@ -347,8 +349,10 @@ To restrict all users in an instance from registering runners: information in the UI for group or project members. 1. Select **Save changes**. -WARNING: -When the registration sections are hidden in the UI, members of the project or group that need to register runners must contact the administrators. If you plan to prevent registration, ensure users have access to the runners they need to run jobs. +NOTE: +After you disable runner registration by members of a project, the registration +token automatically rotates. The token is no longer valid and you must +use the new registration token for the project. ## Restrict runner registration by all members in a group diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index 6d2a3c2cdae..484f51d8739 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -84,6 +84,27 @@ To disable these notifications: 1. Clear the **Enable user deactivation emails** checkbox. 1. Select **Save changes**. +### Custom additional text in deactivation emails **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355964) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `deactivation_email_additional_text`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an +administrator to [enable the feature flag](../../../administration/feature_flags.md) named +`deactivation_email_additional_text`. On GitLab.com, this feature is unavailable. + +You can add additional text at the bottom of the email that GitLab sends to users when their account +is deactivated. This email text is separate from the [custom additional text](#custom-additional-text) +setting. + +To add additional text to deactivation emails: + +1. On the top bar, select **Main menu > Admin**. +1. On the left sidebar, select **Settings > Preferences** (`/admin/application_settings/preferences`). +1. Expand **Email**. +1. Enter your text in the **Additional text for deactivation email** field. +1. Select **Save changes**. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 09ac477b062..94d9ec73640 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -96,7 +96,7 @@ When denying access, a `reason` can be optionally specified in the JSON body: Any other status code than 200, 401 or 403 also deny access to the user, but the response isn't cached. -If the service times out (after 500ms), a message "External Policy Server did +If the service times out (after 500 ms), a message "External Policy Server did not respond" is displayed. ## Classification labels diff --git a/doc/user/admin_area/settings/floc.md b/doc/user/admin_area/settings/floc.md index f8137afa40f..451acc07240 100644 --- a/doc/user/admin_area/settings/floc.md +++ b/doc/user/admin_area/settings/floc.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Federated Learning of Cohorts (FLoC) is a new feature of the Chrome browser. It works by categorizing users into different cohorts, so that advertisers can use this data to uniquely target and track users. For more -information, visit the [FLoC repository](https://github.com/WICG/floc). +information, see the [FLoC repository](https://github.com/WICG/floc). To avoid users being tracked and categorized in any GitLab instance, FLoC is disabled by default by sending the following header: diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index b2b702bde7c..5a550f15a41 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -49,7 +49,6 @@ The **General** settings contain: - [External Authentication](external_authorization.md#configuration) - External Classification Policy Authorization. - [Web terminal](../../../administration/integration/terminal.md#limiting-websocket-connection-time) - Set max session time for web terminal. -- [Web IDE](../../project/web_ide/index.md#enable-live-preview) - Manage Web IDE features. - [FLoC](floc.md) - Enable or disable [Federated Learning of Cohorts (FLoC)](https://en.wikipedia.org/wiki/Federated_Learning_of_Cohorts) tracking. @@ -87,7 +86,7 @@ The **Integrations** settings contain: to receive invite email bounce events from Mailgun, if it is your email provider. - [PlantUML](../../../administration/integration/plantuml.md) - Allow rendering of PlantUML diagrams in documents. -- [Slack application](../../../user/project/integrations/gitlab_slack_application.md#configuration) - +- [Slack application](../../../user/project/integrations/gitlab_slack_application.md) - Slack integration allows you to interact with GitLab via slash commands in a chat window. This option is only available on GitLab.com, though it may be [available for self-managed instances in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). @@ -118,7 +117,7 @@ The **Metrics and profiling** settings contain: The **Network** settings contain: - Performance optimization - Various settings that affect GitLab performance, including: - - [Write to `authorized_keys` file](../../../administration/operations/fast_ssh_key_lookup.md#setting-up-fast-lookup-via-gitlab-shell). + - [Write to `authorized_keys` file](../../../administration/operations/fast_ssh_key_lookup.md#set-up-fast-lookup). - [Push event activities limit and bulk push events](push_event_activities_limit.md). - [User and IP rate limits](user_and_ip_rate_limits.md) - Configure limits for web and API requests. These rate limits can be overridden: diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index 5be9081d9b2..1e7c75363ab 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -28,7 +28,7 @@ Only the complete settings for an integration can be inherited. Per-field inheri 1. Enter configuration details and select **Save changes**. WARNING: -This may affect all or most of the groups and projects on your GitLab instance. Please review the details +This may affect all or most of the groups and projects on your GitLab instance. Review the details below. If this is the first time you are setting up instance-level settings for an integration: @@ -82,7 +82,7 @@ for an integration. 1. Enter configuration details and select **Save changes**. WARNING: -This may affect all or most of the subgroups and projects belonging to the group. Please review the details below. +This may affect all or most of the subgroups and projects belonging to the group. Review the details below. If this is the first time you are setting up group-level settings for an integration: diff --git a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md index 3c6fd4b1e45..547e543ab88 100644 --- a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md @@ -22,7 +22,7 @@ For example, if you set a limit of 300, requests using the [Projects::IssuesController#create](https://gitlab.com/gitlab-org/gitlab/blob/master/app/controllers/projects/issues_controller.rb) action exceeding a rate of 300 per minute are blocked. Access to the endpoint is allowed after one minute. -When using [epics](../../group/epics/index.md), epic creation will share this rate limit with issues. +When using [epics](../../group/epics/index.md), epic creation shares this rate limit with issues.  diff --git a/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md b/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md index 820f7eaf854..152ef535ff8 100644 --- a/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_pipelines_creation.md @@ -16,7 +16,7 @@ the eleventh request is blocked. Access to the endpoint is allowed again after o This limit is: -- Applied independently per project, user, and commit. +- Applied to the number of pipelines created for the same combination of project, commit, and user. - Not applied per IP address. - Disabled by default. diff --git a/doc/user/admin_area/settings/scim_setup.md b/doc/user/admin_area/settings/scim_setup.md new file mode 100644 index 00000000000..fd6e3061140 --- /dev/null +++ b/doc/user/admin_area/settings/scim_setup.md @@ -0,0 +1,34 @@ +--- +type: reference, howto +stage: Manage +group: Authentication and Authorization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Configure SCIM for self-managed GitLab instances **(PREMIUM SELF)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8902) in GitLab 15.8. + +You can use the open standard System for Cross-domain Identity Management (SCIM) to automatically: + +- Create users. +- Remove users (deactivate SCIM identity). + +The [internal GitLab SCIM API](../../../development/internal_api/index.md#instance-scim-api) implements part of [the RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644). + +If you are a GitLab.com user, see [configuring SCIM for GitLab.com groups](../../../user/group/saml_sso/scim_setup.md). + +## Configure GitLab + +Prerequisites: + +- Configure [SAML single sign-on](../../../integration/saml.md). + +To configure GitLab SCIM: + +1. On the top bar, select **Main menu > Admin area**. +1. On the left sidebar, select **Settings > General**. +1. Expand the **SCIM Token** section and select **Generate a SCIM token**. +1. For configuration of your identity provider, save the: + - Token from the **Your SCIM token** field. + - URL from the **SCIM API endpoint URL** field. diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index d663238a88c..82a54787101 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -149,7 +149,7 @@ period in hours. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218457) in GitLab 13.2. When enabled, GitLab notifies users of sign-ins from unknown IP addresses or devices. For more information, -see [Email notification for unknown sign-ins](../../profile/unknown_sign_in_notification.md). +see [Email notification for unknown sign-ins](../../profile/notifications.md#notifications-for-unknown-sign-ins).  diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index 8aabe503065..c44901b1ad7 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -48,7 +48,7 @@ automatically approved in a background job. NOTE: This setting doesn't apply to LDAP or OmniAuth users. To enforce approvals for new users signing up using OmniAuth or LDAP, set `block_auto_created_users` to `true` in the -[OmniAuth configuration](../../../integration/omniauth.md#configure-initial-settings) or +[OmniAuth configuration](../../../integration/omniauth.md#configure-common-settings) or [LDAP configuration](../../../administration/auth/ldap/index.md#basic-configuration-settings). ## Require email confirmation @@ -142,7 +142,7 @@ Existing passwords are unaffected. To change password complexity requirements: You can specify an inclusive or exclusive list of email domains which can be used for user sign up. These restrictions are only applied during sign up from an external user. An administrator can add a -user through the administrator panel with a disallowed domain. Also, note that the users can change their +user through the administrator panel with a disallowed domain. The users can also change their email addresses to disallowed domains after sign up. ### Allowlist email domains diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 8b9f09d9df5..212769ed89b 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -27,7 +27,7 @@ There are several other benefits to enabling Service Ping: - Analyze the users' activities over time of your GitLab installation. - A [DevOps Score](../analytics/dev_ops_reports.md#devops-score) to give you an overview of your entire instance's adoption of concurrent DevOps from planning to monitoring. -- More proactive support (assuming that our TAMs and support organization used the data to deliver more value). +- More proactive support (assuming that our [Customer Success Managers (CSMs)](https://about.gitlab.com/job-families/sales/customer-success-management/) and support organization used the data to deliver more value). - Insight and advice into how to get the most value out of your investment in GitLab. - Reports that show how you compare against other similar organizations (anonymized), with specific advice and recommendations on how to improve your DevOps processes. - Participation in our [Registration Features Program](#registration-features-program) to receive free paid features. 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 e285275f5bb..9b8718fc336 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 @@ -140,7 +140,7 @@ It is important that your load balancer erases or overwrites the bypass header on all incoming traffic. Otherwise, you must trust your users to not set that header and bypass the GitLab rate limiter. -Note that the bypass only works if the header is set to `1`. +The bypass works only if the header is set to `1`. Requests that bypassed the rate limiter because of the bypass header are marked with `"throttle_safelist":"throttle_bypass_header"` in @@ -209,7 +209,7 @@ To enable dry run mode for all throttles, the variable can be set to `*`. Setting a throttle to dry run mode logs a message to the [`auth.log`](../../../administration/logs/index.md#authlog) when it would hit the limit, while letting the -request continue as normal. The log message contains an `env` field set to `track`. The `matched` +request continue. The log message contains an `env` field set to `track`. The `matched` field contains the name of throttle that was hit. It is important to set the environment variable **before** enabling diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md index 5ca942a42bb..acff483e4f8 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -61,19 +61,19 @@ Instance-level protection against accidental deletion of groups and projects. > [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. -Groups and projects will remain restorable within a defined retention period. By default this is 7 days but it can be changed. +Groups and projects remain restorable within a defined retention period. By default this is 7 days but it can be changed. Setting the retention period to `0` means that groups and project are removed immediately and cannot be restored. In GitLab 15.1 and later, the retention period must be between `1` and `90`. If the retention period was `0` before the 15.1 update, -then it will get automatically changed to `1` while also disabling deletion protection the next time any application setting is changed. +then it gets automatically changed to `1` while also disabling deletion protection the next time any application setting is changed. ### Delayed project deletion > User interface [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. Administrators can enable [delayed project deletion](../../project/settings/index.md#delayed-project-deletion) by default for -newly-created groups. Group owners can choose to disable this and existing groups will retain their existing setting. When enabled -deleted groups will remain restorable within a retention period. +newly-created groups. Group owners can choose to disable this. When disabled, existing groups retain their existing setting. When enabled +deleted groups remain restorable within a retention period. To configure delayed project deletion: @@ -95,7 +95,7 @@ In GitLab 15.1, and later this setting is enforced on groups when disabled and i > User interface [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. -Groups will remain restorable if the retention period is `1` or more days. +Groups remain restorable if the retention period is `1` or more days. In GitLab 15.1 and later, delayed group deletion can be enabled by setting **Deletion projection** to **Keep deleted**. @@ -155,18 +155,23 @@ For more details on group visibility, see ## Restrict visibility levels -To restrict visibility levels for projects, snippets, and selected pages: +To restrict visibility levels for groups, projects, snippets, and selected pages: 1. Sign in to GitLab as a user with Administrator access level. 1. On the top bar, select **Main menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. In the **Restricted visibility levels** section, select the desired visibility levels to restrict. - If you restrict the **Public** level: - - User profiles are only visible to authenticated users via the Web interface. - - User attributes via the GraphQL API are: - - Not visible in [GitLab 15.1 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88020). - - Only visible to authenticated users between [GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33195) and GitLab 15.0. + - If you restrict the **Public** level: + - Only administrators are able to create public groups, projects, and snippets. + - User profiles are only visible to authenticated users through the Web interface. + - User attributes through the GraphQL API are: + - Not visible in [GitLab 15.1 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88020). + - Only visible to authenticated users between [GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33195) and GitLab 15.0. + - If you restrict the **Internal** level: + - Only administrators are able to create internal groups, projects, and snippets. + - If you restrict the **Private** level: + - Only administrators are able to create private groups, projects, and snippets. 1. Select **Save changes**. For more details on project visibility, see @@ -200,7 +205,9 @@ To enable the export of > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383268) in GitLab 15.8. -You can enable migration of groups by direct transfer. To also migrate projects with the groups, you must enable the +You can enable migration of groups by direct transfer using the UI. + +To also migrate projects with the groups, you must enable the [`bulk_import_projects` feature flag](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). To enable migration of groups by direct transfer: @@ -213,6 +220,10 @@ To enable migration of groups by direct transfer: 1. Select the **Enabled** checkbox. 1. Select **Save changes**. +The same setting +[is available](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls) in the API as the +`bulk_import_enabled` attribute. + ## Configure enabled Git access protocols With GitLab access restrictions, you can select the protocols users can use to diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index 86f1e24429b..fae9545003f 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -10,19 +10,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Moved to GitLab Premium in 13.9. -Use code review analytics to view review metrics per merge request and -make improvements to your code review process: +Code review analytics displays a table of open merge requests that have at least one non-author comment. +The review time is the amount of time since the first comment by a non-author in a merge request. + +You can use code review analytics to view review metrics per merge request +and improve your code review process. - A high number of comments or commits may indicate: - - The code is too complex. + - Code that is too complex. - Authors who require more training. - A long review time may indicate: - Types of work that move slower than other types. - Opportunities to accelerate your development cycle. -- Fewer comments and approvers may indicate staffing requirements. - -Code review analytics displays a table of open merge requests that have at least one non-author comment. -The review time is measured from when the first non-author comment was submitted. +- Few comments and approvers may indicate a lack of available team members. ## View code review analytics @@ -34,4 +34,18 @@ To view code review analytics: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Code Review**. -1. Filter merge requests by milestone and label. +1. Optional. Filter results: + 1. Select the filter bar. + 1. Select a parameter. You can filter merge requests by milestone and label. + 1. Select a value for the selected parameter. + +The table shows up to 20 merge requests in review per page, +and includes the following information about each merge request: + +- Merge request title +- Review time +- Author +- Approvers +- Comments +- Commits +- Line changes diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 1d1127c3d9f..69ba5a67197 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -13,18 +13,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w Use merge request analytics to view: - The number of merge requests your organization merged per month. -- The average time between merge request creation and merge. -- Information about each merged merge request. +- The average time between merge request creation and merge event. +- Information about each merged merge request (such as milestone, commits, line changes, and assignees). You can use merge request analytics to identify: - Low or high productivity months. -- Efficiency and productivity of your merge request process. -- Efficiency of your code review process. +- The efficiency and productivity of your merge request and code review processes. ## View merge request analytics -You must have at least the Reporter role to view merge request analytics. +Prerequisite: + +- You must have at least the Reporter role. To view merge request analytics: @@ -52,17 +53,26 @@ The **Throughput** chart shows issues closed or merge requests merged (not close time. The table shows up to 20 merge requests per page, and includes -information about each merge request. +the following information about each merge request: + +- Merge request name +- Date merged +- Time to merge +- Milestone +- Commits +- Pipelines +- Line changes +- Assignees ## View average time between merge request creation and merge > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229389) in GitLab 13.9. -Use the number in **Mean time to merge** to view the average time between when a merge request is -created and when it's merged. Closed and un-merged merge requests are not included. +The number in **Mean time to merge** shows the average time between when a merge request is +created and when it's merged. Closed and not yet merged merge requests are not included. To view **Mean time to merge**: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Merge request**. The **Mean time to merge** number -is shown on the dashboard. +is displayed on the dashboard. diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index 0906f7d17a7..093266e8aee 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -214,3 +214,33 @@ as every merge request should be tested. stream analytics dashboard shows the calculated median elapsed time for these issues. - Value stream analytics identifies production environments based on the [deployment tier of environments](../../ci/environments/index.md#deployment-tier-of-environments). + +## Troubleshooting + +### 100% CPU utilization by Sidekiq `cronjob:analytics_cycle_analytics` + +It is possible that Value stream analytics background jobs +strongly impact performance by monopolizing CPU resources. + +To recover from this situation: + +1. Disable the feature for all projects in [the Rails console](../../administration/operations/rails_console.md), + and remove existing jobs: + + ```ruby + Project.find_each do |p| + p.analytics_access_level='disabled'; + p.save! + end + + Analytics::CycleAnalytics::GroupStage.delete_all + Analytics::CycleAnalytics::Aggregation.delete_all + ``` + +1. Configure a [Sidekiq routing](../../administration/sidekiq/processing_specific_job_classes.md) + with for example a single `feature_category=value_stream_management` + and multiple `feature_category!=value_stream_management` entries. + Find other relevant queue metadata in the + [Enterprise Edition list](../../administration/sidekiq/processing_specific_job_classes.md#list-of-available-job-classes). +1. Enable value stream analytics for one project after another. + You might need to tweak the Sidekiq routing further according to your performance requirements. diff --git a/doc/user/analytics/value_streams_dashboard.md b/doc/user/analytics/value_streams_dashboard.md index 1de26749deb..f8cfb1bf06b 100644 --- a/doc/user/analytics/value_streams_dashboard.md +++ b/doc/user/analytics/value_streams_dashboard.md @@ -16,6 +16,9 @@ The Value Streams Dashboard is a customizable dashboard to enable decision-maker This page is a work in progress, and we're updating the information as we add more features. For more information, see the [Value Stream Management category direction page](https://about.gitlab.com/direction/plan/value_stream_management/). +After the feature flag is enabled, to open the new page, append this path `/analytics/dashboards` to the group URL +(for example, `https://gitlab.com/groups/gitlab-org/-/analytics/dashboards`). + ## Initial use case Our initial use case is focused on providing the ability to compare software delivery metrics. @@ -59,3 +62,16 @@ For example, the parameter `query=gitlab-org/gitlab-foss,gitlab-org/gitlab,gitla - `gitlab-org` group - `gitlab-ui` project - `gitlab-org/plan-stage` subgroup + +## Dashboard metrics and drill-down reports + +| Metric | Description | Drill-down report | Documentation page | +| ------ | ----------- | --------------- | ------------------ | +| Deployment frequency | Average number of deployments to production per day. This metric measures how often value is delivered to end users. | [Deployment frequency tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=deployment-frequency) | [Deployment frequency](dora_metrics.md#deployment-frequency) | +| Lead time for changes | The time to successfully deliver a commit into production. This metric reflects the efficiency of CI/CD pipelines. | [Lead time tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=lead-time) | [Lead time for changes](dora_metrics.md#lead-time-for-changes) | +| Time to restore service | The time it takes an organization to recover from a failure in production. | [Time to restore service tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=time-to-restore-service) | [Time to restore service](dora_metrics.md#time-to-restore-service) | +| Change failure rate | Percentage of deployments that cause an incident in production. | [Change failure rate tab](https://gitlab.com/groups/gitlab-org/-/analytics/ci_cd?tab=change-failure-rate) | [Change failure rate](dora_metrics.md#change-failure-rate) | +| VSA Lead time | Median time from issue created to issue closed. | [Value Stream Analytics](https://gitlab.com/groups/gitlab-org/-/analytics/value_stream_analytics) | [View the lead time and cycle time for issues](value_stream_analytics.md#view-the-lead-time-and-cycle-time-for-issues) | +| VSA Cycle time | Median time from the earliest commit of a linked issue's merge request to when that issue is closed. | [VSA overview](https://gitlab.com/groups/gitlab-org/-/analytics/value_stream_analytics) | [View the lead time and cycle time for issues](value_stream_analytics.md#view-the-lead-time-and-cycle-time-for-issues) | +| New issues | Number of new issues created. | [Issue Analytics](https://gitlab.com/groups/gitlab-org/-/issues_analytics) | Issue analytics [for projects](issue_analytics.md) and [for groups](../../user/group/issues_analytics/index.md) | +| Number of deploys | Total number of deploys to production. | [Merge Request Analytics](https://gitlab.com/gitlab-org/gitlab/-/analytics/merge_request_analytics) | [Merge request analytics](merge_request_analytics.md) | diff --git a/doc/user/application_security/api_fuzzing/create_har_files.md b/doc/user/application_security/api_fuzzing/create_har_files.md index 5e033a75902..0ad87facc50 100644 --- a/doc/user/application_security/api_fuzzing/create_har_files.md +++ b/doc/user/application_security/api_fuzzing/create_har_files.md @@ -109,7 +109,7 @@ responses in HAR format. 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 list select **HTTP Archive v1.2**. +1. In the **Choose Format** dropdown list select **HTTPArchive v1.2**. 1. Enter a filename and select **Save**. Fiddler shows a popup message confirming the export has succeeded. @@ -211,7 +211,7 @@ Review the HAR file for any of the following: 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. +Use the following as a checklist to start with. It's not an exhaustive list. - Look for secrets. For example: if your application requires authentication, check common locations or authentication information: diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 31322419902..b55c5a1b299 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -26,7 +26,7 @@ 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 + `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. We plan to remove them in a future GitLab version. If your pipeline is configured to deploy to the same web server on each run, running a @@ -142,11 +142,11 @@ OpenAPI 2.x lets you specify the accepted media types globally or per operation, - In GitLab 14.9 and earlier, the default behavior is to perform testing using all supported media types. This means if two media types are listed (for example, `application/json` and `application/xml`), tests are performed using JSON, and then the same tests using XML. Testing the same operation (for example, `POST /user`) using different media types (for example, `application/json` and `application/xml`) is not always desirable. -For example, if the target application executes the same code regardless of the request content type, it will take longer to finish the test session, and it may report duplicate vulnerabilities related to the request body depending on the target app. +For example, if the target application executes the same code regardless of the request content type, it takes longer to finish the test session, and it may report duplicate vulnerabilities related to the request body depending on the target app. -The environment variable `FUZZAPI_OPENAPI_ALL_MEDIA_TYPES` lets you specify whether or not to use all supported media types instead of one when generating requests for a given operation. When the environmental variable `FUZZAPI_OPENAPI_ALL_MEDIA_TYPES` is set to any value, API Fuzzing will try to generate requests for all supported media types instead of one in a given operation. This will cause testing to take longer as testing is repeated for each provided media type. +The environment variable `FUZZAPI_OPENAPI_ALL_MEDIA_TYPES` lets you specify whether or not to use all supported media types instead of one when generating requests for a given operation. When the environmental variable `FUZZAPI_OPENAPI_ALL_MEDIA_TYPES` is set to any value, API Fuzzing tries to generate requests for all supported media types instead of one in a given operation. This causes testing to take longer as testing is repeated for each provided media type. -Alternatively, the variable `FUZZAPI_OPENAPI_MEDIA_TYPES` is used to provide a list of media types that will each be tested. Providing more than one media type causes testing to take longer, as testing is performed for each media type selected. When the environment variable `FUZZAPI_OPENAPI_MEDIA_TYPES` is set to a list of media types, only the listed media types are included when creating requests. +Alternatively, the variable `FUZZAPI_OPENAPI_MEDIA_TYPES` is used to provide a list of media types that each is tested. Providing more than one media type causes testing to take longer, as testing is performed for each media type selected. When the environment variable `FUZZAPI_OPENAPI_MEDIA_TYPES` is set to a list of media types, only the listed media types are included when creating requests. Multiple media types in `FUZZAPI_OPENAPI_MEDIA_TYPES` must separated by a colon (`:`). For example, to limit request generation to the media types `application/x-www-form-urlencoded` and `multipart/form-data`, set the environment variable `FUZZAPI_OPENAPI_MEDIA_TYPES` to `application/x-www-form-urlencoded:multipart/form-data`. Only supported media types in this list are included when creating requests, though unsupported media types are always skipped. A media type text may contain different sections. For example, `application/vnd.api+json; charset=UTF-8` is a compound of `type "/" [tree "."] subtype ["+" suffix]* [";" parameter]`. Parameters are not taken into account when filtering media types on request generation. @@ -1390,7 +1390,7 @@ By default the output of the overrides command is hidden. If the overrides comma It is also possible to write messages from your script to a log file that is collected when the job completes or fails. The log file must be created in a specific location and follow a naming convention. -Adding some basic logging to your overrides script is useful in case the script fails unexpectedly during normal running of the job. The log file is automatically included as an artifact of the job, allowing you to download it after the job has finished. +Adding some basic logging to your overrides script is useful in case the script fails unexpectedly during typical running of the job. The log file is automatically included as an artifact of the job, allowing you to download it after the job has finished. Following our example, we provided `renew_token.py` in the environmental variable `FUZZAPI_OVERRIDES_CMD`. Notice two things in the script: @@ -1499,7 +1499,7 @@ logging.info("Override file has been updated") # end ``` -In the overrides command example, the Python script depends on the `backoff` library. To make sure the library is installed before executing the Python script, the `FUZZAPI_PRE_SCRIPT` is set to a script that will install the dependencies of your overrides command. +In the overrides command example, the Python script depends on the `backoff` library. To make sure the library is installed before executing the Python script, the `FUZZAPI_PRE_SCRIPT` is set to a script that installs the dependencies of your overrides command. As for example, the following script `user-pre-scan-set-up.sh`: ```shell @@ -1589,7 +1589,7 @@ variables: While testing an API you may might want to exclude a parameter (query string, header, or body element) from testing. This may be needed because a parameter always causes a failure, slows down testing, or for other reasons. To exclude parameters you can use one of the following variables: `FUZZAPI_EXCLUDE_PARAMETER_ENV` or `FUZZAPI_EXCLUDE_PARAMETER_FILE`. -The `FUZZAPI_EXCLUDE_PARAMETER_ENV` allows providing a JSON string containing excluded parameters. This is a good option if the JSON is short and will not often change. Another option is the variable `FUZZAPI_EXCLUDE_PARAMETER_FILE`. This variable is set to a file path that can be checked into the repository, created by another job as an artifact, or generated at runtime from a pre-script using `FUZZAPI_PRE_SCRIPT`. +The `FUZZAPI_EXCLUDE_PARAMETER_ENV` allows providing a JSON string containing excluded parameters. This is a good option if the JSON is short and can not often change. Another option is the variable `FUZZAPI_EXCLUDE_PARAMETER_FILE`. This variable is set to a file path that can be checked into the repository, created by another job as an artifact, or generated at runtime from a pre-script using `FUZZAPI_PRE_SCRIPT`. #### Exclude parameters using a JSON document @@ -1991,7 +1991,7 @@ Repeat this configuration for each profile as needed. When configured correctly, a CI/CD pipeline contains a `fuzz` stage and an `apifuzzer_fuzz` or `apifuzzer_fuzz_dnd` job. The job only fails when an invalid configuration is provided. During -normal operation, the job always succeeds even if faults are identified during fuzz testing. +typical operation, the job always succeeds even if faults are identified during fuzz testing. Faults are displayed on the **Security** pipeline tab with the suite name. When testing against the repositories default branch, the fuzzing faults are also shown on the Security & Compliance's @@ -2026,7 +2026,7 @@ Follow these steps to view details of a fuzzing fault: 1. You can view faults in a project, or a merge request: - - In a project, go to the project's **{shield}** **Security & Compliance > Vulnerability Report** + - In a project, go to the project's **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 select the **Expand** button. API Fuzzing faults are available in a section labeled @@ -2042,7 +2042,7 @@ Follow these steps to view details of a fuzzing fault: | Method | HTTP method used to detect the vulnerability. | | URL | URL at which the vulnerability was detected. | | Request | The HTTP request that caused the fault. | - | Unmodified Response | Response from an unmodified request. This is what a normal working response looks like. | + | Unmodified Response | Response from an unmodified request. This is what a typical working response looks like. | | Actual Response | Response received from fuzzed request. | | Evidence | How we determined a fault occurred. | | Identifiers | The fuzzing check used to find this fault. | @@ -2377,7 +2377,7 @@ apifuzzer_v2: In the case of one or two slow operations, the team might decide to skip testing the operations, or exclude them from feature branch tests, but include them for default branch tests. Excluding the operation is done using the `FUZZAPI_EXCLUDE_PATHS` configuration [variable as explained in this section.](#exclude-paths) -In this example, we have an operation that returns a large amount of data. The operation is `GET http://target:7777/api/large_response_json`. To exclude it we provide the `FUZZAPI_EXCLUDE_PATHS` configuration variable with the path portion of our operation URL `/api/large_response_json`. Our configuration disables the main `apifuzzer_fuzz` job and creates two new jobs `apifuzzer_main` and `apifuzzer_branch`. The `apifuzzer_branch` is set up to exclude the long operation and only run on non-default branches (e.g. feature branches). The `apifuzzer_main` branch is set up to only execute on the default branch (`main` in this example). The `apifuzzer_branch` jobs run faster, allowing for quick development cycles, while the `apifuzzer_main` job which only runs on default branch builds, takes longer to run. +In this example, we have an operation that returns a large amount of data. The operation is `GET http://target:7777/api/large_response_json`. To exclude it we provide the `FUZZAPI_EXCLUDE_PATHS` configuration variable with the path portion of our operation URL `/api/large_response_json`. Our configuration disables the main `apifuzzer_fuzz` job and creates two new jobs `apifuzzer_main` and `apifuzzer_branch`. The `apifuzzer_branch` is set up to exclude the long operation and only run on non-default branches (for example, feature branches). The `apifuzzer_main` branch is set up to only execute on the default branch (`main` in this example). The `apifuzzer_branch` jobs run faster, allowing for quick development cycles, while the `apifuzzer_main` job which only runs on default branch builds, takes longer to run. To verify the operation is excluded, run the API Fuzzing job and review the job console output. It includes a list of included and excluded operations at the end of the test. @@ -2538,14 +2538,14 @@ The API Fuzzing engine outputs an error message when it cannot establish a conne **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. +- Remove the `FUZZAPI_API` variable from the `.gitlab-ci.yml` file. The value is 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. +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 tries to use the `FUZZAPI_TARGET_URL`. If the environment variable has not been set, then the API Fuzzing analyzer attempts to use the `environment_url.txt` file. If there is no file `environment_url.txt`, the API Fuzzing analyzer now uses 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 depends on whether or not your target API changes for each deployment: @@ -2642,7 +2642,7 @@ variables: ### `No operation in the OpenAPI document is consuming any supported media type` -API Fuzzing uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error will be thrown. +API Fuzzing uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error is thrown. **Error message** diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index fc06b50b03d..0a586a14cc4 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -234,7 +234,7 @@ When you enable this feature, you may see [duplicate findings](../terminology/in in the [Vulnerability Report](../vulnerability_report/index.md) if [Dependency Scanning](../dependency_scanning/index.md) is enabled for your project. This happens because GitLab can't automatically deduplicate findings -across different types of scanning tools. Please reference [this comparison](../dependency_scanning/index.md#dependency-scanning-compared-to-container-scanning) +across different types of scanning tools. Reference [this comparison](../dependency_scanning/index.md#dependency-scanning-compared-to-container-scanning) between GitLab Dependency Scanning and Container Scanning for more details on which types of dependencies are likely to be duplicated. #### Available CI/CD variables @@ -268,6 +268,7 @@ including a large number of false positives. | `CS_REGISTRY_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. The default is only set if `$CS_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). Not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. | All | | `CS_REGISTRY_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. The default is only set if `$CS_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). Not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. | All | | `CS_DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to use for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project. You should configure this variable only if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | All | +| `CS_QUIET` | `""` | If set, this variable disables output of the [vulnerabilities table](#container-scanning-job-log-format) in the job log. [Introduced](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/-/merge_requests/50) in GitLab 15.1. | All | | `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. | All | ### Supported distributions @@ -532,7 +533,7 @@ To use container scanning in an offline environment, you need: | --- | --- | | [Container-Scanning](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning) | [Container-Scanning container registry](https://gitlab.com/security-products/container-scanning/container_registry/) | -Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), +GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), meaning the runner tries to pull Docker images from the GitLab container registry even if a local copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we @@ -560,7 +561,7 @@ registry.gitlab.com/security-products/container-scanning/trivy:5 ``` 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 +**your network security policy**. Consult your IT staff to find an accepted and approved process by which you can import or temporarily access external resources. These scanners are [periodically updated](../index.md#vulnerability-scanner-maintenance), and you may be able to make occasional updates on your own. @@ -580,7 +581,7 @@ For details on saving and transporting Docker images as a file, see the Docker d - template: Jobs/Container-Scanning.gitlab-ci.yml container_scanning: - image: $CI_REGISTRY/namespace/gitlab-container-scanning + image: $CI_REGISTRY/namespace/container-scanning ``` 1. If your local Docker container registry is running securely over `HTTPS`, but you're using a @@ -597,7 +598,7 @@ following `.gitlab-ci.yml` example as a template. ```yaml variables: SOURCE_IMAGE: registry.gitlab.com/security-products/container-scanning:5 - TARGET_IMAGE: $CI_REGISTRY/namespace/gitlab-container-scanning + TARGET_IMAGE: $CI_REGISTRY/namespace/container-scanning image: docker:stable diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 71c842ca277..5d2593a1bed 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -102,7 +102,7 @@ targets. Each fuzzing target **must** have a separate job. For example, the [go-fuzzing-example project](https://gitlab.com/gitlab-org/security-products/demos/go-fuzzing-example) contains one job that extends `.fuzz_base` for its single fuzzing target. -Note that the hidden job `.fuzz_base` uses several YAML keys that you must not override in your own +The hidden job `.fuzz_base` uses several YAML keys that you must not override in your own job. If you include these keys in your own job, you must copy their original content: - `before_script` diff --git a/doc/user/application_security/dast/authentication.md b/doc/user/application_security/dast/authentication.md index d5ba92f399c..77732ab532c 100644 --- a/doc/user/application_security/dast/authentication.md +++ b/doc/user/application_security/dast/authentication.md @@ -5,13 +5,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Authentication (DAST) **(ULTIMATE)** +# DAST authentication **(ULTIMATE)** WARNING: -**Never** run an authenticated scan against a production server. -Authenticated scans may perform *any* function that the authenticated user can, +**DO NOT** use credentials that are valid for production systems, production servers, or any that +contain production data. + +WARNING: +**DO NOT** run an authenticated scan against a production server. +Authenticated scans may perform **any** function that the authenticated user can, including modifying or deleting data, submitting forms, and following links. -Only run an authenticated scan against a test server. +Only run an authenticated scan against non-production systems or servers. Authentication logs a user in before a DAST scan so that the analyzer can test as much of the application as possible when searching for vulnerabilities. @@ -44,8 +48,8 @@ To run a DAST authenticated scan: - You are using either the [DAST proxy-based analyzer](proxy-based.md) or the [DAST browser-based analyzer](browser_based.md). - You know the URL of the login form of your application. Alternatively, you know how to navigate to the login form from the authentication URL (see [clicking to navigate to the login form](#clicking-to-navigate-to-the-login-form)). - You have the username and password of the user you would like to authenticate as during the scan. -- You know the [selectors](#finding-an-elements-selector) of the username and password HTML fields that DAST will use to input the respective values. -- You know the element's [selector](#finding-an-elements-selector) that will submit the login form when selected. +- You know the [selectors](#finding-an-elements-selector) of the username and password HTML fields that DAST uses to input the respective values. +- You know the element's [selector](#finding-an-elements-selector) that submits the login form when selected. - You have thought about how you can [verify](#verifying-authentication-is-successful) whether or not authentication was successful. - You have checked the [known limitations](#known-limitations) to ensure DAST can authenticate to your application. @@ -140,7 +144,7 @@ See [Custom CI/CI variables](../../../ci/variables/index.md#for-a-project) for m ### Configuration for Single Sign-On (SSO) -If a user can log into an application, then in most cases, DAST will also be able to log in. +If a user can log into an application, then in most cases, DAST is also able to log in. This is the case even when an application uses Single Sign-on. Applications using SSO solutions should configure DAST authentication using the [single-step](#configuration-for-a-single-step-login-form) or [multi-step](#configuration-for-a-multi-step-login-form) login form configuration guides. @@ -168,8 +172,8 @@ dast: ### Excluding logout URLs -If DAST crawls the logout URL while running an authenticated scan, the user will be logged out, resulting in the remainder of the scan being unauthenticated. -It is therefore recommended to exclude logout URLs using the CI/CD variable `DAST_EXCLUDE_URLS`. DAST will not access any excluded URLs, ensuring the user remains logged in. +If DAST crawls the logout URL while running an authenticated scan, the user is logged out, resulting in the remainder of the scan being unauthenticated. +It is therefore recommended to exclude logout URLs using the CI/CD variable `DAST_EXCLUDE_URLS`. DAST isn't accessing any excluded URLs, ensuring the user remains logged in. Provided URLs can be either absolute URLs, or regular expressions of URL paths relative to the base path of the `DAST_WEBSITE`. For example: @@ -193,7 +197,7 @@ Selectors have the format `type`:`search string`. DAST searches for the selector | `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://input[@id="my-button"]/a` | Searches for a HTML element with the provided XPath. Note that XPath searches are expected to be less performant than other searches. | +| `xpath` | `xpath://input[@id="my-button"]/a` | Searches for a HTML element with the provided XPath. XPath searches are expected to be less performant than other searches. | | None provided | `a.click-me` | Defaults to searching using a CSS selector. **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383348)** in GitLab 15.8. Replaced by explicitly declaring the selector type. | #### Find selectors with Google Chrome @@ -234,7 +238,7 @@ When using selectors to locate specific fields we recommend you avoid searching ## Verifying authentication is successful Once DAST has submitted the login form, a verification process takes place -to determine if authentication succeeded. The scan will halt with an error if authentication is unsuccessful. +to determine if authentication succeeded. The scan halts with an error if authentication is unsuccessful. Following the submission of the login form, authentication is determined to be unsuccessful when: @@ -247,13 +251,13 @@ Following the submission of the login form, authentication is determined to be u Verification checks run checks on the state of the browser once authentication is complete to determine further if authentication succeeded. -DAST will test for the absence of a login form if no verification checks are configured. +DAST tests for the absence of a login form if no verification checks are configured. #### Verify based on the URL Define `DAST_AUTH_VERIFICATION_URL` as the URL displayed in the browser tab once the login form is successfully submitted. -DAST will compare the verification URL to the URL in the browser after authentication. +DAST compares the verification URL to the URL in the browser after authentication. If they are not the same, authentication is unsuccessful. For example: @@ -270,7 +274,7 @@ dast: #### Verify based on presence of an element -Define `DAST_AUTH_VERIFICATION_SELECTOR` as a [selector](#finding-an-elements-selector) that will find one or many elements on the page +Define `DAST_AUTH_VERIFICATION_SELECTOR` as a [selector](#finding-an-elements-selector) that finds one or many elements on the page displayed once the login form is successfully submitted. If no element is found, authentication is unsuccessful. Searching for the selector on the page displayed when login fails should return no elements. @@ -333,8 +337,8 @@ dast: ## Known limitations -- DAST cannot bypass a CAPTCHA if the authentication flow includes one. Please turn these off in the testing environment for the application being scanned. -- DAST cannot handle multi-factor authentication like one-time passwords (OTP) by using SMS, biometrics, or authenticator apps. Please turn these off in the testing environment for the application being scanned. +- DAST cannot bypass a CAPTCHA if the authentication flow includes one. Turn these off in the testing environment for the application being scanned. +- DAST cannot handle multi-factor authentication like one-time passwords (OTP) by using SMS, biometrics, or authenticator apps. Turn these off in the testing environment for the application being scanned. - DAST cannot authenticate to applications that do not set an [authentication token](#authentication-tokens) during login. - DAST cannot authenticate to applications that require more than two inputs to be filled out. Two inputs must be supplied, username and password. diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index 96480bcb6a5..bdc08988cc0 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -227,13 +227,13 @@ In such cases, we recommend you disable Anti-CSRF tokens when running a full sca ## Managing scan time -It is expected that running the browser-based crawler results in better coverage for many web applications, when compared to the normal GitLab DAST solution. +It is expected that running the browser-based crawler results in better coverage for many web applications, when compared to the standard 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-cicd-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-cicd-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`. +- Limit the page depth that the browser-based crawler checks coverage on with the [variable](#available-cicd-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 scale the runner and use a higher number of browsers with [variable](#available-cicd-variables) `DAST_BROWSER_NUMBER_OF_BROWSERS`. The default is `3`. ## Timeouts diff --git a/doc/user/application_security/dast/browser_based_troubleshooting.md b/doc/user/application_security/dast/browser_based_troubleshooting.md index 78f2723ee38..6cc80bcfbc3 100644 --- a/doc/user/application_security/dast/browser_based_troubleshooting.md +++ b/doc/user/application_security/dast/browser_based_troubleshooting.md @@ -53,7 +53,7 @@ Knowing the outcome you expect, try to replicate it manually using a browser on DAST cannot scan correctly when: -- There is a CAPTCHA. Please turn these off in the testing environment for the application being scanned. +- There is a CAPTCHA. Turn these off in the testing environment for the application being scanned. - It does not have access to the target application. Ensure the GitLab Runner can access the application using the URLs used in the DAST configuration. ### How does your application work? diff --git a/doc/user/application_security/dast/checks/16.7.md b/doc/user/application_security/dast/checks/16.7.md index cef13c9663f..d407234d2c2 100644 --- a/doc/user/application_security/dast/checks/16.7.md +++ b/doc/user/application_security/dast/checks/16.7.md @@ -25,8 +25,7 @@ Only three directives are applicable for the `Strict-Transport-Security` header. Note that invalid directives, or the `Strict-Transport-Security` header appearing more than once (if the values are different) is considered invalid. -Prior to adding to this security configuration to your website, it is recommended you review the hstspreload.org -[Deployment Recommendations](https://hstspreload.org/#deployment-recommendations). +Prior to adding to this security configuration to your website, it is recommended you review the hstspreload.org [Deployment Recommendations](https://hstspreload.org/#deployment-recommendations). ## Details diff --git a/doc/user/application_security/dast/checks/16.8.md b/doc/user/application_security/dast/checks/16.8.md index 07bd2a6842f..b8faef75de7 100644 --- a/doc/user/application_security/dast/checks/16.8.md +++ b/doc/user/application_security/dast/checks/16.8.md @@ -8,12 +8,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Description -A `Content-Security-Policy` (CSP) was identified on the target site. CSP can aid in hardening -a website against various client side attacks such as Cross-Site Scripting (XSS). +A missing or invalid `Content-Security-Policy` (CSP) was identified on the target site. CSP can aid in +hardening a website against various client side attacks such as Cross-Site Scripting (XSS). ## Remediation -Follow the recommendations to determine if any actions are necessary to harden this `Content-Security-Policy`. +If the target site is missing a CSP, please investigate the relevant URLs for enabling CSP. Otherwise, +follow the recommendations to determine if any actions are necessary. ## Details diff --git a/doc/user/application_security/dast/checks/22.1.md b/doc/user/application_security/dast/checks/22.1.md new file mode 100644 index 00000000000..60a73b4248b --- /dev/null +++ b/doc/user/application_security/dast/checks/22.1.md @@ -0,0 +1,38 @@ +--- +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/product/ux/technical-writing/#assignments +--- + +# Improper limitation of a pathname to a restricted directory (Path traversal) + +## Description + +The vulnerability can be exploited by inserting a payload into a +parameter on the URL endpoint which allows for reading arbitrary files. +This could be used to read sensitive files, access other users data, or aid in +exploitation to gain further system access. + +## Remediation + +User input should never be used in constructing paths or files for interacting +with the filesystem. This includes filenames supplied by user uploads or downloads. + +If possible, consider hashing the filenames and reference the hashed filenames in +a database or datastore instead of directly attempting to access filenames provided +by users or other system components. + +In the rare cases that the application must work with filenames, use the language +provided functionality to extract only the filename part of the supplied value. +Never attempt to use the path or directory information that comes from user input. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 22.1 | false | 22 | Active | high | + +## Links + +- [OWASP](https://owasp.org/www-community/attacks/Path_Traversal) +- [CWE](https://cwe.mitre.org/data/definitions/22.html) diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md index 56406b24586..bafe426ca43 100644 --- a/doc/user/application_security/dast/checks/index.md +++ b/doc/user/application_security/dast/checks/index.md @@ -8,6 +8,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w The [DAST browser-based crawler](../browser_based.md) provides a number of vulnerability checks that are used to scan for vulnerabilities in the site under test. +## Passive Checks + | ID | Check | Severity | Type | |:---|:------|:---------|:-----| | [1004.1](1004.1.md) | Sensitive cookie without HttpOnly attribute | Low | Passive | @@ -126,7 +128,7 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | [798.94](798.94.md) | Exposure of confidential secret or token Private Key | High | Passive | | [798.95](798.95.md) | Exposure of confidential secret or token Pulumi API token | High | Passive | | [798.96](798.96.md) | Exposure of confidential secret or token PyPI upload token | High | Passive | -| [798.97](798.97.md) | Exposure of confidential secret or token RubyGem API token | High | Passive | +| [798.97](798.97.md) | Exposure of confidential secret or token RubyGems API token | High | Passive | | [798.98](798.98.md) | Exposure of confidential secret or token RapidAPI Access Token | High | Passive | | [798.99](798.99.md) | Exposure of confidential secret or token Sendbird Access ID | High | Passive | | [798.100](798.100.md) | Exposure of confidential secret or token Sendbird Access Token | High | Passive | @@ -160,3 +162,9 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | [798.128](798.128.md) | Exposure of confidential secret or token Zendesk Secret Key | High | Passive | | [829.1](829.1.md) | Inclusion of Functionality from Untrusted Control Sphere | Low | Passive | | [829.2](829.2.md) | Invalid Sub-Resource Integrity values detected | Medium | Passive | + +## Active Checks + +| ID | Check | Severity | Type | +|:---|:------|:---------|:-----| +| [22.1](22.1.md) | Improper limitation of a pathname to a restricted directory (Path traversal) | High | Active | diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md index 0dcf203a3a9..da382920604 100644 --- a/doc/user/application_security/dast/dast_troubleshooting.md +++ b/doc/user/application_security/dast/dast_troubleshooting.md @@ -77,7 +77,7 @@ For information on this, see the [general Application Security troubleshooting s To avoid overwriting stages from other CI files, newer versions of the DAST CI template do not define stages. If you recently started using `DAST.latest.gitlab-ci.yml` or upgraded to a new major release of GitLab and began receiving this error, you must define a `dast` stage with your other -stages. Note that you must have a running application for DAST to scan. If your application is set +stages. You must have a running application for DAST to scan. If your application is set up in your pipeline, it must be deployed in a stage _before_ the `dast` stage: ```yaml diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 283e48ec499..3cb8967afd2 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -57,7 +57,7 @@ which GitLab uses to determine discovered vulnerabilities based on differences b #### Recommendations -- Take care if your pipeline is configured to deploy to the same web server in each run. Running a DAST scan while a server is being updated will lead to inaccurate and non-deterministic results. +- Take care if your pipeline is configured to deploy to the same web server in each run. Running a DAST scan while a server is being updated leads to inaccurate and non-deterministic results. - Configure runners to use the [always pull policy](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy) to run the latest versions of the analyzers. - By default, DAST downloads all artifacts defined by previous jobs in the pipeline. If your DAST job does not rely on `environment_url.txt` to define the URL under test or any other files created @@ -71,7 +71,7 @@ which GitLab uses to determine discovered vulnerabilities based on differences b #### Analyzer configuration -Please see [DAST proxy-based analyzer](proxy-based.md), [DAST browser-based analyzer](browser_based.md) or [DAST API analyzer](../dast_api/index.md) for +See [DAST proxy-based analyzer](proxy-based.md), [DAST browser-based analyzer](browser_based.md) or [DAST API analyzer](../dast_api/index.md) for analyzer-specific configuration instructions. ### View scan results @@ -83,8 +83,8 @@ and the [Vulnerability report](../index.md#view-security-scan-information-in-the 1. To see all vulnerabilities detected, either: - From your project, select **Security & Compliance**, then **Vulnerability report**. - - From your pipeline, click on the **Security** tab. - - From the merge request, go to the **Security scanning** widget and click **Full report** tab. + - From your pipeline, select the **Security** tab. + - From the merge request, go to the **Security scanning** widget and select **Full report** tab. 1. Select a DAST vulnerability's description. The following fields are examples of what a DAST analyzer may produce to aid investigation and rectification of the underlying cause. Each analyzer may output different fields. @@ -142,7 +142,7 @@ After your Docker build job completes and your image is added to your container By using service definitions in your `.gitlab-ci.yml`, you can scan services with the DAST analyzer. -When adding a `services` section to the job, the `alias` is used to define the hostname that can be used to access the service. In the following example, the `alias: yourapp` portion of the `dast` job definition means that the URL to the deployed application will use `yourapp` as the hostname (`https://yourapp/`). +When adding a `services` section to the job, the `alias` is used to define the hostname that can be used to access the service. In the following example, the `alias: yourapp` portion of the `dast` job definition means that the URL to the deployed application uses `yourapp` as the hostname (`https://yourapp/`). ```yaml stages: diff --git a/doc/user/application_security/dast/proxy-based.md b/doc/user/application_security/dast/proxy-based.md index fc78018bdad..f70afac4c26 100644 --- a/doc/user/application_security/dast/proxy-based.md +++ b/doc/user/application_security/dast/proxy-based.md @@ -9,7 +9,7 @@ type: reference, howto The DAST proxy-based analyzer can be added to your [GitLab CI/CD](../../../ci/index.md) pipeline. This helps you discover vulnerabilities in web applications that do not use JavaScript heavily. For applications that do, -please see the [DAST browser-based analyzer](browser_based.md). +see the [DAST browser-based analyzer](browser_based.md). WARNING: Do not run DAST scans against a production server. Not only can it perform *any* function that @@ -231,7 +231,7 @@ variables: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. To specify the paths to scan in a CI/CD variable, add a comma-separated list of the paths to the `DAST_PATHS` -variable. Note that you can only scan paths of a single host. +variable. You can only scan paths of a single host. ```yaml include: @@ -247,7 +247,7 @@ When using `DAST_PATHS` and `DAST_PATHS_FILE`, note the following: - `DAST_WEBSITE` must be defined when using either `DAST_PATHS_FILE` or `DAST_PATHS`. The paths listed in either use `DAST_WEBSITE` to build the URLs to scan - Spidering is disabled when `DAST_PATHS` or `DAST_PATHS_FILE` are defined - `DAST_PATHS_FILE` and `DAST_PATHS` cannot be used together -- The `DAST_PATHS` variable has a limit of about 130kb. If you have a list or paths +- The `DAST_PATHS` variable has a limit of about 130 kb. If you have a list or paths greater than this, use `DAST_PATHS_FILE`. #### Full Scan @@ -360,13 +360,14 @@ including a large number of false positives. |:------------------------------------------------|:--------------|:------------------------------| | `DAST_ADVERTISE_SCAN` | boolean | Set to `true` to add a `Via` header to every request sent, advertising that the request was sent as part of a GitLab DAST scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334947) in GitLab 14.1. | | `DAST_AGGREGATE_VULNERABILITIES` | boolean | Vulnerability aggregation is set to `true` by default. To disable this feature and see each vulnerability individually set to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254043) in GitLab 14.0. | +| `DAST_ALLOWED_HOSTS` | Comma-separated list of strings | Hostnames included in this variable are considered in scope when crawled. By default the `DAST_WEBSITE` hostname is included in the allowed hosts list. Headers set using `DAST_REQUEST_HEADERS` are added to every request made to these hostnames. Example, `site.com,another.com`. | | `DAST_API_HOST_OVERRIDE` <sup>1</sup> | string | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383467)** in GitLab 15.7. Replaced by [DAST API scan](../dast_api/index.md#available-cicd-variables). Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080`. | | `DAST_API_SPECIFICATION` <sup>1</sup> | URL or string | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383467)** in GitLab 15.7. Replaced by [DAST API scan](../dast_api/index.md#available-cicd-variables). 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. The variable `DAST_WEBSITE` must be specified if this is omitted. | | `DAST_AUTH_EXCLUDE_URLS` | URLs | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289959)** in GitLab 14.0. Replaced by `DAST_EXCLUDE_URLS`. The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. | | `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_DEBUG` <sup>1</sup> | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | -| `DAST_EXCLUDE_URLS` <sup>1</sup> | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Example, `http://example.com/sign-out`. | +| `DAST_EXCLUDE_URLS` <sup>1</sup> | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Example, `http://example.com/sign-out`. | | `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293595)** in GitLab 14.0. Set to `true` to require domain validation when running DAST full scans. Default: `false` | | `DAST_FULL_SCAN_ENABLED` <sup>1</sup> | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | | `DAST_HTML_REPORT` | string | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/384340)** in GitLab 15.7. The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | @@ -427,7 +428,7 @@ dast: The ZAProxy server contains many [useful configurable values](https://gitlab.com/gitlab-org/gitlab/-/issues/36437#note_245801885). Many key/values for `-config` remain undocumented, but there is an untested list of [possible keys](https://gitlab.com/gitlab-org/gitlab/-/issues/36437#note_244981023). -Note that these options are not supported by DAST, and may break the DAST scan +These options are not supported by DAST, and may break the DAST scan when used. An example of how to rewrite the Authorization header value with `TOKEN` follows: ```yaml diff --git a/doc/user/application_security/dast/run_dast_offline.md b/doc/user/application_security/dast/run_dast_offline.md index 7cb4eff8e68..a75e5832b7c 100644 --- a/doc/user/application_security/dast/run_dast_offline.md +++ b/doc/user/application_security/dast/run_dast_offline.md @@ -20,7 +20,7 @@ To use DAST in an offline environment, you need: [container image](https://gitlab.com/security-products/dast), found in the [DAST container registry](https://gitlab.com/security-products/dast/container_registry). -Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), +GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), meaning the runner tries to pull Docker images from the GitLab container registry even if a local copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we @@ -34,7 +34,7 @@ For DAST, import the following default DAST analyzer image from `registry.gitlab - `registry.gitlab.com/security-products/dast: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 +**your network security policy**. Consult your IT staff to find an accepted and approved process by which external resources can be imported or temporarily accessed. These scanners are [periodically updated](../index.md#vulnerability-scanner-maintenance) with new definitions, and you may be able to make occasional updates on your own. diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 4c324033140..0cdbb879cfc 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -5,13 +5,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# DAST API **(ULTIMATE)** +# DAST API analyzer **(ULTIMATE)** > DAST API analyzer [became the default analyzer for on-demand DAST API scans](https://gitlab.com/groups/gitlab-org/-/epics/4254) in GitLab 15.6. Perform Dynamic Application Security Testing (DAST) of web APIs to help discover bugs and potential security issues that other QA processes may miss. Use DAST API tests in addition to -[GitLab Secure](../index.md)'s other security scanners and your own test processes. You can run DAST +other [GitLab Secure](../index.md) security scanners and your own test processes. You can run DAST API tests either as part your CI/CD workflow, [on-demand](../dast/proxy-based.md#on-demand-scans), or both. WARNING: @@ -1161,7 +1161,7 @@ Example usage for setting a `body-json` override: } ``` -Note that each JSON property name in the object `body-json` is set to a [JSON Path](https://goessner.net/articles/JsonPath/) +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. @@ -1200,7 +1200,7 @@ the second entry overrides an XML element: } ``` -Note that each JSON property name in the object `body-xml` is set to an +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 @@ -1340,7 +1340,7 @@ By default the output of the overrides command is hidden. If the overrides comma It is also possible to write messages from your script to a log file that is collected when the job completes or fails. The log file must be created in a specific location and following a naming convention. -Adding some basic logging to your overrides script is useful in case the script fails unexpectedly during normal running of the job. The log file is automatically included as an artifact of the job, allowing you to download it after the job has finished. +Adding some basic logging to your overrides script is useful in case the script fails unexpectedly during standard running of the job. The log file is automatically included as an artifact of the job, allowing you to download it after the job has finished. Following our example, we provided `renew_token.py` in the environment variable `DAST_API_OVERRIDES_CMD`. Notice two things in the script: @@ -1449,7 +1449,7 @@ logging.info("Override file has been updated") # end ``` -In the overrides command example, the Python script depends on the `backoff` library. To make sure the library is installed before executing the Python script, the `DAST_API_PRE_SCRIPT` is set to a script that will install the dependencies of your overrides command. +In the overrides command example, the Python script depends on the `backoff` library. To make sure the library is installed before executing the Python script, the `DAST_API_PRE_SCRIPT` is set to a script that installs the dependencies of your overrides command. As for example, the following script `user-pre-scan-set-up.sh` ```shell @@ -1495,7 +1495,7 @@ In the previous sample, you could use the script `user-pre-scan-set-up.sh` to al The request headers feature lets you specify fixed values for the headers during the scan session. For example, you can use the configuration variable `DAST_API_REQUEST_HEADERS` to set a fixed value in the `Cache-Control` header. If the headers you need to set include sensitive values like the `Authorization` header, use the [masked variable](../../../ci/variables/index.md#mask-a-cicd-variable) feature along with the [variable `DAST_API_REQUEST_HEADERS_BASE64`](#base64). -Note that if the `Authorization` header or any other header needs to get updated while the scan is in progress, consider using the [overrides](#overrides) feature. +If the `Authorization` header or any other header needs to get updated while the scan is in progress, consider using the [overrides](#overrides) feature. The variable `DAST_API_REQUEST_HEADERS` lets you specify a comma-separated (`,`) list of headers. These headers are included on each request that the scanner performs. Each header entry in the list consists of a name followed by a colon (`:`) and then by its value. Whitespace before the key or value is ignored. For example, to declare a header name `Cache-Control` with the value `max-age=604800`, the header entry is `Cache-Control: max-age=604800`. To use two headers, `Cache-Control: max-age=604800` and `Age: 100`, set `DAST_API_REQUEST_HEADERS` variable to `Cache-Control: max-age=604800, Age: 100`. @@ -1606,7 +1606,7 @@ variables: While testing an API you may might want to exclude a parameter (query string, header, or body element) from testing. This may be needed because a parameter always causes a failure, slows down testing, or for other reasons. To exclude parameters, you can set one of the following variables: `DAST_API_EXCLUDE_PARAMETER_ENV` or `DAST_API_EXCLUDE_PARAMETER_FILE`. -The `DAST_API_EXCLUDE_PARAMETER_ENV` allows providing a JSON string containing excluded parameters. This is a good option if the JSON is short and will not often change. Another option is the variable `DAST_API_EXCLUDE_PARAMETER_FILE`. This variable is set to a file path that can be checked into the repository, created by another job as an artifact, or generated at runtime with a pre-script using `DAST_API_PRE_SCRIPT`. +The `DAST_API_EXCLUDE_PARAMETER_ENV` allows providing a JSON string containing excluded parameters. This is a good option if the JSON is short and does not change often. Another option is the variable `DAST_API_EXCLUDE_PARAMETER_FILE`. This variable is set to a file path that can be checked into the repository, created by another job as an artifact, or generated at runtime with a pre-script using `DAST_API_PRE_SCRIPT`. #### Exclude parameters using a JSON document @@ -1833,7 +1833,7 @@ The `dast-api-exclude-parameters.json` is a JSON document that follows the struc > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357195) in GitLab 14.10. -As an alternative to excluding by paths, you can filter by any other component in the URL by using the `DAST_API_EXCLUDE_URLS` CI/CD variable. This variable can be set in your `.gitlab-ci.yml` file. The variable can store multiple values, separated by commas (`,`). Each value is a regular expression. Because each entry is a regular expression, an entry like `.*` will exclude all URLs because it is a regular expression that matches everything. +As an alternative to excluding by paths, you can filter by any other component in the URL by using the `DAST_API_EXCLUDE_URLS` CI/CD variable. This variable can be set in your `.gitlab-ci.yml` file. The variable can store multiple values, separated by commas (`,`). Each value is a regular expression. Because each entry is a regular expression, an entry like `.*` excludes all URLs because it is a regular expression that matches everything. In your job output you can check if any URLs matched any provided regular expression from `DAST_API_EXCLUDE_URLS`. Matching operations are listed in the **Excluded Operations** section. Operations listed in the **Excluded Operations** should not be listed in the **Tested Operations** section. For example the following portion of a job output: @@ -1888,7 +1888,7 @@ variables: ##### Excluding two URLs and their child resources -In order to exclude the URLs: `http://target/api/buy` and `http://target/api/sell`, and their child resources. To provide multiple URLs we use the `,` character as follows: +To exclude the URLs: `http://target/api/buy` and `http://target/api/sell`, and their child resources. To provide multiple URLs we use the `,` character as follows: ```yaml stages: @@ -1905,7 +1905,7 @@ variables: ##### Excluding URL using regular expressions -In order to exclude exactly `https://target/api/v1/user/create` and `https://target/api/v2/user/create` or any other version (`v3`,`v4`, and more). We could use `https://target/api/v.*/user/create$`, in the previous regular expression `.` indicates any character and `*` indicates zero or more times, additionally `$` indicates that the URL should end there. +To exclude exactly `https://target/api/v1/user/create` and `https://target/api/v2/user/create` or any other version (`v3`,`v4`, and more). We could use `https://target/api/v.*/user/create$`, in the previous regular expression `.` indicates any character and `*` indicates zero or more times, additionally `$` indicates that the URL should end there. ```yaml stages: @@ -1922,7 +1922,7 @@ variables: ## 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. +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 typical 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. @@ -1941,7 +1941,7 @@ 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** + - In a project, go to the project's **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 select the **Expand** button. DAST API vulnerabilities are available in a section labeled @@ -1957,7 +1957,7 @@ Follow these steps to view details of a vulnerability: | 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. | + | Unmodified Response | Response from an unmodified request. This is what a typical 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. | @@ -2274,7 +2274,7 @@ dast_api_v2: In the case of one or two slow operations, the team might decide to skip testing the operations, or exclude them from feature branch tests, but include them for default branch tests. Excluding the operation is done using the `DAST_API_EXCLUDE_PATHS` configuration [variable as explained in this section.](#exclude-paths) -In this example, we have an operation that returns a large amount of data. The operation is `GET http://target:7777/api/large_response_json`. To exclude it we provide the `DAST_API_EXCLUDE_PATHS` configuration variable with the path portion of our operation URL `/api/large_response_json`. Our configuration disables the main `dast_api` job and creates two new jobs `dast_api_main` and `dast_api_branch`. The `dast_api_branch` is set up to exclude the long operation and only run on non-default branches (e.g. feature branches). The `dast_api_main` branch is set up to only execute on the default branch (`main` in this example). The `dast_api_branch` jobs run faster, allowing for quick development cycles, while the `dast_api_main` job which only runs on default branch builds, takes longer to run. +In this example, we have an operation that returns a large amount of data. The operation is `GET http://target:7777/api/large_response_json`. To exclude it we provide the `DAST_API_EXCLUDE_PATHS` configuration variable with the path portion of our operation URL `/api/large_response_json`. Our configuration disables the main `dast_api` job and creates two new jobs `dast_api_main` and `dast_api_branch`. The `dast_api_branch` is set up to exclude the long operation and only run on non-default branches (for example, feature branches). The `dast_api_main` branch is set up to only execute on the default branch (`main` in this example). The `dast_api_branch` jobs run faster, allowing for quick development cycles, while the `dast_api_main` job which only runs on default branch builds, takes longer to run. To verify the operation is excluded, run the DAST API job and review the job console output. It includes a list of included and excluded operations at the end of the test. @@ -2368,7 +2368,7 @@ The DAST API engine outputs an error message when it cannot establish a connecti **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. +- Remove the `DAST_API_API` variable from the `.gitlab-ci.yml` file. The value inherits 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. ### `Failed to start session with scanner. Please retry, and if the problem persists reach out to support.` @@ -2412,9 +2412,9 @@ Once you have confirmed the issue was produced because the port was already take 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. +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 tries to use the `DAST_API_TARGET_URL`. If the environment variable has not been set, then the DAST API engine attempts to use the `environment_url.txt` file. If there is no file `environment_url.txt`, then the DAST API engine uses 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 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. +The best-suited solution depends 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 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 @@ -2498,7 +2498,7 @@ variables: ### `No operation in the OpenAPI document is consuming any supported media type` -DAST API uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error will be thrown. +DAST API uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error is thrown. **Error message** diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 9fffdec2612..b86d98471ac 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -81,7 +81,7 @@ You can download your project's full list of dependencies and their details in ### In the UI -You can download your project's list of dependencies and their details in JSON format by selecting the **Export** button. Note that the dependency list only shows the results of the last successful pipeline to run on the default branch. +You can download your project's list of dependencies and their details in JSON format by selecting the **Export** button. The dependency list only shows the results of the last successful pipeline to run on the default branch. ### Using the API diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index d13c4cecdf4..4feac0cb5e6 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -100,7 +100,7 @@ The following table lists the data available for the Gemnasium analyzer. | Property \ Tool | Gemnasium | |---------------------------------------|:------------------:| -| Severity | 𐄂 | +| Severity | ✓ | | Title | ✓ | | File | ✓ | | Start line | 𐄂 | diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 8106201cb99..579dd4dfc4f 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -59,7 +59,7 @@ possible, we encourage you to use all of our security scanning tools: Turning this variable on can result in some duplicate findings, as we do not yet de-duplicate results between Container Scanning and Dependency Scanning. For more details, efforts to de-duplicate these findings can be tracked in - [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/348655). + [this epic](https://gitlab.com/groups/gitlab-org/-/epics/8026). The following table summarizes which types of dependencies each scanning tool can detect: @@ -155,23 +155,14 @@ table.supported-languages ul { </thead> <tbody> <tr> - <td>Ruby</td> - <td>All versions</td> - <td><a href="https://bundler.io/">Bundler</a></td> - <td> - <ul> - <li><code>Gemfile.lock</code></li> - <li><code>gems.locked</code></li> - </ul> - </td> - <td>Y</td> + <td>.NET</td> + <td rowspan="2">All versions</td> + <td rowspan="2"><a href="https://www.nuget.org/">NuGet</a></td> + <td rowspan="2"><a href="https://learn.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file"><code>packages.lock.json</code></a></td> + <td rowspan="2">Y</td> </tr> <tr> - <td>PHP</td> - <td>All versions</td> - <td><a href="https://getcomposer.org/">Composer</a></td> - <td><code>composer.lock</code></td> - <td>Y</td> + <td>C#</td> </tr> <tr> <td>C</td> @@ -226,7 +217,7 @@ table.supported-languages ul { <td><a href="https://www.npmjs.com/">npm</a></td> <td> <ul> - <li><code>package-lock.json</code><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-3">3</a></b></sup></li> + <li><code>package-lock.json</code></li> <li><code>npm-shrinkwrap.json</code></li> </ul> </td> @@ -239,14 +230,11 @@ table.supported-languages ul { <td>Y</td> </tr> <tr> - <td>.NET</td> - <td rowspan="2">All versions</td> - <td rowspan="2"><a href="https://www.nuget.org/">NuGet</a></td> - <td rowspan="2"><a href="https://learn.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file"><code>packages.lock.json</code></a></td> - <td rowspan="2">Y</td> - </tr> - <tr> - <td>C#</td> + <td>PHP</td> + <td>All versions</td> + <td><a href="https://getcomposer.org/">Composer</a></td> + <td><code>composer.lock</code></td> + <td>Y</td> </tr> <tr> <td rowspan="4">Python</td> @@ -282,6 +270,18 @@ table.supported-languages ul { <td>N</td> </tr> <tr> + <td>Ruby</td> + <td>All versions</td> + <td><a href="https://bundler.io/">Bundler</a></td> + <td> + <ul> + <li><code>Gemfile.lock</code></li> + <li><code>gems.locked</code></li> + </ul> + </td> + <td>Y</td> + </tr> + <tr> <td>Scala</td> <td>All versions</td> <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-6">6</a></b></sup></td> @@ -307,16 +307,10 @@ table.supported-languages ul { </p> </li> <li> - <a id="notes-regarding-supported-languages-and-package-managers-3"></a> - <p> - npm is supported for <code>lockfileVersion = 1</code>, <code>lockfileVersion = 2</code>, and <code>lockfileVersion = 3</code>. Support for <code>lockfileVersion = 3</code> was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/365176">introduced</a> in GitLab 15.7. - </p> - </li> - <li> <a id="notes-regarding-supported-languages-and-package-managers-4"></a> <p> The presence of a <code>Pipfile.lock</code> file alone will <i>not</i> trigger the analyzer; the presence of a <code>Pipfile</code> is - still required in order for the analyzer to be executed. However, if a <code>Pipfile.lock</code> file is found, it will be used by + still required in order for the analyzer to be executed. However, if a <code>Pipfile.lock</code> file is found, it is used by <code>Gemnasium</code> to scan the exact package versions listed in this file. </p> <p> @@ -360,7 +354,7 @@ The following package managers use lockfiles that GitLab analyzers are capable o | Conan | 0.4 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/c-conan/default/conan.lock#L38) | | Go | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/go-modules/gosum/default/go.sum) <sup><strong><a href="#notes-regarding-parsing-lockfiles-1">1</a></strong></sup> | | NuGet | v1 | [4.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/csharp-nuget-dotnetcore/default/src/web.api/packages.lock.json#L2) | -| npm | v1, v2, v3 | [6.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/default/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/lockfileVersion2/package-lock.json#L4), [9.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/npm/fixtures/lockfile-v3/simple/package-lock.json#L4) | +| npm | v1, v2, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-2">2</a></b></sup> | [6.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/default/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/lockfileVersion2/package-lock.json#L4), [9.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/npm/fixtures/lockfile-v3/simple/package-lock.json#L4) | | yarn | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/default/yarn.lock#L2) | | Poetry | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/python-poetry/default/poetry.lock) | @@ -369,10 +363,16 @@ The following package managers use lockfiles that GitLab analyzers are capable o <li> <a id="notes-regarding-parsing-lockfiles-1"></a> <p> - Dependency Scanning will only parse <code>go.sum</code> if it's unable to generate the build list + Dependency Scanning only parses <code>go.sum</code> if it's unable to generate the build list used by the Go project. </p> </li> + <li> + <a id="notes-regarding-parsing-lockfiles-2"></a> + <p> + Support for <code>lockfileVersion = 3</code> was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/365176">introduced</a> in GitLab 15.7. + </p> + </li> </ol> <!-- markdownlint-enable MD044 --> @@ -431,7 +431,7 @@ To support the following package managers, the GitLab analyzers proceed in two s <li> <a id="exported-dependency-information-notes-3"></a> <p> - This test confirms that if a <code>Pipfile.lock</code> file is found, it will be used by <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a> to scan the exact package versions listed in this file. + This test confirms that if a <code>Pipfile.lock</code> file is found, it is used by <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a> to scan the exact package versions listed in this file. </p> </li> <li> @@ -659,7 +659,7 @@ The following variables are used for configuring specific analyzers (used for a #### Other variables -The previous tables are not an exhaustive list of all variables that can be used. They contain all specific GitLab and analyzer variables we support and test. There are many variables, such as environment variables, that you can pass in and they will work. This is a large list, many of which we may be unaware of, and as such is not documented. +The previous tables are not an exhaustive list of all variables that can be used. They contain all specific GitLab and analyzer variables we support and test. There are many variables, such as environment variables, that you can pass in and they do work. This is a large list, many of which we may be unaware of, and as such is not documented. For example, to pass the non-GitLab environment variable `HTTPS_PROXY` to all Dependency Scanning jobs, set it as a [CI/CD variable in your `.gitlab-ci.yml`](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) @@ -678,7 +678,7 @@ dependency_scanning: HTTPS_PROXY: $HTTPS_PROXY ``` -As we have not tested all variables you may find some will work and others will not. +As we have not tested all variables you may find some do work and others do not. If one does not work and you need it we suggest [submitting a feature request](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal%20-%20detailed&issue[title]=Docs%20feedback%20-%20feature%20proposal:%20Write%20your%20title) or [contributing to the code](../../../development/index.md) to enable it to be used. @@ -966,7 +966,7 @@ Here are the requirements for using dependency scanning in an offline environmen This advisory database is constantly being updated, so you must periodically sync your local copy with GitLab. -Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), +GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), meaning the runner tries to pull Docker images from the GitLab container registry even if a local copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we @@ -1262,7 +1262,7 @@ analyzers, edit your `.gitlab-ci.yml` file and either: [our current Dependency Scanning template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml#L18). - If you hardcoded the `DS_ANALYZER_IMAGE` variable directly, change it to match the latest line as found in our [current Dependency Scanning template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml). - The line number will vary depending on which scanning job you edited. + The line number varies depending on which scanning job you edited. For example, currently the `gemnasium-maven-dependency_scanning` job pulls the latest `gemnasium-maven` Docker image because `DS_ANALYZER_IMAGE` is set to @@ -1274,7 +1274,7 @@ Support for [2to3](https://docs.python.org/3/library/2to3.html) was [removed](https://setuptools.pypa.io/en/latest/history.html#v58-0-0) in `setuptools` version `v58.0.0`. Dependency Scanning (running `python 3.9`) uses `setuptools` version `58.1.0+`, which doesn't support `2to3`. Therefore, a `setuptools` dependency relying on -`lib2to3` will fail with this message: +`lib2to3` fails with this message: ```plaintext error in <dependency name> setup command: use_2to3 is invalid @@ -1313,12 +1313,12 @@ To avoid this error, follow [Poetry's configuration advice](https://python-poetr ### Error: Project has `<number>` unresolved dependencies -The error message `Project has <number> unresolved dependencies` indicates a dependency resolution problem caused by your `gradle.build` or `gradle.build.kts` file. In the current release, `gemnasium-maven` cannot continue processing when an unresolved dependency is encountered. However, There is an [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337083) to allow `gemnasium-maven` to recover from unresolved dependency errors and produce a dependency graph. Until this issue has been resolved, you'll need to consult the [Gradle dependency resolution docs](https://docs.gradle.org/current/userguide/dependency_resolution.html) for details on how to fix your `gradle.build` file. +The error message `Project has <number> unresolved dependencies` indicates a dependency resolution problem caused by your `gradle.build` or `gradle.build.kts` file. In the current release, `gemnasium-maven` cannot continue processing when an unresolved dependency is encountered. However, There is an [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337083) to allow `gemnasium-maven` to recover from unresolved dependency errors and produce a dependency graph. Until this issue has been resolved, consult the [Gradle dependency resolution docs](https://docs.gradle.org/current/userguide/dependency_resolution.html) for details on how to fix your `gradle.build` file. ### Setting build constraints when scanning Go projects Dependency scanning runs within a `linux/amd64` container. As a result, the build list generated -for a Go project will contain dependencies that are compatible with this environment. If your deployment environment is not +for a Go project contains dependencies that are compatible with this environment. If your deployment environment is not `linux/amd64`, the final list of dependencies might contain additional incompatible modules. The dependency list might also omit modules that are only compatible with your deployment environment. To prevent this issue, you can configure the build process to target the operating system and architecture of the deployment diff --git a/doc/user/application_security/get-started-security.md b/doc/user/application_security/get-started-security.md index 5774bf940b0..c1524c4b517 100644 --- a/doc/user/application_security/get-started-security.md +++ b/doc/user/application_security/get-started-security.md @@ -9,14 +9,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Adopting GitLab application security](https://www.youtube.com/watch?v=5QlxkiKR04k). -The following steps will help you get the most from GitLab application security tools. These steps are a recommended order of operations. You can choose to implement capabilities in a different order or omit features that do not apply to your specific needs. +The following steps help you get the most from GitLab application security tools. These steps are a recommended order of operations. You can choose to implement capabilities in a different order or omit features that do not apply to your specific needs. 1. Enable [Secret Detection](secret_detection/index.md) and [Dependency Scanning](dependency_scanning/index.md) to identify any leaked secrets and vulnerable packages in your codebase. - For all security scanners, enable them by updating your [`.gitlab-ci.yml`](../../ci/yaml/gitlab_ci_yaml.md) directly on your `default` branch. This creates a baseline scan of your `default` branch, which is necessary for feature branch scans to be compared against. This allows [merge requests](../project/merge_requests/index.md) - to display only newly-introduced vulnerabilities. Otherwise, merge requests will display every + to display only newly-introduced vulnerabilities. Otherwise, merge requests display every vulnerability in the branch, regardless of whether it was introduced by a change in the branch. - If you are after simplicity, enable only Secret Detection first. It only has one analyzer, no build requirements, and relatively simple findings: is this a secret or not? @@ -27,8 +27,9 @@ The following steps will help you get the most from GitLab application security 1. Consider creating [labels](../project/labels.md) and [issue boards](../project/issue_board.md) to help manage issues created from vulnerabilities. Issue boards allow all stakeholders to have a common view of all issues and track remediation progress. -1. Use [scheduled pipelines](../../ci/pipelines/schedules.md#scheduled-pipelines) to regularly scan important branches such as `default` or those used for maintenance releases. - - Running regular dependency and [container scans](container_scanning/index.md) will surface newly-discovered vulnerabilities that already exist in your repository. +1. Enforce scheduled security scanning jobs by using a [scan execution policy](policies/scan-execution-policies.md). + - These scheduled jobs run independently from any other security scans you may have defined in a compliance framework pipeline or in the project's `.gitlab-ci.yml` file. + - Running regular dependency and [container scans](container_scanning/index.md) surface newly-discovered vulnerabilities that already exist in your repository. - Scheduled scans are most useful for projects or important branches with low development activity where pipeline scans are infrequent. 1. Create a [scan result policy](policies/index.md) to limit new vulnerabilities from being merged into your `default` branch. @@ -36,7 +37,7 @@ The following steps will help you get the most from GitLab application security remediating existing vulnerabilities and preventing the introduction of new ones. 1. Enable other scan types such as [SAST](sast/index.md), [DAST](dast/index.md), [Fuzz testing](coverage_fuzzing/index.md), or [Container Scanning](container_scanning/index.md). -1. Use [Compliance Pipelines](../group/compliance_frameworks.md#configure-a-compliance-pipeline) +1. Use [Compliance Pipelines](../group/compliance_frameworks.md#compliance-pipelines) or [Scan Execution Policies](policies/scan-execution-policies.md) to enforce required scan types and ensure separation of duties between security and engineering. 1. Consider enabling [Review Apps](../../development/testing_guide/review_apps.md) to allow for DAST diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index 24448dc9668..c2f1257f989 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -16,7 +16,7 @@ IaC Scanning supports configuration files for Terraform, Ansible, AWS CloudForma IaC Scanning runs in the `test` stage, which is available by default. If you redefine the stages in the `.gitlab-ci.yml` file, the `test` stage is required. -We recommend a minimum of 4GB RAM to ensure consistent performance. +We recommend a minimum of 4 GB RAM to ensure consistent performance. To run IaC Scanning jobs, by default, you need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or @@ -24,7 +24,7 @@ To run IaC Scanning jobs, by default, you need GitLab Runner with the If you're using the shared runners on GitLab.com, this is enabled by default. WARNING: -Our IaC Scanning jobs require a Linux/amd64 container type. Windows containers are not supported. +GitLab IaC Scanning analyzers don't support running on Windows or on any CPU architectures other than amd64. WARNING: If you use your own runners, make sure the Docker version installed @@ -222,13 +222,13 @@ To override the automatic update behavior, set the `SAST_ANALYZER_IMAGE_TAG` CI/ in your CI/CD configuration file after you include the [`SAST-IaC.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST-IaC.gitlab-ci.yml). Only set this variable in a specific job. -If you set it [at the top level](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file), the version you set will be used for other SAST analyzers. +If you set it [at the top level](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file), the version you set is used for other SAST analyzers. You can set the tag to: -- A major version, like `3`. Your pipelines will use any minor or patch updates that are released within this major version. -- A minor version, like `3.7`. Your pipelines will use any patch updates that are released within this minor version. -- A patch version, like `3.7.0`. Your pipelines won't receive any updates. +- A major version, like `3`. Your pipelines use any minor or patch updates that are released within this major version. +- A minor version, like `3.7`. Your pipelines use any patch updates that are released within this minor version. +- A patch version, like `3.7.0`. Your pipelines don't receive any updates. This example uses a specific minor version of the `KICS` analyzer: @@ -241,6 +241,19 @@ kics-iac-sast: SAST_ANALYZER_IMAGE_TAG: "3.1" ``` +## Automatic vulnerability resolution + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368284) in GitLab 15.9 [with a project-level flag](../../../administration/feature_flags.md) named `sec_mark_dropped_findings_as_resolved`. Enabled by default on GitLab.com; disabled by default in self-managed. On GitLab.com, [contact Support](https://about.gitlab.com/support/) if you need to disable the flag for your project. + +To help you focus on the vulnerabilities that are still relevant, GitLab IaC Scanning automatically [resolves](../vulnerabilities/index.md#vulnerability-status-values) vulnerabilities when: + +- You [disable a predefined rule](#disable-predefined-analyzer-rules). +- We remove a rule from the default ruleset. + +The Vulnerability Management system leaves a comment on automatically-resolved vulnerabilities so you still have a historical record of the vulnerability. + +If you re-enable the rule later, the findings are reopened for triage. + ## Reports JSON format The IaC tool emits a JSON report file in the existing SAST report format. For more information, see the @@ -269,3 +282,8 @@ be ineffective or false positives, and the findings are marked as `No longer det - In GitLab 15.3, [secret detection in the KICS SAST IaC scanner was disabled](https://gitlab.com/gitlab-org/gitlab/-/issues/346181), so IaC findings in the "Passwords and Secrets" family show as `No longer detected`. + +### `exec /bin/sh: exec format error` message in job log + +The GitLab IaC Scanning analyzer [only supports](#requirements) running on the `amd64` CPU architecture. +This message indicates that the job is being run on a different architecture, such as `arm`. diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index a623b819b08..492b200d22b 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -4,7 +4,7 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Secure your application **(ULTIMATE)** +# Application security **(ULTIMATE)** GitLab can check your application for security vulnerabilities including: @@ -104,10 +104,10 @@ The following vulnerability scanners and their databases are regularly updated: | [Container Scanning](container_scanning/index.md) | A job runs on a daily basis to build new images with the latest vulnerability database updates from the upstream scanner. For more details, see [Vulnerabilities database update](container_scanning/index.md#vulnerabilities-database). | | [Dependency Scanning](dependency_scanning/index.md) | Relies on the [GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db). It is updated on a daily basis using [data from NVD, the `ruby-advisory-db` and the GitHub Advisory Database as data sources](https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/blob/master/SOURCES.md). 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/main/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. | +| [Static Application Security Testing (SAST)](sast/index.md) | The source of scan rules depends on which [analyzer](sast/analyzers.md) is used for each [supported programming language](sast/index.md#supported-languages-and-frameworks). GitLab maintains a ruleset for the Semgrep-based analyzer and updates it regularly based on internal research and user feedback. For other analyzers, the ruleset is sourced from the upstream open-source scanner. Each analyzer is updated at least once per month if a relevant update is available. | In versions of GitLab that use the same major version of the analyzer, you do not have to update -GitLab to benefit from the latest vulnerabilities definitions. The security tools are released as +them 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. Although in a major analyzer version you automatically get the latest versions of the scanning @@ -130,7 +130,7 @@ While you cannot directly customize Auto DevOps, you can [include the Auto DevOp ## Security scanning without Auto DevOps -To enable all GitLab security scanning tools, with the option of customizing settings, add the +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. WARNING: @@ -164,7 +164,7 @@ variables: By default, GitLab security scanners use `registry.gitlab.com/security-products` as the base address for Docker images. You can override this for most scanners by setting the CI/CD variable -`SECURE_ANALYZERS_PREFIX` to another location. Note that this affects all scanners at once. +`SECURE_ANALYZERS_PREFIX` to another location. This affects all scanners at once. The [Container Scanning](container_scanning/index.md) analyzer is an exception, and it does not use the `SECURE_ANALYZERS_PREFIX` variable. To override its Docker image, see @@ -179,7 +179,7 @@ you must reference the [`latest` templates](../../development/cicd/templates.md) All `latest` security templates support merge request pipelines. -For example, to run both SAST and Dependency Scanning: +For example, to run both SAST and Dependency Scanning, the following template is used: ```yaml include: @@ -205,7 +205,7 @@ that rely on this scan data only show results from pipelines on the default bran Our language and package manager specific jobs attempt to assess which analyzers they should run for your project so that you can do less configuration. -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. +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. ### Secure job status @@ -242,7 +242,7 @@ reports are available to download. To download a report, select A merge request contains a security widget which displays a summary of the new results. New results are determined by comparing the findings of the merge request against the findings of the most recent completed pipeline (`success`, `failed`, `canceled` or `skipped`) for the latest commit in the target branch. -If security scans have not run for the most recent completed pipeline in the target branch there is no base for comparison. The vulnerabilities from the merge request findings will be listed as new in the merge request security widget. We recommend you run a scan of the `default` (target) branch before enabling feature branch scans for your developers. +If security scans have not run for the most recent completed pipeline in the target branch there is no base for comparison. The vulnerabilities from the merge request findings are listed as new in the merge request security widget. We recommend you run a scan of the `default` (target) branch before enabling feature branch scans for your developers. 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. @@ -280,7 +280,7 @@ security issues: - A security vulnerability. For more details, read [Scan result policies](policies/scan-result-policies.md). - A software license compliance violation. For more details, read - [Enabling license approvals within a project](../compliance/license_compliance/index.md#enabling-license-approvals-within-a-project). + [Enabling license approvals within a project](../compliance/license_check_rules.md#enabling-license-approvals-within-a-project). ## Using private Maven repositories @@ -397,7 +397,7 @@ To fix this issue, you can either: - echo "custom job" ``` -Learn more on overriding security jobs: +For more information about overriding security jobs, see: - [Overriding SAST jobs](sast/index.md#overriding-sast-jobs). - [Overriding Dependency Scanning jobs](dependency_scanning/index.md#overriding-dependency-scanning-jobs). @@ -443,9 +443,9 @@ You can always find supported and deprecated schema versions in the [source code You can interact with the results of the security scanning tools in several locations: - [Scan information in merge requests](#view-security-scan-information-in-merge-requests) -- [Project Security Dashboard](security_dashboard/index.md) +- [Project Security Dashboard](security_dashboard/index.md#view-vulnerabilities-over-time-for-a-project) - [Security pipeline tab](security_dashboard/index.md) -- [Group Security Dashboard](security_dashboard/index.md) +- [Group Security Dashboard](security_dashboard/index.md#view-vulnerabilities-over-time-for-a-group) - [Security Center](security_dashboard/index.md#security-center) - [Vulnerability Report](vulnerability_report/index.md) - [Vulnerability Pages](vulnerabilities/index.md) @@ -487,7 +487,7 @@ Security and compliance teams must ensure that security scans: GitLab provides two methods of accomplishing this, each with advantages and disadvantages. -- [Compliance framework pipelines](../group/compliance_frameworks.md#configure-a-compliance-pipeline) +- [Compliance framework pipelines](../group/compliance_frameworks.md#compliance-pipelines) are recommended when: - Scan execution enforcement is required for any scanner that uses a GitLab template, such as SAST IaC, DAST, Dependency Scanning, @@ -516,7 +516,7 @@ Additional details about the differences between the two solutions are outlined | ------ | ------ | ------ | | **Flexibility** | Supports anything that can be done in a CI file. | Limited to only the items for which GitLab has explicitly added support. DAST, SAST, Secret Detection, Dependency Scanning, and Container Scanning scans are supported. | | **Usability** | Requires knowledge of CI YAML. | Follows a `rules` and `actions`-based YAML structure. | -| **Inclusion in CI pipeline** | The compliance pipeline is executed instead of the project's `.gitlab-ci.yml` file. To include the project's `.gitlab-ci.yml` file, use an `include` statement. Defined variables aren't allowed to be overwritten by the included project's YAML file. | Forced inclusion of a new job into the CI pipeline. DAST jobs that must be customized on a per-project basis can have project-level Site Profiles and Scan Profiles defined. To ensure separation of duties, these profiles are immutable when referenced in a scan execution policy. All jobs can be customized as part of the security policy itself with the same variables that are normally available to the CI job. | +| **Inclusion in CI pipeline** | The compliance pipeline is executed instead of the project's `.gitlab-ci.yml` file. To include the project's `.gitlab-ci.yml` file, use an `include` statement. Defined variables aren't allowed to be overwritten by the included project's YAML file. | Forced inclusion of a new job into the CI pipeline. DAST jobs that must be customized on a per-project basis can have project-level Site Profiles and Scan Profiles defined. To ensure separation of duties, these profiles are immutable when referenced in a scan execution policy. All jobs can be customized as part of the security policy itself with the same variables that are usually available to the CI job. | | **Schedulable** | Can be scheduled through a scheduled pipeline on the group. | Can be scheduled natively through the policy configuration itself. | | **Separation of Duties** | Only group owners can create compliance framework labels. Only project owners can apply compliance framework labels to projects. The ability to make or approve changes to the compliance pipeline definition is limited to individuals who are explicitly given access to the project that contains the compliance pipeline. | Only project owners can define a linked security policy project. The ability to make or approve changes to security policies is limited to individuals who are explicitly given access to the security policy project. | | **Ability to apply one standard to multiple projects** | The same compliance framework label can be applied to multiple projects inside a group. | The same security policy project can be used for multiple projects across GitLab with no requirement of being located in the same group. | @@ -602,7 +602,7 @@ To fix this issue, you must either: - [Transition your `only/except` syntax to `rules`](#transitioning-your-onlyexcept-syntax-to-rules). - (Temporarily) [Pin your templates to the deprecated versions](#pin-your-templates-to-the-deprecated-versions) -[Learn more on overriding SAST jobs](sast/index.md#overriding-sast-jobs). +For more information, see [Overriding SAST jobs](sast/index.md#overriding-sast-jobs). #### Transitioning your `only/except` syntax to `rules` @@ -664,7 +664,7 @@ spotbugs-sast: - if: $CI_COMMIT_TAG == null ``` -[Learn more on the usage of `rules`](../../ci/yaml/index.md#rules). +For more information, see [`rules`](../../ci/yaml/index.md#rules). #### Pin your templates to the deprecated versions @@ -702,7 +702,7 @@ The `sast` or `dependency_scanning` stanzas can be used to make changes to all S such as changing `variables` or the `stage`, but they cannot be used to define shared `rules`. There [is an issue open to improve extendability](https://gitlab.com/gitlab-org/gitlab/-/issues/218444). -Please upvote the issue to help with prioritization, and +You can upvote the issue to help with prioritization, and [contributions are welcomed](https://about.gitlab.com/community/contribute/). ### Empty Vulnerability Report, Dependency List, License list pages @@ -710,9 +710,9 @@ Please upvote the issue to help with prioritization, and If the pipeline has manual steps with a job that has the `allow_failure: false` option, and this job is not finished, GitLab can't populate listed pages with the data from security reports. In this case, [the Vulnerability Report](vulnerability_report/index.md), [the Dependency List](dependency_list/index.md), -and [the License list](../compliance/license_compliance/index.md#license-list) pages will be empty. +and [the License list](../compliance/license_list.md) pages are empty. These security pages can be populated by running the jobs from the manual step of the pipeline. There is [an issue open to handle this scenario](https://gitlab.com/gitlab-org/gitlab/-/issues/346843). -Please upvote the issue to help with prioritization, and +You can upvote the issue to help with prioritization, and [contributions are welcomed](https://about.gitlab.com/community/contribute/). diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 6976956758d..5a075bf731b 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -234,6 +234,6 @@ Once these steps are complete, GitLab has local copies of the Secure analyzers a them instead of an Internet-hosted container image. This allows you to run Secure in AutoDevOps in an offline environment. -Note that these steps are specific to GitLab Secure with AutoDevOps. Using other stages with +These steps are specific to GitLab Secure with AutoDevOps. Using other stages with AutoDevOps may require other steps covered in the [Auto DevOps documentation](../../../topics/autodevops/index.md). diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index c9c48c0c926..26c7e1d9c77 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -11,21 +11,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Operational container scanning [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3410) in GitLab 15.5 Group, subgroup, or project owners can use scan execution policies to require that security scans run on a specified -schedule or with the project (or multiple projects if the policy is defined at a group or subgroup level) pipeline. Required scans are injected into the CI pipeline as new jobs -with a long, random job name. In the unlikely event of a job name collision, the security policy job overwrites -any pre-existing job in the pipeline. If a policy is created at the group-level, it will apply to every child -project or subgroup. A group-level policy cannot be edited from a child project or subgroup. +schedule or with the project pipeline. The security scan runs with multiple project pipelines if you define the policy +at a group or subgroup level. GitLab injects the required scans into the CI pipeline as new jobs. In the event +of a job name collision, GitLab adds a dash and a number to the job name. GitLab increments the number until the name +no longer conflicts with existing job names. If you create a policy at the group level, it applies to every child project +or subgroup. You cannot edit a group-level policy from a child project or subgroup. -This feature has some overlap with [compliance framework pipelines](../../group/compliance_frameworks.md#configure-a-compliance-pipeline), +This feature has some overlap with [compliance framework pipelines](../../group/compliance_frameworks.md#compliance-pipelines), as we have not [unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). For details on the similarities and differences between these features, see [Enforce scan execution](../index.md#enforce-scan-execution). NOTE: -Policy jobs are created in the `test` stage of the pipeline. If you modify the default pipeline +Policy jobs for scans other than DAST scans are created in the `test` stage of the pipeline. If you modify the default pipeline [`stages`](../../../ci/yaml/index.md#stages), -you must ensure that the `test` stage exists in the list. Otherwise, the pipeline fails to run and -an error appears that states `chosen stage does not exist`. +to remove the `test` stage, jobs will run in the `scan-policies` stage instead. This stage is injected into the CI pipeline at evaluation time if it doesn't exist. If the `build` stage exists, it is injected just after the `build` stage. If the `build` stage does not exist, it is injected at the beginning of the pipeline. DAST scans always run in the `dast` stage. If this stage does not exist, then a `dast` stage is injected at the end of the pipeline. ## Scan execution policy editor @@ -89,7 +89,7 @@ This rule enforces the defined actions and schedules a scan on the provided date | `type` | `string` | `schedule` | The rule's type. | | `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). This field is required if the `agents` field is not set. | | `cadence` | `string` | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. | -| `agents` | `object` | | The name of the [GitLab agents](../../clusters/agent/index.md) where [cluster image scanning](../../clusters/agent/vulnerabilities.md) will run. The object key is the name of the Kubernetes agent configured for your project in GitLab. This field is required if the `branches` field is not set. | +| `agents` | `object` | | The name of the [GitLab agents](../../clusters/agent/index.md) where [Operational Container Scanning](../../clusters/agent/vulnerabilities.md) runs. The object key is the name of the Kubernetes agent configured for your project in GitLab. This field is required if the `branches` field is not set. | GitLab supports the following types of CRON syntax for the `cadence` field: @@ -97,10 +97,10 @@ GitLab supports the following types of CRON syntax for the `cadence` field: - A weekly cadence of once per week on a specified day and at a specified hour, for example: `0 13 * * 0` NOTE: -Other elements of the [CRON syntax]((https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm)) may work in the cadence field if supported by the [cron](https://github.com/robfig/cron) we are using in our implementation, however, GitLab does not officially test or support them. +Other elements of the [CRON syntax](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) may work in the cadence field if supported by the [cron](https://github.com/robfig/cron) we are using in our implementation, however, GitLab does not officially test or support them. NOTE: -If using the `agents` field, required for `Operational Container Scanning`, the CRON expression is evaluated in [UTC](https://www.timeanddate.com/worldclock/timezone/utc) using the system-time of the Kubernetes-agent pod. If not using the `agents` field, the CRON expression is evaluated in standard [UTC](https://www.timeanddate.com/worldclock/timezone/utc) time from GitLab.com. If you have a self-managed GitLab instance and have [changed the server timezone](../../../administration/timezone.md), the CRON expression is evaluated with the new timezone. +If using the `agents` field, required for `Operational Container Scanning`, the CRON expression is evaluated in [UTC](https://www.timeanddate.com/worldclock/timezone/utc) using the system-time of the Kubernetes-agent pod. If not using the `agents` field, the CRON expression is evaluated in standard [UTC](https://www.timeanddate.com/worldclock/timezone/utc) time from GitLab.com. If you have a self-managed GitLab instance and have [changed the server time zone](../../../administration/timezone.md), the CRON expression is evaluated with the new time zone. ### `agent` schema @@ -108,7 +108,7 @@ Use this schema to define `agents` objects in the [`schedule` rule type](#schedu | Field | Type | Possible values | Description | |--------------|---------------------|--------------------------|-------------| -| `namespaces` | `array` of `string` | | The namespace that is scanned. If empty, all namespaces will be scanned. | +| `namespaces` | `array` of `string` | | The namespace that is scanned. If empty, all namespaces are scanned. | #### Policy example @@ -129,9 +129,9 @@ Use this schema to define `agents` objects in the [`schedule` rule type](#schedu The keys for a schedule rule are: -- `cadence` (required): a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans will be run +- `cadence` (required): a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans are run - `agents:<agent-name>` (required): The name of the agent to use for scanning -- `agents:<agent-name>:namespaces` (optional): The Kubernetes namespaces to scan. If omitted, all namespaces will be scanned. +- `agents:<agent-name>:namespaces` (optional): The Kubernetes namespaces to scan. If omitted, all namespaces are scanned. ## `scan` action type @@ -144,7 +144,7 @@ rule in the defined policy are met. | `site_profile` | `string` | Name of the selected [DAST site profile](../dast/proxy-based.md#site-profile). | The DAST site profile to execute the DAST scan. This field should only be set if `scan` type is `dast`. | | `scanner_profile` | `string` or `null` | Name of the selected [DAST scanner profile](../dast/proxy-based.md#scanner-profile). | The DAST scanner profile to execute the DAST scan. This field should only be set if `scan` type is `dast`.| | `variables` | `object` | | A set of CI variables, supplied as an array of `key: value` pairs, to apply and enforce for the selected scan. The `key` is the variable name, with its `value` provided as a string. This parameter supports any variable that the GitLab CI job supports for the specified scan. | -| `tags` | `array` of `string` | | A list of runner tags for the policy. The policy jobs will be run by runner with the specified tags. | +| `tags` | `array` of `string` | | A list of runner tags for the policy. The policy jobs are run by runner with the specified tags. | Note the following: @@ -238,3 +238,14 @@ actions: - scan: secret_detection - scan: container_scanning ``` + +## Avoiding duplicate scans + +Scan execution policies can cause the same type of scanner to run more than once if developers include scan jobs in the project's +`.gitlab-ci.yml` file. This behavior is intentional as scanners can run more than once with different variables and settings. For example, a +developer may want to try running a SAST scan with different variables than the one enforced by the security and compliance team. In +this case, two SAST jobs run in the pipeline, one with the developer's variables and one with the security and compliance team's variables. + +If you want to avoid running duplicate scans, you can either remove the scans from the project's `.gitlab-ci.yml` file or disable your +local jobs by setting `SAST_DISABLED: true`. Disabling jobs this way does not prevent the security jobs defined by scan execution +policies from running. diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index 6bf3532f95e..bc74b8bdfb1 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -42,7 +42,7 @@ before the policy changes take effect. The [policy editor](index.md#policy-editor) supports YAML mode and rule mode. NOTE: -Propagating scan result policies created for groups with a large number of projects will take a while to complete. +Propagating scan result policies created for groups with a large number of projects take a while to complete. ## Scan result policies schema @@ -79,10 +79,16 @@ This rule enforces the defined actions based on security scan findings. | `scanners` | `array` of `string` | `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing` | The security scanners for this rule to consider. | | `vulnerabilities_allowed` | `integer` | Greater than or equal to zero | Number of vulnerabilities allowed before this rule is considered. | | `severity_levels` | `array` of `string` | `info`, `unknown`, `low`, `medium`, `high`, `critical`| The severity levels for this rule to consider. | -| `vulnerability_states` | `array` of `string` | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed` | All vulnerabilities fall into two categories:<br><br>**Newly Detected Vulnerabilities** - the `newly_detected` policy option covers vulnerabilities that are both `Detected` or `Dismissed` within the merge request itself where the vulnerabilities do not currently exist on the default branch. This policy option requires a pipeline to complete before the rule is evaluated so that it knows whether vulnerabilities are newly detected or not. Merge requests are blocked until the pipeline, and necessary security scans are complete.<br><br> • Detected<br> • Dismissed<br><br>**Pre-Existing Vulnerabilities** - these policy options are evaluated immediately and do not require a pipeline complete as they consider only vulnerabilities previously detected in the default branch.<br><br> • `Detected` - the policy looks for vulnerabilities in the detected state.<br> • `Confirmed` - the policy looks for vulnerabilities in the confirmed state.<br> • `Dismissed` - the policy looks for vulnerabilities in the dismissed state.<br> • `Resolved` - the policy looks for vulnerabilities in the resolved state. | +| `vulnerability_states` | `array` of `string` | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed` | All vulnerabilities fall into two categories:<br><br>**Newly Detected Vulnerabilities** - the `newly_detected` policy option covers vulnerabilities identified in the merge request branch itself but that do not currently exist on the default branch. This policy option requires a pipeline to complete before the rule is evaluated so that it knows whether vulnerabilities are newly detected or not. Merge requests are blocked until the pipeline and necessary security scans are complete. The `newly_detected` option considers both of the following statuses:<br><br> • Detected<br> • Dismissed<br><br>**Pre-Existing Vulnerabilities** - these policy options are evaluated immediately and do not require a pipeline complete as they consider only vulnerabilities previously detected in the default branch.<br><br> • `Detected` - the policy looks for vulnerabilities in the detected state.<br> • `Confirmed` - the policy looks for vulnerabilities in the confirmed state.<br> • `Dismissed` - the policy looks for vulnerabilities in the dismissed state.<br> • `Resolved` - the policy looks for vulnerabilities in the resolved state. | ## `license_finding` rule type +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8092) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `license_scanning_policies`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `license_scanning_policies`. +On GitLab.com, this feature is not available. + This rule enforces the defined actions based on license findings. | Field | Type | Possible values | Description | @@ -91,7 +97,7 @@ This rule enforces the defined actions based on license findings. | `branches` | `array` of `string` | `[]` or the branch's name | Applicable only to protected target branches. An empty array, `[]`, applies the rule to all protected target branches. | | `match_on_inclusion` | `boolean` | `true`, `false` | Whether the rule matches inclusion or exclusion of licenses listed in `license_types`. | | `license_types` | `array` of `string` | license types | License types to match on, for example `BSD` or `MIT`. | -| `license_states` | `array` of `string` | `newly_detected`, `detected` | Whether to match newly detected and/or previously detected licenses. | +| `license_states` | `array` of `string` | `newly_detected`, `detected` | Whether to match newly detected and/or previously detected licenses. The `newly_detected` state triggers approval when either a new package is introduced or when a new license for an existing package is detected. | ## `require_approval` action type @@ -110,7 +116,7 @@ the defined policy. Requirements and limitations: - You must add the respective [security scanning tools](../index.md#application-coverage). - Otherwise, scan result policies won't have any effect. + Otherwise, scan result policies do not have any effect. - The maximum number of policies is five. - Each policy can have a maximum of five rules. @@ -199,7 +205,7 @@ It corresponds to a single object from the previous example: ## Example situations where scan result policies require additional approval -There are several situations where the scan result policy will require an additional approval step. For example: +There are several situations where the scan result policy requires an additional approval step. For example: - The number of security jobs is reduced in the working branch and no longer matches the number of security jobs in the target branch. Users can't skip the Scanning Result Policies by removing scanning jobs from the CI configuration. - Someone stops a pipeline security job, and users can't skip the security scan. diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index efbbf447845..c8542142830 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -12,7 +12,7 @@ Static Application Security Testing (SAST) uses analyzers to detect vulnerabilities in source code. Each analyzer is a wrapper around a [scanner](../terminology/index.md#scanner), a third-party code analysis tool. The analyzers are published as Docker images that SAST uses to launch dedicated containers for each -analysis. We recommend a minimum of 4GB RAM to ensure consistent performance of the analyzers. +analysis. We recommend a minimum of 4 GB RAM to ensure consistent performance of the analyzers. SAST default images are maintained by GitLab, but you can also integrate your own custom image. @@ -77,8 +77,8 @@ Work to remove language-specific analyzers and replace them with the Semgrep-bas You can choose to disable the other analyzers early and use Semgrep-based scanning for supported languages before the default behavior changes. If you do so: -- You'll enjoy significantly faster scanning, reduced CI minutes usage, and more customizable scanning rules. -- However, vulnerabilities previously reported by language-specific analyzers will be reported again under certain conditions, including if you've dismissed the vulnerabilities before. The system behavior depends on: +- You enjoy significantly faster scanning, reduced CI minutes usage, and more customizable scanning rules. +- However, vulnerabilities previously reported by language-specific analyzers are reported again under certain conditions, including if you've dismissed the vulnerabilities before. The system behavior depends on: - whether you've excluded the Semgrep-based analyzer from running in the past. - which analyzer first discovered the vulnerabilities shown in the project's [Vulnerability Report](../vulnerability_report/index.md). @@ -92,7 +92,7 @@ The Vulnerability Management system automatically moves vulnerabilities from the - For Go, a vulnerability is moved if it has only ever been detected by Gosec in pipelines where Semgrep also detected it. Semgrep coverage for Go was introduced by default into the CI/CD template in GitLab 14.2 (August 2021). - For JavaScript and TypeScript, a vulnerability is moved if it has only ever been detected by ESLint in pipelines where Semgrep also detected it. Semgrep coverage for these languages was introduced into the CI/CD template in GitLab 13.12 (May 2021). -However, you'll see old vulnerabilities re-created based on Semgrep results if: +However, old vulnerabilities re-created based on Semgrep results are visible if: - A vulnerability was created by Bandit or SpotBugs and you disable those analyzers. We only recommend disabling Bandit and SpotBugs now if the analyzers aren't working. Work to automatically translate Bandit and SpotBugs vulnerabilities to Semgrep is tracked in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/328062). - A vulnerability was created by ESLint, Gosec, or Flawfinder in a default-branch pipeline where Semgrep scanning did not run successfully (before Semgrep coverage was introduced for the language, because you disabled Semgrep explicitly, or because the Semgrep scan failed in that pipeline). We do not currently plan to combine these vulnerabilities if they already exist. @@ -119,13 +119,13 @@ To switch to Semgrep-based scanning early, you can: 1. Create a merge request (MR) to set the [`SAST_EXCLUDED_ANALYZERS` CI/CD variable](#disable-specific-default-analyzers) to `"bandit,gosec,eslint"`. - If you also want to disable SpotBugs scanning, add `spotbugs` to the list. We only recommend this for Java projects. SpotBugs is the only current analyzer that can scan Groovy, Kotlin, and Scala. - If you also want to disable Flawfinder scanning, add `flawfinder` to the list. We only recommend this for C projects. Flawfinder is the only current analyzer that can scan C++. -1. Verify that scanning jobs succeed in the MR. You'll notice findings from the removed analyzers in _Fixed_ and findings from Semgrep in _New_. (Some findings may show different names, descriptions, and severities, since GitLab manages and edits the Semgrep rulesets.) +1. Verify that scanning jobs succeed in the MR. Findings from the removed analyzers are available in _Fixed_ and findings from Semgrep in _New_. (Some findings may show different names, descriptions, and severities, since GitLab manages and edits the Semgrep rulesets.) 1. Merge the MR and wait for the default-branch pipeline to run. 1. Use the Vulnerability Report to dismiss the findings that are no longer detected by the language-specific analyzers. #### Preview Semgrep-based scanning -You can see how Semgrep-based scanning will work in your projects before the GitLab-managed Stable CI/CD template for SAST is updated. +You can see how Semgrep-based scanning works in your projects before the GitLab-managed Stable CI/CD template for SAST is updated. We recommend that you test this change in a merge request but continue using the Stable template in your default branch pipeline configuration. In GitLab 15.3, we [activated a feature flag](https://gitlab.com/gitlab-org/gitlab/-/issues/362179) to migrate security findings on the default branch from other analyzers to Semgrep. @@ -148,10 +148,10 @@ To preview the upcoming changes to the CI/CD configuration in GitLab 15.3 or ear remote: 'https://gitlab.com/gitlab-org/gitlab/-/raw/2851f4d5/lib/gitlab/ci/templates/Jobs/SAST.latest.gitlab-ci.yml' ``` -1. Verify that scanning jobs succeed in the MR. You'll notice findings from the removed analyzers in _Fixed_ and findings from Semgrep in _New_. (Some findings may show different names, descriptions, and severities, since GitLab manages and edits the Semgrep rulesets.) +1. Verify that scanning jobs succeed in the MR. You notice findings from the removed analyzers in _Fixed_ and findings from Semgrep in _New_. (Some findings may show different names, descriptions, and severities, since GitLab manages and edits the Semgrep rulesets.) 1. Close the MR. -To learn more about Stable and Latest templates, see documentation on [CI/CD template versioning](../../../development/cicd/templates.md#versioning). +For more information about Stable and Latest templates, see [CI/CD template versioning](../../../development/cicd/templates.md#versioning). ## Customize analyzers diff --git a/doc/user/application_security/sast/customize_rulesets.md b/doc/user/application_security/sast/customize_rulesets.md index aec7158d2e4..d070883df9a 100644 --- a/doc/user/application_security/sast/customize_rulesets.md +++ b/doc/user/application_security/sast/customize_rulesets.md @@ -23,7 +23,7 @@ repository being scanned. There are two kinds of customization: ## Disable predefined rules -You can disable predefined rules for any SAST analyzer. Disabled rules won't appear +You can disable predefined rules for any SAST analyzer. Disabled rules don't appear on the [Pipeline Security](../index.md#view-security-scan-information-in-the-pipeline-security-tab) tab or the [Vulnerability Report](../index.md#view-security-scan-information-in-the-vulnerability-report). @@ -103,7 +103,7 @@ differ based on the kind of configuration you're making. | `[[$analyzer.ruleset]]` | Predefined rules | Defines modifications to an existing rule. | | `interpolate` | All | If set to `true`, you can use `$VAR` in the configuration to evaluate environment variables. Use this feature with caution, so you don't leak secrets or tokens. (Default: `false`) | | `description` | Passthroughs | Description of the custom ruleset. | -| `targetdir` | Passthroughs | The directory where the final configuration should be persisted. If empty, a directory with a random name is created. The directory can contain up to 100MB of files. | +| `targetdir` | Passthroughs | The directory where the final configuration should be persisted. If empty, a directory with a random name is created. The directory can contain up to 100 MB of files. | | `validate` | Passthroughs | If set to `true`, the content of each passthrough is validated. The validation works for `yaml`, `xml`, `json` and `toml` content. The proper validator is identified based on the extension used in the `target` parameter of the `[[$analyzer.passthrough]]` section. (Default: `false`) | | `timeout` | Passthroughs | The maximum time to spend to evaluate the passthrough chain, before timing out. The timeout cannot exceed 300 seconds. (Default: 60) | @@ -249,13 +249,13 @@ a higher precedence and can overwrite or append to data yielded by previous passthroughs (depending on the `mode`). This is useful for cases where you need to use or modify an existing configuration. -The amount of data generated by a single passthrough is limited to 1MB. +The amount of data generated by a single passthrough is limited to 1 MB. | Setting | Applies to | Description | | ------- | ---------- | ----------- | | `type` | All | One of `file`, `raw`, `git` or `url`. | | `target` | All | The target file to contain the data written by the passthrough evaluation. If empty, a random filename is used. | -| `mode` | All | If `overwrite`, the `target` file is overwritten. If `append`, new content is appended to the `target` file. Note that the `git` type only supports `overwrite`. (Default: `overwrite`) | +| `mode` | All | If `overwrite`, the `target` file is overwritten. If `append`, new content is appended to the `target` file. The `git` type only supports `overwrite`. (Default: `overwrite`) | | `ref` | `type = "git"` | Contains the name of the branch or the SHA to pull. When using a branch name, specify it in the form `refs/heads/<branch>`, not `refs/remotes/<remote_name>/<branch>`. | | `subdir` | `type = "git"` | Used to select a subdirectory of the Git repository as the configuration source. | | `value` | All | For the `file`, `url`, and `git` types, defines the location of the file or Git repository. For the `raw` type, contains the inline configuration. | @@ -273,7 +273,7 @@ The amount of data generated by a single passthrough is limited to 1MB. WARNING: When using the `raw` passthrough with a YAML snippet, it's recommended to format all indentation in the `sast-ruleset.toml` file as spaces. The YAML specification mandates spaces over tabs, and the -analyzer will fail to parse your custom ruleset unless the indentation is represented accordingly. +analyzer fails to parse your custom ruleset unless the indentation is represented accordingly. ## Examples @@ -317,8 +317,7 @@ With the following custom ruleset configuration, the following rules are omitted ### Override predefined rules of SAST analyzers With the following custom ruleset configuration, vulnerabilities found with -`semgrep` with a type `CWE` and a value `322` will have their severity -overridden to `Critical`. +`semgrep` with a type `CWE` and a value `322` have their severity overridden to `Critical`. ```toml [semgrep] @@ -416,7 +415,7 @@ Different passthrough types are demonstrated in this example: - The `sast-rules` entry has a higher precedence because it appears later in the configuration. - If there's a filename collision between the two checkouts, files - from the `sast-rules` repository will overwrite files from the + from the `sast-rules` repository overwrite files from the `myrules` repository. - A `raw` passthrough, which writes its `value` to `/sgrules/insecure.yml`. - A `url` passthrough, which fetches a configuration hosted at a URL and diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index c4352f45704..b0d84e4cff9 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -62,7 +62,7 @@ To run SAST jobs, by default, you need GitLab Runner with the If you're using the shared runners on GitLab.com, this is enabled by default. WARNING: -Our SAST jobs require a Linux/amd64 container type. Windows containers are not yet supported. +GitLab SAST analyzers don't support running on Windows or on any CPU architectures other than amd64. WARNING: If you use your own runners, make sure the Docker version installed @@ -73,7 +73,7 @@ is **not** `19.03.0`. See [troubleshooting information](#error-response-from-dae GitLab SAST supports scanning a variety of programming languages and frameworks. Once you [enable SAST](#configuration), the right set of analyzers runs automatically even if your project uses more than one language. -Check the [SAST direction page](https://about.gitlab.com/direction/secure/static-analysis/sast/#language-support) to learn more about our plans for language support in SAST. +For more information about our plans for language support in SAST, see the [category direction page](https://about.gitlab.com/direction/secure/static-analysis/sast/#language-support). | Language / framework | [Analyzer](analyzers.md) used for scanning | Minimum supported GitLab version | |------------------------------|--------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------| @@ -144,12 +144,15 @@ the repository. For details on the Solution format, see the Microsoft reference ## False positive detection **(ULTIMATE)** -> Introduced in GitLab 14.2. +> - Introduced for Ruby in GitLab 14.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378622) for Go in GitLab 15.8. -Vulnerabilities that have been detected and are false positives will be flagged as false positives in the security dashboard. +GitLab SAST can identify certain types of false positive results in the output of other tools. +These results are flagged as false positives on the [Vulnerability Report](../vulnerability_report/index.md) and the [Vulnerability Page](../vulnerabilities/index.md). False positive detection is available in a subset of the [supported languages](#supported-languages-and-frameworks) and [analyzers](analyzers.md): +- Go, in the Semgrep-based analyzer - Ruby, in the Brakeman-based analyzer  @@ -168,7 +171,7 @@ GitLab SAST uses an advanced vulnerability tracking algorithm to more accurately Advanced vulnerability tracking is available in a subset of the [supported languages](#supported-languages-and-frameworks) and [analyzers](analyzers.md): - C, in the Semgrep-based analyzer only -- Go, in the Gosec- and Semgrep-based analyzers +- Go, in the Semgrep-based analyzer only - Java, in the Semgrep-based analyzer only - JavaScript, in the Semgrep-based analyzer only - Python, in the Semgrep-based analyzer only @@ -178,9 +181,23 @@ Support for more languages and analyzers is tracked in [this epic](https://gitla For more information, see the confidential project `https://gitlab.com/gitlab-org/security-products/post-analyzers/tracking-calculator`. The content of this project is available only to GitLab team members. +## Automatic vulnerability resolution + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368284) in GitLab 15.9 [with a project-level flag](../../../administration/feature_flags.md) named `sec_mark_dropped_findings_as_resolved`. Enabled by default on GitLab.com; disabled by default in self-managed. On GitLab.com, [contact Support](https://about.gitlab.com/support/) if you need to disable the flag for your project. + +To help you focus on the vulnerabilities that are still relevant, GitLab SAST automatically [resolves](../vulnerabilities/index.md#vulnerability-status-values) vulnerabilities when: + +- You [disable a predefined rule](customize_rulesets.md#disable-predefined-rules). +- We remove a rule from the default ruleset. + +Automatic resolution is available only for findings from the [Semgrep-based analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep). +The Vulnerability Management system leaves a comment on automatically-resolved vulnerabilities so you still have a historical record of the vulnerability. + +If you re-enable the rule later, the findings are reopened for triage. + ## Supported distributions -The default scanner images are build off a base Alpine image for size and maintainability. +The default scanner images are built on a base Alpine image for size and maintainability. ### FIPS-enabled images @@ -350,13 +367,13 @@ To override the automatic update behavior, set the `SAST_ANALYZER_IMAGE_TAG` CI/ in your CI/CD configuration file after you include the [`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml). Only set this variable within a specific job. -If you set it [at the top level](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file), the version you set will be used for other SAST analyzers. +If you set it [at the top level](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file), the version you set is used for other SAST analyzers. You can set the tag to: -- A major version, like `3`. Your pipelines will use any minor or patch updates that are released within this major version. -- A minor version, like `3.7`. Your pipelines will use any patch updates that are released within this minor version. -- A patch version, like `3.7.0`. Your pipelines won't receive any updates. +- A major version, like `3`. Your pipelines use any minor or patch updates that are released within this major version. +- A minor version, like `3.7`. Your pipelines use any patch updates that are released within this minor version. +- A patch version, like `3.7.0`. Your pipelines don't receive any updates. This example uses a specific minor version of the `semgrep` analyzer and a specific patch version of the `brakeman` analyzer: @@ -552,7 +569,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 (see [`doublestar.Match`](https://pkg.go.dev/github.com/bmatcuk/doublestar/v4@v4.0.2#Match) for supported patterns), or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. 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. | +| `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 (see [`doublestar.Match`](https://pkg.go.dev/github.com/bmatcuk/doublestar/v4@v4.0.2#Match) for supported patterns), or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. 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 override the defaults and _only_ paths you specify are 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/*'`. [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/352554) in GitLab 15.4. | | `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | @@ -788,6 +805,11 @@ If you're seeing a new error that doesn't appear to be related to [the GitLab-ma Each [analyzer project](analyzers.md#sast-analyzers) has a `CHANGELOG.md` file listing the changes made in each available version. +### `exec /bin/sh: exec format error` message in job log + +GitLab SAST analyzers [only support](#requirements) running on the `amd64` CPU architecture. +This message indicates that the job is being run on a different architecture, such as `arm`. + ### `Error response from daemon: error processing tar file: docker-tar: relocation error` This error occurs when the Docker version that runs the SAST job is `19.03.0`. diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index d955170ece2..d6aab71a2c6 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -65,17 +65,76 @@ Different features are available in different [GitLab tiers](https://about.gitla | [Access the Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** No | **{check-circle}** Yes | | [Customize Secret Detection rulesets](#custom-rulesets) | **{dotted-circle}** No | **{check-circle}** Yes | +## Coverage + +Secret Detection scans different aspects of your code, depending on the situation. For all methods +except "Default branch", Secret Detection scans commits, not the working tree. For example, +Secret Detection can detect if a secret was added in one commit and removed in a later commit. + +- Historical scan + + If the `SECRET_DETECTION_HISTORIC_SCAN` variable is set, the content of all + [branches](../../project/repository/branches/index.md) is scanned. Before scanning the + repository's content, Secret Detection runs the command `git fetch --all` to fetch the content of all + branches. + +- Commit range + + If the `SECRET_DETECTION_LOG_OPTS` variable is set, the secrets analyzer fetches the entire + history of the branch or reference the pipeline is being run for. Secret Detection then runs, + scanning the commit range specified. + +- Default branch + + When Secret Detection is run on the default branch, the Git repository is treated as a plain + folder. Only the contents of the repository at the current HEAD are scanned. Commit history is not scanned. + +- Push event + + On a push event, Secret Detection determines what commit range to scan, given the information + available in the runner. To determine the commit range, the variables `CI_COMMIT_SHA` and + `CI_COMMIT_BEFORE_SHA` are important. + + - `CI_COMMIT_SHA` is the commit at HEAD for a given branch. This variable is always set for push events. + - `CI_COMMIT_BEFORE_SHA` is set in most cases. However, it is not set for the first push event on + a new branch, nor for merge pipelines. Because of this, Secret Detection can't be guaranteed + when multiple commits are committed to a new branch. + +- Merge request + + In a merge request, Secret Detection scans every commit made on the source branch. To use this + feature, you must use the [`latest` Secret Detection template](#templates), as it supports + [merge request pipelines](../../../ci/pipelines/merge_request_pipelines.md). + +## Templates + +Secret Detection default configuration is defined in CI/CD templates. Updates to the template are +provided with GitLab upgrades, allowing you to benefit from any improvements and additions. + +Available templates: + +- [`Secret-Detection.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Secret-Detection.gitlab-ci.yml): Stable version of the Secret Detection CI/CD template. +- [`Secret-Detection.latest.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Secret-Detection.latest.gitlab-ci.yml): Latest version of the Secret Detection template. + +WARNING: +The latest version of the template may include breaking changes. Use the stable template unless you +need a feature provided only in the latest template. + +For more information about template versioning, see the +[CI/CD documentation](../../../development/cicd/templates.md#latest-version). + ## Enable Secret Detection Prerequisites: -- GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or +- Linux-based GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. If you're using the shared runners on GitLab.com, this is enabled by default. + - Windows Runners are not supported. + - CPU architectures other than amd64 are not supported. - If you use your own runners, make sure the Docker version installed is **not** `19.03.0`. See [troubleshooting information](../sast#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. -- Linux/amd64 container type. Windows containers are not supported. - GitLab CI/CD configuration (`.gitlab-ci.yml`) must include the `test` stage. To enable Secret Detection, either: @@ -136,7 +195,12 @@ Pipelines now include a Secret Detection job. ## Responding to a leaked secret -If the scanner detects a secret you should rotate it immediately. [Purging a file from the repository's history](../../project/repository/reducing_the_repo_size_using_git.md#purge-files-from-repository-history) may not be effective in removing all references to the file. Also, the secret remains in any forks of the repository. +Secrets detected by the analyzer should be immediately rotated. +[Purging a file from the repository's history](../../project/repository/reducing_the_repo_size_using_git.md#purge-files-from-repository-history) +may not be effective in removing all references to the file. Additionally, the secret will remain in any existing +forks or clones of the repository. + +GitLab will attempt to [automatically revoke](post_processing.md) some types of leaked secrets. ## Pinning to specific analyzer version @@ -150,9 +214,9 @@ in your CI/CD configuration file after you include the [`Secret-Detection.gitlab You can set the tag to: -- A major version, like `4`. Your pipelines will use any minor or patch updates that are released within this major version. -- A minor version, like `4.5`. Your pipelines will use any patch updates that are released within this minor version. -- A patch version, like `4.5.0`. Your pipelines won't receive any updates. +- A major version, like `4`. Your pipelines use any minor or patch updates that are released within this major version. +- A minor version, like `4.5`. Your pipelines use any patch updates that are released within this minor version. +- A patch version, like `4.5.0`. Your pipelines don't receive any updates. This example uses a specific minor version of the analyzer: @@ -531,3 +595,8 @@ repository's default branch is unrelated to the branch the job was triggered for To resolve the issue, make sure to correctly [set your default branch](../../project/repository/branches/default.md#change-the-default-branch-name-for-a-project) on your repository. You should set it to a branch that has related history with the branch you run the `secret-detection` job on. + +### `exec /bin/sh: exec format error` message in job log + +The GitLab Secret Detection analyzer [only supports](#enable-secret-detection) running on the `amd64` CPU architecture. +This message indicates that the job is being run on a different architecture, such as `arm`. diff --git a/doc/user/application_security/secret_detection/post_processing.md b/doc/user/application_security/secret_detection/post_processing.md index e026c663854..22d7a8ba5af 100644 --- a/doc/user/application_security/secret_detection/post_processing.md +++ b/doc/user/application_security/secret_detection/post_processing.md @@ -4,36 +4,39 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Secret Detection post-processing and revocation **(FREE SAAS)** +# Secret Detection post-processing and revocation **(ULTIMATE SAAS)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4639) in GitLab 13.6. > - [Disabled by default for GitLab personal access tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/371658) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `gitlab_pat_auto_revocation`. Available to GitLab.com only. +> - [Enabled by default for GitLab personal access tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/371658) in GitLab 15.9 -FLAG: -By default, auto revocation of GitLab personal access tokens is not available. To opt-in on GitLab.com -during the [Beta period](../../../policy/alpha-beta-support.md#beta-features), please -[let us know by completing this form](https://docs.google.com/forms/d/e/1FAIpQLSdRbFhvA5jvI-Rt_Qnl1PQ1znOXKK8m6lRtmM0uva4upetKvQ/viewform). - -GitLab supports running post-processing hooks after detecting a secret. These -hooks can perform actions, like notifying the cloud service that issued the secret. -The cloud provider can then confirm the credentials and take remediation actions, like: +GitLab.com and self-managed supports running post-processing hooks after detecting a secret. These +hooks can perform actions, like notifying the vendor that issued the secret. +The vendor can then confirm the credentials and take remediation actions, like: - Revoking a secret. - Reissuing a secret. - Notifying the creator of the secret. -GitLab SaaS supports post-processing for [GitLab personal access tokens](../../profile/personal_access_tokens.md) and Amazon Web Services (AWS). -Post-processing workflows vary by supported cloud providers. +GitLab supports post-processing for the following vendors and secrets: + +| Vendor | Secret | GitLab.com | Self-managed | +| ----- | --- | --- | --- | +| GitLab | [Personal access tokens](../../profile/personal_access_tokens.md) | ✅ | ✅ 15.9 and later | +| Amazon Web Services (AWS) | [IAM access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) | ✅ | ⚙ | + +**Component legend** -Post-processing is limited to a project's default branch. The epic -[Post-processing of leaked secrets](https://gitlab.com/groups/gitlab-org/-/epics/4639). -contains: +- ✅ - Available by default +- ⚙ - Requires manual integration using a [Token Revocation API](../../../development/sec/token_revocation_api.md) -- Technical details of post-processing secrets. -- Discussions of efforts to support additional branches. +## Feature availability -NOTE: -Post-processing is currently limited to a project's default branch +Credentials are only post-processed when Secret Detection finds them: + +- In public projects, because publicly exposed credentials pose an increased threat. Expansion to private projects is considered in [issue 391379](https://gitlab.com/gitlab-org/gitlab/-/issues/391379). +- On the project [default branch](../../project/repository/branches/default.md), for technical reasons. Expansion to all branches is tracked in [issue 299212](https://gitlab.com/gitlab-org/gitlab/-/issues/299212). +- In projects with GitLab Ultimate, for technical reasons. Expansion to all tiers is tracked in [issue 391763](https://gitlab.com/gitlab-org/gitlab/-/issues/391763). ## High-level architecture @@ -44,142 +47,51 @@ sequenceDiagram autonumber GitLab Rails->>+Sidekiq: gl-secret-detection-report.json Sidekiq-->+Sidekiq: StoreSecurityReportsWorker - Sidekiq-->+RevocationAPI: GET revocable keys types - RevocationAPI-->>-Sidekiq: OK - Sidekiq->>+RevocationAPI: POST revoke revocable keys - RevocationAPI-->>-Sidekiq: ACCEPTED - RevocationAPI-->>+Cloud Vendor: revoke revocable keys - Cloud Vendor-->>+RevocationAPI: ACCEPTED -``` - -## Integrate your cloud provider service with GitLab SaaS - -Third party cloud and SaaS providers can [express integration interest by filling out this form](https://forms.gle/wWpvrtLRK21Q2WJL9). - -### Implement a vendor revocation receiver service - -A vendor revocation receiver service integrates with a GitLab instance to receive -a web notification and respond to leaked token requests. - -To implement a receiver service to revoke leaked tokens: - -1. Create a publicly accessible HTTP service matching the corresponding API contract - below. Your service should be idempotent and rate-limited. -1. When a pipeline corresponding to its revocable token type (in the example, `my_api_token`) - completes, GitLab sends a request to your receiver service. -1. The included URL should be publicly accessible, and contain the commit where the - leaked token can be found. For example: - - ```plaintext - POST / HTTP/2 - Accept: */* - Content-Type: application/json - X-Gitlab-Token: MYSECRETTOKEN - - [ - {"type": "my_api_token", "token":"XXXXXXXXXXXXXXXX","url": "https://example.com/some-repo/blob/abcdefghijklmnop/compromisedfile1.java"} - ] - ``` - -## Implement a revocation service for self-managed - -Self-managed instances interested in using the revocation capabilities must: - -- Deploy the [RevocationAPI](#high-level-architecture). -- Configure the GitLab instance to use the RevocationAPI. - -A RevocationAPI must: - -- Match a minimal API specification. -- Provide two endpoints: - - Fetching revocable token types. - - Revoking leaked tokens. -- Be rate-limited and idempotent. - -Requests to the documented endpoints are authenticated via API tokens passed in -the `Authorization` header. Request and response bodies, if present, are -expected to have the content type `application/json`. - -All endpoints may return these responses: - -- `401 Unauthorized` -- `405 Method Not Allowed` -- `500 Internal Server Error` - -### `GET /v1/revocable_token_types` - -Returns the valid `type` values for use in the `revoke_tokens` endpoint. - -NOTE: -These values match the concatenation of [the `secrets` analyzer's](index.md) -[primary identifier](../../../development/integrations/secure.md#identifiers) by means -of concatenating the `primary_identifier.type` and `primary_identifier.value`. -In the case below, a finding identifier matches: - -```json -{"type": "gitleaks_rule_id", "name": "Gitleaks rule ID GitLab Personal Access Token", "value": "GitLab Personal Access Token"} -``` - -| Status Code | Description | -| ----- | --- | -| `200` | The response body contains the valid token `type` values. | - -Example response body: - -```json -{ - "types": ["gitleaks_rule_id_gitlab_personal_access_token"] -} + Sidekiq-->+Token Revocation API: GET revocable keys types + Token Revocation API-->>-Sidekiq: OK + Sidekiq->>+Token Revocation API: POST revoke revocable keys + Token Revocation API-->>-Sidekiq: ACCEPTED + Token Revocation API-->>+Receiver Service: revoke revocable keys + Receiver Service-->>+Token Revocation API: ACCEPTED ``` -### `POST /v1/revoke_tokens` - -Accepts a list of tokens to be revoked by the appropriate provider. - -| Status Code | Description | -| ----- | --- | -| `204` | All submitted tokens have been accepted for eventual revocation. | -| `400` | The request body is invalid or one of the submitted token types is not supported. The request should not be retried. | -| `429` | The provider has received too many requests. The request should be retried later. | - -Example request body: - -```json -[{ - "type": "gitleaks_rule_id_gitlab_personal_access_token", - "token": "glpat--8GMtG8Mf4EnMJzmAWDU", - "location": "https://example.com/some-repo/blob/abcdefghijklmnop/compromisedfile1.java" -}, -{ - "type": "gitleaks_rule_id_gitlab_personal_access_token", - "token": "glpat--tG84EGK33nMLLDE70zU", - "location": "https://example.com/some-repo/blob/abcdefghijklmnop/compromisedfile2.java" -}] +1. A pipeline with a Secret Detection job completes on the project's default branch, producing a scan + report (**1**). +1. The report is processed (**2**) by an asynchronous worker, which communicates with an externally + deployed HTTP service (**3** and **4**) to determine which kinds of secrets can be automatically + revoked. +1. The worker sends (**5** and **6**) the list of detected secrets which the Token Revocation API is able to + revoke. +1. The Token Revocation API sends (**7** and **8**) each revocable token to their respective vendor's [receiver service](#integrate-your-cloud-provider-service-with-gitlabcom). + +See the [Token Revocation API](../../../development/sec/token_revocation_api.md) documentation for more +information. + +## Integrate your cloud provider service with GitLab.com + +Third-party cloud and SaaS vendors interested in automated token revocation can +[express integration interest by filling out this form](https://forms.gle/wWpvrtLRK21Q2WJL9). +Vendors must [implement a revocation receiver service](#implement-a-revocation-receiver-service) +which will be called by the Token Revocation API. + +### Implement a revocation receiver service + +A revocation receiver service integrates with a GitLab instance's Token Revocation API to receive and respond +to leaked token revocation requests. The service should be a publicly accessible HTTP API that is +idempotent and rate-limited. Requests to your service from the Token Revocation API will follow the example +below: + +```plaintext +POST / HTTP/2 +Accept: */* +Content-Type: application/json +X-Gitlab-Token: MYSECRETTOKEN + +[ + {"type": "my_api_token", "token":"XXXXXXXXXXXXXXXX","url": "https://example.com/some-repo/~/raw/abcdefghijklmnop/compromisedfile1.java"} +] ``` -### Configure GitLab to interface with RevocationAPI - -You must configure the following database settings in the GitLab instance: - -- `secret_detection_token_revocation_enabled` -- `secret_detection_token_revocation_url` -- `secret_detection_token_revocation_token` -- `secret_detection_revocation_token_types_url` - -For example, to configure these values in the -[Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): - -```ruby -::Gitlab::CurrentSettings.update!(secret_detection_token_revocation_token: 'MYSECRETTOKEN') -::Gitlab::CurrentSettings.update!(secret_detection_token_revocation_url: 'https://example.gitlab.com/revocation_service/v1/revoke_tokens') -::Gitlab::CurrentSettings.update!(secret_detection_revocation_token_types_url: 'https://example.gitlab.com/revocation_service/v1/revocable_token_types') -::Gitlab::CurrentSettings.update!(secret_detection_token_revocation_enabled: true) -``` - -After you configure these values, completing a pipeline performs these actions: - -1. The revocation service is triggered once. -1. A request is made to `secret_detection_revocation_token_types_url` to fetch a - list of revocable tokens. -1. Any Secret Detection findings matching the results of the `token_types` request - are included in the subsequent revocation request. +In this example, Secret Detection has determined that an instance of `my_api_token` has been leaked. The +value of the token is provided to you, in addition to a publicly accessible URL to the raw content of the +file containing the leaked token. diff --git a/doc/user/application_security/secure_your_application.md b/doc/user/application_security/secure_your_application.md new file mode 100644 index 00000000000..fb10efff2c6 --- /dev/null +++ b/doc/user/application_security/secure_your_application.md @@ -0,0 +1,29 @@ +--- +stage: Secure +group: Static Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Secure your application **(FREE)** + +GitLab can check your applications for security vulnerabilities. + +- [Get started](get-started-security.md) +- [Security Configuration](configuration/index.md) +- [Container Scanning](container_scanning/index.md) +- [Dependency Scanning](dependency_scanning/index.md) +- [Static Application Security Testing](sast/index.md) +- [Infrastructure as Code (IaC) Scanning](iac_scanning/index.md) +- [Secret Detection](secret_detection/index.md) +- [Dynamic Application Security Testing (DAST)](dast/index.md) +- [API Fuzzing](api_fuzzing/index.md) +- [Coverage-guided fuzz testing](coverage_fuzzing/index.md) +- [Security Dashboard](security_dashboard/index.md) +- [Offline Environments](offline_deployments/index.md) +- [Vulnerability Report](vulnerability_report/index.md) +- [Vulnerability Page](vulnerabilities/index.md) +- [Vulnerability severity levels](vulnerabilities/severities.md) +- [CVE ID requests](cve_id_request.md) +- [Policies](policies/index.md) +- [Security scanner integration](../../development/integrations/secure.md) +- [Secure and Govern Terminology](terminology/index.md) diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 7c44b49b78c..7388ef80e68 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -21,12 +21,18 @@ To use the Security Dashboards, you must: ## When Security Dashboards are updated -The Security Dashboards show results of the most recent security scan on the +The Security Dashboards show results of scans from the most recent completed pipeline on the [default branch](../../project/repository/branches/default.md). -Security scans run only when the default branch updates, so -information on the Security Dashboard might not reflect newly-discovered vulnerabilities. +Dashboards are updated with the result of completed pipelines run on the default branch; they do not include vulnerabilities discovered in pipelines from other un-merged branches. -To run a daily security scan, +If you use manual jobs, for example gate deployments, in the default branch's pipeline, +the results of any scans are only updated when the job has been successfully run. +If manual jobs are skipped regularly, you should to define the job as optional, +using the [`allow_failure`](../../../ci/jobs/job_control.md#types-of-manual-jobs) attribute. + +To ensure regular security scans (even on infrequently developed projects), +you should use [scan execution policies](../../../user/application_security/policies/scan-execution-policies.md). +Alternatively, you can [configure a scheduled pipeline](../../../ci/pipelines/schedules.md). ## Reduce false negatives in dependency scans @@ -51,7 +57,7 @@ To reduce false negatives in [dependency scans](../../../user/application_securi The project Security Dashboard shows the total number of vulnerabilities over time, with up to 365 days of historical data. Data refresh begins daily at 01:15 UTC via a scheduled job. Each refresh captures a snapshot of open vulnerabilities. Data is not backported to prior days -so vulnerabilities opened after the job has already run for the day will not be reflected in the +so vulnerabilities opened after the job has already run for the day cannot be reflected in the counts until the following day's refresh job. Project Security Dashboards show statistics for all vulnerabilities with a current status of `Needs triage` or `Confirmed` . @@ -99,7 +105,7 @@ To view project security status for a group: 1. Select **Security > Security Dashboard**. Each project is assigned a letter [grade](#project-vulnerability-grades) according to the highest-severity open vulnerability. -Dismissed or resolved vulnerabilities are excluded. Each project can receive only one letter grade and will appear only once +Dismissed or resolved vulnerabilities are excluded. Each project can receive only one letter grade and appears only once in the Project security status report. To view vulnerabilities, go to the group's [vulnerability report](../vulnerability_report/index.md). diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index 2666d91c5aa..772a7d17e1e 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -91,7 +91,7 @@ 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). -You can interact with vulnerability findings in two ways. +You can interact with vulnerability findings in two ways. 1. You can open an issue or merge request for the vulnerability finding. 1. You can dismiss the vulnerability finding. Dismissing the finding hides it from the default views. @@ -243,7 +243,7 @@ of the finding's [first identifier](https://gitlab.com/gitlab-org/security-produ combine to create the value. Examples of primary identifiers include `PluginID` for OWASP Zed Attack Proxy (ZAP), or `CVE` for -Trivy. Note that the identifier must be stable. Subsequent scans must return the same value for the +Trivy. The identifier must be stable. Subsequent scans must return the same value for the same finding, even if the location has slightly changed. ### Report finding @@ -257,7 +257,6 @@ once it's imported into the database. Describes the type of scan. This must be one of the following: - `api_fuzzing` -- `cluster_image_scanning` - `container_scanning` - `coverage_fuzzing` - `dast` diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 22ef3ed8a1b..67a1257799b 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -213,8 +213,8 @@ Security training uses content from third-party vendors. You must have an intern The vulnerability page may include a training link relevant to the detected vulnerability if security training is enabled. The availability of training depends on whether the enabled training vendor has content matching the particular vulnerability. Training content is requested based on the [vulnerability identifiers](../../../development/integrations/secure.md#identifiers). -The identifier given to a vulnerability will vary from one vulnerability to the next. The available training -content varies between vendors. This means some vulnerabilities will display no training content. +The identifier given to a vulnerability varies from one vulnerability to the next. The available training +content varies between vendors. This means some vulnerabilities do not display training content. Vulnerabilities with a CWE are most likely to return a training result. To view the security training for a vulnerability: diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index dd919889b4d..e6353264f39 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -171,22 +171,6 @@ To change the status of vulnerabilities in the table:  -## Dismissing a vulnerability - -When you evaluate a vulnerability and decide it requires no more action, you can mark it -as **Dismissed**. Dismissed vulnerabilities do not appear in the merge request security widget -when detected in future scans. - -When a vulnerability is dismissed, a record is made of: - -- Who dismissed it. -- Date and time when it was dismissed. -- Optionally, a reason why it was dismissed. - -Vulnerability records cannot be deleted, so a permanent record always remains. - -If a vulnerability is dismissed in error, reverse the dismissal by changing its status. - ## Sort vulnerabilities by date detected By default, vulnerabilities are sorted by severity level, with the highest-severity vulnerabilities listed at the top. @@ -199,7 +183,7 @@ To sort vulnerabilities by the date each vulnerability was detected, select the > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213013) to the group-level Vulnerability Report in GitLab 13.1. You can export details of the vulnerabilities listed in the Vulnerability Report. The export format -is CSV (comma separated values). Note that all vulnerabilities are included because filters do not +is CSV (comma separated values). All vulnerabilities are included because filters do not apply to the export. Fields included are: @@ -218,7 +202,7 @@ Fields included are: - Other identifiers - Detected At - Location -- Activity +- Activity: Returns `true` if the vulnerability is resolved on the default branch, and `false` if not. - Comments NOTE: @@ -242,10 +226,23 @@ thousands of vulnerabilities. Do not close the page until the download finishes. > The option of adding a dismissal reason was introduced in GitLab 12.0. -You can dismiss a vulnerability for the entire project: +When you evaluate a vulnerability and decide it requires no more action, +you can mark it as **Dismissed**. +Dismissed vulnerabilities do not appear in the merge request security widget +when detected in future scans. + +When a vulnerability is dismissed in a project or group, a record is made of: + +- Who dismissed it. +- Date and time when it was dismissed. +- Optionally, a reason why it was dismissed. + +Vulnerability records cannot be deleted, so a permanent record always remains. + +You can dismiss a vulnerability in projects and groups: 1. Select the vulnerability in the Security Dashboard. -1. In the top-right, from the **Status** selector menu, select **Dismissed**. +1. In the upper 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. @@ -263,7 +260,7 @@ To add a new vulnerability finding from your project level Vulnerability Report 1. Select **Submit vulnerability**. 1. Complete the fields and submit the form. -You will be brought to the newly created vulnerability's detail page. Manually created records appear in the +You are brought to the newly created vulnerability's detail page. Manually created records appear in the Group, Project, and Security Center Vulnerability Reports. To filter them, use the Generic Tool filter. ## Operational vulnerabilities diff --git a/doc/user/application_security/vulnerability_report/pipeline.md b/doc/user/application_security/vulnerability_report/pipeline.md index 57c18cb045e..0e5bb5e10f7 100644 --- a/doc/user/application_security/vulnerability_report/pipeline.md +++ b/doc/user/application_security/vulnerability_report/pipeline.md @@ -38,7 +38,7 @@ Before GitLab displays results, the vulnerability findings in all pipeline repor GitLab displays one row of information for each [scan type](../terminology/index.md#scan-type-report-type) artifact present in the pipeline. -Note that each scan type's total number of vulnerabilities includes dismissed findings. If the number of findings +Each scan type's total number of vulnerabilities includes dismissed findings. If the number of findings in the report doesn't match the number in **Scan details**, ensure that **Hide dismissed** is disabled. ### Download security scan outputs @@ -64,7 +64,7 @@ This shows a list of the combined results for all security report artifacts. The the addition of a **Hide dismissed** toggle. When you review the vulnerability findings reported in the pipeline, you can select one or more entries for dismissal, -similar to [Dismissing a vulnerability](index.md#dismissing-a-vulnerability) in the Vulnerability Report. +similar to [Dismissing a vulnerability](index.md#dismiss-a-vulnerability) in the Vulnerability Report. When you merge the branch corresponding to the pipeline into the default branch, all reported findings are combined into the [Vulnerability Report](index.md). Scan results in pipelines executed on the default branch are @@ -77,7 +77,7 @@ incorporated once the pipeline finishes. | Confirmed | No | Confirmed | | Needs triage (Detected) | No | Needs triage (Detected) | | Resolved | No | Needs triage (Detected) | -| N/A (i.e.: new vulnerability) | No | Needs triage (Detected) | +| N/A (That is: new vulnerability) | No | Needs triage (Detected) | ## Retention period for vulnerabilities diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md index 5df38550c40..e1459717241 100644 --- a/doc/user/award_emojis.md +++ b/doc/user/award_emojis.md @@ -36,7 +36,7 @@ celebrate an accomplishment or agree with an opinion. To add an award emoji: -1. In the top right of the comment, select the smile (**{slight-smile}**). +1. In the upper right of the comment, select the smile (**{slight-smile}**). 1. Select an emoji from the dropdown list. To remove an award emoji, select the emoji again. @@ -44,11 +44,11 @@ To remove an award emoji, select the emoji again. ## Custom emojis You can upload custom emojis to a GitLab instance with the GraphQL API. -For more, visit [Use custom emojis with GraphQL](../api/graphql/custom_emoji.md). +For more information, see [Use custom emojis with GraphQL](../api/graphql/custom_emoji.md). Custom emojis don't show in the emoji picker. To use them in a text box, type the filename without the extension and surrounded by colons. For example, for a file named `thank-you.png`, type `:thank-you:`. -For the list of custom emojis available for GitLab.com, visit +For a list of custom emojis available for GitLab.com, see [the `custom_emoji` project](https://gitlab.com/custom_emoji/custom_emoji/-/tree/main/img). diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index 304bbaee256..982411d35f9 100644 --- a/doc/user/clusters/agent/ci_cd_workflow.md +++ b/doc/user/clusters/agent/ci_cd_workflow.md @@ -66,7 +66,7 @@ To authorize the agent to access the GitLab project where you keep Kubernetes ma 1. On the top bar, select **Main menu > Projects** and find the project that contains the [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`). 1. Edit the `config.yaml` file. Under the `ci_access` keyword, add the `projects` attribute. -1. For the `id`, add the path: +1. For the `id`, add the path to the project. Do not wrap the path in quotation marks. ```yaml ci_access: diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md index bd7dfb3abee..787b0062017 100644 --- a/doc/user/clusters/agent/gitops.md +++ b/doc/user/clusters/agent/gitops.md @@ -115,10 +115,7 @@ The agent has [default sorting](https://github.com/kubernetes-sigs/cli-utils/blo but with annotations, you can fine-tune the order and apply time-value injection. To provide the GitOps functionality, the GitLab agent for Kubernetes uses the [`cli-utils` library](https://github.com/kubernetes-sigs/cli-utils/), -a Kubernetes SIG project. You can read more about the available annotations in the [`cli-utils` documentation](https://github.com/kubernetes-sigs/cli-utils/blob/master/README.md#apply-sort-ordering). - -- [Learn more about apply sort ordering](https://github.com/kubernetes-sigs/cli-utils#apply-sort-ordering). -- [Learn more about apply-time mutation](https://github.com/kubernetes-sigs/cli-utils#apply-time-mutation). +a Kubernetes SIG project. For more information, see the available annotations in the [`cli-utils` documentation](https://github.com/kubernetes-sigs/cli-utils/blob/master/README.md). ## Automatic drift remediation @@ -183,4 +180,4 @@ update your agent configuration file with the location of these projects. WARNING: The project with the agent's configuration file can be private or public. Other projects with Kubernetes manifests must be public. Support for private manifest projects is tracked -in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/283885). +in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/7704). diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index 62767f1dfd9..bb9a9c371a2 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -22,7 +22,7 @@ Before you can install the agent in your cluster, you need: - [Digital Ocean](https://docs.digitalocean.com/products/kubernetes/quickstart/) - On self-managed GitLab instances, a GitLab administrator must set up the [agent server](../../../../administration/clusters/kas.md). - Then it will be available by default at `wss://gitlab.example.com/-/kubernetes-agent/`. + Then it is available by default at `wss://gitlab.example.com/-/kubernetes-agent/`. On GitLab.com, the agent server is available at `wss://kas.gitlab.com`. ## Installation steps @@ -155,6 +155,10 @@ helm upgrade --install gitlab-agent gitlab/gitlab-agent \ ... ``` +NOTE: +DNS rebind protection is disabled when either the HTTP_PROXY or the HTTPS_PROXY environment variable is set, +and the domain DNS can't be resolved. + #### Advanced installation method GitLab also provides a [KPT package for the agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent). This method provides greater flexibility, but is only recommended for advanced users. diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md index a44d1e9685b..f5f235d2758 100644 --- a/doc/user/clusters/agent/troubleshooting.md +++ b/doc/user/clusters/agent/troubleshooting.md @@ -108,7 +108,7 @@ certificate authority that is unknown to the agent. To fix this issue, you can present the CA certificate file to the agent by using a Kubernetes `configmap` and mount the file in the agent `/etc/ssl/certs` directory from where it -will be picked up automatically. +is picked up automatically. For example, if your internal CA certificate is `myCA.pem`: @@ -200,7 +200,7 @@ are stored in the repository where the agent is configured. ``` The GitLab agent performs vulnerability scans by creating a job to scan each workload. If a scan -is interrupted, these jobs may be left behind and will need to be cleaned up before more jobs can +is interrupted, these jobs may be left behind and need to be cleaned up before more jobs can be run. You can clean up these jobs by running: ```shell diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md index 37d742e2b08..a71eea82df5 100644 --- a/doc/user/clusters/agent/vulnerabilities.md +++ b/doc/user/clusters/agent/vulnerabilities.md @@ -1,13 +1,13 @@ --- -stage: Configure -group: Configure +stage: Secure +group: Composition analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Operational Container Scanning **(ULTIMATE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6346) in GitLab 14.8. -> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/368828) the starboard directive in GitLab 15.4. The starboard directive will be removed in GitLab 16.0. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/368828) the starboard directive in GitLab 15.4. The starboard directive is scheduled for removal in GitLab 16.0. To view cluster vulnerabilities, you can view the [vulnerability report](../../application_security/vulnerabilities/index.md). You can also configure your agent so the vulnerabilities are displayed with other agent information in GitLab. @@ -24,7 +24,7 @@ In GitLab 15.0 and later, you do not need to install Starboard operator in the K ### Enable via agent configuration To enable scanning of all images within your Kubernetes cluster via the agent configuration, add a `container_scanning` configuration block to your agent -configuration with a `cadence` field containing a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans will be run. +configuration with a `cadence` field containing a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans are run. ```yaml container_scanning: @@ -42,7 +42,7 @@ Other elements of the [CRON syntax](https://docs.oracle.com/cd/E12058_01/doc/doc NOTE: The CRON expression is evaluated in [UTC](https://www.timeanddate.com/worldclock/timezone/utc) using the system-time of the Kubernetes-agent pod. -By default, operational container scanning will attempt to scan the workloads in all +By default, operational container scanning attempts to scan the workloads in all namespaces for vulnerabilities. You can set the `vulnerability_report` block with the `namespaces` field which can be used to restrict which namespaces are scanned. For example, if you would like to scan only the `default`, `kube-system` namespaces, you can use this configuration: @@ -60,10 +60,10 @@ container_scanning: To enable scanning of all images within your Kubernetes cluster via scan execution policies, we can use the [scan execution policy editor](../../application_security/policies/scan-execution-policies.md#scan-execution-policy-editor) -in order to create a new schedule rule. +To create a new schedule rule. NOTE: -The Kubernetes agent must be running in your cluster in order to scan running container images +The Kubernetes agent must be running in your cluster to scan running container images Here is an example of a policy which enables operational container scanning within the cluster the Kubernetes agent is attached to: @@ -84,9 +84,9 @@ Here is an example of a policy which enables operational container scanning with The keys for a schedule rule are: -- `cadence` (required): a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans will be run +- `cadence` (required): a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans are run - `agents:<agent-name>` (required): The name of the agent to use for scanning -- `agents:<agent-name>:namespaces` (optional): The Kubernetes namespaces to scan. If omitted, all namespaces will be scanned +- `agents:<agent-name>:namespaces` (optional): The Kubernetes namespaces to scan. If omitted, all namespaces are scanned NOTE: Other elements of the [CRON syntax](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) may work in the cadence field if supported by the [cron](https://github.com/robfig/cron) we are using in our implementation, however, GitLab does not officially test or support them. diff --git a/doc/user/clusters/agent/work_with_agent.md b/doc/user/clusters/agent/work_with_agent.md index 566eae8e24e..0b0e1365604 100644 --- a/doc/user/clusters/agent/work_with_agent.md +++ b/doc/user/clusters/agent/work_with_agent.md @@ -19,6 +19,7 @@ Prerequisite: To view the list of agents: 1. On the top bar, select **Main menu > Projects** and find the project that contains your agent configuration file. + You cannot view registered agents from a project that does not contain the agent configuration file. 1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. 1. Select **Agent** tab to view clusters connected to GitLab through the agent. @@ -76,7 +77,7 @@ observability: grpc_level: warn ``` -When `grpc_level` is set to `info` or below, there will be a lot of gRPC logs. +When `grpc_level` is set to `info` or below, there are a lot of gRPC logs. Commit the configuration changes and inspect the agent service logs: diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md index 75bc9e23c0f..74bfab49c55 100644 --- a/doc/user/clusters/cost_management.md +++ b/doc/user/clusters/cost_management.md @@ -19,7 +19,7 @@ On self-managed GitLab, by default this feature is not available. To make it ava Cluster cost management provides insights into cluster resource usage. GitLab provides an example [`kubecost-cost-model`](https://gitlab.com/gitlab-examples/kubecost-cost-model/) project that uses the GitLab Prometheus integration and -[Kubecost's `cost-model`](https://github.com/kubecost/cost-model) to provide cluster cost +[OpenCost `cost-model`](https://github.com/opencost/opencost) to provide cluster cost insights within GitLab:  @@ -60,8 +60,8 @@ this dashboard. ### Customize the cost dashboard You can customize the cost dashboard by editing the `.gitlab/dashboards/default_costs.yml` -file or creating similar dashboard configuration files. To learn more, read about -[customizing dashboards in our documentation](../../operations/metrics/dashboards/index.md). +file or creating similar dashboard configuration files. For more information, see +[Custom dashboards](../../operations/metrics/dashboards/index.md). #### Available metrics diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index 98292cf9103..f4313656803 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -38,7 +38,7 @@ Access to cluster environments is restricted to ## Usage -In order to: +To: - Track environments for the cluster, you must [deploy to a Kubernetes cluster](../project/clusters/deploy_to_cluster.md) diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index 6f7fdc46ad4..9edb012ba92 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -75,9 +75,9 @@ The base image used in the pipeline is built by the This image contains a set of Bash utility scripts to support [Helm v3 releases](https://helm.sh/docs/intro/using_helm/#three-big-concepts). If you are on a self-managed instance of GitLab, you must modify the `.gitlab-ci.yml` file. -Specifically, the section that starts with the comment `Automatic package upgrades` will not +Specifically, the section that starts with the comment `Automatic package upgrades` does not work on a self-managed instance, because the `include` refers to a GitLab.com project. -If you remove everything below this comment, the pipeline will succeed. +If you remove everything below this comment, the pipeline succeeds. ### The main `helmfile.yml` file diff --git a/doc/user/clusters/migrating_from_gma_to_project_template.md b/doc/user/clusters/migrating_from_gma_to_project_template.md index a86a84fe9ae..e5d81091094 100644 --- a/doc/user/clusters/migrating_from_gma_to_project_template.md +++ b/doc/user/clusters/migrating_from_gma_to_project_template.md @@ -77,7 +77,7 @@ See also [video walk-throughs](#video-walk-throughs) with examples. 1. Overwrite `applications/gitlab-runner/values.yaml` with the output of the previous command. - This safe step will guarantee that no unexpected default values overwrite your currently deployed values. + This safe step guarantees that no unexpected default values overwrite your currently deployed values. For instance, your GitLab Runner could have its `gitlabUrl` or `runnerRegistrationToken` overwritten by mistake. 1. Some apps require special attention: diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md index 0d33dfce30b..04609026793 100644 --- a/doc/user/compliance/compliance_report/index.md +++ b/doc/user/compliance/compliance_report/index.md @@ -55,9 +55,9 @@ The following is a list of violations that are either: | Violation | Severity level | Category | Description | Availability | |:-------------------------------------|:----------------|:---------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------| -| Author approved merge request | High | [Separation of duties](#separation-of-duties) | The author of the merge request approved their own merge request. [Learn more](../../project/merge_requests/approvals/settings.md#prevent-approval-by-author). | [Available in GitLab 14.10](https://gitlab.com/groups/gitlab-org/-/epics/6870) | -| Committers approved merge request | High | [Separation of duties](#separation-of-duties) | The committers of the merge request approved the merge request they contributed to. [Learn more](../../project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits). | [Available in GitLab 14.10](https://gitlab.com/groups/gitlab-org/-/epics/6870) | -| Fewer than two approvals | High | [Separation of duties](#separation-of-duties) | The merge request was merged with fewer than two approvals. [Learn more](../../project/merge_requests/approvals/rules.md). | [Available in GitLab 14.10](https://gitlab.com/groups/gitlab-org/-/epics/6870) | +| Author approved merge request | High | [Separation of duties](#separation-of-duties) | The author of the merge request approved their own merge request. For more information, see [Prevent approval by author](../../project/merge_requests/approvals/settings.md#prevent-approval-by-author). | [Available in GitLab 14.10](https://gitlab.com/groups/gitlab-org/-/epics/6870) | +| Committers approved merge request | High | [Separation of duties](#separation-of-duties) | The committers of the merge request approved the merge request they contributed to. For more information, see [Prevent approvals by users who add commits](../../project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits). | [Available in GitLab 14.10](https://gitlab.com/groups/gitlab-org/-/epics/6870) | +| Fewer than two approvals | High | [Separation of duties](#separation-of-duties) | The merge request was merged with fewer than two approvals. For more information, see [Merge request approval rules](../../project/merge_requests/approvals/rules.md). | [Available in GitLab 14.10](https://gitlab.com/groups/gitlab-org/-/epics/6870) | | Pipeline failed | Medium | [Pipeline results](../../../ci/pipelines/index.md) | The merge requests pipeline failed and was merged. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | | Pipeline passed with warnings | Info | [Pipeline results](../../../ci/pipelines/index.md) | The merge request pipeline passed with warnings and was merged. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | | Code coverage down more than 10% | High | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | The code coverage report for the merge request indicates a reduction in coverage of more than 10%. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | @@ -95,12 +95,35 @@ Our criteria for the separation of duties is as follows: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213364) in GitLab 13.3. > - Chain of Custody reports sent using email [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342594) in GitLab 15.3 with a flag named `async_chain_of_custody_report`. Disabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/370100) in GitLab 15.5. Feature flag `async_chain_of_custody_report` removed. +> - Chain of Custody report includes all commits (instead of just merge commits) [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267601) in GitLab 15.9 with a flag named `all_commits_compliance_report`. Disabled by default. + +FLAG: +On self-managed GitLab, by default the Chain of Custody report only contains information on merge commits. To make the report contain information on all commits to projects within a group, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `all_commits_compliance_report`. On GitLab.com, this feature is not available. The Chain of Custody report allows customers to export a list of merge commits within the group. The data provides a comprehensive view with respect to merge commits. It includes the merge commit SHA, merge request author, merge request ID, merge user, date merged, pipeline ID, group name, project name, and merge request approvers. Depending on the merge strategy, the merge commit SHA can be a merge commit, squash commit, or a diff head commit. +With the `all_commits_compliance_report` flag enabled, the Chain of Custody report provides a 1 month trailing window of any commit into a project under the group. + +To generate the report for all commits, GitLab: + +1. Fetches all projects under the group. +1. For each project, fetches the last 1 month of commits. Each project is capped at 1024 commits. If there are more than 1024 commits in the 1-month window, they + are truncated. +1. Writes the commits to a CSV file. The file is truncated at 15 MB because the report is emailed as an attachment. + +The expanded report includes the commit SHA, commit author, committer, date committed, the group, and the project. +If the commit has a related merge commit, then the following are also included: + +- Merge commit SHA. +- Merge request ID. +- User who merged the merge request. +- Merge date. +- Pipeline ID. +- Merge request approvers. + To generate the Chain of Custody report: 1. On the top bar, select **Main menu > Groups** and find your group. diff --git a/doc/user/compliance/license_compliance/img/denied_licenses_v15_3.png b/doc/user/compliance/img/denied_licenses_v15_3.png Binary files differindex 4ed84047133..4ed84047133 100644 --- a/doc/user/compliance/license_compliance/img/denied_licenses_v15_3.png +++ b/doc/user/compliance/img/denied_licenses_v15_3.png diff --git a/doc/user/compliance/license_compliance/img/license-check_v13_4.png b/doc/user/compliance/img/license-check_v13_4.png Binary files differindex bc80f938395..bc80f938395 100644 --- a/doc/user/compliance/license_compliance/img/license-check_v13_4.png +++ b/doc/user/compliance/img/license-check_v13_4.png diff --git a/doc/user/compliance/img/license_approval_policy_v15_9.png b/doc/user/compliance/img/license_approval_policy_v15_9.png Binary files differnew file mode 100644 index 00000000000..43b1f89a07c --- /dev/null +++ b/doc/user/compliance/img/license_approval_policy_v15_9.png diff --git a/doc/user/compliance/license_compliance/img/license_list_v13_0.png b/doc/user/compliance/img/license_list_v13_0.png Binary files differindex 3c15d4fc99a..3c15d4fc99a 100644 --- a/doc/user/compliance/license_compliance/img/license_list_v13_0.png +++ b/doc/user/compliance/img/license_list_v13_0.png diff --git a/doc/user/compliance/license_compliance/img/policies_maintainer_add_v14_3.png b/doc/user/compliance/img/policies_maintainer_add_v14_3.png Binary files differindex 7a27899f8c9..7a27899f8c9 100644 --- a/doc/user/compliance/license_compliance/img/policies_maintainer_add_v14_3.png +++ b/doc/user/compliance/img/policies_maintainer_add_v14_3.png diff --git a/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_3.png b/doc/user/compliance/img/policies_maintainer_edit_v14_3.png Binary files differindex 256c66bf7d8..256c66bf7d8 100644 --- a/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_3.png +++ b/doc/user/compliance/img/policies_maintainer_edit_v14_3.png diff --git a/doc/user/compliance/license_compliance/img/policies_v13_0.png b/doc/user/compliance/img/policies_v13_0.png Binary files differindex 4918a0e6b62..4918a0e6b62 100644 --- a/doc/user/compliance/license_compliance/img/policies_v13_0.png +++ b/doc/user/compliance/img/policies_v13_0.png diff --git a/doc/user/compliance/license_approval_policies.md b/doc/user/compliance/license_approval_policies.md new file mode 100644 index 00000000000..32c90a1d317 --- /dev/null +++ b/doc/user/compliance/license_approval_policies.md @@ -0,0 +1,58 @@ +--- +type: reference, howto +stage: Govern +group: Security Policies +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# License Approval Policies **(ULTIMATE)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8092) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `license_scanning_policies`. Disabled by default. + +License Approval Policies allow you to specify multiple types of criteria that define when approval is required before a merge request can be merged in. + +## Create a new license approval policy + +Create a license approval policy to enforce license compliance. + +To create a license approval policy: + +1. [Link a security policy project](../application_security/policies/index.md#managing-the-linked-security-policy-project) to your development group, subgroup, or project (the Owner role is required). +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Policies**. +1. Create a new [Scan Result Policy](../application_security/policies/scan-result-policies.md). +1. In your policy rule, select **License scanning**. + +## Criteria defining which licenses require approval + +The following types of criteria can be used to determine which licenses are "approved" or "denied" and require approval. + +- When any license in a list of explicitly prohibited licenses is detected. +- When any license is detected except for licenses that have been explicitly listed as acceptable. + +## Criteria comparing licenses detected in the merge request branch to licenses detected in the default branch + +The following types of criteria can be used to determine whether or not approval is required based on the licenses that exist in the default branch: + +- Denied licenses can be configured to only require approval if the denied license is part of a dependency that does not already exist in the default branch. +- Denied licenses can be configured to require approval if the denied license exists in any component that already exists in the default branch. + + + +If a license is found that violates the license approval policy, it blocks the merge request and instructs the developer to remove it. Note, the merge request is not able to be merged until the `denied` license is removed unless an eligible approver for the License Approval Policy approves the merge request. + + + +## Troubleshooting + +### The License Compliance widget is stuck in a loading state + +A loading spinner is displayed in the following scenarios: + +- While the pipeline is in progress. +- If the pipeline is complete, but still parsing the results in the background. +- If the license scanning job is complete, but the pipeline is still running. + +The License Compliance widget polls every few seconds for updated results. When the pipeline is complete, the first poll after pipeline completion triggers the parsing of the results. This can take a few seconds depending on the size of the generated report. + +The final state is when a successful pipeline run has been completed, parsed, and the licenses displayed in the widget. diff --git a/doc/user/compliance/license_check_rules.md b/doc/user/compliance/license_check_rules.md new file mode 100644 index 00000000000..968cf49ffdf --- /dev/null +++ b/doc/user/compliance/license_check_rules.md @@ -0,0 +1,84 @@ +--- +type: reference, howto +stage: Govern +group: Security Policies +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# License Check Policies (DEPRECATED) **(ULTIMATE)** + +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/390417) in GitLab 15.9. + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/390417) in GitLab 15.9. Users should migrate over to use [License Approval Policies](license_approval_policies.md) prior to GitLab 16.0. + +License check policies allow you to specify licenses that are `allowed` or `denied` in a project. If a `denied` +license is newly committed it blocks the merge request and instructs the developer to remove it. +Note, the merge request is not able to be merged until the `denied` license is removed. +You may add a [`License-Check` approval rule](#enabling-license-approvals-within-a-project), +which enables a designated approver that can approve and then merge a merge request with `denied` license. + +These policies can be configured by using the [Managed Licenses API](../../api/managed_licenses.md). + + + +The **Policies** tab in the project's license compliance section displays your project's license +policies. Project maintainers can specify policies in this section. + + + + + +Developers of the project can view the policies configured in a project. + + + +## Enabling License Approvals within a project + +Prerequisites: + +- Maintainer or Owner role. + +`License-Check` is a [merge request approval](../project/merge_requests/approvals/index.md) rule +you can enable to allow an individual or group to approve a merge request that contains a `denied` +license. + +You can enable `License-Check` one of two ways: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Merge request approvals**. +1. Select **Enable** or **Edit**. +1. Add or change the **Rule name** to `License-Check` (case sensitive). + + + +- Create an approval group in the [project policies section for License Compliance](license_check_rules.md#license-check-policies-deprecated). + You must set this approval group's number of approvals required to greater than zero. After you + enable this group in your project, the approval rule is enabled for all merge requests. + +Any code changes cause the approvals required to reset. + +An approval is required when a license report: + +- Contains a dependency that includes a software license that is `denied`. +- Is not generated during pipeline execution. + +An approval is optional when a license report: + +- Contains no software license violations. +- Contains only new licenses that are `allowed` or unknown. + +## Troubleshooting + +### The License Compliance widget is stuck in a loading state + +A loading spinner is displayed in the following scenarios: + +- While the pipeline is in progress. +- If the pipeline is complete, but still parsing the results in the background. +- If the license scanning job is complete, but the pipeline is still running. + +The License Compliance widget polls every few seconds for updated results. When the pipeline is complete, the first poll after pipeline completion triggers the parsing of the results. This can take a few seconds depending on the size of the generated report. + +The final state is when a successful pipeline run has been completed, parsed, and the licenses displayed in the widget. diff --git a/doc/user/compliance/license_compliance/img/license_compliance_v13_0.png b/doc/user/compliance/license_compliance/img/license_compliance_v13_0.png Binary files differdeleted file mode 100644 index 20ed30a21e7..00000000000 --- a/doc/user/compliance/license_compliance/img/license_compliance_v13_0.png +++ /dev/null diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index cf9fac6b25d..43e88e89c18 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -5,9 +5,13 @@ group: Composition Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# License compliance **(ULTIMATE)** +# License compliance (DEPRECATED) **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5483) in GitLab 11.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5483) in GitLab 11.0. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387561) in GitLab 15.9. + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387561) in GitLab 15.9. Users should migrate over to use the [new method of license scanning](../license_scanning_of_cyclonedx_files/index.md) prior to GitLab 16.0. If you're using [GitLab CI/CD](../../../ci/index.md), you can use License Compliance to search your project's dependencies for their licenses. You can then decide whether to allow or deny the use of @@ -21,12 +25,17 @@ For the job to activate, License Finder needs to find a compatible package defin GitLab checks the License Compliance report, compares the licenses between the source and target branches, and shows the information right on the merge request. Denied licenses are indicated by a `x` red icon next to them as well as new licenses that -need a decision from you. In addition, you can [manually allow or deny](#policies) licenses in your +need a decision from you. In addition, you can [manually allow or deny](../license_check_rules.md) licenses in your project's license compliance policy section. If a denied license is detected in a new commit, GitLab blocks any merge requests containing that commit and instructs the developer to remove the license. NOTE: +Starting with GitLab 15.9, License Compliance can detect the licenses in use +[using Dependency Scanning CI jobs](../license_scanning_of_cyclonedx_files/index.md) +instead of the License Scanning ones. + +NOTE: If the license compliance report doesn't have anything to compare to, no information is displayed in the merge request area. That is the case when you add the `license_scanning` job in your `.gitlab-ci.yml` for the first time. @@ -40,23 +49,11 @@ that you can later download and analyze. WARNING: License Compliance Scanning does not support run-time installation of compilers and interpreters. - - -You can select a license to see more information. - -When GitLab detects a **Denied** license, you can view it in the [license list](#license-list). - - - -You can view and modify existing policies from the [policies](#policies) tab. - - - ## License expressions -GitLab has limited support for [composite licenses](https://spdx.github.io/spdx-spec/SPDX-license-expressions/). +GitLab has limited support for [composite licenses](https://spdx.github.io/spdx-spec/v2-draft/SPDX-license-expressions/). License compliance can read multiple licenses, but always considers them combined using the `AND` operator. For example, -if a dependency has two licenses, and one of them is allowed and the other is denied by the project [policy](#policies), +if a dependency has two licenses, and one of them is allowed and the other is denied by the project [policy](../license_check_rules.md), GitLab evaluates the composite license as _denied_, as this is the safer option. The ability to support other license expression operators (like `OR`, `WITH`) is tracked in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/6571). @@ -696,117 +693,18 @@ Additional configuration may be needed for connecting to private registries for: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212388) in GitLab 13.3. -Prior to GitLab 13.3, offline environments required an exact name match for [project policies](#policies). -In GitLab 13.3 and later, GitLab matches the name of [project policies](#policies) +Prior to GitLab 13.3, offline environments required an exact name match for [project policies](../license_check_rules.md). +In GitLab 13.3 and later, GitLab matches the name of [project policies](../license_check_rules.md) with identifiers from the [SPDX license list](https://spdx.org/licenses/). A local copy of the SPDX license list is distributed with the GitLab instance. If needed, the GitLab instance's administrator can manually update it with a [Rake task](../../../raketasks/spdx.md). -## License list - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13582) in GitLab 12.7. - -The License list allows you to see your project's licenses and key -details about them. - -For the licenses to appear under the license list, the following -requirements must be met: - -1. The License Compliance CI/CD job must be [enabled](#enable-license-compliance) for your project. -1. Your project must use at least one of the - [supported languages and package managers](#supported-languages-and-package-managers). - -When everything is configured, on the left sidebar, select **Security & Compliance > License Compliance**. - -The licenses are displayed, where: - -- **Name:** The name of the license. -- **Component:** The components which have this license. -- **Policy Violation:** The license has a [license policy](#policies) marked as **Deny**. - - - -## Policies - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22465) in GitLab 12.9. - -Policies allow you to specify licenses that are `allowed` or `denied` in a project. If a `denied` -license is newly committed it blocks the merge request and instructs the developer to remove it. -Note, the merge request is not able to be merged until the `denied` license is removed. -You may add a [`License-Check` approval rule](#enabling-license-approvals-within-a-project), -which enables a designated approver that can approve and then merge a merge request with `denied` license. - -These policies can be configured by using the [Managed Licenses API](../../../api/managed_licenses.md). - - - -The **Policies** tab in the project's license compliance section displays your project's license -policies. Project maintainers can specify policies in this section. - - - - - -Developers of the project can view the policies configured in a project. - - - -## Enabling License Approvals within a project - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13067) in GitLab 12.3. - -Prerequisites: - -- Maintainer or Owner role. - -`License-Check` is a [merge request approval](../../project/merge_requests/approvals/index.md) rule -you can enable to allow an individual or group to approve a merge request that contains a `denied` -license. - -You can enable `License-Check` one of two ways: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > General**. -1. Expand **Merge request approvals**. -1. Select **Enable** or **Edit**. -1. Add or change the **Rule name** to `License-Check` (case sensitive). - - - -- Create an approval group in the [project policies section for License Compliance](#policies). - You must set this approval group's number of approvals required to greater than zero. Once you - enable this group in your project, the approval rule is enabled for all merge requests. - -Any code changes cause the approvals required to reset. - -An approval is required when a license report: - -- Contains a dependency that includes a software license that is `denied`. -- Is not generated during pipeline execution. - -An approval is optional when a license report: - -- Contains no software license violations. -- Contains only new licenses that are `allowed` or unknown. - ## Warnings We recommend that you use the most recent version of all containers, and the most recent supported version of all package managers and languages. Using previous versions carries an increased security risk because unsupported versions may no longer benefit from active security reporting and backporting of security fixes. ## Troubleshooting -### The License Compliance widget is stuck in a loading state - -A loading spinner is displayed in the following scenarios: - -- While the pipeline is in progress. -- If the pipeline is complete, but still parsing the results in the background. -- If the license scanning job is complete, but the pipeline is still running. - -The License Compliance widget polls every few seconds for updated results. When the pipeline is complete, the first poll after pipeline completion triggers the parsing of the results. This can take a few seconds depending on the size of the generated report. - -The final state is when a successful pipeline run has been completed, parsed, and the licenses displayed in the widget. - ### ASDF_PYTHON_VERSION does not automatically install the version Defining a non-latest Python version in ASDF_PYTHON_VERSION [doesn't have it automatically installed](https://gitlab.com/gitlab-org/gitlab/-/issues/325604). If your project requires a non-latest version of Python: diff --git a/doc/user/compliance/license_list.md b/doc/user/compliance/license_list.md new file mode 100644 index 00000000000..7f55ba50c5b --- /dev/null +++ b/doc/user/compliance/license_list.md @@ -0,0 +1,35 @@ +--- +type: reference, howto +stage: Govern +group: Threat Insights +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# License list **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13582) in GitLab 12.7. + +The License list allows you to see your project's licenses and key +details about them. + +For the licenses to appear under the license list, the following +requirements must be met: + +1. You must be generating an SBOM file with components from one of our [one of our supported languages](license_scanning_of_cyclonedx_files/index.md#supported-languages-and-package-managers). +1. If using our [`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/License-Scanning.gitlab-ci.yml) to generate the SBOM file, then your project must use at least one of the [supported languages and package managers](license_compliance/index.md#supported-languages-and-package-managers). + +Alternatively, licenses will also appear under the license list when using our deprecated [`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/License-Scanning.gitlab-ci.yml) as long as the following requirements are met: + +1. The License Compliance CI/CD job must be [enabled](license_compliance/index.md#enable-license-compliance) for your project. +1. Your project must use at least one of the + [supported languages and package managers](license_compliance/index.md#supported-languages-and-package-managers). + +When everything is configured, on the left sidebar, select **Security & Compliance > License Compliance**. + +The licenses are displayed, where: + +- **Name:** The name of the license. +- **Component:** The components which have this license. +- **Policy Violation:** The license has a [license policy](license_approval_policies.md) marked as **Deny**. + + diff --git a/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md b/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md new file mode 100644 index 00000000000..483c15d648c --- /dev/null +++ b/doc/user/compliance/license_scanning_of_cyclonedx_files/index.md @@ -0,0 +1,123 @@ +--- +type: reference, howto +stage: Secure +group: Composition Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# License scanning of CycloneDX files **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/384932) in GitLab 15.9 [with two flags](../../../administration/feature_flags.md) named `license_scanning_sbom_scanner` and `package_metadata_synchronization`. Both flags are disabled by default and both flags must be enabled for this feature to work. + +FLAG: +On self-managed GitLab, this feature is not available. + +To detect the licenses in use, License Compliance relies on running the +[Dependency Scanning CI Jobs](../../application_security/dependency_scanning/index.md), +and analyzing the [CycloneDX](https://cyclonedx.org/) Software Bill of Materials (SBOM) generated by those jobs. +Other 3rd party scanners may also be used as long as they produce a CycloneDX file with a list of dependencies for [one of our supported languages](#supported-languages-and-package-managers). +This method of scanning is also capable of parsing and identifying over 500 different types of licenses +and can extract license information from packages that are dual-licensed or have multiple different licenses that apply. + +To enable license detection using Dependency Scanning in a project, +include the `Jobs/Dependency-Scanning.yml` template in its CI configuration, +but do not include the `Jobs/License-Scanning.yml` template. + +## Requirements + +The license scanning requirements are the same as those for [Dependency Scanning](../../application_security/dependency_scanning/index.md#requirements). + +## Supported languages and package managers + +License scanning is supported for the following languages and package managers: + +<!-- markdownlint-disable MD044 --> +<table class="supported-languages"> + <thead> + <tr> + <th>Language</th> + <th>Package Manager</th> + </tr> + </thead> + <tbody> + <tr> + <td>.NET</td> + <td rowspan="2"><a href="https://www.nuget.org/">NuGet</a></td> + </tr> + <tr> + <td>C#</td> + </tr> + <tr> + <td>C</td> + <td rowspan="2"><a href="https://conan.io/">Conan</a></td> + </tr> + <tr> + <td>C++</td> + </tr> + <tr> + <td>Go</td> + <td><a href="https://go.dev/">Go</a></td> + </tr> + <tr> + <td rowspan="2">Java</td> + <td><a href="https://gradle.org/">Gradle</a></td> + </tr> + <tr> + <td><a href="https://maven.apache.org/">Maven</a></td> + </tr> + <tr> + <td rowspan="2">JavaScript and TypeScript</td> + <td><a href="https://www.npmjs.com/">npm</a></td> + </tr> + <tr> + <td><a href="https://classic.yarnpkg.com/en/">yarn</a></td> + </tr> + <tr> + <td>PHP</td> + <td><a href="https://getcomposer.org/">Composer</a></td> + </tr> + <tr> + <td rowspan="4">Python</td> + <td><a href="https://setuptools.readthedocs.io/en/latest/">setuptools</a></td> + </tr> + <tr> + <td><a href="https://pip.pypa.io/en/stable/">pip</a></td> + </tr> + <tr> + <td><a href="https://pipenv.pypa.io/en/latest/">Pipenv</a></td> + </tr> + <tr> + <td><a href="https://python-poetry.org/">Poetry</a></td> + </tr> + <tr> + <td>Ruby</td> + <td><a href="https://bundler.io/">Bundler</a></td> + </tr> + <tr> + <td>Scala</td> + <td><a href="https://www.scala-sbt.org/">sbt</a></td> + </tr> + </tbody> +</table> +<!-- markdownlint-disable MD044 --> + +The supported files and versions are the ones supported by +[Dependency Scanning](../../application_security/dependency_scanning/index.md#supported-languages-and-package-managers). + +## Configuration + +To enable license scanning of CycloneDX files, +you must configure [Dependency Scanning](../../application_security/dependency_scanning/index.md#configuration). + +## License expressions + +GitLab has limited support for [composite licenses](https://spdx.github.io/spdx-spec/v2-draft/SPDX-license-expressions/). +License compliance can read multiple licenses, but always considers them combined using the `AND` operator. For example, +if a dependency has two licenses, and one of them is allowed and the other is denied by the project [policy](../license_approval_policies.md), +GitLab evaluates the composite license as _denied_, as this is the safer option. +The ability to support other license expression operators (like `OR`, `WITH`) is tracked +in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/6571). + +## Blocking merge requests based on detected licenses + +Users can require approval for merge requests based on the licenses that are detected by configuring a [license approval policy](../license_approval_policies.md). diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md index 8c4fb6f1334..ebacda506b4 100644 --- a/doc/user/crm/index.md +++ b/doc/user/crm/index.md @@ -17,7 +17,7 @@ With customer relations management (CRM) you can create a record of contacts Contacts and organizations can only be created for root groups. You can use contacts and organizations to tie work to customers for billing and reporting purposes. -To read more about what is planned for the future, see [issue 2256](https://gitlab.com/gitlab-org/gitlab/-/issues/2256). +For more information about what is planned for the future, see [issue 2256](https://gitlab.com/gitlab-org/gitlab/-/issues/2256). ## Permissions diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 44e13f70f2e..9c9b5301460 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -260,7 +260,7 @@ Prerequisites: To create a thread by replying to a comment: -1. On the top right of the comment, select **Reply to comment** (**{comment}**). +1. In the upper right of the comment, select **Reply to comment** (**{comment}**).  @@ -308,7 +308,7 @@ To resolve a thread: 1. Go to the thread. 1. Do one of the following: - - In the top right of the original comment, select the **Resolve thread** (**{check-circle}**) icon. + - In the upper right of the original comment, select **Resolve thread** (**{check-circle}**). - Below the last reply, in the **Reply** field, select **Resolve thread**. - Below the last reply, in the **Reply** field, enter text, select the **Resolve thread** checkbox, and select **Add comment now**. diff --git a/doc/user/enterprise_user/index.md b/doc/user/enterprise_user/index.md new file mode 100644 index 00000000000..3daee460956 --- /dev/null +++ b/doc/user/enterprise_user/index.md @@ -0,0 +1,71 @@ +--- +stage: Manage +group: Authentication and Authorization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +type: reference +--- + +# Enterprise users **(PREMIUM SAAS)** + +Enterprise users have user accounts that are administered by an organization that +has purchased a [GitLab subscription](../../subscriptions/index.md). + +Enterprise users are identified by the [**Enterprise** badge](../project/badges.md) +next to their names on the [Members list](../group/manage.md#filter-and-sort-members-in-a-group). + +## Provision an enterprise user + +A user account is considered an enterprise account when: + +- A user without an existing GitLab user account uses the group's + [SAML SSO](../group/saml_sso/index.md) to sign in for the first time. +- [SCIM](../group/saml_sso/scim_setup.md) creates the user account on behalf of + the group. + +A user can also [manually connect an identity provider (IdP) to a GitLab account whose email address matches the subscribing organization's domain](../group/saml_sso/index.md#linking-saml-to-your-existing-gitlabcom-account). +By selecting **Authorize** when connecting these two accounts, the user account +with the matching email address is classified as an enterprise user. However, this +user account does not have an **Enterprise** badge in GitLab. + +Although a user can be a member of more than one group, each user account can be +provisioned by only one group. As a result, a user is considered an enterprise +user under one top-level group only. + +## Manage enterprise users in a namespace + +A top-level Owner of a namespace on a paid plan can retrieve information about and +manage enterprise user accounts in that namespace. + +These enterprise user-specific actions are in addition to the standard +[group member permissions](../permissions.md#group-members-permissions). + +### Disable two-factor authentication + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/9484) in GitLab 15.8. + +Top-level group Owners can disable two-factor authentication (2FA) for enterprise users. + +To disable 2FA: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Group information > Members**. +1. Find a user with the **Enterprise** and **2FA** badges. +1. Select **More actions** (**{ellipsis_v}**) and select **Disable two-factor authentication**. + +### Prevent users from creating groups and projects outside the corporate group + +A SAML identity administrator can configure the SAML response to set: + +- Whether users can create groups. +- The maximum number of personal projects users can create. + +For more information, see the [supported user attributes for SAML responses](../group/saml_sso/index.md#supported-user-attributes). + +### Bypass email confirmation for provisioned users + +A top-level group Owner can [set up verified domains to bypass confirmation emails](../group/saml_sso/index.md#bypass-user-email-confirmation-with-verified-domains). + +### Get users' email addresses through the API + +A top-level group Owner can use the [group and project members API](../../api/members.md) +to access users' information, including email addresses. diff --git a/doc/user/feature_flags.md b/doc/user/feature_flags.md index cc4bfdb01de..f665395b103 100644 --- a/doc/user/feature_flags.md +++ b/doc/user/feature_flags.md @@ -2,35 +2,14 @@ stage: none group: Development info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines" -description: "Understand what 'GitLab features deployed behind flags' means." +description: "View a list of all the flags available in the GitLab application." layout: 'feature_flags' --- -# GitLab functionality may be limited by feature flags +# All feature flags in GitLab > Feature flag documentation warnings were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227806) in GitLab 13.4. -GitLab releases some features in a disabled state using [feature flags](../development/feature_flags/index.md), -allowing them to be tested by specific groups of users and strategically -rolled out until they become enabled for everyone. +The following feature flags exist in GitLab. These flags determine the availability of each feature. -As a GitLab user, this means that some features included in a GitLab release -may be unavailable to you. - -In this case, you'll see a warning like this in the feature documentation: - -This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](../administration/feature_flags.md#risks-when-enabling-features-still-in-development). -Refer to this feature's version history for more details. - -In the version history note, you'll find information on the state of the -feature flag, including whether the feature is on ("enabled by default") or -off ("disabled by default") for self-managed GitLab instances and for users of -GitLab.com. - -If you're a user of a GitLab self-managed instance and you want to try to use a -disabled feature, you can ask a [GitLab administrator to enable it](../administration/feature_flags.md), -although changing a feature's default state isn't recommended. - -If you're a GitLab.com user and the feature is disabled, be aware that GitLab may -be working on the feature for potential release in the future. +For self-managed instances, [GitLab administrators can change the state of the flag](../administration/feature_flags.md). diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 9bb1c4e968c..fb32c64f06c 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -268,15 +268,18 @@ For more information, see [Runner SaaS](../../ci/runners/index.md). GitLab.com runs [Sidekiq](https://sidekiq.org) with arguments `--timeout=4 --concurrency=4` and the following environment variables: -| Setting | GitLab.com | Default | -|----------------------------------------|-------------|-----------| -| `SIDEKIQ_DAEMON_MEMORY_KILLER` | - | `1` | -| `SIDEKIQ_MEMORY_KILLER_MAX_RSS` | `2000000` | `2000000` | -| `SIDEKIQ_MEMORY_KILLER_HARD_LIMIT_RSS` | - | - | -| `SIDEKIQ_MEMORY_KILLER_CHECK_INTERVAL` | - | `3` | -| `SIDEKIQ_MEMORY_KILLER_GRACE_TIME` | - | `900` | -| `SIDEKIQ_MEMORY_KILLER_SHUTDOWN_WAIT` | - | `30` | -| `SIDEKIQ_LOG_ARGUMENTS` | `1` | `1` | +| Setting | GitLab.com | Default | +|----------------------------------------|------------|-----------| +| `GITLAB_MEMORY_WATCHDOG_ENABLED` | - | `true` | +| `SIDEKIQ_MEMORY_KILLER_MAX_RSS` | - | `2000000` | +| `SIDEKIQ_MEMORY_KILLER_HARD_LIMIT_RSS` | - | - | +| `SIDEKIQ_MEMORY_KILLER_CHECK_INTERVAL` | - | `3` | +| `SIDEKIQ_MEMORY_KILLER_GRACE_TIME` | - | `900` | +| `SIDEKIQ_MEMORY_KILLER_SHUTDOWN_WAIT` | - | `30` | +| `SIDEKIQ_LOG_ARGUMENTS` | `1` | `1` | + +For more information, see how to +[configure the environment variables](../../administration/sidekiq/sidekiq_memory_killer.md). NOTE: The `SIDEKIQ_MEMORY_KILLER_MAX_RSS` setting is `16000000` on Sidekiq import @@ -301,7 +304,7 @@ The list of GitLab.com specific settings (and their defaults) is as follows: | `autovacuum_vacuum_scale_factor` | 0.01 | 0.02 | | `checkpoint_completion_target` | 0.7 | 0.9 | | `checkpoint_segments` | 32 | 10 | -| `effective_cache_size` | 338688MB | Based on how much memory is available | +| `effective_cache_size` | 338688 MB | Based on how much memory is available | | `hot_standby` | on | off | | `hot_standby_feedback` | on | off | | `log_autovacuum_min_duration` | 0 | -1 | @@ -309,19 +312,19 @@ The list of GitLab.com specific settings (and their defaults) is as follows: | `log_line_prefix` | `%t [%p]: [%l-1]` | empty | | `log_min_duration_statement` | 1000 | -1 | | `log_temp_files` | 0 | -1 | -| `maintenance_work_mem` | 2048MB | 16 MB | +| `maintenance_work_mem` | 2048 MB | 16 MB | | `max_replication_slots` | 5 | 0 | | `max_wal_senders` | 32 | 0 | -| `max_wal_size` | 5GB | 1GB | -| `shared_buffers` | 112896MB | Based on how much memory is available | +| `max_wal_size` | 5 GB | 1 GB | +| `shared_buffers` | 112896 MB | Based on how much memory is available | | `shared_preload_libraries` | `pg_stat_statements` | empty | | `shmall` | 30146560 | Based on the server's capabilities | | `shmmax` | 123480309760 | Based on the server's capabilities | -| `wal_buffers` | 16MB | -1 | +| `wal_buffers` | 16 MB | -1 | | `wal_keep_segments` | 512 | 10 | | `wal_level` | replica | minimal | -| `statement_timeout` | 15s | 60s | -| `idle_in_transaction_session_timeout` | 60s | 60s | +| `statement_timeout` | 15 s | 60 s | +| `idle_in_transaction_session_timeout` | 60 s | 60 s | Some of these settings are in the process being adjusted. For example, the value for `shared_buffers` is quite high, and we are @@ -331,11 +334,15 @@ for `shared_buffers` is quite high, and we are GitLab.com uses the default of 60 seconds for [Puma request timeouts](../../administration/operations/puma.md#change-the-worker-timeout). -## Merge request reviewer maximum +## Maximum number of reviewers and assignees -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91406) in GitLab 15.3. +> - Maximum assignees [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368936) in GitLab 15.6. +> - Maximum reviewers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366485) in GitLab 15.9. -A maximum of 100 reviewers can be assigned to a merge request. +Merge requests enforce these maximums: + +- Maximum assignees: 200 +- Maximum reviewers: 200 ## GitLab.com-specific rate limits @@ -373,9 +380,9 @@ More details are available on the rate limits for GitLab can rate-limit requests at several layers. The rate limits listed here are configured in the application. These limits are the most -restrictive per IP address. To learn more about the rate limiting -for GitLab.com, read our runbook page -[Overview of rate limits for GitLab.com](https://gitlab.com/gitlab-com/runbooks/-/tree/master/docs/rate-limiting). +restrictive per IP address. For more information about the rate limits +for GitLab.com, see +[an overview](https://gitlab.com/gitlab-com/runbooks/-/tree/master/docs/rate-limiting). ### Rate limiting responses @@ -429,7 +436,7 @@ No response headers are provided. ### Pagination response headers -For performance reasons, if a query returns more than 10,000 records, [GitLab excludes some headers](../../api/index.md#pagination-response-headers). +For performance reasons, if a query returns more than 10,000 records, [GitLab excludes some headers](../../api/rest/index.md#pagination-response-headers). ### Visibility settings diff --git a/doc/user/group/access_and_permissions.md b/doc/user/group/access_and_permissions.md index 4629f33f088..4aecf016e56 100644 --- a/doc/user/group/access_and_permissions.md +++ b/doc/user/group/access_and_permissions.md @@ -205,7 +205,7 @@ By default, projects in a group can be forked. Optionally, on [GitLab Premium](https://about.gitlab.com/pricing/) or higher tiers, you can prevent the projects in a group from being forked outside of the current top-level group. -This setting will be removed from the SAML setting page, and migrated to the +This setting is removed from the SAML setting page, and migrated to the group settings page. In the interim period, both of these settings are taken into consideration. If even one is set to `true`, then the group does not allow outside forks. @@ -296,7 +296,7 @@ Now you can edit the user's permissions from the **Members** page. ### Verify if access is blocked by IP restriction -If a user sees a 404 when they would normally expect access, and the problem is limited to a specific group, search the `auth.log` rails log for one or more of the following: +If a user sees a 404 when they would usually expect access, and the problem is limited to a specific group, search the `auth.log` rails log for one or more of the following: - `json.message`: `'Attempting to access IP restricted group'` - `json.allowed`: `false` diff --git a/doc/user/group/compliance_frameworks.md b/doc/user/group/compliance_frameworks.md index 9f40f9e84bf..84cca5800c2 100644 --- a/doc/user/group/compliance_frameworks.md +++ b/doc/user/group/compliance_frameworks.md @@ -11,22 +11,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can create a compliance framework that is a label to identify that your project has certain compliance requirements or needs additional oversight. The label can optionally enforce -[compliance pipeline configuration](#configure-a-compliance-pipeline) to the projects on which it is +[compliance pipeline configuration](#compliance-pipelines) to the projects on which it is [applied](../project/settings/index.md#add-a-compliance-framework-to-a-project). -Group owners can create, edit, and delete compliance frameworks: +Compliance frameworks are created on top-level groups. Group owners can create, edit, and delete compliance frameworks: 1. On the top bar, select **Main menu > Groups > View all groups** and find your group. 1. On the left sidebar, select **Settings** > **General**. 1. Expand the **Compliance frameworks** section. 1. Create, edit, or delete compliance frameworks. +Subgroups and projects have access to all compliance frameworks created on their top-level group. However, compliance frameworks cannot be created, edited, +or deleted at the subgroup or project level. Project owners can choose a framework to apply to their projects. + ## Default compliance frameworks > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375036) in GitLab 15.6. -Group owners can set a default compliance framework. The default framework is applied to all the new and imported -projects that are created within that group. It does not affect the framework applied to the existing projects. The +Group owners can set a default compliance framework. The default framework is applied to all the new and imported +projects that are created in that group. It does not affect the framework applied to the existing projects. The default framework cannot be deleted. A compliance framework that is set to default has a **default** label. @@ -84,7 +87,7 @@ mutation { } ``` -## Configure a compliance pipeline **(ULTIMATE)** +## Compliance pipelines **(ULTIMATE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3156) in GitLab 13.9, disabled behind `ff_evaluate_group_level_compliance_pipeline` [feature flag](../../administration/feature_flags.md). > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/300324) in GitLab 13.11. @@ -103,6 +106,19 @@ However, the compliance pipeline configuration can reference the `.gitlab-ci.yml See [example configuration](#example-configuration) for help configuring a compliance pipeline that runs jobs from labeled project pipeline configuration. +### Effect on labeled projects + +Users have no way of knowing that a compliance pipeline has been configured and might be confused why their own +pipelines are not running at all, or include jobs that they did not define themselves. + +When authoring pipelines on a labeled project, there is no indication that a compliance pipeline has been configured. +The only marker at the project level is the compliance framework label itself, but the label does not say whether the +framework has a compliance pipeline configured or not. + +Therefore, communicate with project users about compliance pipeline configuration to reduce uncertainty and confusion. + +### Configure a compliance pipeline + To configure a compliance pipeline: 1. On the top bar, select **Main menu > Groups > View all groups** and find your group. @@ -194,15 +210,21 @@ audit trail: include: # Execute individual project's configuration (if project contains .gitlab-ci.yml) project: '$CI_PROJECT_PATH' file: '$CI_CONFIG_PATH' - ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch + ref: '$CI_COMMIT_SHA' # Must be defined or MR pipelines always use the use default branch + rules: + - if: $CI_PROJECT_PATH != "my-group/project-1" # Must be the hardcoded path to the project that hosts this configuration. ``` -#### CF pipelines in Merge Requests originating in project forks +The `rules` configuration in the `include` definition avoids circular inclusion in case the compliance pipeline must be able to run in the host project itself. +You can leave it out if your compliance pipeline only ever runs in labeled projects. + +#### Compliance pipelines in merge requests originating in project forks -When an MR originates in a fork, the branch to be merged usually only exists in the fork. -When creating such an MR against a project with CF pipelines, the above snippet will fail with a +When a merge request originates in a fork, the branch to be merged usually only exists in the fork. +When creating such a merge request against a project with compliance pipelines, the above snippet fails with a `Project <project-name> reference <branch-name> does not exist!` error message. -This is because in the context of the target project, `$CI_COMMIT_REF_NAME` evaluates to a non-existing branch name. +This error occurs because in the context of the target project, `$CI_COMMIT_REF_NAME` evaluates to a non-existing +branch name. To get the correct context, use `$CI_MERGE_REQUEST_SOURCE_PROJECT_PATH` instead of `$CI_PROJECT_PATH`. This variable is only available in @@ -241,7 +263,7 @@ Generally, if a value in a compliance job: Either might be wanted or not depending on your use case. -There are a few best practices for ensuring that these jobs are always run exactly +The following are a few best practices for ensuring that these jobs are always run exactly as you define them and that downstream, project-level pipeline configurations cannot change them: @@ -266,7 +288,7 @@ compatibility for combining compliance pipelines, and parent and child pipelines Compliance pipelines start on the run of _every_ pipeline in a labeled project. This means that if a pipeline in the labeled project triggers a child pipeline, the compliance pipeline runs first. This can trigger the parent pipeline, instead of the child pipeline. -Therefore, in projects with compliance frameworks, we recommend replacing +Therefore, in projects with compliance frameworks, you should replace [parent-child pipelines](../../ci/pipelines/downstream_pipelines.md#parent-child-pipelines) with the following: - Direct [`include`](../../ci/yaml/index.md#include) statements that provide the parent pipeline with child pipeline configuration. @@ -274,3 +296,19 @@ Therefore, in projects with compliance frameworks, we recommend replacing pipeline feature. This alternative ensures the compliance pipeline does not re-start the parent pipeline. + +## Troubleshooting + +### Cannot remove compliance framework from a project + +Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/390626), if you move a project, its compliance +framework becomes orphaned and can't be removed. To manually remove a compliance framework from a project, run the +following GraphQL mutation with your project's ID: + +```graphql +mutation { + projectSetComplianceFramework(input: {projectId: "gid://gitlab/Project/1234567", complianceFrameworkId: null}) { + errors + } +} +``` diff --git a/doc/user/group/contribution_analytics/img/group_stats_graph.png b/doc/user/group/contribution_analytics/img/group_stats_graph.png Binary files differindex ccfd3782c6f..1c38a9c1fdf 100644 --- a/doc/user/group/contribution_analytics/img/group_stats_graph.png +++ b/doc/user/group/contribution_analytics/img/group_stats_graph.png diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index ddf468e39b0..b0347ba5caa 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -4,62 +4,65 @@ stage: Plan group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Contribution Analytics **(PREMIUM)** +# Contribution analytics **(PREMIUM)** > [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 [contribution events](../../profile/contributions_calendar.md#user-contribution-events) in your -group. +Contribution analytics provide an overview of the +[contribution events](../../profile/contributions_calendar.md#user-contribution-events) made by your group's members. -- Analyze your team's contributions over a period of time. -- Identify opportunities for improvement with group members who may benefit from additional - support. +Use contribution analytics data visualizations to: -## View Contribution Analytics +- Analyze your group's contributions over a period of time. +- Identify group members who are high-performers or may benefit from additional support. -To view Contribution Analytics: +## View contribution analytics + +To view contribution analytics: 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Contribution**. -## Using Contribution Analytics - -Three bar graphs illustrate the number of contributions made by each group member: +Three bar charts and a table illustrate the number of contributions made by each group member: - Push events - Merge requests - Closed issues -Hover over each bar to display the number of events for a specific group member. +### View a member's contributions + +You can view the number of events associated with a specific group member. + +To do this, hover over the bar with the member's name.  -## Changing the period time +### Zoom in on a chart -You can choose from the following three periods: +You can zoom in on a bar chart to display only a subset of group members. -- Last week (default) -- Last month -- Last three months +To do this, select the sliders (**{status-paused}**) below the chart and slide them along the axis. + +### Sort contributions + +Contributions per group member are also displayed in tabular format. +The table columns include the members' names and the number of contributions for different events. -Select the desired period from the calendar dropdown list. +To sort the table by a column, select the column header or the chevron (**{chevron-lg-down}** +for descending order, **{chevron-lg-up}** for ascending order). - +## Change the time period -## Sorting by different factors +You can display contribution analytics over different time periods: -Contributions per group member are also presented in tabular format. Select a column header to sort the table by that column: +- Last week (default) +- Last month +- Last three months -- Member name -- Number of pushed events -- Number of opened issues -- Number of closed issues -- Number of opened MRs -- Number of merged MRs -- Number of closed MRs -- Number of total contributions +To change the time period of the contribution analytics, select one of the three tabs +under **Contribution Analytics**. - +The selected time period applies to all charts and the table. ## Contribution analytics GraphQL API diff --git a/doc/user/group/epics/linked_epics.md b/doc/user/group/epics/linked_epics.md index 63bf1a4471c..9ce4a585d14 100644 --- a/doc/user/group/epics/linked_epics.md +++ b/doc/user/group/epics/linked_epics.md @@ -16,7 +16,7 @@ The relationship only shows up in the UI if the user can see both epics. When yo epic that has open blockers, a warning is displayed. NOTE: -To manage linked epics through our API, visit the [epic links API documentation](../../../api/linked_epics.md). +To manage linked epics through our API, see [Linked epics API](../../../api/linked_epics.md). ## Add a linked epic diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index fa8f96952b3..74cfa2bd6ed 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -24,7 +24,7 @@ To create an epic in the group you're in: 1. Get to the New Epic form: - Go to your group and from the left sidebar select **Epics**. Then select **New epic**. - - From an epic in your group, select the vertical ellipsis (**{ellipsis_v}**). Then select **New epic**. + - From an epic in your group, select **Epic actions** (**{ellipsis_v}**). Then select **New epic**. - From anywhere, in the top menu, select **New...** (**{plus-square}**). Then select **New epic**. - In an empty [roadmap](../roadmap/index.md), select **New epic**. @@ -116,10 +116,10 @@ Prerequisites: To reorder list items, when viewing an epic: -1. Hover over the list item row to make the drag icon (**{drag-vertical}**) visible. -1. Select and hold the drag icon. +1. Hover over the list item row to make the grip icon (**{grip}**) visible. +1. Select and hold the grip icon. 1. Drag the row to the new position in the list. -1. Release the drag icon. +1. Release the grip icon. ## Bulk edit epics @@ -240,6 +240,7 @@ than 1000. The cached value is rounded to thousands or millions and updated ever > - Filtering by milestone and confidentiality [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/268372) in GitLab 14.2 [with a flag](../../../administration/feature_flags.md) named `vue_epics_list`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/276189) in GitLab 14.7. > - [Feature flag `vue_epics_list`](https://gitlab.com/gitlab-org/gitlab/-/issues/327320) removed in GitLab 14.8. +> - Filtering by group was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385191) in GitLab 15.9. You can filter the list of epics by: @@ -249,6 +250,7 @@ You can filter the list of epics by: - Milestones - Confidentiality - Reaction emoji +- Groups  @@ -260,6 +262,25 @@ To filter: 1. From the dropdown list, select the scope or enter plain text to search by epic title or description. 1. Press <kbd>Enter</kbd> on your keyboard. The list is filtered. +### Filter with the OR operator + +> OR filtering for labels and authors was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382969) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. +To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `or_issuable_queries`. +On GitLab.com, this feature is not available. +The feature is not ready for production use. + +When this feature is enabled, you can use the OR operator (**is one of: `||`**) +when you [filter the list of epics](#filter-the-list-of-epics) by: + +- Authors +- Labels + +`is one of` represents an inclusive OR. For example, if you filter by `Label is one of Deliverable` and +`Label is one of UX`, GitLab shows epics with either `Deliverable`, `UX`, or both labels. + ## Sort the list of epics You can sort the epics list by: @@ -500,10 +521,12 @@ The maximum number of direct child epics is 100. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8502) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `child_epics_from_different_hierarchies`. Disabled by default. > - Minimum required role for the group [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/382503) from Reporter to Guest in GitLab 15.7. +> - Cross-group child epics [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/375622) in GitLab 15.9. Enabled by default. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per group, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `child_epics_from_different_hierarchies`. -On GitLab.com, this feature is not available. The feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To disable it, +ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `child_epics_from_different_hierarchies`. +On GitLab.com, this feature is available. You can add a child epic that belongs to a group that is different from the parent epic's group. diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index c264b5ceaf8..7f8bb95f4d5 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -35,75 +35,87 @@ Also on self-managed GitLab, by default [migrating project items](#migrated-proj this feature, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `bulk_import_projects`. The feature is not ready for production use. On GitLab.com, migration of both groups and projects is available. -You can migrate top-level groups to: +Migrating groups by direct transfer copies the groups from one place to another. You can: -- Another top-level group. -- The subgroup of any existing top-level group. -- Another GitLab instance, including GitLab.com. +- Copy many groups at once. +- Copy top-level groups to: + - Another top-level group. + - The subgroup of any existing top-level group. + - Another GitLab instance, including GitLab.com. +- Copy groups with projects (in [beta](../../../policy/alpha-beta-support.md#beta-features) and not ready for production + use) or without projects. Copying projects with groups is available: + - On GitLab.com by default. + - On self-managed GitLab instances after an administrator first [enables the feature flag](../../../administration/feature_flags.md) named `bulk_import_projects`. -You can migrate: - -- By direct transfer through either the UI or the [API](../../../api/bulk_imports.md). -- Many groups at once. -- With projects (in [Beta](../../../policy/alpha-beta-support.md#beta-features) and not ready for production use) or - without projects. - -When you migrate a group by direct transfer, you can also migrate subgroups and projects. When you migrate a group: - -- To GitLab.com, all its subgroups and projects are migrated too. -- To a self-managed instance, migrating project items is not available by default. An administrator must - [enable the feature flag](../../../administration/feature_flags.md) named `bulk_import_projects`. - -WARNING: -Migrating subgroups and projects this way is in [Beta](../../../policy/alpha-beta-support.md#beta-features) and is not -ready for production use. - -Not all group and project resources are imported. See list of migrated resources below: +Not all group and project resources are copied. See list of copied resources below: - [Migrated group items](#migrated-group-items). - [Migrated project items](#migrated-project-items-beta). -Prerequisites: - -- Network connection between instances or GitLab.com. Must support HTTPS. -- Both GitLab instances have [migration enabled in application settings](../../admin_area/settings/visibility_and_access_controls.md#enable-migration-of-groups-and-projects-by-direct-transfer) - by an instance administrator. -- Owner role on the top-level source group to migrate from. -- At least the Maintainer role on the destination group to migrate to. Using the Developer role for this purpose was - [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. +We invite you to leave your feedback about migrating by direct transfer in +[the feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/284495). -### Preparation +If you want to move groups instead of copying groups, you can [transfer groups](../manage.md#transfer-a-group) if the +groups are in the same GitLab instance. Transferring groups is a faster and more complete option. -GitLab maps users and their contributions correctly provided: +### Visibility rules -- Users already exist on the target GitLab instance. -- Users have a public email on the source GitLab instance that matches their primary email on the target GitLab instance. -- Users' primary email addresses on the target GitLab instance are confirmed. Most users receives an email asking them to confirm their email address. -- When using an OmniAuth provider like SAML, GitLab and SAML accounts of users on GitLab must be linked. All users on the target GitLab instance must sign in - and verify their account on the target GitLab instance. +After migration: -You might need to reconfigure your firewall to prevent blocking the connection on the self-managed -instance. +- Private groups and projects stay private. +- Public groups and projects: + - Stay public when copied into a public group. + - Become private when copied into a private group. -If you use [SAML SSO for GitLab.com groups](../../group/saml_sso/index.md), -contributing users must have [linked their SAML identity to their GitLab.com account](../../group/saml_sso/index.md#linking-saml-to-your-existing-gitlabcom-account). +If used a private network on your source instance to hide content from the general public, +make sure to have a similar setup on the destination instance, or to import into a private group. -When migrating to GitLab.com, you must create users manually unless [SCIM](../../group/saml_sso/scim_setup.md) is used. Creating users with the API is only -available to self-managed instances because it requires administrator access. +### Prerequisites -### Connect to the source GitLab instance +To migrate groups by direct transfer: -Create the group you want to import to and connect the source: +- The network connection between instances or GitLab.com must support HTTPS. +- Any firewalls must not block the connection between the source and destination GitLab instances. +- Both GitLab instances must have group migration by direct transfer + [enabled in application settings](../../admin_area/settings/visibility_and_access_controls.md#enable-migration-of-groups-and-projects-by-direct-transfer) + by an instance administrator. +- The source GitLab instance must be running GitLab 14.0 or later. +- You must have a [personal access token](../../../user/profile/personal_access_tokens.md) for the source GitLab + instance: + - For GitLab 15.1 and later source instances, the personal access token must have the `api` scope. + - For GitLab 15.0 and earlier source instances, the personal access token must have both the `api` and + `read_repository` scopes. +- You must have the Owner role on the source group to migrate from. +- You must have at least the Maintainer role on the destination group to migrate to. Using the Developer role for this + purpose was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in + GitLab 16.0. + +### Prepare user accounts + +To ensure GitLab maps users and their contributions correctly: + +1. Create the required users on the destination GitLab instance. When migrating to GitLab.com, you must create users + manually unless [SCIM](../../group/saml_sso/scim_setup.md) is used. Creating users with the API is only available to + self-managed instances because it requires administrator access. +1. Check that users have a public email on the source GitLab instance that matches their primary email on the + destination GitLab instance. +1. Ensure that users confirm their primary email addresses on the destination GitLab instance. Most users receive an + email asking them to confirm their email address. +1. If using an OmniAuth provider like SAML, link GitLab and SAML accounts of users on GitLab. All users on the + destination GitLab instance must sign in and verify their account on the destination GitLab instance. If using + [SAML SSO for GitLab.com groups](../../group/saml_sso/index.md), users must + [link their SAML identity to their GitLab.com account](../../group/saml_sso/index.md#linking-saml-to-your-existing-gitlabcom-account). + +### Connect the source GitLab instance + +Create the group you want to import to and connect the source GitLab instance: 1. Create either: - - A new group. On the top bar, select **{plus-square}**, then **New group**, and select **Import group**. - A new subgroup. On existing group's page, either: - Select **New subgroup**. - On the top bar, Select **{plus-square}** and then **New subgroup**. Then on the left sidebar, select the **import an existing group** link. -1. Enter the URL of your source GitLab instance. -1. Generate or copy a [personal access token](../../../user/profile/personal_access_tokens.md) - with the `api` scope on your source GitLab instance. Both `api` and `read_repository` scopes are required when migrating from GitLab 15.0 and earlier. +1. Enter the URL of a GitLab instance running GitLab 14.0 or later. 1. Enter the [personal access token](../../../user/profile/personal_access_tokens.md) for your source GitLab instance. 1. Select **Connect instance**. @@ -112,7 +124,8 @@ Create the group you want to import to and connect the source: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385689) in GitLab 15.8, option to import groups with or without projects. After you have authorized access to the source GitLab instance, you are redirected to the GitLab group -importer page. The top-level groups on the connected source instance you have the Owner role for are listed. +importer page. Here you can see a list of the top-level groups on the connected source instance where you have the Owner +role. 1. By default, the proposed group namespaces match the names as they exist in source instance, but based on your permissions, you can choose to edit these names before you proceed to import any of them. 1. Next to the groups you want to import, select either: @@ -148,7 +161,7 @@ file for groups lists many of the items imported when migrating groups by direct for your version of GitLab to see the list of items relevant to you. For example, [`import_export.yml` on the `14-10-stable-ee` branch](https://gitlab.com/gitlab-org/gitlab/-/blob/14-10-stable-ee/lib/gitlab/import_export/group/import_export.yml). -Group items that are migrated to the target instance include: +Group items that are migrated to the destination GitLab instance include: - Badges ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292431) in 13.11) - Board Lists @@ -161,9 +174,9 @@ Group items that are migrated to the target instance include: - Iterations cadences ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96570) in 15.4) - Members ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299415) in 13.9) Group members are associated with the imported group if: - - The user already exists in the target GitLab instance and + - The user already exists in the destination GitLab instance and - The user has a public email in the source GitLab instance that matches a - confirmed email in the target GitLab instance + confirmed email in the destination GitLab instance - Milestones ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292427) in 13.10) - Namespace Settings - Releases @@ -192,7 +205,7 @@ WARNING: Migrating projects when migrating groups by direct transfer is in [Beta](../../../policy/alpha-beta-support.md#beta-features) and is not ready for production use. -Project items that are migrated to the target instance include: +Project items that are migrated to the destination GitLab instance include: - Projects ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4) - Auto DevOps ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339410) in GitLab 14.6) @@ -241,9 +254,6 @@ Items excluded from migration, because they contain sensitive information: - Pipeline Triggers. -Migrating projects with file exports uses the same export and import mechanisms as creating projects from templates at the [group](../../group/custom_project_templates.md) and -[instance](../../admin_area/custom_project_templates.md) levels. Therefore, the list of exported items is the same. - ### Troubleshooting In a [rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session), @@ -251,7 +261,7 @@ you can find the failure or error messages for the group import attempt using: ```ruby # Get relevant import records -import = BulkImports::Entity.where(namespace_id: Group.id).map(&:bulk_import) +import = BulkImports::Entity.where(namespace_id: Group.id).map(&:bulk_import).last # Alternative lookup by user import = BulkImport.where(user_id: User.find(...)).last @@ -267,7 +277,7 @@ entities.where(status: [-1]).pluck(:destination_name, :destination_namespace, :s ``` You can also see all migrated entities with any failures related to them using an -[API endpoint](../../../api/bulk_imports.md#list-all-gitlab-migrations-entities). +[API endpoint](../../../api/bulk_imports.md#list-all-group-migrations-entities). #### Stale imports @@ -300,11 +310,6 @@ To solve this, you must change the source group path to include a non-numerical - The [Groups API](../../../api/groups.md#update-group). -### Provide feedback - -Please leave your feedback about migrating groups by direct transfer in -[the feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/284495). - ## Migrate groups by uploading an export file (deprecated) > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2888) in GitLab 13.0 as an experimental feature. May change in future releases. @@ -343,6 +348,25 @@ Note the following: exporting a group from the Enterprise Edition to the Community Edition, you may lose this data. For more information, see [downgrading from EE to CE](../../../index.md). +### Compatibility + +Group file exports are in NDJSON format. GitLab previously produced group file exports in JSON format, however: + +- From GitLab 15.8, GitLab no longer supports importing a JSON-formatted group file export. +- Between GitLab 14.0 and GitLab 14.7, GitLab no longer produces group file exports in JSON format but, to support + transitions, can still import JSON-formatted group file exports. + +From GitLab 13.0, GitLab can import group file exports that were exported from a version of GitLab up to two +[minor](../../../policy/maintenance.md#versioning) versions behind, which is similar to our process for +[security releases](../../../policy/maintenance.md#security-releases). + +For example: + +| Destination version | Compatible source versions | +|:--------------------|:---------------------------| +| 13.0 | 13.0, 12.10, 12.9 | +| 13.1 | 13.1, 13.0, 12.10 | + ### Exported contents The [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/group/import_export.yml) @@ -441,27 +465,6 @@ To help avoid abuse, by default, users are rate limited to: | Download export | 1 download per group per minute | | Import | 6 groups per minute | -### 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). - -For example: - -| Current version | Can import bundles exported from | -|-----------------|----------------------------------| -| 13.0 | 13.0, 12.10, 12.9 | -| 13.1 | 13.1, 13.0, 12.10 | - ## Automate group and project import **(PREMIUM)** For information on automating user, group, and project import API calls, see diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 518370fc7ac..72d3bf65447 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -33,7 +33,7 @@ In GitLab, iterations are similar to milestones, with a few differences: > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5077) in GitLab 14.1 [with a flag](../../../administration/feature_flags.md), named `iteration_cadences`. Disabled by default. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/354977) in GitLab 15.0: All scheduled iterations must start on the same day of the week as the cadence start day. Start date of cadence cannot be edited after the first iteration starts. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/354878) in GitLab 15.0. -> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/367493) in GitLab 15.4: A new automation start date can be selected for cadence. Upcoming iterations will be scheduled to start on the same day of the week as the changed start date. Iteration cadences can be manually managed by turning off the automatic scheduling feature. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/367493) in GitLab 15.4: A new automation start date can be selected for cadence. Upcoming iterations are scheduled to start on the same day of the week as the changed start date. Iteration cadences can be manually managed by turning off the automatic scheduling feature. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/354878) in GitLab 15.5. Feature flag `iteration_cadences` removed. Iteration cadences are containers for iterations and can be used to automate iteration scheduling. @@ -56,7 +56,7 @@ To create an iteration cadence: 1. Enter the title and description of the iteration cadence. 1. To manually manage the iteration cadence, clear the **Enable automatic scheduling** checkbox and skip the next step. 1. Complete the required fields to use automatic scheduling. - - Select the automation start date of the iteration cadence. Iterations will be scheduled to + - Select the automation start date of the iteration cadence. Iterations are scheduled to begin on the same day of the week as the day of the week of the start date. - From the **Duration** dropdown list, select how many weeks each iteration should last. - From the **Upcoming iterations** dropdown list, select how many upcoming iterations should be @@ -77,8 +77,7 @@ From there you can create a new iteration or select an iteration to get a more d NOTE: If a project has issue tracking [turned off](../../project/settings/index.md#configure-project-visibility-features-and-permissions), -you can view the iterations list -by going to its URL. To do so, add: `/-/cadences` to your project or group URL. +to view the iterations list, enter its URL. To do so, add: `/-/cadences` to your project or group URL. For example `https://gitlab.com/gitlab-org/sample-data-templates/sample-gitlab-project/-/cadences`. This is tracked in [issue 339009](https://gitlab.com/gitlab-org/gitlab/-/issues/339009). diff --git a/doc/user/group/manage.md b/doc/user/group/manage.md index a755447c47c..fc72b81d74c 100644 --- a/doc/user/group/manage.md +++ b/doc/user/group/manage.md @@ -33,8 +33,8 @@ To create a group: 1. Choose the [visibility level](../public_access.md). 1. Personalize your GitLab experience by answering the following questions: - What is your role? - - Who will be using this group? - - What will you use this group for? + - Who is using this group? + - What are you using this group for? 1. Invite GitLab members or other users to join the group. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> @@ -131,7 +131,7 @@ Filter a group to find members. By default, all members in the group and subgrou In lists of group members, entries can display the following badges: - **SAML**, to indicate the member has a [SAML account](saml_sso/index.md) connected to them. -- **Enterprise**, to indicate that [SCIM created the account](saml_sso/scim_setup.md). +- **Enterprise**, to indicate that the member is an [enterprise user](../enterprise_user/index.md). 1. On the top bar, select **Main menu > Groups** and find your group. 1. Above the list of members, in the **Filter members** box, enter filter criteria. @@ -155,7 +155,7 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Group information > Members**. -1. Above the list of members, on the top right, from the **Account** list, select +1. Above the list of members, in the upper right, from the **Account** list, select the criteria to filter by. 1. To switch the sort between ascending and descending, to the right of the **Account** list, select the arrow (**{sort-lowest}** or **{sort-highest}**). @@ -336,12 +336,15 @@ After sharing the `Frontend` group with the `Engineering` group: ## Transfer a group -You can transfer groups in the following ways: +Transferring groups moves them from one place to another in the same GitLab instance. You can: - Transfer a subgroup to a new parent group. - Convert a top-level group into a subgroup by transferring it to the desired group. - Convert a subgroup into a top-level group by transferring it out of its current group. +If you need to copy a group to a different GitLab instance, +[migrate the group by direct transfer](import/index.md#migrate-groups-by-direct-transfer-recommended). + When transferring groups, note: - Changing a group's parent can have unintended side effects. See [what happens when a repository path changes](../project/repository/index.md#what-happens-when-a-repository-path-changes). @@ -350,6 +353,7 @@ When transferring groups, note: - If the immediate parent group's visibility is lower than the group's current visibility, visibility levels for subgroups and projects change to match the new parent group's visibility. - Only explicit group membership is transferred, not inherited membership. If the group's owners have only inherited membership, this leaves the group without an owner. In this case, the user transferring the group becomes the group's owner. - Transfers fail if [packages](../packages/index.md) exist in any of the projects in the group, or in any of its subgroups. +- Top-level groups that have a subscription on GitLab.com cannot be transferred. To make the transfer possible, the top-level group's subscription must be removed first. Then the top-level group can be transferred as a subgroup to another top-level group. To transfer a group: diff --git a/doc/user/group/reporting/git_abuse_rate_limit.md b/doc/user/group/reporting/git_abuse_rate_limit.md index a5515079294..14b188e1204 100644 --- a/doc/user/group/reporting/git_abuse_rate_limit.md +++ b/doc/user/group/reporting/git_abuse_rate_limit.md @@ -38,3 +38,17 @@ Prerequisites: 1. On the left sidebar, select **Group information > Members**. 1. Select the **Banned** tab. 1. For the account you want to unban, select **Unban**. + +## Ban a user + +> [Introduced](https://gitlab.com/gitlab-org/modelops/anti-abuse/team-tasks/-/issues/155) in GitLab 15.8. + +Prerequisites: + +- You must have the Owner role. + +To manually ban a user: + +1. On the left sidebar, select **Group information > Members**. +1. Next to the member you want to ban, select the vertical ellipsis (**{ellipsis_v}**). +1. From the dropdown list, select **Ban member**. diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index 3a9d0c833c1..9e0ff22eafa 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -38,6 +38,7 @@ heading to toggle the list of the milestone bars. > - Filtering by epic confidentiality [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218624) in GitLab 13.9. > - Filtering by epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218623) in GitLab 13.11. > - Filtering by milestone [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323917) in GitLab 14.5. +> - Filtering by group was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385191) in GitLab 15.9. NOTE: Filtering roadmaps by milestone might not be available to you. Be sure to review this section's version history for details. @@ -62,6 +63,7 @@ You can also filter epics in the Roadmap view by the epics': - [Confidentiality](../epics/manage_epics.md#make-an-epic-confidential) - Epic - Your Reaction +- Groups  @@ -71,6 +73,7 @@ You can also [visualize roadmaps inside of an epic](../epics/index.md#roadmap-in > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345158) in GitLab 14.8 [with a flag](../../../administration/feature_flags.md) named `roadmap_settings`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/350830) in GitLab 14.9. Feature flag `roadmap_settings`removed. +> - Labels visible on roadmaps [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385231) in GitLab 15.9. When you enable the roadmap settings sidebar, you can use it to refine epics shown in the roadmap. @@ -82,6 +85,7 @@ You can configure the following: - Show all, open, or closed epics. - Turn progress tracking for child issues on or off and select whether to use issue weights or counts. +- Turn labels on or off. The progress tracking setting isn't saved in user preferences, but is saved or shared using URL parameters. @@ -148,7 +152,7 @@ due dates. ## Blocked epics **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33587) in GitLab 15.5: View blocking epics when hovering over the “blocked” icon. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33587) in GitLab 15.5: View blocking epics when hovering over the "blocked" icon. If an epic is [blocked by another epic](../epics/linked_epics.md#blocking-epics), an icon appears next to its title to indicate its blocked status. diff --git a/doc/user/group/saml_sso/example_saml_config.md b/doc/user/group/saml_sso/example_saml_config.md index aef39f587ef..7778648e985 100644 --- a/doc/user/group/saml_sso/example_saml_config.md +++ b/doc/user/group/saml_sso/example_saml_config.md @@ -55,6 +55,9 @@ Attribute mapping:  +NOTE: +Using the **Group ID** source attribute requires users to enter the group ID or object ID when configuring SAML group links. If available, use the **sAMAccountName** source attribute for the friendly group name instead. + ## Google Workspace Basic SAML app configuration: diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md index 65c4d68f743..27482893bd6 100644 --- a/doc/user/group/saml_sso/group_sync.md +++ b/doc/user/group/saml_sso/group_sync.md @@ -109,9 +109,9 @@ Users granted: ### Automatic member removal -After a group sync, for GitLab subgroups, users who are not members of a mapped SAML -group are removed from the group. Users in the top-level group are assigned the -[default membership role](index.md#role). +After a group sync, users who are not members of a mapped SAML group are removed from the group. +On GitLab.com, users in the top-level group are assigned the +[default membership role](index.md#role) instead of being removed. For example, in the following diagram: @@ -191,23 +191,23 @@ graph TB GitLabGroupD --> |Member|GitLabUserD ``` -### Use the API +#### User that belongs to many SAML groups automatically removed from GitLab group -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3. +When using Azure AD as the SAML identity provider, users that belong to many SAML groups can be automatically removed from your GitLab group. Users are removed from GitLab +groups if the group claim is missing from the user's SAML assertion. -You can use the GitLab API to [list, add, and delete](../../../api/groups.md#saml-group-links) SAML group links. +Because of a [known issue with Azure AD](https://support.esri.com/en/technical-article/000022190), if a user belongs to more than 150 SAML groups, the group claim is not sent +in the user's SAML assertion. -## Troubleshooting +With an Azure AD premium subscription, you can allow up to 500 group IDs to be sent in a SAML token using the +[Azure AD documentation configuration steps](https://support.esri.com/en/technical-article/000022190). -This section contains possible solutions for problems you might encounter. +Otherwise, you can work around this issue by changing the [group claims](https://learn.microsoft.com/en-us/azure/active-directory/hybrid/how-to-connect-fed-group-claims#configure-the-azure-ad-application-registration-for-group-attributes) to use the `Groups assigned to the application` option instead. -### User that belongs to many SAML groups automatically removed from GitLab group +. -When using Azure AD as the SAML identity provider, users that belong to many SAML groups can be automatically removed from your GitLab group. Users are removed from GitLab -groups if the group claim is missing from the user's SAML assertion. +### Use the API -Because of a [known issue with Azure AD](https://support.esri.com/en/technical-article/000022190), if a user belongs to more than 150 SAML groups, the group claim is not sent -in the user's SAML assertion. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3. -To work around this issue, allow more than 150 group IDs to be sent in SAML token using configuration steps in the -[Azure AD documentation](https://support.esri.com/en/technical-article/000022190). +You can use the GitLab API to [list, add, and delete](../../../api/groups.md#saml-group-links) SAML group links. diff --git a/doc/user/group/saml_sso/img/Azure-manage-group-claims.png b/doc/user/group/saml_sso/img/Azure-manage-group-claims.png Binary files differnew file mode 100644 index 00000000000..2ff24733282 --- /dev/null +++ b/doc/user/group/saml_sso/img/Azure-manage-group-claims.png diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 1275e3a21e4..e650b2dd130 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Introduced in GitLab 11.0. -This page describes SAML for groups. For instance-wide SAML on self-managed GitLab instances, see [SAML OmniAuth Provider](../../../integration/saml.md). +This page describes SAML for groups. For instance-wide SAML on self-managed GitLab instances, see [SAML SSO for self-managed GitLab instances](../../../integration/saml.md). [View the differences between SaaS and Self-Managed Authentication and Authorization Options](../../../administration/auth/index.md#saas-vs-self-managed-comparison). SAML on GitLab.com allows users to sign in through their SAML identity provider. If the user is not already a member, the sign-in process automatically adds the user to the appropriate group. @@ -97,7 +97,7 @@ After you set up your identity provider to work with GitLab, you must configure  NOTE: -The certificate [fingerprint algorithm](../../../integration/saml.md#configure-saml-on-your-idp) must be in SHA1. When configuring the identity provider (such as [Google Workspace](#google-workspace-setup-notes)), use a secure signature algorithm. +The certificate [fingerprint algorithm](../../../integration/saml.md#configure-saml-on-your-idp) must be in SHA1. When configuring the identity provider (such as [Google Workspace](#set-up-google-workspace)), use a secure signature algorithm. ### Additional configuration information @@ -121,34 +121,39 @@ It can also help to compare the XML response from your provider with our [exampl > - [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. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/339888) in GitLab 14.7 to not enforce SSO checks for Git activity originating from CI/CD jobs. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/215155) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `transparent_sso_enforcement` to include transparent enforcement even when SSO enforcement is not enabled. Disabled on GitLab.com. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/375788) in GitLab 15.8 by enabling transparent SSO by default on GitLab.com. FLAG: -On self-managed GitLab, transparent SSO enforcement is unavailable. On GitLab.com, see the [Transparent SSO rollout](https://gitlab.com/gitlab-org/gitlab/-/issues/375788) issue for the current status. +On self-managed GitLab, transparent SSO enforcement is unavailable. An +[issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/382917) to add +transparent SSO enforcement to self-managed GitLab. +On GitLab.com, transparent SSO enforcement is available by default. To turn off +transparent SSO, ask a support or production team to enable the +`transparent_sso_enforcement_override` feature flag for a specific customer +group. -SSO is enforced when users access groups and projects in the organization's group hierarchy. Users can view other groups and projects without SSO sign in. +#### Transparent SSO enforcement -SSO is enforced for each user with an existing SAML identity when the following is enabled: +By default, transparent SSO enforcement is enabled in GitLab.com. This means SSO is enforced: -- SAML SSO. -- The `:transparent_sso_enforcement` feature flag. +- When users access groups and projects in the organization's + group hierarchy. Users can view other groups and projects without SSO sign in. +- For each user with an existing SAML identity. + +When transparent SSO enforcement is enabled, users: + +- Are not prompted to sign in through SSO on each visit. GitLab checks + whether a user has authenticated through SSO. If the user last signed in more + than 24 hours ago, GitLab prompts the user to sign in again through SSO. +- Without SAML identities are not required to use SSO unless **Enforce + SSO-only authentication for web activity for this group** is enabled. A user has a SAML identity if one or both of the following are true: - They have signed in to GitLab by using their GitLab group's single sign-on URL. - They were provisioned by SCIM. -Users without SAML identities are not required to use SSO unless explicit enforcement is enabled. - -When the **Enforce SSO-only authentication for web activity for this group** option is enabled, all users must access GitLab by using their GitLab group's single sign-on URL to access group resources, -regardless of whether they have an existing SAML identity. -Users also cannot be added as new members manually. -Users with the Owner role can use the standard sign in process to make necessary changes to top-level group settings. - -However, users are not prompted to sign in through SSO on each visit. GitLab checks whether a user -has authenticated through SSO. If it's been more than 1 day since the last sign-in, GitLab -prompts the user to sign in again through SSO. - -When the transparent SSO enforcement feature flag is enabled, SSO is enforced as follows: +With transparent SSO enabled, SSO is enforced as follows: | Project/Group visibility | Enforce SSO setting | Member with identity | Member without identity | Non-member or not signed in | |--------------------------|---------------------|--------------------| ------ |------------------------------| @@ -157,36 +162,45 @@ When the transparent SSO enforcement feature flag is enabled, SSO is enforced as | Public | Off | Enforced | Not enforced | Not enforced | | Public | On | Enforced | Enforced | Not enforced | -An [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/297389) to add a similar SSO requirement for API and GitLab Pages activities. - -SSO enforcement has the following effects when enabled: - -- For groups, users can't share a project in the group outside the top-level group, - even if the project is forked. -- For Git activity over SSH and HTTPS, users must have at least one active session signed-in through SSO before they can push to or - pull from a GitLab repository. -- Git activity originating from CI/CD jobs do not have the SSO check enforced. -- Credentials that are not tied to regular users (for example, project and group access tokens, and deploy keys) do not have the SSO check enforced. -- Users must be signed-in through SSO before they can pull images using the [Dependency Proxy](../../packages/dependency_proxy/index.md). -- When the **Enforce SSO-only authentication for Git and Dependency Proxy activity for this group** option is enabled, any API endpoint that involves Git activity is under SSO - enforcement. For example, creating or deleting a branch, commit, or tag. - -When SSO is enforced, users are not immediately revoked. If the user: +An [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/297389) to add a similar SSO requirement for API activity. -- Is signed out, they cannot access the group after being removed from the identity provider. -- Has an active session, they can continue accessing the group for up to 24 hours until the identity - provider session times out. +#### SSO-only for web activity enforcement -### Selectively enable and disable transparent SSO enforcement +When the **Enforce SSO-only authentication for web activity for this group** option is enabled: -There are two feature flags associated with this feature to allow precise control. If a customer has a problem with transparent SSO on GitLab.com, GitLab can help troubleshoot and override the feature flag as necessary. +- All users must access GitLab by using their GitLab group's single sign-on URL + to access group resources, regardless of whether they have an existing SAML + identity. +- SSO is enforced when users access groups and projects in the organization's + group hierarchy. Users can view other groups and projects without SSO sign in. +- Users cannot be added as new members manually. +- Users with the Owner role can use the standard sign in process to make + necessary changes to top-level group settings. -**`transparent_sso_enforcement`:** This feature flag should only be enabled or disabled by the Authentication and Authorization group -or in the case of a serious and widespread issue affecting many groups or users. See [issue 375788](https://gitlab.com/gitlab-org/gitlab/-/issues/375788) for the current GitLab.com rollout status. +SSO enforcement for web activity has the following effects when enabled: -**`transparent_sso_enforcement_override`:** When the `transparent_sso_enforcement` feature flag is enabled, support or production teams can -turn off transparent SSO by enabling this feature flag for a specific customer group. **Enabling** this feature flag -disables transparent SSO enforcement. +- For groups, users cannot share a project in the group outside the top-level + group, even if the project is forked. +- For Git activity over SSH and HTTPS, users must have at least one active + session signed-in through SSO before they can push to or + pull from a GitLab repository. +- Git activity originating from CI/CD jobs do not have the SSO check enforced. +- Credentials that are not tied to regular users (for example, project and group + access tokens, and deploy keys) do not have the SSO check enforced. +- Users must be signed-in through SSO before they can pull images using the + [Dependency Proxy](../../packages/dependency_proxy/index.md). +- When the **Enforce SSO-only authentication for Git and Dependency Proxy + activity for this group** option is enabled, any API endpoint that involves + Git activity is under SSO enforcement. For example, creating or deleting a + branch, commit, or tag. + +When SSO for web activity is enforced, non-SSO group members do not lose access +immediately. If the user: + +- Has an active session, they can continue accessing the group for up to 24 + hours until the identity provider session times out. +- Is signed out, they cannot access the group after being removed from the + identity provider. ## Providers @@ -200,9 +214,9 @@ for additional guidance on information your identity provider may require. GitLab provides the following information for guidance only. If you have any questions on configuring the SAML app, contact your provider's support. -### Azure setup notes +### Set up Azure -Follow the Azure documentation on [configuring single sign-on to applications](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal) with the notes below for consideration. +Follow the Azure documentation on [configuring single sign-on to applications](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-setup-sso), and use the following notes when needed. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a demo of the Azure SAML setup including SCIM, see [SCIM Provisioning on Azure Using SAML SSO for Groups Demo](https://youtu.be/24-ZxmTeEBU). @@ -216,90 +230,92 @@ The video is outdated in regard to objectID mapping and you should follow the [S | Identity provider single sign-on URL | Login URL | | Certificate fingerprint | Thumbprint | -The recommended attributes are: +You should set the following attributes: -- **Unique User Identifier (Name identifier)** set to `user.objectID`. -- **nameid-format** set to persistent. -- Additional claims set to [supported attributes](#user-attributes). +- **Unique User Identifier (Name identifier)** to `user.objectID`. +- **nameid-format** to persistent. +- Additional claims to [supported attributes](#user-attributes). If using [Group Sync](#group-sync), customize the name of the group claim to match the required attribute. See our [example configuration page](example_saml_config.md#azure-active-directory). -### Google Workspace setup notes - -Follow the Google Workspace documentation on -[setting up SSO with Google as your identity provider](https://support.google.com/a/answer/6087519?hl=en) -with the notes below for consideration. - -| GitLab setting | Google Workspace field | -|:-------------------------------------|:-----------------------| -| Identifier | Entity ID | -| Assertion consumer service URL | ACS URL | -| GitLab single sign-on URL | Start URL | -| Identity provider single sign-on URL | SSO URL | - -NOTE: -Google Workspace displays a SHA256 fingerprint. To retrieve the SHA1 fingerprint required by GitLab for [configuring SAML](#configure-gitlab), download the certificate and calculate -the SHA1 certificate fingerprint using this sample command: `openssl x509 -noout -fingerprint -sha1 -inform pem -in "GoogleIDPCertificate-domain.com.pem"`. +### Set up Google Workspace -The recommended attributes and claims settings are: +1. [Set up SSO with Google as your identity provider](https://support.google.com/a/answer/6087519?hl=en). + The following GitLab settings correspond to the Google Workspace fields. -- **Primary email** set to `email`. -- **First name** set to `first_name`. -- **Last name** set to `last_name`. + | GitLab setting | Google Workspace field | + |:-------------------------------------|:-----------------------| + | Identifier | **Entity ID** | + | Assertion consumer service URL | **ACS URL** | + | GitLab single sign-on URL | **Start URL** | + | Identity provider single sign-on URL | **SSO URL** | -For NameID, the following settings are recommended: +1. Google Workspace displays a SHA256 fingerprint. To retrieve the SHA1 fingerprint + required by GitLab to [configure SAML](#configure-gitlab): + 1. Download the certificate. + 1. Run this command: -- **Name ID format** is set to `EMAIL`. -- **NameID** set to `Basic Information > Primary email`. + ```shell + openssl x509 -noout -fingerprint -sha1 -inform pem -in "GoogleIDPCertificate-domain.com.pem" + ``` -When selecting **Verify SAML Configuration** on the GitLab SAML SSO page, disregard the warning recommending setting the NameID format to "persistent". +1. Set these values: + - For **Primary email**: `email` + - For **First name**: `first_name` + - For **Last name**: `last_name` + - For **Name ID format**: `EMAIL` + - For **NameID**: `Basic Information > Primary email` -See our [example configuration page](example_saml_config.md#google-workspace). +On the GitLab SAML SSO page, when you select **Verify SAML Configuration**, disregard +the warning that recommends setting the **NameID** format to `persistent`. -### Okta setup notes +For details, see the [example configuration page](example_saml_config.md#google-workspace). -Follow the Okta documentation on [setting up a SAML application in Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/) with the notes below for consideration. +### Set up Okta <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a demo of the Okta SAML setup including SCIM, see [Demo: Okta Group SAML & SCIM setup](https://youtu.be/0ES9HsZq0AQ). -| GitLab Setting | Okta Field | -| ------------------------------------ | ---------------------------------------------------------- | -| Identifier | Audience URI | -| Assertion consumer service URL | Single sign-on URL | -| GitLab single sign-on URL | Login page URL (under **Application Login Page** settings) | -| Identity provider single sign-on URL | Identity Provider Single Sign-On URL | +1. [Set up a SAML application in Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/). + The following GitLab settings correspond to the Okta fields. -Under the Okta **Single sign-on URL** field, check the option **Use this for Recipient URL and Destination URL**. + | GitLab setting | Okta field | + | ------------------------------------ | ---------------------------------------------------------- | + | Identifier | **Audience URI** | + | Assertion consumer service URL | **Single sign-on URL** | + | GitLab single sign-on URL | **Login page URL** (under **Application Login Page** settings) | + | Identity provider single sign-on URL | **Identity Provider Single Sign-On URL** | -For NameID, the following settings are recommended; for SCIM, the following settings are required: +1. Under the Okta **Single sign-on URL** field, select the **Use this for Recipient URL and Destination URL** checkbox. -- **Application username** (NameID) set to **Custom** `user.getInternalProperty("id")`. -- **Name ID Format** set to **Persistent**. +1. Set these values: + - For **Application username (NameID)**: **Custom** `user.getInternalProperty("id")` + - For **Name ID Format**: `Persistent` The Okta GitLab application available in the App Catalog only supports [SCIM](scim_setup.md). Support -for SAML is proposed in issue [216173](https://gitlab.com/gitlab-org/gitlab/-/issues/216173). +for SAML is proposed in [issue 216173](https://gitlab.com/gitlab-org/gitlab/-/issues/216173). -### OneLogin setup notes +### Set up OneLogin -OneLogin supports their own [GitLab (SaaS)](https://onelogin.service-now.com/support?id=kb_article&sys_id=92e4160adbf16cd0ca1c400e0b961923&kb_category=50984e84db738300d5505eea4b961913) -application. +OneLogin supports its own [GitLab (SaaS) application](https://onelogin.service-now.com/support?id=kb_article&sys_id=92e4160adbf16cd0ca1c400e0b961923&kb_category=50984e84db738300d5505eea4b961913). -If you decide to use the OneLogin generic [SAML Test Connector (Advanced)](https://onelogin.service-now.com/support?id=kb_article&sys_id=b2c19353dbde7b8024c780c74b9619fb&kb_category=93e869b0db185340d5505eea4b961934), -we recommend the ["Use the OneLogin SAML Test Connector" documentation](https://onelogin.service-now.com/support?id=kb_article&sys_id=93f95543db109700d5505eea4b96198f) with the following settings: +1. If you use the OneLogin generic + [SAML Test Connector (Advanced)](https://onelogin.service-now.com/support?id=kb_article&sys_id=b2c19353dbde7b8024c780c74b9619fb&kb_category=93e869b0db185340d5505eea4b961934), + you should [use the OneLogin SAML Test Connector](https://onelogin.service-now.com/support?id=kb_article&sys_id=93f95543db109700d5505eea4b96198f). The following GitLab settings correspond + to the OneLogin fields: -| GitLab Setting | OneLogin Field | -| ------------------------------------------------ | ---------------------------- | -| Identifier | Audience | -| Assertion consumer service URL | Recipient | -| Assertion consumer service URL | ACS (Consumer) URL | -| Assertion consumer service URL (escaped version) | ACS (Consumer) URL Validator | -| GitLab single sign-on URL | Login URL | -| Identity provider single sign-on URL | SAML 2.0 Endpoint | + | GitLab setting | OneLogin field | + | ------------------------------------------------ | -------------------------------- | + | Identifier | **Audience** | + | Assertion consumer service URL | **Recipient** | + | Assertion consumer service URL | **ACS (Consumer) URL** | + | Assertion consumer service URL (escaped version) | **ACS (Consumer) URL Validator** | + | GitLab single sign-on URL | **Login URL** | + | Identity provider single sign-on URL | **SAML 2.0 Endpoint** | -Recommended `NameID` value: `OneLogin ID`. +1. For **NameID**, use `OneLogin ID`. ### Change the SAML app @@ -333,7 +349,7 @@ To migrate users to a new email domain, users must: ## User access and management > - SAML user provisioning [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/268142) in GitLab 13.7. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325712) in GitLab 14.0, GitLab users created by [SAML SSO](index.md#user-access-and-management) or SCIM provisioning are displayed with an **Enterprise** badge in the **Members** view. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325712) in GitLab 14.0, GitLab users created by [SAML SSO](index.md#user-access-and-management) or SCIM provisioning are displayed with an ][**Enterprise**](../../enterprise_user/index.md) badge in the **Members** view. After group SSO is configured and enabled, users can access the GitLab.com group through the identity provider's dashboard. If [SCIM](scim_setup.md) is configured, see [user access](scim_setup.md#user-access) on the SCIM page. @@ -431,8 +447,9 @@ convert the information to XML. An example SAML response is shown here. By default, users provisioned with SAML or SCIM are sent a verification email to verify their identity. Instead, you can [configure GitLab with a custom domain](../../project/pages/custom_domains_ssl_tls_certification/index.md) and GitLab -automatically confirms user accounts. Users still receive an enterprise user welcome email. Confirmation is bypassed for -users: +automatically confirms user accounts. Users still receive an +[enterprise user](../../enterprise_user/index.md) welcome email. Confirmation is +bypassed for users: - That are provisioned with SAML or SCIM. - That have an email address that belongs to the verified domain. @@ -477,7 +494,7 @@ group owner, and then you can unlink the account. For example, to unlink the `MyOrg` account: -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. In the **Service sign-in** section, select **Disconnect** next to the connected account. diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 8c30c246566..c6ff5dc63c3 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -116,7 +116,7 @@ For each attribute: 1. Select the required settings. 1. Select **Ok**. -If your SAML configuration differs from [the recommended SAML settings](index.md#azure-setup-notes), select the mapping +If your SAML configuration differs from [the recommended SAML settings](index.md#set-up-azure), select the mapping attributes and modify them accordingly. In particular, the `objectId` source attribute must map to the `externalId` target attribute. @@ -133,13 +133,13 @@ Prerequisites: product tier is required to use SCIM on Okta. - [GitLab is configured](#configure-gitlab). - SAML application for [Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/) set up as - described in the [Okta setup notes](index.md#okta-setup-notes). + described in the [Okta setup notes](index.md#set-up-okta). - Your Okta SAML setup matches the [configuration steps exactly](index.md), especially the NameID configuration. To configure Okta for SCIM: 1. Sign in to Okta. -1. Ensure you are in the Admin Area by selecting the **Admin** button located in the top right. The button is not visible from the Admin Area. +1. Ensure you are in the Admin Area by selecting the **Admin** button located in the upper right. The button is not visible from the Admin Area. 1. In the **Application** tab, select **Browse App Catalog**. 1. Search for **GitLab**, find and select the **GitLab** application. 1. On the GitLab application overview page, select **Add**. @@ -170,7 +170,7 @@ encounter issues. ## User access -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325712) in GitLab 14.0, GitLab users created by [SAML SSO](index.md#user-access-and-management) or SCIM provisioning are displayed with an **Enterprise** badge in the **Members** view. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325712) in GitLab 14.0, GitLab users created by [SAML SSO](index.md#user-access-and-management) or SCIM provisioning are displayed with an [**Enterprise**](../../enterprise_user/index.md) badge in the **Members** view. During the synchronization process, all new users: diff --git a/doc/user/group/saml_sso/troubleshooting.md b/doc/user/group/saml_sso/troubleshooting.md index a42d3f8fd03..eadf385feb3 100644 --- a/doc/user/group/saml_sso/troubleshooting.md +++ b/doc/user/group/saml_sso/troubleshooting.md @@ -58,6 +58,16 @@ You can use one of the following to troubleshoot SAML: For convenience, we've included some [example resources](../../../user/group/saml_sso/example_saml_config.md) used by our Support Team. While they may help you verify the SAML app configuration, they are not guaranteed to reflect the current state of third-party products. +### Calculate the fingerprint + +If you use a `idp_cert_fingerprint`, it must be a SHA1 fingerprint. To calculate a SHA1 fingerprint, download the certificate file and run: + +```shell +openssl x509 -in <filename.crt> -noout -fingerprint -sha1 +``` + +Replace `filename.crt` with the name of the certificate file. + ## Searching Rails log for a SAML response **(FREE SELF)** You can find the base64-encoded SAML Response in the [`production_json.log`](../../../administration/logs/index.md#production_jsonlog). @@ -122,13 +132,17 @@ must be validated using either a fingerprint, a certificate, or a validator. For this requirement, be sure to take the following into account: -- If a fingerprint is used, it must be the SHA1 fingerprint +- If you use a fingerprint, it must be the correct SHA1 fingerprint. To confirm that you are using + the correct SHA1 fingerprint: + 1. Re-download the certificate file. + 1. [Calculate the fingerprint](#calculate-the-fingerprint). + 1. Compare the fingerprint to the value provided in `idp_cert_fingerprint`. The values should be the same. - If no certificate is provided in the settings, a fingerprint or fingerprint validator needs to be provided and the response from the server must contain - a certificate (`<ds:KeyInfo><ds:X509Data><ds:X509Certificate>`) + a certificate (`<ds:KeyInfo><ds:X509Data><ds:X509Certificate>`). - If a certificate is provided in the settings, it is no longer necessary for the request to contain one. In this case the fingerprint or fingerprint - validators are optional + validators are optional. If none of the above described scenarios is valid, the request fails with one of the mentioned errors. @@ -193,7 +207,7 @@ Alternatively, the SAML response may be missing the `InResponseTo` attribute in The identity provider administrator should ensure that the login is initiated by the service provider and not only the identity provider. -### Message: "Sign in to GitLab to connect your organization's account" **(PREMIUM SAAS)** +### Message: "There is already a GitLab account associated with this email address. Sign in with your existing credentials to connect your organization's account" **(PREMIUM SAAS)** A user can see this message when they are trying to [manually link SAML to their existing GitLab.com account](index.md#linking-saml-to-your-existing-gitlabcom-account). @@ -233,10 +247,17 @@ If you receive a `404` during setup when using "verify configuration", make sure If a user is trying to sign in for the first time and the GitLab single sign-on URL has not [been configured](index.md#configure-your-identity-provider), they may see a 404. As outlined in the [user access section](index.md#linking-saml-to-your-existing-gitlabcom-account), a group Owner needs to provide the URL to users. -If all users are receiving a `404` after signing in to the identity provider (IdP), verify the `assertion_consumer_service_url`: +If all users are receiving a `404` after signing in to the identity provider (IdP): + +- Verify the `assertion_consumer_service_url`: + + - In the GitLab configuration by [matching it to the HTTPS endpoint of GitLab](../../../integration/saml.md#configure-saml-support-in-gitlab). + - As the `Assertion Consumer Service URL` or equivalent when setting up the SAML app on your IdP. + +- Verify if the `404` is related to [the user having too many groups assigned to them in their Azure IdP](group_sync.md#user-that-belongs-to-many-saml-groups-automatically-removed-from-gitlab-group) by checking: -- In the GitLab configuration by [matching it to the HTTPS endpoint of GitLab](../../../integration/saml.md#configure-saml-support-in-gitlab). -- As the `Assertion Consumer Service URL` or equivalent when setting up the SAML app on your IdP. + - If the user has group links configured. + - Audit events if the user gets added to the group and then immediately removed. For configuration examples for some of the common providers, see the [example group SAML and SCIM configurations](example_saml_config.md). diff --git a/doc/user/group/settings/group_access_tokens.md b/doc/user/group/settings/group_access_tokens.md index 6e0caa633eb..cd50c209b0d 100644 --- a/doc/user/group/settings/group_access_tokens.md +++ b/doc/user/group/settings/group_access_tokens.md @@ -14,7 +14,7 @@ With group access tokens, you can use a single token to: You can use a group access token to authenticate: -- With the [GitLab API](../../../api/index.md#personalprojectgroup-access-tokens). +- With the [GitLab API](../../../api/rest/index.md#personalprojectgroup-access-tokens). - In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/330718) and later, authenticate with Git over HTTPS. Use: @@ -163,7 +163,9 @@ Even when creation is disabled, you can still use and revoke existing group acce ## Bot users for groups -Each time you create a group access token, a bot user is created and added to the group. These bot users are similar to +Bot users for groups are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users). +Each time you create a group access token, a bot user is created and added to the group. +These bot users are similar to [bot users for projects](../../project/settings/project_access_tokens.md#bot-users-for-projects), except they are added to groups instead of projects. Bot users for groups: @@ -174,5 +176,3 @@ to groups instead of projects. Bot users for groups: - Have an email set to `group{group_id}_bot@noreply.{Gitlab.config.gitlab.host}`. For example, `group123_bot@noreply.example.com`. All other properties are similar to [bot users for projects](../../project/settings/project_access_tokens.md#bot-users-for-projects). - -For more information, see [Bot users for projects](../../project/settings/project_access_tokens.md#bot-users-for-projects). diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index f8d3456648d..6c7baa848e7 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can organize GitLab [groups](../index.md) into subgroups. You can use subgroups to: - Separate internal and external organizations. Because every subgroup can have its own - [visibility level](../../../development/permissions.md#general-permissions), you can host groups for different + [visibility level](../../public_access.md), you can host groups for different purposes under the same parent group. - Organize large projects. You can use subgroups to give different access to parts of the source code. @@ -85,7 +85,7 @@ You cannot host a GitLab Pages subgroup website with a top-level domain name. Fo To create a subgroup: 1. On the top bar, select **Main menu > Groups** and find and select the parent group to add a subgroup to. -1. On the parent group's overview page, in the top right, select **New subgroup**. +1. On the parent group's overview page, in the upper right, select **New subgroup**. 1. Select **Create group**. 1. Fill in the fields. View a list of [reserved names](../../reserved_names.md) that cannot be used as group names. 1. Select **Create group**. diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 8635b4567ef..c5a95779087 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -305,7 +305,7 @@ After you create a value stream, you can customize it to suit your purposes. To 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value Stream**. -1. In the top right, select the dropdown list, and select a value stream. +1. In the upper right, select the dropdown list, and select a value stream. 1. Next to the value stream dropdown list, select **Edit**. 1. Optional: - Rename the value stream. @@ -324,7 +324,7 @@ To delete a custom value stream: 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value Stream**. -1. In the top right, select the dropdown list and then select the value stream you would like to delete. +1. In the upper right, select the dropdown list and then select the value stream you would like to delete. 1. Select **Delete (name of value stream)**. 1. To confirm, select **Delete**. @@ -367,3 +367,7 @@ To view tasks by type: and select **Issues** or **Merge Requests**. 1. To add or remove labels, select the **Settings** (**{settings}**) dropdown list and select or search for a label. By default the top group-level labels (maximum 10) are selected. You can select a maximum of 15 labels. + +## Troubleshooting + +See [Value stream analytics for projects](../../analytics/value_stream_analytics.md#troubleshooting). diff --git a/doc/user/index.md b/doc/user/index.md index 81561d23c7b..8d761c88484 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -10,10 +10,10 @@ Get to know the GitLab end-to-end workflow. Configure permissions, organize your work, create and secure your application, and analyze its performance. Report on team productivity throughout the process. - [Set up your organization](../topics/set_up_organization.md) -- [Organize work with projects](../user/project/index.md) +- [Organize work with projects](../user/project/organize_work_with_projects.md) - [Plan and track work](../topics/plan_and_track.md) - [Build your application](../topics/build_your_application.md) -- [Secure your application](../user/application_security/index.md) +- [Secure your application](../user/application_security/secure_your_application.md) - [Deploy and release your application](../topics/release_your_application.md) - [Monitor application performance](../operations/index.md) - [Monitor runner performance](https://docs.gitlab.com/runner/monitoring/index.html) diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index eb6a8db0c05..93a82023480 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -58,7 +58,10 @@ WARNING: Like any other job artifact, Terraform plan data is viewable by anyone with the Guest role on the repository. Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform plan includes sensitive data, like passwords, access tokens, or certificates, you should -encrypt plan output or modify the project visibility settings. +encrypt plan output or modify the project visibility settings. We also strongly recommend that you **disable** +[public pipelines](../../../ci/pipelines/settings.md#change-pipeline-visibility-for-non-project-members-in-public-projects) +by setting the artifact's public flag to false (`public: false`). This setting ensures artifacts are +accessible only to GitLab Administrators and project members with the Reporter role and above. To configure GitLab CI/CD as a backend: diff --git a/doc/user/infrastructure/iac/terraform_template_recipes.md b/doc/user/infrastructure/iac/terraform_template_recipes.md index 0d1b56ae979..89a97f305e4 100644 --- a/doc/user/infrastructure/iac/terraform_template_recipes.md +++ b/doc/user/infrastructure/iac/terraform_template_recipes.md @@ -29,6 +29,69 @@ The `destroy` job is part of the `cleanup` stage. Like the `deploy` job, the `destroy` job is always `manual` and is not tied to the default branch. +To connect the `destroy` job to the GitLab environment: + +```yaml +include: + - template: Terraform.latest.gitlab-ci.yml + +deploy: + envrionment: + name: $TF_STATE_NAME + action: start + on_stop: destroy + +destroy: + extends: .terraform:destroy + environment: + name: $TF_STATE_NAME + action: stop +``` + +In this configuration, the `destroy` job is always created. However, you might want to create a `destroy` job only if certain +conditions are met. + +The following configuration creates a `destroy` job, runs a destroy plan and omits the `deploy` job only if `TF_DESTROY` is true: + +```yaml +include: + - template: Terraform.latest.gitlab-ci.yml + +build: + rules: + - if: $TF_DESTROY == "true" + variables: + TF_CLI_ARGS_plan: "-destroy" + - when: on_success + +deploy: + envrionment: + name: $TF_STATE_NAME + action: start + on_stop: destroy + rules: + - if: $TF_DESTROY == "true" + when: never + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $TF_AUTO_DEPLOY == "true" + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH + when: manual + +destroy: + extends: .terraform:destroy + dependencies: + - build + variables: + TF_CLI_ARGS_destroy: "${TF_PLAN_CACHE}" + environment: + name: $TF_STATE_NAME + action: stop + rules: + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $TF_DESTROY == "true" + when: manual +``` + +This configuration has a known issue: when the `destroy` job is not in the same pipeline as the `deploy` job, the `on_stop` environment action does not work. + ## Run a custom `terraform` command in a job To define a job that runs a custom `terraform` command, the @@ -182,6 +245,19 @@ deploy: For an example repository, see the [GitLab Terraform template usage project](https://gitlab.com/gitlab-org/configure/examples/terraform-template-usage). +## Automatically deploy from the default branch + +You can automatically deploy from the default branch by setting the `TF_AUTO_DEPLOY` variable +to `"true"`. All other values are interpreted as `"false"`. + +```yaml +variables: + TF_AUTO_DEPLOY: "true" + +include: + - template: Terraform.latest.gitlab-ci.yml +``` + ## Deploy Terraform to multiple environments You can run pipelines in multiple environments, each with a unique Terraform state. diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index 811e4ad6ad6..87633932e0d 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -25,7 +25,7 @@ The various GitLab integrations help you: with code changes. - Scale using a module registry. -Learn more about how GitLab can help you run [Infrastructure as Code](iac/index.md). +For more information, see how GitLab can help you run [Infrastructure as Code](iac/index.md). ## Integrated Kubernetes management @@ -34,7 +34,7 @@ cluster applications. With the GitLab agent, you can connect clusters behind a f have real-time access to API endpoints, perform pull-based or push-based deployments for production and non-production environments, and much more. -Learn more about the [GitLab agent](../clusters/agent/index.md). +For more information, see the [GitLab agent](../clusters/agent/index.md). ## Runbooks in GitLab diff --git a/doc/user/markdown.md b/doc/user/markdown.md index d29369f142c..eaceeccc148 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -84,9 +84,9 @@ The following features are not found in standard Markdown. ### Colors -[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#colors). +Markdown does not support changing text color. -You can write a color in the formats: `HEX`, `RGB`, or `HSL`. +You can write a color code in the formats: `HEX`, `RGB`, or `HSL`. - `HEX`: `` `#RGB[A]` `` or `` `#RRGGBB[AA]` `` - `RGB`: `` `RGB[A](R, G, B[, A])` `` @@ -94,7 +94,8 @@ You can write a color in the formats: `HEX`, `RGB`, or `HSL`. Named colors are not supported. -Colors in backticks are followed by a color indicator: +In the GitLab application (but not the GitLab documentation) color codes in backticks +display a color chip next to the color code. For example: ```markdown - `#F00` @@ -108,6 +109,9 @@ Colors in backticks are followed by a color indicator: - `HSLA(540,70%,50%,0.3)` ``` +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#colors) +to see the color chips next to the color code: + - `#F00` - `#F00A` - `#FF0000` @@ -353,7 +357,7 @@ _KaTeX only supports a [subset](https://katex.org/docs/supported.html) of LaTeX. This syntax also works for the Asciidoctor `:stem: latexmath`. For details, see the [Asciidoctor user manual](https://asciidoctor.org/docs/user-manual/#activating-stem-support). -Math written between dollar signs with backticks (``$`...`$``) or single dollar signs (`$...$`) +Math written between dollar signs with backticks (``$`...`$``) or single dollar signs (`$...$`) is rendered inline with the text. Math written between double dollar signs (`$$...$$`) or in a [code block](#code-spans-and-blocks) with @@ -1007,11 +1011,12 @@ Do not change to a reference style link.  -#### Change the image dimensions +#### Change the image or video dimensions -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28118) in GitLab 15.7. +> - Support for images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28118) in GitLab 15.7. +> - Support for videos [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17139) in GitLab 15.9. -You can control the width and height of an image by following the image with +You can control the width and height of an image or video by following the image with an attribute list. The value must an integer with a unit of either `px` (default) or `%`. diff --git a/doc/user/okrs.md b/doc/user/okrs.md index 0b6bffa97ce..0d3be8474fe 100644 --- a/doc/user/okrs.md +++ b/doc/user/okrs.md @@ -13,8 +13,8 @@ OKRs are in [**Alpha**](../policy/alpha-beta-support.md#alpha-features). For the OKR feature roadmap, see [epic 7864](https://gitlab.com/groups/gitlab-org/-/epics/7864). FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the featured flag](../administration/feature_flags.md) named `okrs_mvc`. +On self-managed GitLab, by default this feature is not available. To make it available per project, ask an administrator to [enable the featured flag](../administration/feature_flags.md) named `okrs_mvc`. +On GitLab.com, this feature is not available. The feature is not ready for production use. Use objectives and key results to align your workforce towards common goals and track the progress. @@ -41,7 +41,7 @@ To create an objective: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Issues**. -1. In the top right corner, next to **New issue**, select the down arrow **{chevron-lg-down}** and then select **New objective**. +1. In the upper-right corner, next to **New issue**, select the down arrow **{chevron-lg-down}** and then select **New objective**. 1. Select **New objective** again. 1. Enter the objective title. 1. Select **Create objective**. diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 619d822adf2..2911a700e14 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -36,4 +36,4 @@ You can drag project cards to change their order. The card order is currently on ## Making it the default dashboard when you sign in The Operations Dashboard can also be made the default GitLab dashboard shown when -you sign in. To make it the default, visit your [profile preferences](../profile/preferences.md). +you sign in. To make it the default, see [Profile preferences](../profile/preferences.md). diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 49c54ec191e..b990cf1f09b 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -308,7 +308,7 @@ used to access them: ### Caching -To improve performance, Composer caches files related to a package. Note that Composer doesn't remove data by +To improve performance, Composer caches files related to a package. Composer doesn't remove data by itself. The cache grows as new packages are installed. If you encounter issues, clear the cache with this command: diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index dd6605c2f01..05daa525893 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -121,7 +121,9 @@ To authenticate to the Package Registry, you need one of the following: 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. +authenticated. If you try to search or download a package from a private or internal +project without authenticating, you receive the error `unable to find the package in remote` +in the Conan client. ### Add your credentials to the GitLab remote @@ -271,7 +273,7 @@ Prerequisites: NOTE: If you try installing the package you created in this tutorial, the install command -will have no effect because the package already exists. +has no effect because the package already exists. Delete `~/.conan/data` to clean up the packages stored in the cache. ## Remove a Conan package diff --git a/doc/user/packages/container_registry/authenticate_with_container_registry.md b/doc/user/packages/container_registry/authenticate_with_container_registry.md index cdc7cbe947b..f48ba7bbf52 100644 --- a/doc/user/packages/container_registry/authenticate_with_container_registry.md +++ b/doc/user/packages/container_registry/authenticate_with_container_registry.md @@ -6,6 +6,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Authenticate with the Container Registry **(FREE)** +<!--- start_remove The following content will be removed on remove_date: '2023-11-22' --> +WARNING: +[External authorization](../../admin_area/settings/external_authorization.md) will be enabled by default in GitLab 16.0. External authorization prevents personal access tokens and deploy tokens from accessing container and package registries and affects all users who use these tokens to access the registries. You can disable external authorization if you want to use personal access tokens and deploy tokens with the container or package registries. +<!--- end_remove --> + To authenticate with the Container Registry, you can use a: - [Personal access token](../../profile/personal_access_tokens.md). diff --git a/doc/user/packages/container_registry/build_and_push_images.md b/doc/user/packages/container_registry/build_and_push_images.md index bbb82300488..aa86b87660b 100644 --- a/doc/user/packages/container_registry/build_and_push_images.md +++ b/doc/user/packages/container_registry/build_and_push_images.md @@ -144,7 +144,7 @@ In this example, `$CI_REGISTRY_IMAGE` resolves to the address of the registry ti to this project. `$CI_COMMIT_REF_NAME` resolves to the branch or tag name, which can contain forward slashes. Image tags can't contain forward slashes. Use `$CI_COMMIT_REF_SLUG` as the image tag. You can declare the variable, `$IMAGE_TAG`, -combining `$CI_REGISTRY_IMAGE` and `$CI_REGISTRY_IMAGE` to save some typing in the +combining `$CI_REGISTRY_IMAGE` and `$CI_COMMIT_REF_NAME` to save some typing in the `script` section. This example splits the tasks into 4 pipeline stages, including two tests that run in parallel. The `build` is stored in the container diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index c3790c252cc..4d7b25e2d77 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -72,7 +72,7 @@ NOTE: You must [authenticate with the container registry](authenticate_with_container_registry.md) to download container images from a private repository. -For more information on running container images, visit the [Docker documentation](https://docs.docker.com/get-started/). +For more information on running container images, see the [Docker documentation](https://docs.docker.com/get-started/). ## Naming convention for your container images @@ -165,3 +165,9 @@ this setting. However, disabling the Container Registry disables all Container R | Private project with Container Registry visibility <br/> set to **Everyone With Access** (UI) or `enabled` (API) | View Container Registry <br/> and pull images | No | No | Yes | | Private project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | | Any project with Container Registry `disabled` | All operations on Container Registry | No | No | No | + +## Supported image types + +The Container Registry supports [Docker V2](https://docs.docker.com/registry/spec/manifest-v2-2/) and [Open Container Initiative (OCI)](https://github.com/opencontainers/image-spec/blob/main/spec.md) image formats. + +OCI support means that you can host OCI-based image formats in the registry, such as [Helm 3+ chart packages](https://helm.sh/docs/topics/registries/). There is no distinction between image formats in the GitLab [API](../../../api/container_registry.md) and the UI. [Issue 38047](https://gitlab.com/gitlab-org/gitlab/-/issues/38047) addresses this distinction, starting with Helm. diff --git a/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md b/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md index 0ce9635e05a..110f3ff908c 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md +++ b/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md @@ -22,7 +22,7 @@ usage. Use these tools and techniques to determine your image's size: - [Skopeo](https://github.com/containers/skopeo): - use Skopeo's `inspect` command to examine layer count and sizes through API calls. You can + use the Skopeo `inspect` command to examine layer count and sizes through API calls. You can therefore inspect this data prior to running `docker pull IMAGE`. - Docker in CI: examine and record the image size when using GitLab CI prior to pushing an image @@ -41,7 +41,7 @@ Use these tools and techniques to determine your image's size: ### Use a smaller base image Consider using a smaller base image, such as [Alpine Linux](https://alpinelinux.org/). -An Alpine image is around 5MB, which is several times smaller than popular base images such as +An Alpine image is around 5 MB, which is several times smaller than popular base images such as [Debian](https://hub.docker.com/_/debian). If your application is distributed as a self-contained static binary, such as for Go applications, you can also consider using the Docker [scratch](https://hub.docker.com/_/scratch/) diff --git a/doc/user/packages/container_registry/reduce_container_registry_storage.md b/doc/user/packages/container_registry/reduce_container_registry_storage.md index 15948569cb8..9229ea61821 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_storage.md +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -320,7 +320,7 @@ the tags. To create the list and delete the tags: the tags' names are written to the `list_o_tags.out` file: ```shell - # Get a list of all tags in a certain container repository while considering [pagination](../../../api/index.md#pagination) + # Get a list of all tags in a certain container repository while considering [pagination](../../../api/rest/index.md#pagination) echo -n "" > list_o_tags.out; for i in {1..N}; do curl --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 ``` diff --git a/doc/user/packages/debian_repository/index.md b/doc/user/packages/debian_repository/index.md index 7db2a341743..7ec20e3d036 100644 --- a/doc/user/packages/debian_repository/index.md +++ b/doc/user/packages/debian_repository/index.md @@ -15,9 +15,6 @@ The Debian package registry for GitLab is under development and isn't ready for limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6057) details the remaining work and timelines to make it production ready. -NOTE: -The Debian registry is not FIPS compliant and is disabled when [FIPS mode](../../../development/fips_compliance.md) is enabled. - Publish Debian packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency. @@ -65,32 +62,52 @@ Feature.disable(:debian_group_packages) Creating a Debian package is documented [on the Debian Wiki](https://wiki.debian.org/Packaging). -## Authenticate to the Package Registry +## Authenticate to the Debian endpoints + +Authentication methods differs between [distributions APIs](#authenticate-to-the-debian-distributions-apis) +and [package repositories](#authenticate-to-the-debian-package-repositories). -To create a distribution, publish a package, or install a private package, you need one of the -following: +### Authenticate to the Debian distributions APIs -- [Personal access token](../../../api/index.md#personalprojectgroup-access-tokens) +To create, read, update, or delete a distribution, you need one of the following: + +- [Personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens), + using `--header "PRIVATE-TOKEN: <personal_access_token>"` +- [Deploy token](../../project/deploy_tokens/index.md) + using `--header "Deploy-Token: <deploy_token>"` - [CI/CD job token](../../../ci/jobs/ci_job_token.md) + using `--header "Job-Token: <job_token>"` + +### Authenticate to the Debian Package Repositories + +To publish a package, or install a private package, you need to use basic authentication, +with one of the following: + +- [Personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens), + using `<username>:<personal_access_token>` - [Deploy token](../../project/deploy_tokens/index.md) + using `<deploy_token_name>:<deploy_token>` +- [CI/CD job token](../../../ci/jobs/ci_job_token.md) + using `gitlab-ci-token:<job_token>` ## Create a Distribution On the project-level, Debian packages are published using *Debian Distributions*. To publish packages on the group level, create a distribution with the same `codename`. -To create a project-level distribution: +To create a project-level distribution using a personal access token: ```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/debian_distributions?codename=<codename>" +curl --request POST --header "PRIVATE-TOKEN: <personal_access_token>" \ + "https://gitlab.example.com/api/v4/projects/<project_id>/debian_distributions?codename=<codename>" ``` -Example response with `codename=unstable`: +Example response with `codename=sid`: ```json { "id": 1, - "codename": "unstable", + "codename": "sid", "suite": null, "origin": null, "label": null, @@ -123,33 +140,50 @@ Once built, several files are created: - `.buildinfo` file: Used for Reproducible builds (optional) - `.changes` file: Upload metadata, and list of uploaded files (all the above) -To upload these files, you can use `dput-ng >= 1.32` (Debian bullseye): +To upload these files, you can use `dput-ng >= 1.32` (Debian bullseye). +`<username>` and `<password>` are defined +[as above](#authenticate-to-the-debian-package-repositories): ```shell cat <<EOF > dput.cf [gitlab] method = https -fqdn = <username>:<your_access_token>@gitlab.example.com +fqdn = <username>:<password>@gitlab.example.com incoming = /api/v4/projects/<project_id>/packages/debian EOF dput --config=dput.cf --unchecked --no-upload-log gitlab <your_package>.changes ``` +## Directly upload a package + +> Direct upload [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/101838) in GitLab 15.9. + +When you don't have access to `.changes` file, you can directly upload a `.deb` by passing +distribution `codename` and target `component` as parameters with +your [credentials](#authenticate-to-the-debian-package-repositories). +For example, to upload to component `main` of distribution `sid` using a personal access token: + +```shell +curl --request PUT --user "<username>:<personal_access_token>" \ + "https://gitlab.example.com/api/v4/projects/<project_id>/packages/debian/?distribution=sid&component=main" \ + --upload-file /path/to/your.deb +``` + ## Install a package To install a package: 1. Configure the repository: - If you are using a private project, add your [credentials](#authenticate-to-the-package-registry) to your apt configuration: + If you are using a private project, add your [credentials](#authenticate-to-the-debian-package-repositories) to your apt configuration: ```shell - echo 'machine gitlab.example.com login <username> password <your_access_token>' \ + echo 'machine gitlab.example.com login <username> password <password>' \ | sudo tee /etc/apt/auth.conf.d/gitlab_project.conf ``` - Download your distribution key: + Download your distribution key using your [credentials](#authenticate-to-the-debian-distributions-apis): ```shell sudo mkdir -p /usr/local/share/keyrings @@ -182,14 +216,14 @@ To download a source package: 1. Configure the repository: - If you are using a private project, add your [credentials](#authenticate-to-the-package-registry) to your apt configuration: + If you are using a private project, add your [credentials](#authenticate-to-the-debian-package-repositories) to your apt configuration: ```shell - echo 'machine gitlab.example.com login <username> password <your_access_token>' \ + echo 'machine gitlab.example.com login <username> password <password>' \ | sudo tee /etc/apt/auth.conf.d/gitlab_project.conf ``` - Download your distribution key: + Download your distribution key using your [credentials](#authenticate-to-the-debian-distributions-apis): ```shell sudo mkdir -p /usr/local/share/keyrings diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index a1a9d2a4915..8dc3c98795b 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -322,7 +322,7 @@ services: ### Issues when authenticating to the Dependency Proxy from CI/CD jobs -GitLab Runner will automatically authenticate to the Dependency Proxy. However, the underlying Docker engine is still subject to its [authorization resolving process](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/advanced-configuration.md#precedence-of-docker-authorization-resolving). +GitLab Runner authenticates automatically to the Dependency Proxy. However, the underlying Docker engine is still subject to its [authorization resolving process](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/docs/configuration/advanced-configuration.md#precedence-of-docker-authorization-resolving). Misconfigurations in the authentication mechanism may cause `HTTP Basic: Access denied` and `403: Access forbidden` errors. diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 9b49f946984..932de0bcde6 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -13,13 +13,13 @@ Publish generic files, like release binaries, in your project's Package Registry ## Authenticate to the Package Registry -To authenticate to the Package Registry, you need either a [personal access token](../../../api/index.md#personalprojectgroup-access-tokens), +To authenticate to the Package Registry, you need either a [personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens), [CI/CD job token](../../../ci/jobs/ci_job_token.md), or [deploy token](../../project/deploy_tokens/index.md). In addition to the standard API authentication mechanisms, the generic package API allows authentication with HTTP Basic authentication for use with tools that do not support the other available mechanisms. The `user-id` is not checked and -may be any value, and the `password` must be either a [personal access token](../../../api/index.md#personalprojectgroup-access-tokens), +may be any value, and the `password` must be either a [personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens), a [CI/CD job token](../../../ci/jobs/ci_job_token.md), or a [deploy token](../../project/deploy_tokens/index.md). ## Publish a package file @@ -28,7 +28,7 @@ When you publish a package file, if the package does not exist, it is created. Prerequisites: -- You must [authenticate with the API](../../../api/index.md#authentication). +- You must [authenticate with the API](../../../api/rest/index.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope. If authenticating with a personal access token or project access token, it must be configured with the `api` scope. @@ -44,7 +44,7 @@ PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name?sta | Attribute | Type | Required | Description | | -------------------| --------------- | ---------| -------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/rest/index.md#namespaced-path-encoding). | | `package_name` | string | yes | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), or underscores (`_`). | `package_version` | string | yes | The package version. The following regex validates this: `\A(\.?[\w\+-]+\.?)+\z`. You can test your version strings on [Rubular](https://rubular.com/r/aNCV0wG5K14uq8). | `file_name` | string | yes | The filename. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), or underscores (`_`). @@ -139,7 +139,7 @@ If multiple packages have the same name, version, and filename, then the most re Prerequisites: -- You need to [authenticate with the API](../../../api/index.md#authentication). If authenticating with a deploy token, it must be configured with the `read_package_registry` and/or `write_package_registry` scope. +- You need to [authenticate with the API](../../../api/rest/index.md#authentication). If authenticating with a deploy token, it must be configured with the `read_package_registry` and/or `write_package_registry` scope. ```plaintext GET /projects/:id/packages/generic/:package_name/:package_version/:file_name @@ -147,7 +147,7 @@ GET /projects/:id/packages/generic/:package_name/:package_version/:file_name | Attribute | Type | Required | Description | | -------------------| --------------- | ---------| ------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/index.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/rest/index.md#namespaced-path-encoding). | | `package_name` | string | yes | The package name. | | `package_version` | string | yes | The package version. | | `file_name` | string | yes | The filename. | @@ -215,7 +215,7 @@ It also demonstrates how to manage a semantic version for the generic package: s ### Internal Server error on large file uploads to S3 -S3-compatible object storage [limits the size of a single PUT request to 5GB](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html). If the `aws_signature_version` is set to `2` in the [object storage connection settings](../../../administration/object_storage.md), attempting to publish a package file larger than the 5GB limit can result in a `HTTP 500: Internal Server Error` response. +S3-compatible object storage [limits the size of a single PUT request to 5 GB](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html). If the `aws_signature_version` is set to `2` in the [object storage connection settings](../../../administration/object_storage.md), attempting to publish a package file larger than the 5 GB limit can result in a `HTTP 500: Internal Server Error` response. If you are receiving `HTTP 500: Internal Server Error` responses when publishing large files to S3, set the `aws_signature_version` to `4`: diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index a147c3656b7..1a089cd82be 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -107,8 +107,8 @@ Open your [`~/.netrc`](https://everything.curl.dev/usingcurl/netrc) file and add the following text. Replace the variables in `< >` with your values. WARNING: -If you use an environment variable called `NETRC`, Go will use its value -as a filename and ignore `~/.netrc`. If you intend to use `~/.netrc` in +If you use an environment variable called `NETRC`, Go uses its value +as a filename and ignores `~/.netrc`. If you intend to use `~/.netrc` in the GitLab CI **do not use `NETRC` as an environment variable name**. ```plaintext diff --git a/doc/user/packages/harbor_container_registry/index.md b/doc/user/packages/harbor_container_registry/index.md index f159522d77d..1ad5e2c2f05 100644 --- a/doc/user/packages/harbor_container_registry/index.md +++ b/doc/user/packages/harbor_container_registry/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Harbor Registry **(FREE)** -You can integrate the [Harbor container registry](../../../user/project/integrations/harbor.md#harbor-container-registry-integration) into GitLab and use Harbor as the container registry for your GitLab project to store images. +You can integrate the [Harbor container registry](../../../user/project/integrations/harbor.md) into GitLab and use Harbor as the container registry for your GitLab project to store images. ## View the Harbor Registry diff --git a/doc/user/packages/helm_repository/index.md b/doc/user/packages/helm_repository/index.md index 785ef344c8e..58c8e17f48b 100644 --- a/doc/user/packages/helm_repository/index.md +++ b/doc/user/packages/helm_repository/index.md @@ -30,7 +30,7 @@ Read more in the Helm documentation about these topics: To authenticate to the Helm repository, you need either: -- A [personal access token](../../../api/index.md#personalprojectgroup-access-tokens) with the scope set to `api`. +- A [personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens) with the scope set to `api`. - A [deploy token](../../project/deploy_tokens/index.md) with the scope set to `read_package_registry`, `write_package_registry`, or both. - A [CI/CD job token](../../../ci/jobs/ci_job_token.md). @@ -54,7 +54,7 @@ Once built, a chart can be uploaded to the desired channel with `curl` or `helm - `<username>`: the GitLab username or the deploy token username. - `<access_token>`: the personal access token or the deploy token. - `<project_id>`: the project ID (like `42`) or the - [URL-encoded](../../../api/index.md#namespaced-path-encoding) path of the project (like `group%2Fproject`). + [URL-encoded](../../../api/rest/index.md#namespaced-path-encoding) path of the project (like `group%2Fproject`). - `<channel>`: the name of the channel (like `stable`). - With the [`helm cm-push`](https://github.com/chartmuseum/helm-push/#readme) plugin: diff --git a/doc/user/packages/infrastructure_registry/index.md b/doc/user/packages/infrastructure_registry/index.md index ac31b491a0e..d06c5e7fb1e 100644 --- a/doc/user/packages/infrastructure_registry/index.md +++ b/doc/user/packages/infrastructure_registry/index.md @@ -34,9 +34,8 @@ authenticate with the [`CI_JOB_TOKEN` predefined variable](../../../ci/variables CI/CD templates, which you can use to get started, are in [this repository](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). -Learn more about using CI/CD to build: - -- [Terraform modules](../terraform_module_registry/index.md#publish-a-terraform-module-by-using-cicd) +For more information about using CI/CD to build Terraform modules, +see [Publish a Terraform module by using CI/CD](../terraform_module_registry/index.md#publish-a-terraform-module-by-using-cicd). If you use CI/CD to build a package, you can find extended activity information when you view the package details: diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 2d1efd024a0..1899cdc213f 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -232,7 +232,7 @@ to [Maven Central](https://search.maven.org/). When the feature flag is enabled, administrators can disable this behavior in the [Continuous Integration settings](../../admin_area/settings/continuous_integration.md). -There are many ways to configure your Maven project so that it will request packages +There are many ways to configure your Maven project so that it requests packages in Maven Central from GitLab. Maven repositories are queried in a [specific order](https://maven.apache.org/guides/mini/guide-multiple-repositories.html#repository-order). By default, maven-central is usually checked first through the diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index c62999100c1..11e3d0e5131 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -25,7 +25,7 @@ Create a token and save it to use later in the process. ### Naming convention -Depending on how the package will be installed, you may need to adhere to the naming convention. +Depending on how the package is installed, you may need to adhere to the naming convention. You can use one of two API endpoints to install packages: @@ -36,7 +36,7 @@ If you plan to install a package through the [project level](#install-from-the-p If you plan to install a package through the [instance level](#install-from-the-instance-level), then you must name your package with a [scope](https://docs.npmjs.com/misc/scope/). Scoped packages begin with a `@` have the format of `@owner/package-name`. You can set up the scope for your package in the `.npmrc` file and by using the `publishConfig` option in the `package.json`. -- The value used for the `@scope` is the root of the project that will host the packages and not the root +- The value used for the `@scope` is the root of the project that is hosting the packages and not the root of the project with the source code of the package itself. The scope should be lowercase. - The package name can be anything you want @@ -64,7 +64,7 @@ Create or edit the `.npmrc` file in the same directory as your `package.json`. I - Replace `@scope` with the [root level group](#naming-convention) of the project you're publishing to the package to. - Replace `your_domain_name` with your domain name, for example, `gitlab.com`. - Replace `your_project_id` is your project ID, found on the project's home page. -- `"${NPM_TOKEN}"` will be associated with the token you created later in the process. +- `"${NPM_TOKEN}"` is associated with the token you created later in the process. WARNING: Never hardcode GitLab tokens (or any tokens) directly in `.npmrc` files or any other files that can @@ -125,11 +125,11 @@ You can install a package from a GitLab project or instance: ### Install from the instance level WARNING: -In order to install a package from the instance level, the package must have been published following the scoped [naming convention](#naming-convention). +To install a package from the instance level, the package must have been published following the scoped [naming convention](#naming-convention). 1. Authenticate to the Package Registry - If you would like to install a package from a private project, you will need to authenticate to the Package Registry. Skip this step if the project is not private. + If you would like to install a package from a private project, you would have to authenticate to the Package Registry. Skip this step if the project is not private. ```shell npm config set -- //your_domain_name/api/v4/packages/npm/:_authToken=your_token @@ -158,7 +158,7 @@ In order to install a package from the instance level, the package must have bee 1. Authenticate to the Package Registry - If you would like to install a package from a private project, you will need to authenticate to the Package Registry. Skip this step if the project is not private. + If you would like to install a package from a private project, you would have to authenticate to the Package Registry. Skip this step if the project is not private. ```shell npm config set -- //your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken=your_token @@ -264,6 +264,22 @@ The GitLab npm repository supports the following commands for the npm CLI (`npm` ## Troubleshooting +### `404 Not Found` errors are happening on `npm install` or `yarn` + +Using `CI_JOB_TOKEN` to install npm packages with dependencies in another project gives you 404 Not Found errors. A fix for this problem is proposed in [issue 352962](https://gitlab.com/gitlab-org/gitlab/-/issues/352962). + +As a workaround, you can: + +1. Create a [personal access token](../../profile/personal_access_tokens.md). +1. Authenticate at both the instance level and project level for each package: + + ```ini + @foo:registry=https://gitlab.example.com/api/v4/packages/npm/ + //gitlab.example.com/api/v4/packages/npm/:_authToken=${MY_TOKEN} + //gitlab.example.com/api/v4/projects/<your_project_id_a>/packages/npm/:_authToken=${MY_TOKEN} + //gitlab.example.com/api/v4/projects/<your_project_id_b>/packages/npm/:_authToken=${MY_TOKEN} + ``` + ### `npm publish` targets default npm registry (`registry.npmjs.org`) Ensure that your package scope is set consistently in your `package.json` and `.npmrc` files. @@ -317,7 +333,7 @@ Make sure that your `package.json` file does not exceed `20,000` characters. ### `npm publish` returns `npm ERR! 500 Internal Server Error - PUT` -This is a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/238950) in GitLab 13.3.x and later. The error in the logs will appear as: +This is a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/238950) in GitLab 13.3.x and later. The error in the logs appears as: ```plaintext >NoMethodError - undefined method `preferred_language' for #<Rack::Response diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 540db463f0a..6710c147c87 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -283,7 +283,7 @@ To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Re Prerequisite: -- Set up the [source](#https://docs.gitlab.com/ee/user/packages/nuget_repository/#add-the-package-registry-as-a-source-for-nuget-packages) with a [project-level endpoint](#use-the-gitlab-endpoint-for-nuget-packages). +- Set up the [source](#add-the-package-registry-as-a-source-for-nuget-packages) with a [project-level endpoint](#use-the-gitlab-endpoint-for-nuget-packages). When publishing packages: @@ -461,9 +461,15 @@ for more details on what other GitLab CI patterns are demonstrated. ## Troubleshooting +### Clear NuGet cache + To improve performance, NuGet caches files related to a package. If you encounter issues, clear the cache with this command: ```shell nuget locals all -clear ``` + +### `Error publishing` or `Invalid Package: Failed metadata extraction error` messages when trying to publish NuGet packages in a Docker-based GitLab installation + +Webhook requests to local network addresses are blocked to prevent the exploitation of internal web services. If you get `Error publishing` or `Invalid Package` messages when you try to publish NuGet packages, change your network settings to [allow webhook and service requests to the local network](../../../security/webhooks.md#allow-webhook-and-service-requests-to-local-network). diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index ab5d652b731..cd60a229479 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -43,6 +43,11 @@ For information on how to create and upload a package, view the GitLab documenta ## Authenticate with the registry +<!--- start_remove The following content will be removed on remove_date: '2023-11-22' --> +WARNING: +[External authorization](../../admin_area/settings/external_authorization.md) will be enabled by default in GitLab 16.0. External authorization prevents personal access tokens and deploy tokens from accessing container and package registries and affects all users who use these tokens to access the registries. You can disable external authorization if you want to use personal access tokens and deploy tokens with the container or package registries. +<!--- end_remove --> + Authentication depends on the package manager being used. For more information, see the docs on the specific package format you want to use. @@ -59,12 +64,11 @@ For most package types, the following credential types are valid: - [Job token](../../../ci/jobs/ci_job_token.md): allows access to packages in the project running the job for the users running the pipeline. Access to other external projects can be configured. - - If your organization uses two factor authentication (2FA), you must use a personal access token with the scope set to `api`. - If you are publishing a package via CI/CD pipelines, you must use a CI job token. NOTE: -If you have not activated the "Packages" feature for your project at **Settings > General > Project features**, you will receive a 403 Forbidden response. +If you have not activated the "Package registry" feature for your project at **Settings > General > Visibility, project features, permissions**, you receive a 403 Forbidden response. Accessing package registry via deploy token is not available when external authorization is enabled. ## Use GitLab CI/CD to build packages @@ -75,7 +79,7 @@ authenticate with GitLab by using the `CI_JOB_TOKEN`. CI/CD templates, which you can use to get started, are in [this repository](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). -Learn more about using the GitLab Package Registry with CI/CD: +For more information about using the GitLab Package Registry with CI/CD, see: - [Composer](../composer_repository/index.md#publish-a-composer-package-by-using-cicd) - [Conan](../conan_repository/index.md#publish-a-conan-package-by-using-cicd) @@ -151,7 +155,7 @@ Several known issues exist when you allow anyone to pull from the Package Regist - Project-level endpoints are supported. Group-level and instance-level endpoints are not supported. Support for group-level endpoints is proposed in [issue 383537](https://gitlab.com/gitlab-org/gitlab/-/issues/383537). - It does not work with the [Composer](../composer_repository/index.md#install-a-composer-package), because Composer only has a group endpoint. -- It will work with Conan, but using [`conan search`](../conan_repository/index.md#search-for-conan-packages-in-the-package-registry) does not work. +- It works with Conan, but using [`conan search`](../conan_repository/index.md#search-for-conan-packages-in-the-package-registry) does not work. ## Accepting contributions diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 0e2fc7ca7da..e5b7f06f6ca 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -50,7 +50,7 @@ password = <your_personal_access_token> ``` The `<project_id>` is either the project's -[URL-encoded](../../../api/index.md#namespaced-path-encoding) +[URL-encoded](../../../api/rest/index.md#namespaced-path-encoding) path (for example, `group%2Fproject`), or the project's ID (for example `42`). ### Authenticate with a deploy token @@ -69,7 +69,7 @@ password = <deploy token> ``` The `<project_id>` is either the project's -[URL-encoded](../../../api/index.md#namespaced-path-encoding) +[URL-encoded](../../../api/rest/index.md#namespaced-path-encoding) path (for example, `group%2Fproject`), or the project's ID (for example `42`). ### Authenticate with a CI job token @@ -220,7 +220,7 @@ pip install --index-url https://<personal_access_token_name>:<personal_access_to - `<package_name>` is the package name. - `<personal_access_token_name>` is a personal access token name with the `read_api` scope. - `<personal_access_token>` is a personal access token with the `read_api` scope. -- `<project_id>` is either the project's [URL-encoded](../../../api/index.md#namespaced-path-encoding) +- `<project_id>` is either the project's [URL-encoded](../../../api/rest/index.md#namespaced-path-encoding) path (for example, `group%2Fproject`), or the project's ID (for example `42`). In these commands, you can use `--extra-index-url` instead of `--index-url`. However, using @@ -311,7 +311,7 @@ password <your_personal_token> ## Troubleshooting -To improve performance, the pip command caches files related to a package. Note that pip doesn't remove data by +To improve performance, the pip command caches files related to a package. Pip doesn't remove data by itself. The cache grows as new packages are installed. If you encounter issues, clear the cache with this command: @@ -324,7 +324,7 @@ pip cache purge You can define multiple `index-url` and `extra-index-url` parameters. If you use the same domain name (such as `gitlab.example.com`) multiple times with different authentication -tokens, `pip` may not be able to find your packages. This problem is due to how `pip` +tokens, `pip` may not be able to find your packages. This problem is due to how `pip` [registers and stores your tokens](https://github.com/pypa/pip/pull/10904#issuecomment-1126690115) during commands executions. To workaround this issue, you can use a [group deploy token](../../project/deploy_tokens/index.md) with the diff --git a/doc/user/packages/rubygems_registry/index.md b/doc/user/packages/rubygems_registry/index.md index 7710ad3db01..ae444880b6b 100644 --- a/doc/user/packages/rubygems_registry/index.md +++ b/doc/user/packages/rubygems_registry/index.md @@ -117,7 +117,7 @@ To push your gem, run a command like this one: gem push my_gem-0.0.1.gem --host <host> ``` -Note that `<host>` is the URL you used when setting up authentication. For example: +`<host>` is the URL you used when setting up authentication. For example: ```shell gem push my_gem-0.0.1.gem --host https://gitlab.example.com/api/v4/projects/1/packages/rubygems diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index 9b09d846034..66a42f398b0 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -15,7 +15,7 @@ as a Terraform module registry. To authenticate to the Terraform module registry, you need either: -- A [personal access token](../../../api/index.md#personalprojectgroup-access-tokens) with at least `read_api` rights. +- A [personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens) with at least `read_api` rights. - A [CI/CD job token](../../../ci/jobs/ci_job_token.md). ## Publish a Terraform Module @@ -26,7 +26,7 @@ Prerequisites: - The package name and version [must be unique in the top-level namespace](../infrastructure_registry/index.md#how-module-resolution-works). - Your project and group names must not include a dot (`.`). For example, `source = "gitlab.example.com/my.group/project.name"`. -- You must [authenticate with the API](../../../api/index.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope. +- You must [authenticate with the API](../../../api/rest/index.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope. - The name of a module [must be unique within the scope of its group](../infrastructure_registry/index.md#how-module-resolution-works), otherwise an [error occurs](#troubleshooting). @@ -36,9 +36,9 @@ PUT /projects/:id/packages/terraform/modules/:module-name/:module-system/:module | Attribute | Type | Required | Description | | -------------------| --------------- | ---------| -------------------------------------------------------------------------------------------------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/index.md#namespaced-path-encoding). | -| `module-name` | string | yes | The package name. **Supported syntax**: One to 64 ASCII characters, including lowercase letters (a-z), digits (0-9), and hyphens (`-`). -| `module-system` | string | yes | The package system. **Supported syntax**: One to 64 ASCII characters, including lowercase letters (a-z), digits (0-9), and hyphens (`-`). More information can be found in the [Terraform Module Registry Protocol documentation](https://www.terraform.io/internals/module-registry-protocol). +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/rest/index.md#namespaced-path-encoding). | +| `module-name` | string | yes | The package name. **Supported syntax**: One to 64 ASCII characters, including lowercase letters (a-z) and digits (0-9). The package name can't exceed 64 characters. +| `module-system` | string | yes | The package system. **Supported syntax**: One to 64 ASCII characters, including lowercase letters (a-z) and digits (0-9). The package system can't exceed 64 characters. More information can be found in the [Terraform Module Registry Protocol documentation](https://www.terraform.io/internals/module-registry-protocol). | `module-version` | string | yes | The package version. It must be valid according to the [Semantic Versioning Specification](https://semver.org/). Provide the file content in the request body. @@ -83,7 +83,7 @@ Example response: Prerequisites: -- You need to [authenticate with the API](../../../api/index.md#authentication). If authenticating with a personal access token, it must be configured with the `read_api` scope. +- You need to [authenticate with the API](../../../api/rest/index.md#authentication). If authenticating with a personal access token, it must be configured with the `read_api` scope. Authentication tokens (Job Token or Personal Access Token) can be provided for `terraform` in your `~/.terraformrc` file: @@ -107,6 +107,38 @@ Where `<namespace>` is the [namespace](../../../user/namespace/index.md) of the ## Publish a Terraform module by using CI/CD +> CI/CD template [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110493) in GitLab 15.9. + +### Use a CI/CD template (recommended) + +You can use the [`Terraform-Module.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform-Module.gitlab-ci.yml) +or the advanced [`Terraform/Module-Base.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Module-Base.gitlab-ci.yml) +CI/CD template to publish a Terraform module to the GitLab Terraform Registry: + +```yaml +include: + template: Terraform-Module.gitlab-ci.yml +``` + +The pipeline contains the following jobs: + +- `fmt` - Validate the formatting of the Terraform module. +- `kics-iac-sast` - Test the Terraform module for security issues. +- `deploy` - For tag pipelines only. Deploy the Terraform module to the GitLab Terraform Registry. + +#### Pipeline variables + +You can configure the pipeline with the following variables: + +| Variable | Default | Description | +|----------------------------|----------------------|-------------------------------------------------------------------------------------------------| +| `TERRAFORM_MODULE_DIR` | `${CI_PROJECT_DIR}` | The relative path to the root directory of the Terraform project. | +| `TERRAFORM_MODULE_NAME` | `${CI_PROJECT_NAME}` | The name of your Terraform module. Must not contain any spaces or underscores. | +| `TERRAFORM_MODULE_SYSTEM` | `local` | The system or provider of your Terraform module targets. For example, `local`, `aws`, `google`. | +| `TERRAFORM_MODULE_VERSION` | `${CI_COMMIT_TAG}` | The Terraform module version. You should follow the semantic versioning specification. | + +### Deploy manually via CI/CD + To work with Terraform modules in [GitLab CI/CD](../../../ci/index.md), you can use `CI_JOB_TOKEN` in place of the personal access token in your commands. @@ -114,21 +146,21 @@ For example, this job uploads a new module for the `local` [system provider](htt ```yaml stages: - - upload + - deploy upload: - stage: upload + stage: deploy image: curlimages/curl:latest variables: - TERRAFORM_MODULE_DIR: ${CI_PROJECT_DIR} # The path to your Terraform module - TERRAFORM_MODULE_NAME: ${CI_PROJECT_NAME} # The name of your Terraform module - TERRAFORM_MODULE_SYSTEM: local # The system or provider your Terraform module targets (ex. local, aws, google) - TERRAFORM_MODULE_VERSION: ${CI_COMMIT_TAG} # Tag commits with SemVer for the version of your Terraform module to be published + TERRAFORM_MODULE_DIR: ${CI_PROJECT_DIR} # The relative path to the root directory of the Terraform project. + TERRAFORM_MODULE_NAME: ${CI_PROJECT_NAME} # The name of your Terraform module, must not have any spaces or underscores (will be translated to hyphens). + TERRAFORM_MODULE_SYSTEM: local # The system or provider your Terraform module targets (ex. local, aws, google). + TERRAFORM_MODULE_VERSION: ${CI_COMMIT_TAG} # The version - it's recommended to follow SemVer for Terraform Module Versioning. script: - TERRAFORM_MODULE_NAME=$(echo "${TERRAFORM_MODULE_NAME}" | tr " _" -) # module-name must not have spaces or underscores, so translate them to hyphens - - tar -vczf ${TERRAFORM_MODULE_NAME}-${TERRAFORM_MODULE_SYSTEM}-${TERRAFORM_MODULE_VERSION}.tgz -C ${TERRAFORM_MODULE_DIR} --exclude=./.git . + - tar -vczf /tmp/${TERRAFORM_MODULE_NAME}-${TERRAFORM_MODULE_SYSTEM}-${TERRAFORM_MODULE_VERSION}.tgz -C ${TERRAFORM_MODULE_DIR} --exclude=./.git . - 'curl --fail-with-body --location --header "JOB-TOKEN: ${CI_JOB_TOKEN}" - --upload-file ${TERRAFORM_MODULE_NAME}-${TERRAFORM_MODULE_SYSTEM}-${TERRAFORM_MODULE_VERSION}.tgz + --upload-file /tmp/${TERRAFORM_MODULE_NAME}-${TERRAFORM_MODULE_SYSTEM}-${TERRAFORM_MODULE_VERSION}.tgz ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/terraform/modules/${TERRAFORM_MODULE_NAME}/${TERRAFORM_MODULE_SYSTEM}/${TERRAFORM_MODULE_VERSION}/file' rules: - if: $CI_COMMIT_TAG diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 8455db45030..8e736b6d83e 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -73,7 +73,7 @@ The following table lists project permissions available for each role: | [Clusters](infrastructure/clusters/index.md):<br>Manage clusters | | | | ✓ | ✓ | | [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete [cleanup policies](packages/container_registry/delete_container_registry_images.md#use-a-cleanup-policy) | | | | ✓ | ✓ | | [Container Registry](packages/container_registry/index.md):<br>Push an image to the Container Registry | | | ✓ | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Pull an image from the Container Registry | ✓ (*19*) | ✓ (*19*) | ✓ | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Pull an image from the Container Registry | ✓ (19) | ✓ (19) | ✓ | ✓ | ✓ | | [Container Registry](packages/container_registry/index.md):<br>Remove a Container Registry image | | | ✓ | ✓ | ✓ | | [GitLab Pages](project/pages/index.md):<br>View Pages protected by [access control](project/pages/pages_access_control.md) | ✓ | ✓ | ✓ | ✓ | ✓ | | [GitLab Pages](project/pages/index.md):<br>Manage | | | | ✓ | ✓ | @@ -94,81 +94,81 @@ The following table lists project permissions available for each role: | [Incident Management](../operations/incident_management/index.md):<br>Manage [escalation policies](../operations/incident_management/escalation_policies.md) | | | | ✓ | ✓ | | [Issue boards](project/issue_board.md):<br>Create or delete lists | | ✓ | ✓ | ✓ | ✓ | | [Issue boards](project/issue_board.md):<br>Move issues between lists | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Add Labels | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Add to epic | | ✓ (*22*) | ✓ (*22*) | ✓ (*22*) | ✓ (*22*) | -| [Issues](project/issues/index.md):<br>Assign | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Create (*17*) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Add Labels | ✓ (15) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Add to epic | | ✓ (22) | ✓ (22) | ✓ (22) | ✓ (22) | +| [Issues](project/issues/index.md):<br>Assign | ✓ (15) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Create (17) | ✓ | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Create [confidential issues](project/issues/confidential_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>View [Design Management](project/issues/design_management.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>View [related issues](project/issues/related_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Set [weight](project/issues/issue_weight.md) | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Set [weight](project/issues/issue_weight.md) | ✓ (15) | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Set [parent epic](group/epics/manage_epics.md#add-an-existing-issue-to-an-epic) | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>View [confidential issues](project/issues/confidential_issues.md) | (*2*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Close / reopen (*18*) | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>View [confidential issues](project/issues/confidential_issues.md) | (2) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Close / reopen (18) | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Lock threads | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Manage [related issues](project/issues/related_issues.md) | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Manage tracker | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Move issues (*14*) | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Move issues (14) | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Set issue [time tracking](project/time_tracking.md) estimate and time spent | | ✓ | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Archive [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | | [Issues](project/issues/index.md):<br>Delete | | | | | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View allowed and denied licenses | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View License Compliance reports | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View allowed and denied licenses | ✓ (1) | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View License Compliance reports | ✓ (1) | ✓ | ✓ | ✓ | ✓ | | [License Compliance](compliance/license_compliance/index.md):<br>View License list | | ✓ | ✓ | ✓ | ✓ | | [License Compliance](compliance/license_compliance/index.md):<br>Manage license policy | | | | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Assign reviewer | | ✓ | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>See list | | ✓ | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Apply code change suggestions | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Approve (*8*) | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Approve (8) | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Assign | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Create (*16*) | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Create (16) | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Add labels | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Lock threads | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Manage or accept | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>[Resolve a thread](discussions/index.md#resolve-a-thread) | | | ✓ | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Manage [merge approval rules](project/merge_requests/approvals/settings.md) (project settings) | | | | ✓ | ✓ | | [Merge requests](project/merge_requests/index.md):<br>Delete | | | | | ✓ | -| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Manage user-starred metrics dashboards (*6*) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Manage user-starred metrics dashboards (6) | ✓ | ✓ | ✓ | ✓ | ✓ | | [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | | [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | -| [Package registry](packages/index.md):<br>Pull a package | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Pull a package | ✓ (1) | ✓ | ✓ | ✓ | ✓ | | [Package registry](packages/index.md):<br>Publish a package | | | ✓ | ✓ | ✓ | | [Package registry](packages/index.md):<br>Delete a package | | | | ✓ | ✓ | | [Package registry](packages/index.md):<br>Delete a file associated with a package | | | | ✓ | ✓ | | [Project operations](../operations/index.md):<br>View [Error Tracking](../operations/error_tracking.md) list | | ✓ | ✓ | ✓ | ✓ | | [Project operations](../operations/index.md):<br>Manage [Feature Flags](../operations/feature_flags.md) | | | ✓ | ✓ | ✓ | | [Project operations](../operations/index.md):<br>Manage [Error Tracking](../operations/error_tracking.md) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Download project | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Download project | ✓ (1) | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Reposition comments on images (posted by any user) | ✓ (*9*) | ✓ (*9*) | ✓ (*9*) | ✓ | ✓ | +| [Projects](project/index.md):<br>Reposition comments on images (posted by any user) | ✓ (9) | ✓ (9) | ✓ (9) | ✓ | ✓ | | [Projects](project/index.md):<br>View [Insights](project/insights/index.md) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [releases](project/releases/index.md) | ✓ (*5*) | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [releases](project/releases/index.md) | ✓ (5) | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>View [Requirements](project/requirements/index.md) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [time tracking](project/time_tracking.md) reports | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [time tracking](project/time_tracking.md) reports | ✓ (1) | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>View [wiki](project/wiki/index.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Create [snippets](snippets.md) | | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Manage labels | | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>View [project traffic statistics](../api/project_statistics.md) | | ✓ | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Create, edit, delete [milestones](project/milestones/index.md). | | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Create, edit, delete [releases](project/releases/index.md) | | | ✓ (*12*) | ✓ (*12*) | ✓ (*12*) | +| [Projects](project/index.md):<br>Create, edit, delete [releases](project/releases/index.md) | | | ✓ (12) | ✓ (12) | ✓ (12) | | [Projects](project/index.md):<br>Create, edit [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Enable [Review Apps](../ci/review_apps/index.md) | | | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View project [Audit Events](../administration/audit_events.md) | | | ✓ (*10*) | ✓ | ✓ | +| [Projects](project/index.md):<br>View project [Audit Events](../administration/audit_events.md) | | | ✓ (10) | ✓ | ✓ | | [Projects](project/index.md):<br>Add [deploy keys](project/deploy_keys/index.md) | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Add new [team members](project/members/index.md) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Manage [team members](project/members/index.md) | | | | ✓ (*20*) | ✓ | -| [Projects](project/index.md):<br>Change [project features visibility](public_access.md) level | | | | ✓ (*13*) | ✓ | +| [Projects](project/index.md):<br>Manage [team members](project/members/index.md) | | | | ✓ (20) | ✓ | +| [Projects](project/index.md):<br>Change [project features visibility](public_access.md) level | | | | ✓ (13) | ✓ | | [Projects](project/index.md):<br>Configure [webhooks](project/integrations/webhooks.md) | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Delete [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | | [Projects](project/index.md):<br>Edit comments (posted by any user) | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Edit project badges | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Edit project settings | | | | ✓ | ✓ | | [Projects](project/index.md):<br>[Export project](project/settings/import_export.md) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Manage [project access tokens](project/settings/project_access_tokens.md) (*11*) | | | | ✓ (*20*) | ✓ | +| [Projects](project/index.md):<br>Manage [project access tokens](project/settings/project_access_tokens.md) (11) | | | | ✓ (20) | ✓ | | [Projects](project/index.md):<br>Manage [Project Operations](../operations/index.md) | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Rename project | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Share (invite) projects with groups | | | | ✓ (*7*) | ✓ (*7*) | +| [Projects](project/index.md):<br>Share (invite) projects with groups | | | | ✓ (7) | ✓ (7) | | [Projects](project/index.md):<br>View 2FA status of members | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Assign project to a [compliance framework](project/settings/index.md#add-a-compliance-framework-to-a-project) | | | | | ✓ | | [Projects](project/index.md):<br>Archive project | | | | | ✓ | @@ -177,12 +177,12 @@ The following table lists project permissions available for each role: | [Projects](project/index.md):<br>Disable notification emails | | | | | ✓ | | [Projects](project/index.md):<br>Transfer project to another namespace | | | | | ✓ | | [Projects](project/index.md): View [Usage Quotas](usage_quotas.md) page | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Pull project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>View project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Pull project code | ✓ (1) | ✓ | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>View project code | ✓ (1) (23) | ✓ | ✓ | ✓ | ✓ | | [Repository](project/repository/index.md):<br>View a commit status | | ✓ | ✓ | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Add tags | | | ✓ | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Create new branches | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Create or update commit status | | | ✓ (*4*) | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Create or update commit status | | | ✓ (4) | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Force push to non-protected branches | | | ✓ | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Push to non-protected branches | | | ✓ | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Remove non-protected branches | | | ✓ | ✓ | ✓ | @@ -190,11 +190,11 @@ The following table lists project permissions available for each role: | [Repository](project/repository/index.md):<br>Enable or disable branch protection | | | | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Enable or disable tag protection | | | | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Manage [push rules](project/repository/push_rules.md) | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Push to protected branches (*4*) | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Push to protected branches (4) | | | | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Turn on or off protected branch push for developers | | | | ✓ | ✓ | | [Repository](project/repository/index.md):<br>Remove fork relationship | | | | | ✓ | -| [Repository](project/repository/index.md):<br>Force push to protected branches (*3*) | | | | | | -| [Repository](project/repository/index.md):<br>Remove protected branches (*3*) | | | | | | +| [Repository](project/repository/index.md):<br>Force push to protected branches (3) | | | | | | +| [Repository](project/repository/index.md):<br>Remove protected branches (3) | | | | | | | [Requirements Management](project/requirements/index.md):<br>Archive / reopen | | ✓ | ✓ | ✓ | ✓ | | [Requirements Management](project/requirements/index.md):<br>Create / edit | | ✓ | ✓ | ✓ | ✓ | | [Requirements Management](project/requirements/index.md):<br>Import / export | | ✓ | ✓ | ✓ | ✓ | @@ -207,10 +207,10 @@ The following table lists project permissions available for each role: | [Security dashboard](application_security/security_dashboard/index.md):<br>Use security dashboard | | | ✓ | ✓ | ✓ | | [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability | | | ✓ | ✓ | ✓ | | [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability findings in [dependency list](application_security/dependency_list/index.md) | | | ✓ | ✓ | ✓ | -| [Tasks](tasks.md):<br>Create (*17*) | | ✓ | ✓ | ✓ | ✓ | +| [Tasks](tasks.md):<br>Create (17) | | ✓ | ✓ | ✓ | ✓ | | [Tasks](tasks.md):<br>Edit | | ✓ | ✓ | ✓ | ✓ | | [Tasks](tasks.md):<br>Remove from issue | | ✓ | ✓ | ✓ | ✓ | -| [Tasks](tasks.md):<br>Delete (*21*) | | | | | ✓ | +| [Tasks](tasks.md):<br>Delete (21) | | | | | ✓ | | [Terraform](infrastructure/index.md):<br>Read Terraform state | | | ✓ | ✓ | ✓ | | [Terraform](infrastructure/index.md):<br>Manage Terraform state | | | | ✓ | ✓ | | [Test cases](../ci/test_cases/index.md):<br>Archive | | ✓ | ✓ | ✓ | ✓ | @@ -220,10 +220,7 @@ The following table lists project permissions available for each role: <!-- markdownlint-disable MD029 --> -1. On self-managed GitLab instances, guest users are able to perform this action only on - public and internal projects (not on private projects). [External users](admin_area/external_users.md) - must be given explicit access even if the project is internal. Users with the Guest role on GitLab.com are - only able to perform this action on public projects because internal visibility is not available. +1. On self-managed GitLab instances, users with the Guest role are able to perform this action only on public and internal projects (not on private projects). [External users](admin_area/external_users.md) must be given explicit access even if the project is internal. Users with the Guest role on GitLab.com are only able to perform this action on public projects because internal visibility is not available. In GitLab 15.9 and later, this restriction only applies to users with the non-custom Guest role on self-managed GitLab instances and GitLab.com. 2. Guest users can only view the [confidential issues](project/issues/confidential_issues.md) they created themselves or are assigned to. 3. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [protected branches](project/protected_branches.md). 4. If the [branch is protected](project/protected_branches.md), this depends on the access given to Developers and Maintainers. @@ -250,6 +247,7 @@ The following table lists project permissions available for each role: 20. Maintainers cannot create, demote, or remove Owners, and they cannot promote users to the Owner role. They also cannot approve Owner role access requests. 21. Authors of tasks can delete them even if they don't have the Owner role, but they have to have at least the Guest role for the project. 22. You must have permission to [view the epic](group/epics/manage_epics.md#who-can-view-an-epic). +23. In GitLab 15.9 and later, users with the Guest role and an Ultimate license can view private repository content if an administrator gives those users permission. The administrator can create a [custom role](#custom-roles) through the API and assign that role to the users. <!-- markdownlint-enable MD029 --> @@ -268,26 +266,26 @@ More details about the permissions for some project-level features follow. | Action | Non-member | Guest | Reporter | Developer | Maintainer | Owner | |---------------------------------------------------------------------------------------------------------------------------|------------|---------|----------|-----------|------------|-------| -| See that artifacts exist | ✓ (*3*) | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| View a list of jobs | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | -| View and download artifacts | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | -| View [environments](../ci/environments/index.md) | ✓ (*3*) | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| View job logs and job details page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | -| View pipeline details page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | -| View pipelines page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | -| View pipelines tab in MR | ✓ (*3*) | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| [View vulnerabilities in a pipeline](application_security/vulnerability_report/pipeline.md#view-vulnerabilities-in-a-pipeline) | | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | +| See that artifacts exist | ✓ (3) | ✓ (3) | ✓ | ✓ | ✓ | ✓ | +| View a list of jobs | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| View and download artifacts | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| View [environments](../ci/environments/index.md) | ✓ (3) | ✓ (3) | ✓ | ✓ | ✓ | ✓ | +| View job logs and job details page | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| View pipeline details page | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| View pipelines page | ✓ (1) | ✓ (2) | ✓ | ✓ | ✓ | ✓ | +| View pipelines tab in MR | ✓ (3) | ✓ (3) | ✓ | ✓ | ✓ | ✓ | +| [View vulnerabilities in a pipeline](application_security/vulnerability_report/pipeline.md#view-vulnerabilities-in-a-pipeline) | | ✓ (2) | ✓ | ✓ | ✓ | ✓ | | View and download project-level [Secure Files](../api/secure_files.md) | | | | ✓ | ✓ | ✓ | | Cancel and retry jobs | | | | ✓ | ✓ | ✓ | | Create new [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | -| Delete job logs or job artifacts | | | | ✓ (*4*) | ✓ | ✓ | +| Delete job logs or job artifacts | | | | ✓ (4) | ✓ | ✓ | | Run CI/CD pipeline | | | | ✓ | ✓ | ✓ | -| Run CI/CD pipeline for a protected branch | | | | ✓ (*5*) | ✓ (*5*) | ✓ | +| Run CI/CD pipeline for a protected branch | | | | ✓ (5) | ✓ (5) | ✓ | | Stop [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | | View a job with [debug logging](../ci/variables/index.md#enable-debug-logging) | | | | ✓ | ✓ | ✓ | | Use pipeline editor | | | | ✓ | ✓ | ✓ | | Run [interactive web terminals](../ci/interactive_web_terminal/index.md) | | | | ✓ | ✓ | ✓ | -| Add specific runners to project | | | | | ✓ | ✓ | +| Add project runners to project | | | | | ✓ | ✓ | | Clear runner caches manually | | | | | ✓ | ✓ | | Enable shared runners in project | | | | | ✓ | ✓ | | Manage CI/CD settings | | | | | ✓ | ✓ | @@ -319,18 +317,18 @@ This table shows granted privileges for jobs triggered by specific types of user | Run CI job | | ✓ | ✓ | ✓ | | Clone source and LFS from current project | | ✓ | ✓ | ✓ | | Clone source and LFS from public projects | | ✓ | ✓ | ✓ | -| Clone source and LFS from internal projects | | ✓ (*1*) | ✓ (*1*) | ✓ | -| Clone source and LFS from private projects | | ✓ (*2*) | ✓ (*2*) | ✓ (*2*) | +| Clone source and LFS from internal projects | | ✓ (1) | ✓ (1) | ✓ | +| Clone source and LFS from private projects | | ✓ (2) | ✓ (2) | ✓ (2) | | Pull container images from current project | | ✓ | ✓ | ✓ | | Pull container images from public projects | | ✓ | ✓ | ✓ | -| Pull container images from internal projects | | ✓ (*1*) | ✓ (*1*) | ✓ | -| Pull container images from private projects | | ✓ (*2*) | ✓ (*2*) | ✓ (*2*) | +| Pull container images from internal projects | | ✓ (1) | ✓ (1) | ✓ | +| Pull container images from private projects | | ✓ (2) | ✓ (2) | ✓ (2) | | Push container images to current project | | ✓ | ✓ | ✓ | | Push container images to other projects | | | | | | Push source and LFS | | | | | 1. Only if the triggering user is not an external one. -1. Only if the triggering user is a member of the project. See also [Usage of private Docker images with `if-not-present` pull policy](http://docs.gitlabl.com/runner/security/index.html#usage-of-private-docker-images-with-if-not-present-pull-policy). +1. Only if the triggering user is a member of the project. See also [Usage of private Docker images with `if-not-present` pull policy](http://docs.gitlab.com/runner/security/index.html#usage-of-private-docker-images-with-if-not-present-pull-policy). ## Group members permissions @@ -423,8 +421,8 @@ When you add a member to a subgroup, they inherit the membership and permission level from the parent groups. This model allows access to nested groups if you have membership in one of its parents. -To learn more, read through the documentation on -[subgroups memberships](group/subgroups/index.md#subgroup-membership). +For more information, see +[subgroup memberships](group/subgroups/index.md#subgroup-membership). ## Users with minimal access **(PREMIUM)** @@ -464,3 +462,78 @@ subscriptions. - [Confidential issues](project/issues/confidential_issues.md) - [Container Registry permissions](packages/container_registry/index.md#container-registry-visibility-permissions) - [Release permissions](project/releases/index.md#release-permissions) + +## Custom roles **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106256) in GitLab 15.7 [with a flag](../administration/feature_flags.md) named `customizable_roles`. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110810) in GitLab 15.9. + +Custom roles allow group members who are assigned the Owner role to create roles +specific to the needs of their organization. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a demo of the custom roles feature, see [[Demo] Ultimate Guest can view code on private repositories via custom role](https://www.youtube.com/watch?v=46cp_-Rtxps). + +### Create a custom role + +To enable custom roles for your group, a group member with the Owner role: + +1. Makes sure that there is at least one private project in this group or one of + its subgroups, so that you can see the effect of giving a Guest a custom role. +1. Creates a personal access token with the API scope. +1. Uses [the API](../api/member_roles.md#add-a-member-role-to-a-group) to create the Guest+1 role for the group. + +### Associate a custom role with an existing group member + +To associate a custom role with an existing group member, a group member with +the Owner role: + +1. Invites a test user account to the root group as a Guest. + At this point, this Guest user cannot see any code on the projects in the group. +1. Optional. If the Owner does not know the `ID` of the Guest user receiving a custom + role, finds that `ID` by making an [API request](../api/member_roles.md#list-all-member-roles-of-a-group). + +1. Associates the group member with the Guest+1 role using the [Group and Project Members API endpoint](../api/members.md#edit-a-member-of-a-group-or-project) + + ```shell + curl --request PUT --header "Content-Type: application/json" --header "Authorization: Bearer $YOUR_ACCESS_TOKEN" --data '{"member_role_id": '$MEMBER_ROLE_ID', "access_level": 10}' "https://example.gitlab.com/api/v4/groups/$GROUP_PATH/members/$GUEST_USER_ID" + ``` + + Where: + - `$MEMBER_ROLE_ID`: The `ID` of the member role created in the previous section. + - `$GUEST_USER_ID`: The `ID` of the Guest user receiving a custom role. + + Now the Guest+1 user can view code on all projects in the root group. + +### Remove a custom role from a group member + +To remove a custom role from a group member, use the [Group and Project Members API endpoint](../api/members.md#edit-a-member-of-a-group-or-project) +and pass an empty `member_role_id` value. + +```shell +curl --request PUT --header "Content-Type: application/json" --header "Authorization: Bearer $YOUR_ACCESS_TOKEN" --data '{"member_role_id": "", "access_level": 10}' "https://example.gitlab.com/api/v4/groups/$GROUP_PATH/members/$GUEST_USER_ID" +``` + +Now the user is a regular Guest. + +### Remove a custom role + +Removing a custom role also removes all members with that custom role from +the group. If you decide to delete a custom role, you must re-add any users with that custom +role to the group. + +To remove a custom role from a group, a group member with +the Owner role: + +1. Optional. If the Owner does not know the `ID` of a custom + role, finds that `ID` by making an [API request](../api/member_roles.md#list-all-member-roles-of-a-group). +1. Uses [the API](../api/member_roles.md#remove-member-role-of-a-group) to delete the custom role. + +### Known issues + +- Additional permissions can only be applied to users with the Guest role. +- There is no visual distinction in the UI between the Guest role and the Guest role with additional permission. For more information, see [issue 384099](https://gitlab.com/gitlab-org/gitlab/-/issues/384099). +- If a user with a custom role is shared with a group or project, their custom role is not transferred over with them. The user has the regular Guest role in the new group or project. +- If a custom role is deleted, the users associated with that custom role are also removed from the group. For more information, see [issue 370352](https://gitlab.com/gitlab-org/gitlab/-/issues/370352). +- The API endpoint for associating a custom role with a user only works for users with the Guest role in a group. A project member can be associated with a custom role, but not through the API yet. For more information, see [issue 385495](https://gitlab.com/gitlab-org/gitlab/-/issues/385495). +- The only way to remove a custom role from a user's membership to a Group is to delete the custom role, which deletes the user membership entirely. See [issue 387769](https://gitlab.com/gitlab-org/gitlab/-/issues/387769). diff --git a/doc/user/product_analytics/index.md b/doc/user/product_analytics/index.md index 46f8b57a64c..6d6a609618b 100644 --- a/doc/user/product_analytics/index.md +++ b/doc/user/product_analytics/index.md @@ -6,7 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Product analytics **(ULTIMATE)** -> Introduced in GitLab 15.4 as an [Alpha](../../policy/alpha-beta-support.md#alpha-features) feature [with a flag](../../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default. +> - Introduced in GitLab 15.4 as an [Alpha](../../policy/alpha-beta-support.md#alpha-features) feature [with a flag](../../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default. +> - `cube_api_proxy` revised to only reference the [Product Analytics API](../../api/product_analytics.md) in GitLab 15.6. FLAG: On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `cube_api_proxy`. @@ -14,10 +15,47 @@ On GitLab.com, this feature is not available. This feature is not ready for production use. This page is a work in progress, and we're updating the information as we add more features. -For more information, visit the [Product Analytics group direction page](https://about.gitlab.com/direction/analytics/product-analytics/). +For more information, see the [group direction page](https://about.gitlab.com/direction/analytics/product-analytics/). + +## How Product Analytics works + +```mermaid +--- +title: Product Analytics flow +--- +flowchart TB + subgraph Adding data + A([SDK]) --Send user data--> B[Analytics Proxy] + B --Transform data and pass it through--> C[Jitsu] + C --Pass the data to the associated database--> D([Clickhouse]) + end + subgraph Showing dashboards + E([Dashboards]) --Generated from the YAML definition--> F[Dashboard] + F --Request data--> G[Product Analytics API] + G --Run Cube queries with pre-aggregations--> H[Cube.js] + H --Get data from database--> D + D --Return results--> H + H --> G + G --Transform data to be rendered--> F + end +``` + +Product Analytics uses several tools: + +- [**Jitsu**](https://jitsu.com/docs) - A web and app event collection platform that provides a consistent API to collect user data and pass it through to Clickhouse. +- [**Clickhouse**](https://clickhouse.com/docs) - A database suited to store, query, and retrieve analytical data. +- [**Cube.js**](https://cube.dev/docs/) - An analytical graphing library that provides an API to run queries against the data stored in Clickhouse. ## Enable product analytics +> - Introduced in GitLab 15.6 behind the [feature flag](../../administration/feature_flags.md) named `cube_api_proxy`. Disabled by default. +> - Moved to be behind the [feature flag](../../administration/feature_flags.md) named `product_analytics_admin_settings` in GitLab 15.7. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `product_analytics_admin_settings`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + You can enable and configure product analytics to track events within your project applications on a self-managed instance. @@ -45,11 +83,32 @@ Prerequisite: ## Product analytics dashboards +> Introduced in GitLab 15.5 behind the [feature flag](../../administration/feature_flags.md) named `product_analytics_internal_preview`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `product_analytics_internal_preview`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + Each project can define an unlimited number of dashboards. These dashboards are defined using our YAML schema and stored in the `.gitlab/product_analytics/dashboards/` directory of a project repository. The name of the file is the name of the dashboard, and visualizations are shared across dashboards. Project maintainers can enforce approval rules on dashboard changes using features such as code owners and approval rules. Dashboards are versioned in source control with the rest of a project's code. +### View project dashboards + +> Introduced in GitLab 15.9 behind the [feature flag](../../administration/feature_flags.md) named `combined_analytics_dashboards`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `combined_analytics_dashboards`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +To view a list of product analytics dashboards for a project: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Dashboards**. + ### Define a dashboard To define a dashboard: @@ -72,3 +131,77 @@ The example below includes three dashboards and one visualization that applies t ├── visualizations │ └── example_line_chart.yaml ``` + +## Funnel analysis + +Funnel analysis can be used to understand the flow of users through your application and where +users drop out of a predefined flow (for example, a checkout process or ticket purchase). + +Each product can also define an unlimited number of funnels. +These funnels are defined using our YAML schema and stored in the `.gitlab/product_analytics/funnels/` directory of a project repository. + +Funnel definitions must include the keys `name`, `seconds_to_convert`, and an array of `steps`. + +| Key | Description | +|----------------------|----------------------------------------------------------| +| `name` | The name of the funnel. | +| `seconds_to_convert` | The number of seconds a user has to complete the funnel. | +| `steps` | An array of funnel steps. | + +Each step must include the keys `name`, `target`, and `action`. + +| Key | Description | +|----------|------------------------------------------------------------------------------------------| +| `name` | The name of the step. This should be a unique slug. | +| `action` | The action performed. (Only `pageview` is supported.) | +| `target` | The target of the step. (Because only `pageview` is supported, this should be a path.) | + +### Example funnel definition + +```yaml +name: completed_purchase +seconds_to_convert: 3600 +steps: + - name: view_page_1 + target: '/page1.html' + action: 'pageview' + - name: view_page_2 + target: '/page2.html' + action: 'pageview' + - name: view_page_3 + target: '/page3.html' + action: 'pageview' +``` + +### Query a funnel + +You can [query the funnel data with the REST API](../../api/product_analytics.md#send-query-request-to-cube). +To do this, you can use the example query body below, where you need to replace `FUNNEL_NAME` with your funnel's name. + +NOTE: +The `afterDate` filter is not supported. Please use `beforeDate` or `inDateRange`. + +```json +{ + "query": { + "measures": [ + "FUNNEL_NAME.count" + ], + "order": { + "completed_purchase.count": "desc" + }, + "filters": [ + { + "member": "FUNNEL_NAME.date", + "operator": "beforeDate", + "values": [ + "2023-02-01" + ] + } + ], + "dimensions": [ + "FUNNEL_NAME.step" + ] + } +} +``` diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 18b4e53fb31..a74fd8d5215 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -19,7 +19,7 @@ Deleting a user deletes all projects in that user namespace. As a user, to delete your own account: -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. Select **Delete account**. @@ -56,7 +56,6 @@ When deleting users, you can either: - Issues. - Merge requests. - Notes and comments. - - Releases. - Personal access tokens. - Snippets. diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 5f23f50f439..b76b99b5242 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -21,7 +21,7 @@ If you set up a device, also set up a TOTP so you can still access your account ## Use personal access tokens with two-factor authentication -When 2FA is enabled, you can't use your password to authenticate with Git over HTTPS or the [GitLab API](../../../api/index.md). +When 2FA is enabled, you can't use your password to authenticate with Git over HTTPS or the [GitLab API](../../../api/rest/index.md). You can use a [personal access token](../personal_access_tokens.md) instead. ## Git Credential Manager @@ -297,7 +297,7 @@ If you regenerate 2FA recovery codes, save them. You can't use any previously cr ## Sign in with two-factor authentication enabled -Signing in with 2FA enabled is only slightly different than the normal sign-in process. Enter your username and password +Signing in with 2FA enabled is only slightly different than the typical sign-in process. Enter your username and password and you're presented with a second prompt, depending on which type of 2FA you've enabled. ### Sign in using a one-time password diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index 7a837258cb2..1f7264d740e 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -16,7 +16,7 @@ review the sessions, and revoke any you don't recognize. To list all active sessions: -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Active Sessions**. @@ -33,7 +33,7 @@ exceeds 100, the oldest ones are deleted. To revoke an active session: -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Active Sessions**. 1. Select **Revoke** next to a session. The current session cannot be revoked, as this would sign you out of GitLab. diff --git a/doc/user/profile/contributions_calendar.md b/doc/user/profile/contributions_calendar.md index 49e6319aa12..e9802cccef6 100644 --- a/doc/user/profile/contributions_calendar.md +++ b/doc/user/profile/contributions_calendar.md @@ -40,7 +40,7 @@ GitLab tracks the following contribution events: To view your daily contributions: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select your name from the dropdown list. 1. In the contributions calendar: - To view the number of contributions for a specific day, hover over a tile. @@ -53,7 +53,7 @@ The contributions calendar graph and recent activity list displays your To view private contributions: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Main settings** section, select the **Include private contributions on my profile** checkbox. 1. Select **Update profile settings**. @@ -83,7 +83,7 @@ GitLab provides RSS feeds of user activity. To subscribe to the RSS feed of a user's activity: 1. Go to the [user's profile](index.md#access-your-user-profile). -1. In the top right, select the feed symbol **{rss}** to display the results as an RSS feed in Atom format. +1. In the upper right, select the feed symbol **{rss}** to display the results as an RSS feed in Atom format. The URL of the result contains both a feed token, and the user's activity that you're authorized to view. @@ -96,7 +96,7 @@ If you think your feed token has been exposed, you should reset it. To reset your feed token: -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. 1. Scroll down. In the **Feed token** section, select the diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index f178a3254f3..a84d16e6d0c 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -15,14 +15,14 @@ Your profile also includes settings, which you use to customize your GitLab expe To access your profile: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select your name or username. ## Access your user settings To access your user settings: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. ## Change your username @@ -40,7 +40,7 @@ Prerequisites: To change your username: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. In the **Change username** section, enter a new username as the path. @@ -50,7 +50,7 @@ To change your username: To add new email to your account: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Emails**. 1. In the **Email** text box, enter the new email. @@ -63,7 +63,7 @@ You can make your user profile visible to only you and GitLab administrators. To make your profile private: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. Select the **Private profile** checkbox. 1. Select **Update profile settings**. @@ -129,11 +129,12 @@ They can help other users connect with you on other platforms. To add links to other accounts: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Main settings** section, add your information from: - - Skype + - Discord ([User ID](https://support.discord.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID-)) - LinkedIn + - Skype - Twitter 1. Select **Update profile settings**. @@ -143,7 +144,7 @@ In the user contribution calendar graph and recent activity list, you can see yo To show private contributions: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Main settings** section, select the **Include private contributions on my profile** checkbox. 1. Select **Update profile settings**. @@ -157,7 +158,7 @@ your name in your profile. To specify your pronouns: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Pronouns** text box, enter your pronouns. 1. Select **Update profile settings**. @@ -171,7 +172,7 @@ your name. To add your name pronunciation: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Pronunciation** text box, enter how your name is pronounced. 1. Select **Update profile settings**. @@ -187,7 +188,7 @@ Your status is publicly visible even if your [profile is private](#make-your-use To set your current status: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Set status** or, if you have already set a status, **Edit status**. 1. Set the desired emoji and status message. Status messages must be plain text and 100 characters or less. They can also contain emoji codes like, `I'm on vacation :palm_tree:`. @@ -210,12 +211,12 @@ To indicate to others that you are busy, you can set an indicator. To set the busy status indicator, either: - Set it directly: - 1. On the top bar, in the top-right corner, select your avatar. + 1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Set status** or, if you have already set a status, **Edit status**. 1. Select the **Set yourself as busy** checkbox. - Set it on your profile: - 1. On the top bar, in the top-right corner, select your avatar. + 1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Current status** section, select the **Set yourself as busy** checkbox. @@ -249,7 +250,7 @@ You can set your local time zone to: To set your time zone: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Time settings** section, select your time zone from the dropdown list. @@ -262,30 +263,28 @@ Your primary email is used by default. To change your commit email: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Commit email** dropdown list, select an email address. 1. Select **Update profile settings**. ## Change your primary email -Your primary email: - -- Is the default email address for your login, commit email, and notification email. -- Must be already [linked to your user profile](#add-emails-to-your-user-profile). +Your primary email is the default email address for your login, commit email, and notification email. To change your primary email: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Email** field, enter your new email address. 1. Select **Update profile settings**. +1. Optional. Select the confirmation email if you have not previously added this email to your GitLab.com account. ## Set your public email You can select one of your [configured email addresses](#add-emails-to-your-user-profile) to be displayed on your public profile: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Public email** field, select one of the available email addresses. 1. Select **Update profile settings**. @@ -297,7 +296,7 @@ so you can keep your email information private. To use a private commit email: -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. In the **Commit email** dropdown list, select **Use a private email**. 1. Select **Update profile settings**. @@ -368,7 +367,7 @@ The `remember_user_token` lifetime of a cookie can now extend beyond the deadlin GitLab uses both session and persistent cookies: -- Session cookie: Session cookies are normally removed at the end of the browser session when +- Session cookie: Session cookies are typically removed at the end of the browser session when the browser is closed. The `_gitlab_session` cookie has no fixed expiration date. However, it expires based on its [`session_expire_delay`](#why-do-you-keep-getting-signed-out). - Persistent cookie: The `remember_user_token` is a cookie with an expiration date of two weeks. diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index 7343aea8ce7..dcc78dac05b 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -47,7 +47,7 @@ anyone else. To edit your notification settings: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. 1. Edit the desired global, group, or project notification settings. @@ -100,7 +100,7 @@ You can select a notification level and email address for each group. To select a notification level for a group, use either of these methods: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. 1. Locate the project in the **Groups** section. @@ -119,7 +119,7 @@ Or: You can select an email address to receive notifications for each group you belong to. You can use group notifications, for example, if you work freelance, and want to keep email about clients' projects separate. -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. 1. Locate the project in the **Groups** section. @@ -131,7 +131,7 @@ To help you stay up to date, you can select a notification level for each projec To select a notification level for a project, use either of these methods: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. 1. Locate the project in the **Projects** section. @@ -153,7 +153,7 @@ These emails are enabled by default. To opt out: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. 1. Clear the **Receive product marketing emails** checkbox. @@ -330,7 +330,7 @@ The participants are: If you no longer wish to receive any email notifications: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **Notifications**. 1. Clear the **Receive product marketing emails** checkbox. diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 90def3aa773..3826c602fb4 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -14,7 +14,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Personal access tokens can be an alternative to [OAuth2](../../api/oauth2.md) and used to: -- Authenticate with the [GitLab API](../../api/index.md#personalprojectgroup-access-tokens). +- Authenticate with the [GitLab API](../../api/rest/index.md#personalprojectgroup-access-tokens). - Authenticate with Git using HTTP Basic Authentication. In both cases, you authenticate with a personal access token in place of your password. @@ -40,9 +40,9 @@ Though required, GitLab usernames are ignored when authenticating with a persona There is an [issue for tracking](https://gitlab.com/gitlab-org/gitlab/-/issues/212953) to make GitLab use the username. -For examples of how you can use a personal access token to authenticate with the API, see the [API documentation](../../api/index.md#personalprojectgroup-access-tokens). +For examples of how you can use a personal access token to authenticate with the API, see the [API documentation](../../api/rest/index.md#personalprojectgroup-access-tokens). -Alternately, GitLab administrators can use the API to create [impersonation tokens](../../api/index.md#impersonation-tokens). +Alternately, GitLab administrators can use the API to create [impersonation tokens](../../api/rest/index.md#impersonation-tokens). Use impersonation tokens to automate authentication as a specific user. NOTE: @@ -54,7 +54,7 @@ Personal access tokens are not FIPS compliant and creation and use are disabled You can create as many personal access tokens as you like. -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. 1. Enter a name and optional expiry date for the token. @@ -82,7 +82,7 @@ for guidance on managing personal access tokens (for example, setting a short ex At any time, you can revoke a personal access token. -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. 1. In the **Active personal access tokens** area, next to the key, select **Revoke**. @@ -91,12 +91,12 @@ At any time, you can revoke a personal access token. Token usage information is updated every 24 hours. GitLab considers a token used when the token is used to: -- Authenticate with the [REST](../../api/index.md) or [GraphQL](../../api/graphql/index.md) APIs. +- Authenticate with the [REST](../../api/rest/index.md) or [GraphQL](../../api/graphql/index.md) APIs. - Perform a Git operation. To view the last time a token was used: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. 1. In the **Active personal access tokens** area, next to the key, view the **Last Used** date. @@ -154,7 +154,7 @@ To create a personal access token programmatically: ```ruby user = User.find_by_username('automation-bot') - token = user.personal_access_tokens.create(scopes: [:read_user, :read_repository], name: 'Automation token') + token = user.personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: 'Automation token') token.set_token('token-string-here123') token.save! ``` @@ -163,7 +163,7 @@ This code can be shortened into a single-line shell command by using the [Rails runner](../../administration/operations/rails_console.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!" +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!" ``` ## Revoke a personal access token programmatically **(FREE SELF)** @@ -198,6 +198,29 @@ This code can be shortened into a single-line shell command using the sudo gitlab-rails runner "PersonalAccessToken.find_by_token('token-string-here123').revoke!" ``` +## Clone repository using personal access token **(FREE SELF)** + +To clone a repository when SSH is disabled, clone it using a personal access token by running the following command: + +```shell +git clone https://<username>:<personal_token>@gitlab.com/gitlab-org/gitlab.git +``` + +This method saves your personal access token in your bash history. To avoid this, run the following command: + +```shell +git clone https://<username>@gitlab.com/gitlab-org/gitlab.git +``` + +When asked for your password for `https://gitlab.com`, enter your personal access token. + +The `username` in the `clone` command: + +- Can be any string value. +- Must not be an empty string. + +Remember this if you set up an automation pipeline that depends on authentication. + ## Troubleshooting ### Unrevoke a personal access token **(FREE SELF)** diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 664d22959a2..7e581bb7419 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -12,7 +12,7 @@ of GitLab to their liking. To navigate to your profile's preferences: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Preferences**. ## Navigation theme @@ -67,7 +67,7 @@ GitLab uses the [rouge Ruby library](http://rouge.jneen.net/ "Rouge website") for syntax highlighting outside of any Editor context. The WebIDE (like Snippets) uses [Monaco Editor](https://microsoft.github.io/monaco-editor/) and it's provided [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) library for -syntax highlighting. For a list of supported languages, visit the documentation of +syntax highlighting. For a list of supported languages, see the documentation of the respective libraries. Changing this setting allows you to customize the color theme when viewing any @@ -120,20 +120,8 @@ While `1280px` is the standard max width when using fixed layout, some pages sti For users who have access to a large number of projects but only keep up with a select few, the amount of activity on the your dashboard can be -overwhelming. Changing this setting allows you to redefine what is displayed by default. - -You can include the following options for your default dashboard view: - -- Your projects (default) -- Starred projects -- Your projects' activity -- Starred projects' activity -- Followed Users' Activity -- Your groups -- Your [To-Do List](../todos.md) -- Assigned Issues -- Assigned Merge Requests -- [Operations Dashboard](../operations_dashboard/index.md) +overwhelming. From the **Dashboard** dropdown list, select what you'd like displayed on your +personal dashboard. ### Group overview content diff --git a/doc/user/profile/unknown_sign_in_notification.md b/doc/user/profile/unknown_sign_in_notification.md deleted file mode 100644 index 3bdcd36a34e..00000000000 --- a/doc/user/profile/unknown_sign_in_notification.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'notifications.md' -remove_date: '2023-01-15' ---- - -This document was moved to [another location](notifications.md). - -<!-- This redirect file can be deleted after <2023-01-15>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/profile/user_passwords.md b/doc/user/profile/user_passwords.md index 9c1ba8852d2..eac3db3c71c 100644 --- a/doc/user/profile/user_passwords.md +++ b/doc/user/profile/user_passwords.md @@ -26,7 +26,7 @@ authorization provider, you do not need to choose a password. GitLab You can change your password. GitLab enforces [password requirements](#password-requirements) when you choose your new password. -1. On the top bar, in the top-right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Password**. 1. In the **Current password** text box, enter your current password. diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index dc650bd9482..0ea1a80bc54 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -1,39 +1,145 @@ --- -stage: Create -group: Source Code +stage: Manage +group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Badges **(FREE)** -Badges are a unified way to present condensed pieces of information about your -projects. They consist of a small image and a URL that the image -points to. Examples for badges can be the [pipeline status](../../ci/pipelines/settings.md#pipeline-status-badge), -[test coverage](../../ci/pipelines/settings.md#test-coverage-report-badge), [latest release](../../ci/pipelines/settings.md#latest-release-badge), or ways to contact the -project maintainers. +Badges are a unified way to present condensed pieces of information about your projects. +A badge consists of a small image and a URL that the image points to. +In GitLab, badges are displayed below the project description. +You can use badges at the [project](#project-badges) and [group](#group-badges) level.  +## Available badges + +GitLab provides the following pipeline badges: + +- [Pipeline status badge](#pipeline-status-badges) +- [Test coverage report badge](#test-coverage-report-badges) +- [Latest release badge](#latest-release-badges) + +GitLab also supports [custom badges](#customize-badges). + +## Pipeline status badges + +The pipeline status badge indicates the status of the latest pipeline in a project. +Depending on the status of your pipeline, the badge can have one of the following values: + +- `pending` +- `running` +- `passed` +- `failed` +- `skipped` +- `manual` +- `canceled` +- `unknown` + +You can access a pipeline status badge image by using the following link: + +```plaintext +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg +``` + +### Display only non-skipped status + +To make the pipeline status badge display only the last non-skipped status, use the `?ignore_skipped=true` query parameter: + +```plaintext +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg?ignore_skipped=true +``` + +## Test coverage report badges + +The test coverage report badge indicates the percentage of code that is tested in a project. +The value is calculated based on the latest successful pipeline. + +You can access a test coverage report badge image by using the following link: + +```plaintext +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg +``` + +You can define the regular expression for the [coverage report](../../ci/pipelines/settings.md#merge-request-test-coverage-results) +that each job log is matched against. +This means that each job in the pipeline can have the test coverage percentage value defined. + +To get the coverage report from a specific job, add the `job=coverage_job_name` parameter to the URL. +For example, you can use code similar to the following to add the test coverage report badge of the +`coverage` job to a Markdown file: + +```markdown + +``` + +### Test coverage report badge colors and limits + +The default colors and limits for the badge are as follows: + +- 95 up to and including 100% - good (`#4c1`) +- 90 up to 95% - acceptable (`#a3c51c`) +- 75 up to 90% - medium (`#dfb317`) +- 0 up to 75% - low (`#e05d44`) +- no coverage - unknown (`#9f9f9f`) + +NOTE: +*Up to* means up to, but not including, the upper bound. + +You can overwrite the limits by using the following additional parameters ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28317) in GitLab 14.4): + +- `min_good` (default 95, can use any value between 3 and 100) +- `min_acceptable` (default 90, can use any value between 2 and min_good-1) +- `min_medium` (default 75, can use any value between 1 and min_acceptable-1) + +If an invalid boundary is set, GitLab automatically adjusts it to be valid. For example, +if `min_good` is set `80`, and `min_acceptable` is set to `85` (too high), GitLab automatically +sets `min_acceptable` to `79` (`min_good` - `1`). + +## Latest release badges + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33368) in GitLab 14.8. + +The latest release badge indicates the latest release tag name for your project. +If there is no release, it shows `none`. + +You can access a latest release badge image by using the following link: + +```plaintext +https://gitlab.example.com/<namespace>/<project>/badges/<branch>/release.svg +``` + +By default, the badge fetches the release sorted using the [`released_at`](../../api/releases/index.md#create-a-release) +time with the `?order_by` query parameter. + +```plaintext +https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg?order_by=release_at +``` + ## Project badges Badges can be added to a project by Maintainers or Owners, and are visible on the project's overview page. If you find that you have to add the same badges to several projects, you may want to add them at the [group level](#group-badges). +### Add a badge to a project + To add a new badge to a project: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. 1. Expand **Badges**. -1. Under "Link", enter the URL that the badges should point to and under - "Badge image URL" the URL of the image that should be displayed. +1. Under **Link**, enter the URL that the badges should point to. +1. Under **Badge image URL**, enter the URL of the image that should be displayed. 1. Select **Add badge**. -After adding a badge to a project, you can see it in the list below the form. -You can edit the badge by selecting **Edit** (**{pencil}**) next to it or delete it by -selecting **Delete** (**{remove}**). +After adding a badge to a project, you can see the badge in the list below the form. -Badges associated with a group can only be edited or deleted on the -[group level](#group-badges). +### Edit or delete a project badge + +To edit a badge, select **Edit** (**{pencil}**). + +To delete a badge, select **Delete** (**{remove}**). ### Example project badge: Pipeline Status @@ -66,6 +172,8 @@ If you need individual badges for each project, either: - Add the badge at the [project level](#project-badges). - Use [placeholders](#placeholders). +### Add a badge to a group + To add a new badge to a group: 1. On the top bar, select **Main menu > Groups** and find your group. @@ -76,33 +184,70 @@ To add a new badge to a group: 1. Select **Add badge**. After adding a badge to a group, you can see it in the list below the form. -You can edit the badge by selecting **Edit** (**{pencil}**) next to it or delete it by -selecting **Delete** (**{remove}**). -Badges directly associated with a project can be configured on the -[project level](#project-badges). +### Edit or delete a group badge -## Placeholders +To edit a badge, select **Edit** (**{pencil}**). -Both the URL a badge points to and the image URL can contain placeholders -which are evaluated when displaying the badge. The following placeholders -are available: +To delete a badge, select **Delete** (**{remove}**). -- `%{project_path}`: Path of a project including the parent groups -- `%{project_title}`: Title of a project -- `%{project_name}`: Name of a project -- `%{project_id}`: Database ID associated with a project -- `%{default_branch}`: Default branch name configured for a project's repository -- `%{commit_sha}`: ID of the most recent commit to the default branch of a - project's repository +Badges associated with a group can be edited or deleted only at the [group level](#group-badges). -NOTE: -Placeholders allow badges to expose otherwise-private information, such as the -default branch or commit SHA when the project is configured to have a private -repository. This is by design, as badges are intended to be used publicly. Avoid -using these placeholders if the information is sensitive. +## View the URL of pipeline badges + +You can view the exact link for your badges. +Then you can use the link to embed the badge in your HTML or Markdown pages. + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **General pipelines**. +1. In the **Pipeline status**, **Coverage report**, or **Latest release** sections, view the URLs for the images. + + + +## Customize badges + +You can customize the following aspects of a badge: + +- Style +- Text +- Width +- Image + +### Customize badge style + +Pipeline badges can be rendered in different styles by adding the `style=style_name` parameter to the URL. Two styles are available: + +- Flat (default): + + ```plaintext + https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat + ``` + +  + +- Flat square ([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30120) in GitLab 11.8): -## Use custom badge images + ```plaintext + https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat-square + ``` + +  + +### Customize badge text + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17555) in GitLab 13.1. + +The text for a badge can be customized to differentiate between multiple coverage jobs that run in the same pipeline. +Customize the badge text and width by adding the `key_text=custom_text` and `key_width=custom_key_width` parameters to the URL: + +```plaintext +https://gitlab.com/gitlab-org/gitlab/badges/main/coverage.svg?job=karma&key_text=Frontend+Coverage&key_width=130 +``` + + + +### Customize badge image Use custom badge images in a project or a group if you want to use badges other than the default ones. @@ -118,7 +263,7 @@ Using placeholders, here is an example badge image URL referring to a raw image https://gitlab.example.com/<project_path>/-/raw/<default_branch>/my-image.svg ``` -To add a new badge to a group or project with a custom image: +To add a new badge with a custom image to a group or project: 1. On the top bar, select **Main menu** and find your group or project. 1. On the left sidebar, select **Settings > General**. @@ -129,11 +274,31 @@ To add a new badge to a group or project with a custom image: displayed. 1. Select **Add badge**. -To learn how to use custom images generated via a pipeline, see our documentation on +To learn how to use custom images generated through a pipeline, see the documentation on [accessing the latest job artifacts by URL](../../ci/pipelines/job_artifacts.md#access-the-latest-job-artifacts). -## API +## Placeholders + +Both the URL a badge points to and the image URL can contain placeholders, +which are evaluated when displaying the badge. +The following placeholders are available: + +- `%{project_path}`: Path of a project including the parent groups +- `%{project_title}`: Title of a project +- `%{project_name}`: Name of a project +- `%{project_id}`: Database ID associated with a project +- `%{default_branch}`: Default branch name configured for a project's repository +- `%{commit_sha}`: ID of the most recent commit to the default branch of a + project's repository + +NOTE: +Placeholders allow badges to expose otherwise-private information, such as the +default branch or commit SHA when the project is configured to have a private +repository. This behavior is intentional, as badges are intended to be used publicly. Avoid +using these placeholders if the information is sensitive. + +## Configure badges through the API You can also configure badges via the GitLab API. As in the settings, there is -a distinction between endpoints for badges on the +a distinction between endpoints for badges at the [project level](../../api/project_badges.md) and [group level](../../api/group_badges.md). diff --git a/doc/user/project/changelogs.md b/doc/user/project/changelogs.md new file mode 100644 index 00000000000..a64edd053b1 --- /dev/null +++ b/doc/user/project/changelogs.md @@ -0,0 +1,317 @@ +--- +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/product/ux/technical-writing/#assignments" +type: reference, api +--- + +# Changelogs + +Changelogs are generated based on commit titles and Git trailers. To be included +in a changelog, a commit must contain a specific Git trailer. Changelogs are generated +from commit titles, and categorized by Git trailer type. You can enrich changelog entries +with additional data, such as a link to the merge request or details about the +commit author. Changelog formats [can be customized](#customize-the-changelog-output) with a template. + +Each section in the default changelog has a title containing the version +number and release date, like this: + +````markdown +## 1.0.0 (2021-01-05) + +### Features (4 changes) + +- [Feature 1](gitlab-org/gitlab@123abc) by @alice ([merge request](gitlab-org/gitlab!123)) +- [Feature 2](gitlab-org/gitlab@456abc) ([merge request](gitlab-org/gitlab!456)) +- [Feature 3](gitlab-org/gitlab@234abc) by @steve +- [Feature 4](gitlab-org/gitlab@456) +```` + +The date format for sections can be customized, but the rest of the title cannot. +When adding new sections, GitLab parses these titles to determine where to place +the new information in the file. GitLab sorts sections according to their versions, +not their dates. + +Each section contains changes sorted by category (like **Features**), and the format +of these sections can be changed. The section names derive from the values of the +Git trailer used to include or exclude commits. + +Commits for changelogs can be retrieved when operating on a mirror. GitLab itself +uses this feature, because security releases can include changes from both public +projects and private security mirrors. + +## Add a trailer to a Git commit + +You can add trailers manually when you write a commit message. To include a commit +using the default trailer of `Changelog` and categorize it as a feature, add the +string `Changelog: feature` to your commit message, like this: + +```plaintext +<Commit message subject> + +<Commit message description> + +Changelog: feature +``` + +## Create a changelog + +To generate changelog data based on commits in a repository, see +[Add changelog data to a changelog file](../../api/repositories.md#add-changelog-data-to-a-changelog-file) +in the API documentation. + +The changelog output is formatted in Markdown, and [you can customize it](#customize-the-changelog-output). + +### Reverted commits + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55537) in GitLab 13.10. + +To be treated as a revert commit, the commit message must contain the string +`This reverts commit <SHA>`, where `SHA` is the SHA of the commit to be reverted. + +When generating a changelog for a range, GitLab ignores commits both added and +reverted in that range. In this example, commit C reverts commit B. Because +commit C has no other trailer, only commit A is added to the changelog: + +```mermaid +graph LR + A[Commit A<br>Changelog: changed] --> B[Commit B<br>Changelog: changed] + B --> C[Commit C<br>Reverts commit B] +``` + +However, if the revert commit (commit C) _also_ contains a changelog trailer, +both commits A and C are included in the changelog: + +```mermaid +graph LR + A[Commit A<br><br>Changelog: changed] --> B[Commit B<br><br>Changelog: changed] + B --> C[Commit C<br>Reverts commit B<br>Changelog: changed] +``` + +Commit B is skipped. + +### Customize the changelog output + +To customize the changelog output, edit the changelog configuration file. The default +location for this configuration is `.gitlab/changelog_config.yml`. The file supports +these variables: + +- `date_format`: The date format, in `strftime` format, used in the title of the newly added changelog data. +- `template`: A custom template to use when generating the changelog data. +- `include_groups`: A list of group full paths containing users whose contributions + should be credited regardless of project membership. The user generating the changelog + must have access to each group for credit to be given. +- `categories`: A hash that maps raw category names to the names to use in the changelog. + To alter the names displayed in the changelog, add these lines to your configuration file + and edit them to meet your needs. This example renders the category titles as + `### Features`, `### Bug fixes`, and `### Performance improvements`: + + ```yaml + --- + categories: + feature: Features + bug: Bug fixes + performance: Performance improvements + ``` + +### Custom templates + +Category sections are generated using a template. The default template: + +```plaintext +{% if categories %} +{% each categories %} +### {{ title }} ({% if single_change %}1 change{% else %}{{ count }} changes{% end %}) + +{% each entries %} +- [{{ title }}]({{ commit.reference }})\ +{% if author.credit %} by {{ author.reference }}{% end %}\ +{% if merge_request %} ([merge request]({{ merge_request.reference }})){% end %} + +{% end %} + +{% end %} +{% else %} +No changes. +{% end %} +``` + +The `{% ... %}` tags are for statements, and `{{ ... }}` is used for printing +data. Statements must be terminated using a `{% end %}` tag. Both the `if` and +`each` statements require a single argument. + +For example, for a variable called `valid`, you can display "yes" +when this value is true, and display "nope" otherwise by doing the following: + +```plaintext +{% if valid %} +yes +{% else %} +nope +{% end %} +``` + +The use of `else` is optional. A value is considered true when it's a non-empty +value or boolean `true`. Empty arrays and hashes are considered false. + +Looping is done using `each`, and variables inside a loop are scoped to it. +Referring to the current value in a loop is done using the variable tag +`{{ it }}`. Other variables read their value from the current loop value. Take +this template for example: + +```plaintext +{% each users %} +{{name}} +{% end %} +``` + +Assuming `users` is an array of objects, each with a `name` field, this would +then print the name of every user. + +Using variable tags, you can access nested objects. For example, +`{{ users.0.name }}` prints the name of the first user in the `users` variable. + +If a line ends in a backslash, the next newline is ignored. This allows you to +wrap code across multiple lines, without introducing unnecessary newlines in the +Markdown output. + +Tags that use `{%` and `%}` (known as expression tags) consume the newline that +directly follows them, if any. This means that this: + +```plaintext +--- +{% if foo %} +bar +{% end %} +--- +``` + +Compiles into this: + +```plaintext +--- +bar +--- +``` + +Instead of this: + +```plaintext +--- + +bar + +--- +``` + +You can specify a custom template in your configuration, like this: + +```yaml +--- +template: | + {% if categories %} + {% each categories %} + ### {{ title }} + + {% each entries %} + - [{{ title }}]({{ commit.reference }})\ + {% if author.credit %} by {{ author.reference }}{% end %} + + {% end %} + + {% end %} + {% else %} + No changes. + {% end %} +``` + +When specifying the template you should use `template: |` and not +`template: >`, as the latter doesn't preserve newlines in the template. + +### Template data + +At the top level, the following variable is available: + +- `categories`: an array of objects, one for every changelog category. + +In a category, the following variables are available: + +- `count`: the number of entries in this category. +- `entries`: the entries that belong to this category. +- `single_change`: a boolean that indicates if there is only one change (`true`), + or multiple changes (`false`). +- `title`: the title of the category (after it has been remapped). + +In an entry, the following variables are available (here `foo.bar` means that +`bar` is a sub-field of `foo`): + +- `author.contributor`: a boolean set to `true` when the author is not a project + member, otherwise `false`. +- `author.credit`: a boolean set to `true` when `author.contributor` is `true` or + when `include_groups` is configured, and the author is a member of one of the + groups. +- `author.reference`: a reference to the commit author (for example, `@alice`). +- `commit.reference`: a reference to the commit, for example, + `gitlab-org/gitlab@0a4cdd86ab31748ba6dac0f69a8653f206e5cfc7`. +- `commit.trailers`: an object containing all the Git trailers that were present + in the commit body. +- `merge_request.reference`: a reference to the merge request that first + introduced the change (for example, `gitlab-org/gitlab!50063`). +- `title`: the title of the changelog entry (this is the commit title). + +The `author` and `merge_request` objects might not be present if the data +couldn't be determined. For example, when a commit is created without a +corresponding merge request, no merge request is displayed. + +### Customize the tag format when extracting versions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56889) in GitLab 13.11. + +GitLab uses a regular expression (using the +[re2](https://github.com/google/re2/) engine and syntax) to extract a semantic +version from tag names. The default regular expression is: + +```plaintext +^v?(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<pre>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<meta>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ +``` + +This regular expression is based on the official +[semantic versioning](https://semver.org/) regular expression, and also includes +support for tag names that start with the letter `v`. + +If your project uses a different format for tags, you can specify a different +regular expression. The regular expression used _must_ produce the following +capture groups. If any of these capture groups are missing, the tag is ignored: + +- `major` +- `minor` +- `patch` + +The following capture groups are optional: + +- `pre`: If set, the tag is ignored. Ignoring `pre` tags ensures release candidate + tags and other pre-release tags are not considered when determining the range of + commits to generate a changelog for. +- `meta`: Optional. Specifies build metadata. + +Using this information, GitLab builds a map of Git tags and their release +versions. It then determines what the latest tag is, based on the version +extracted from each tag. + +To specify a custom regular expression, use the `tag_regex` setting in your +changelog configuration YAML file. For example, this pattern matches tag names +such as `version-1.2.3` but not `version-1.2`. + +```yaml +--- +tag_regex: '^version-(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)$' +``` + +To test if your regular expression is working, you can use websites such as +[regex101](https://regex101.com/). If the regular expression syntax is invalid, +an error is produced when generating a changelog. + +## Related topics + +- [Changelog-related endpoints](../../api/repositories.md) in the Repositories API. +- Developer documentation for [changelog entries](../../development/changelog.md) in GitLab. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 7b010bf4478..b1c5bbfc4f7 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -72,8 +72,8 @@ cluster certificates: - **Kubernetes cluster name** - The name you wish to give the cluster. - **Environment scope** - The [associated environment](multiple_kubernetes_clusters.md#setting-the-environment-scope) to this cluster. - **Google Cloud Platform project** - Choose the project you created in your GCP - console to host the Kubernetes cluster. Learn more about - [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). + console to host the Kubernetes cluster. For more information, see + [Creating and managing projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). - **Zone** - Choose the [region zone](https://cloud.google.com/compute/docs/regions-zones/) under which to create the cluster. - **Number of nodes** - Enter the number of nodes you wish the cluster to have. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 523a6fd65f6..d3048158958 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -29,7 +29,7 @@ When you successfully connect an existing cluster using cluster certificates, th > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26815) in GitLab 12.6, you can remove cluster integrations and resources. When you remove a cluster integration, you only remove the cluster relationship -to GitLab, not the cluster. To remove the cluster itself, visit your cluster's +to GitLab, not the cluster. To remove the cluster itself, go to your cluster's GKE or EKS dashboard to do it from their UI or use `kubectl`. You need at least Maintainer [permissions](../../permissions.md) to your diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index 6e188a4923b..173f1f39a66 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -65,7 +65,7 @@ GitLab CI/CD build environment to deployment jobs. Deployment jobs have The Kubernetes integration provides a `KUBECONFIG` with an auto-generated namespace to deployment jobs. It defaults to using project-environment specific namespaces of the form `<prefix>-<environment>`, where `<prefix>` is of the form -`<project_name>-<project_id>`. To learn more, read [Deployment variables](#deployment-variables). +`<project_name>-<project_id>`. For more information, see [Deployment variables](#deployment-variables). You can customize the deployment namespace in a few ways: diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index d5f9c225cde..3fec38a61a0 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -43,7 +43,7 @@ code_navigation: The generated LSIF file size may be limited by the [artifact application limits (`ci_max_artifact_size_lsif`)](../../administration/instance_limits.md#maximum-file-size-per-type-of-artifact), -default to 100MB (configurable by an instance administrator). +default to 100 MB (configurable by an instance administrator). After the job succeeds, code intelligence data can be viewed while browsing the code: diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 641dff2766e..9de9d445965 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -15,6 +15,15 @@ files or directories in a repository. - You can set your merge requests so they must be approved by Code Owners before merge. - You can protect a branch and allow only Code Owners to approve changes to the branch. +<div class="video-fallback"> + Video introduction: <a href="https://www.youtube.com/watch?v=RoyBySTUSB0">Code Owners</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/RoyBySTUSB0" frameborder="0" allowfullscreen> </iframe> +</figure> + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> + Use Code Owners and approvers together with [approval rules](merge_requests/approvals/rules.md) to build a flexible approval workflow: @@ -34,18 +43,25 @@ For example: | Code Owner approval rule | Frontend: Code Style | `*.css` files | A frontend engineer reviews CSS file changes for adherence to project style standards. | | Code Owner approval rule | Backend: Code Review | `*.rb` files | A backend engineer reviews the logic and code style of Ruby files. | -## Set up Code Owners +## Code Owners file -Create a `CODEOWNERS` file to specify users or [shared groups](members/share_project_with_groups.md) +A `CODEOWNERS` file (with no extension) can specify users or [shared groups](members/share_project_with_groups.md) that are responsible for specific files and directories in a repository. Each repository -can have a single `CODEOWNERS` file. To create it: +can have a single `CODEOWNERS` file, and it must be found one of these three locations: + +- In the root directory of the repository. +- In the `.gitlab/` directory. +- In the `docs/` directory. + +A CODEOWNERS file in any other location is ignored. + +## Set up Code Owners -1. Choose the location where you want to specify Code Owners: - - In the root directory of the repository - - In the `.gitlab/` directory - - In the `docs/` directory +1. Create a file named `CODEOWNERS` (with no extension) in one of these locations: -1. In that location, create a file named `CODEOWNERS`. +- In the root directory of the repository +- In the `.gitlab/` directory +- In the `docs/` directory 1. In the file, enter text that follows one of these patterns: @@ -154,7 +170,20 @@ README.md @user1 The Code Owner for `README.md` would be `@user2`. -If you use sections, the last user _for each section_ is used. +If you use sections, the last pattern matching the file for each section is used. +For example, in a `CODEOWNERS` file using sections: + +```plaintext +[README Owners] +README.md @user1 @user2 +internal/README.md @user4 + +[README other owners] +README.md @user3 +``` + +The Code Owners for the `README.md` in the root directory are `@user1`, `@user2`, +and `@user3`. The Code Owners for `internal/README.md` are `@user4` and `@user3`. Only one CODEOWNERS pattern can match per file path. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index e87c5f57fc1..fc88535dc77 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -99,7 +99,7 @@ To create a public deploy key: 1. Select **New deploy key**. 1. Complete the fields. - Use a meaningful description for **Name**. For example, include the name of the external host - or application that will use the public deploy key. + or application that uses the public deploy key. You can modify only a public deploy key's name. @@ -148,7 +148,7 @@ What happens to the deploy key when it is disabled depends on the following: ### Deploy key cannot push to a protected branch -There are a few scenarios where a deploy key will fail to push to a +There are a few scenarios where a deploy key fails to push to a [protected branch](../protected_branches.md). - The owner associated to a deploy key does not have access to the protected branch. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 5f279ddda5b..cfb382d73e2 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -6,10 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Deploy tokens **(FREE)** -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199370) from **Settings > Repository** to **Settings > CI/CD** in GitLab 12.9. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) `write_registry` scope in GitLab 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI/CD** to **Settings > Repository** in GitLab 12.10.1. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) package registry scopes in GitLab 13.0. +> [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) package registry scopes in GitLab 13.0. You can use a deploy token to enable authentication of deployment tasks, independent of a user account. In most cases you use a deploy token from an external host, like a build server or CI/CD @@ -41,7 +38,9 @@ You can create deploy tokens at either the project or group level: By default, a deploy token does not expire. You can optionally set an expiry date when you create it. Expiry occurs at midnight UTC on that date. -Deploy tokens can't be used for Git operations and Package Registry operations if [external authorization](../../admin_area/settings/external_authorization.md) is enabled. +WARNING: +You cannot use new or existing deploy tokens for Git operations and Package Registry operations if +[external authorization](../../admin_area/settings/external_authorization.md) is enabled. ## Scope @@ -185,7 +184,7 @@ nuget source Add -Name GitLab -Source "https://gitlab.example.com/api/v4/project nuget install mypkg.nupkg ``` -## Push packages to a package repository +## Push packages to a package registry > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 6d0d444497e..8d3446994e8 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -10,7 +10,7 @@ Preventing wasted work caused by unresolvable merge conflicts requires a different way of working. This means explicitly requesting write permissions, and verifying no one else is editing the same file before you start. -Although branching strategies usually work well enough for source code and +Although branching strategies typically work well enough for source code and plain text because different versions can be merged together, they do not work for binary files. @@ -73,7 +73,7 @@ you can skip this step. If you're unsure, re-installing it does no harm: git lfs install ``` -Check this document to learn more about [using Git LFS](../../topics/git/lfs/index.md#using-git-lfs). +For more information, see [Using Git LFS](../../topics/git/lfs/index.md#using-git-lfs). ### Configure Exclusive File Locks @@ -209,7 +209,7 @@ requests that modify locked files. Unlock the file to allow changes. To lock a file: 1. Open the file or directory in GitLab. -1. On the top right, above the file, select **Lock**. +1. In the upper right, above the file, select **Lock**. 1. On the confirmation dialog box, select **OK**. If you do not have permission to lock the file, the button is not enabled. diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index 22ff234ac81..fbb6d1b329d 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -11,7 +11,7 @@ GitLab provides syntax highlighting on all files through [Highlight.js](https:// [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It attempts to guess what language to use based on the file extension, which most of the time is sufficient. -The paths here are Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). +The paths here use the [`.gitattributes` interface](https://git-scm.com/docs/gitattributes) in Git. NOTE: The [Web IDE](web_ide/index.md) and [Snippets](../snippets.md) use [Monaco Editor](https://microsoft.github.io/monaco-editor/) diff --git a/doc/user/project/img/pipelines_settings_badges.png b/doc/user/project/img/pipelines_settings_badges.png Binary files differnew file mode 100644 index 00000000000..3bdc6374c15 --- /dev/null +++ b/doc/user/project/img/pipelines_settings_badges.png diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 29d29c12536..7114974d8db 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -46,8 +46,8 @@ the user is not found in the GitLab database, the project creator (most of the t user that started the import process) is set as the author, but a reference on the issue about the original Bitbucket 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. ## Requirements for user-mapped contributions @@ -65,6 +65,8 @@ For user contributions to be mapped, each user must complete the following befor ## Import your Bitbucket repositories +> Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. + 1. Sign in to GitLab. 1. On the top bar, select **New** (**{plus}**). 1. Select **New project/repository**. @@ -76,9 +78,11 @@ For user contributions to be mapped, each user must complete the following befor 1. Select the projects that you'd like to import or import all projects. You can filter projects by name and select the namespace - each project will be imported for. + each project is imported for. -  +1. To import a project: + - For the first time: Select **Import**. + - Again: Select **Re-import**. Specify a new name and select **Re-import** again. Re-importing creates a new copy of the source project. ## Troubleshooting diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index db2a1d956ab..e6d2e3e00b6 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -24,6 +24,8 @@ created as private in GitLab as well. ## Import your Bitbucket repositories +> Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. + Prerequisites: - An administrator must enable **Bitbucket Server** in **Admin > Settings > General > Visibility and access controls > Import sources**. @@ -40,6 +42,9 @@ To import your Bitbucket repositories: 1. Log in to Bitbucket and grant GitLab access to your Bitbucket account. 1. Select the projects to import, or import all projects. You can filter projects by name and select the namespace for which to import each project. +1. To import a project: + - For the first time: Select **Import**. + - Again: Select **Re-import**. Specify a new name and select **Re-import** again. Re-importing creates a new copy of the source project. ### Items that are not imported diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index f8bbb2354fe..00aebb75a50 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -54,7 +54,7 @@ Wikipedia article on [comparing the different version control software](https:// CVS is old with no new release since 2008. Git provides more tools to work with (`git bisect` for one) which makes for a more productive workflow. -Migrating to Git/GitLab will benefit you: +Migrating to Git/GitLab benefits you: - **Shorter learning curve**, Git has a big community and a vast number of tutorials to get you started (see our [Git topic](../../../topics/git/index.md)). diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 08ee4c70dda..d9e03662434 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -7,6 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import your project from FogBugz to GitLab **(FREE)** +> Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. + Using the importer, you can import your FogBugz project to GitLab.com or to your self-managed GitLab instance. @@ -33,4 +35,6 @@ To import your project from FogBugz:  1. After the import finishes, select the link to go to the project dashboard. Follow the directions to push your existing repository. -  +1. To import a project: + - For the first time: Select **Import**. + - Again: Select **Re-import**. Specify a new name and select **Re-import** again. Re-importing creates a new copy of the source project. diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index fb64c902b38..404bb4c8600 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -70,8 +70,8 @@ From there, you can view the import statuses of your Gitea repositories: - Those that are being imported show a _started_ status. - Those already successfully imported are green with a _done_ status. -- Those that aren't yet imported have an **Import** button on the - right side of the table. +- Those that aren't yet imported have **Import** on the right side of the table. +- Those that are already imported have **Re-import** on the right side of the table. You also can: diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index da3637541d9..9298dab6f64 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -7,14 +7,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import your project from GitHub to GitLab **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381902) in GitLab 15.8, GitLab no longer automatically creates namespaces or groups that don't exist. GitLab also no longer falls back to using the user's personal namespace if the namespace or group name is taken. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378267) in GitLab 15.9, GitLab instances behind proxies no longer require `github.com` and `api.github.com` entries in the [allowlist for local requests](../../../security/webhooks.md#create-an-allowlist-for-local-requests). -You can import your GitHub repositories: - -- From either GitHub.com or GitHub Enterprise. -- To either GitLab.com or a self-managed GitLab instance. - -This process does not migrate or import any types of groups or organizations from GitHub to GitLab. +You can import your GitHub projects from either GitHub.com or GitHub Enterprise. Importing projects does not +migrate or import any types of groups or organizations from GitHub to GitLab. The namespace is a user or group in GitLab, such as `gitlab.com/sidney-jones` or `gitlab.com/customer-success`. You can use bulk actions in the rails console to move projects to @@ -24,22 +21,6 @@ If you are importing to a self-managed GitLab instance, you can use the [GitHub Rake task](../../../administration/raketasks/github_import.md) instead. This allows you to import projects without the constraints of a [Sidekiq](../../../development/sidekiq/index.md) worker. -NOTE: -If you are importing a project using the GitHub Rake task, GitLab still creates namespaces or groups that don't exist. - -If you are importing from GitHub Enterprise to a self-managed GitLab instance: - -- You must first enable [GitHub integration](../../../integration/github.md). -- To import projects from GitHub Enterprise to GitLab.com, use the [Import API](../../../api/import.md). -- If GitLab is behind a HTTP/HTTPS proxy, you must populate the [allowlist for local requests](../../../security/webhooks.md#create-an-allowlist-for-local-requests) - with `github.com` and `api.github.com` to solve the hostname. For more information, read the issue - [Importing a GitHub project requires DNS resolution even when behind a proxy](https://gitlab.com/gitlab-org/gitlab/-/issues/37941). - -If you are importing from GitHub.com to a self-managed GitLab instance: - -- Setting up GitHub integration is not required. -- You can use the [Import API](../../../api/import.md). - When importing projects: - If a user referenced in the project is not found in the GitLab database, the project creator is set as the author and @@ -57,24 +38,41 @@ For an overview of the import process, see the video [Migrating from GitHub to G ## Prerequisites -At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was -[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. +To import projects from GitHub: + +- You must have at least the Maintainer role on the destination group to import to. Using the Developer role for this + purpose was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in + GitLab 16.0. +- Each GitHub author and assignee in the repository must have a + [public-facing email address](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address) + on GitHub that matches their GitLab email address (regardless of how the account was created). If their email address + from GitHub is set as their secondary email address in GitLab, they must confirm it. + + When issues and pull requests are being imported, the importer attempts to find their GitHub authors and assignees in + the database of the GitLab instance. Pull requests are called _merge requests_ in GitLab. For the importer to succeed, + matching email addresses are required. +- GitHub accounts must have a GitHub public-facing email address is populated. This means all comments and contributions + are properly mapped to the same user in GitLab. GitHub Enterprise does not require this field to be populated so you + may have to add it on existing accounts. -When issues and pull requests are being imported, the importer attempts to find -their GitHub authors and assignees in the database of the GitLab instance. Pull requests are called _merge requests_ in -GitLab. +See also [Branch protection rules and project settings](#branch-protection-rules-and-project-settings) for additional +prerequisites for those imports. -For this association to succeed, each GitHub author and assignee in the repository -must have a [public-facing email address](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address) -on GitHub that matches their GitLab email address (regardless of how the account was created). -If their email address from GitHub is set as their secondary email address in GitLab, it must be -confirmed. +### Importing from GitHub Enterprise to self-managed GitLab + +If you are importing from GitHub Enterprise to a self-managed GitLab instance: -GitLab content imports that use GitHub accounts require that the GitHub public-facing email address is populated. This means -all comments and contributions are properly mapped to the same user in GitLab. GitHub Enterprise does not require this -field to be populated so you may have to add it on existing accounts. +- You must first enable the [GitHub integration](../../../integration/github.md). +- For GitLab 15.8 and earlier, you must add `github.com` and `api.github.com` entries in the + [allowlist for local requests](../../../security/webhooks.md#create-an-allowlist-for-local-requests). -See also [Branch protection rules and project settings](#branch-protection-rules-and-project-settings) for additional prerequisites for those imports. +### Importing from GitHub.com to self-managed GitLab + +If you are importing from GitHub.com to a self-managed GitLab instance: + +- You don't need to enable the [GitHub integration](../../../integration/github.md). +- GitHub must be enabled as an import source in the + [Admin Area](../../admin_area/settings/visibility_and_access_controls.md#configure-allowed-import-sources). ## Import your GitHub repository into GitLab @@ -145,7 +143,8 @@ You can choose to import these items, but this could significantly increase impo ### Select which repositories to import -> Ability to cancel pending or active imports [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247325) in GitLab 15.7. +> - Ability to cancel pending or active imports [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247325) in GitLab 15.7. +> - Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. After you have authorized access to your GitHub repositories, you are redirected to the GitHub importer page and your GitHub repositories are listed. @@ -167,6 +166,8 @@ If the import has already started, the imported files are kept. To open an repository in GitLab URL after it has been imported, select its GitLab path. +Completed imports can be re-imported by selecting **Re-import** and specifying new name. This creates a new copy of the source project. +  ## Mirror a repository and share pipeline status **(PREMIUM)** diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 3df6a543960..24748b2e89c 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -17,20 +17,22 @@ If you want to bring existing projects to GitLab or copy GitLab projects to a di Prerequisite: -- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. +- At least the Maintainer role on the destination group to import to. Using the Developer role for this purpose was + [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. For any type of source and target, you can migrate GitLab projects: -- When [migrating groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended), which allows you to migrate all - projects in a group at once. Migrating projects by direct transfer is in [Beta](../../../policy/alpha-beta-support.md#beta-features). The feature is not ready - for production use. +- When [migrating groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended), + which allows you to migrate all projects in a group simultaneously. Migrating projects by direct transfer is in + [Beta](../../../policy/alpha-beta-support.md#beta-features). The feature is not ready for production use. - Using [file exports](../settings/import_export.md). With this method you can migrate projects one by one. No network connection between instances is required. 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 metadata like issues and merge requests, either: -- [Migrate projects with groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). This feature is in [Beta](../../../policy/alpha-beta-support.md#beta-features). It is not ready for production use. +- [Migrate projects with groups by direct transfer](../../group/import/index.md#migrate-groups-by-direct-transfer-recommended). + This feature is in [Beta](../../../policy/alpha-beta-support.md#beta-features). It is not ready for production use. - Use [file exports](../settings/import_export.md) to import projects. Keep in mind the limitations of [migrating using file exports](../settings/import_export.md#items-that-are-exported). @@ -47,17 +49,15 @@ You can import projects from: - [CVS](cvs.md) - [FogBugz](fogbugz.md) - [GitHub.com or GitHub Enterprise](github.md) -- [GitLab.com](gitlab_com.md) - [Gitea](gitea.md) - [Perforce](perforce.md) - [TFVC](tfvc.md) - [Repository by URL](repo_by_url.md) -- [Uloading a manifest file (AOSP)](manifest.md) -- [Phabricator](phabricator.md) +- [Uploading a manifest file (AOSP)](manifest.md) - [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 import any Git repository through HTTP from the **New Project** page. If the repository +is too large, the import can timeout. You can then [connect your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). @@ -70,7 +70,7 @@ GitLab can not automatically migrate Subversion repositories to Git. Converting ## Migrate using the API -To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/index.md). +To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/rest/index.md). Migrate the assets in this order: 1. [Groups](../../../api/groups.md) @@ -91,7 +91,7 @@ The backups produced don't depend on the operating system running GitLab. You ca the restore method to switch between different operating system distributions or versions, as long as the same GitLab version [is available for installation](../../../administration/package_information/supported_os.md). -Also note that administrators can use the [Users API](../../../api/users.md) to migrate users. +Administrators can use the [Users API](../../../api/users.md) to migrate users. ## View project import history @@ -119,7 +119,7 @@ to create a new project from a template. ## 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) +When importing a project that contains LFS objects, if the project has an [`.lfsconfig`](https://github.com/git-lfs/git-lfs/blob/main/docs/man/git-lfs-config.adoc) file with a URL host (`lfs.url`) different from the repository URL host, LFS files are not downloaded. ## Project aliases **(PREMIUM SELF)** diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index c125102b0c9..514a6a0cb5a 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -7,7 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import multiple repositories by uploading a manifest file **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28811) in GitLab 11.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28811) in GitLab 11.2. +> - Ability to re-import projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23905) in GitLab 15.9. GitLab allows you to import all the required Git repositories based on a manifest file like the one used by the @@ -26,7 +27,7 @@ repositories like the Android Open Source Project (AOSP). 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 +a `name` and `path` attribute. GitLab then builds the URL to the repository by combining the URL from the `remote` tag with a project name. A path attribute is used to represent the project path in GitLab. @@ -59,6 +60,6 @@ To start the import: 1. Select a group you want to import to (you need to create a group first if you don't have one). 1. Select **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 select **Import all repositories** to start the import. - -  +1. To import: + - All projects for the first time: Select **Import all repositories**. + - Individual projects again: Select **Re-import**. Specify a new name and select **Re-import** again. Re-importing creates a new copy of the source project. diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index ca50a32836e..a96297b1a38 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -16,7 +16,7 @@ The following list illustrates the main differences between Perforce Helix and Git: - In general, the biggest difference is that Perforce branching is heavyweight - compared to Git's lightweight branching. When you create a branch in Perforce, + compared to Git lightweight branching. When you create a branch in Perforce, it creates an integration record in their proprietary database for every file in the branch, regardless how many were actually changed. With Git, however, a single SHA acts as a pointer to the state of the whole repository after the @@ -56,7 +56,7 @@ Here's a few links to get you started: - [`git-p4` example usage](https://git.wiki.kernel.org/index.php/Git-p4_Usage) - [Git book migration guide](https://git-scm.com/book/en/v2/Git-and-Other-Systems-Migrating-to-Git#_perforce_import) -Note that `git p4` and `git filter-branch` are not very good at +`git p4` and `git filter-branch` are not very good at creating small and efficient Git pack files. So it might be a good idea to spend time and CPU to properly repack your repository before sending it for the first time to your GitLab server. See diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index 09e7543bc4a..8a2dbba1343 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -36,7 +36,7 @@ Only the following basic fields are imported: 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. +of the project being imported into, then the user is linked. ## Enable this feature diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 08caa62bcb2..decf3b071e7 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -16,8 +16,7 @@ To create a blank project: 1. On the right of the page, select **New project**. 1. Select **Create blank project**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. + - In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces. - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. @@ -51,8 +50,7 @@ To create a project from a built-in template: - To view a preview of the template, select **Preview**. - To use a template for the project, select **Use template**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. + - In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces. - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. @@ -61,6 +59,11 @@ To create a project from a built-in template: change the **Visibility Level**. 1. Select **Create project**. +NOTE: +A user who creates a project [from a template](#create-a-project-from-a-built-in-template) or [by import](settings/import_export.md#import-a-project-and-its-data) is displayed as the author of the imported objects (such as issues and merge requests), which keep the original timestamp from the template or import. +Imported objects are labeled as `By <username> on <timestamp> (imported from GitLab)`. +For this reason, the creation date of imported objects can be older than the creation date of the user's account. This can lead to objects appearing to have been created by a user before they even had an account. + ## Create a project from a custom template **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in GitLab 11.2. @@ -78,8 +81,7 @@ Custom project templates are available at: - To view a preview of the template, select **Preview**. - To use a template for the project, select **Use template**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. + - In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces. - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. @@ -105,8 +107,7 @@ To create a project from the HIPAA Audit Protocol template: - To view a preview of the template, select **Preview**. - To use the template for the project, select **Use template**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You cannot use special characters at - the start or end of a project name. + - In the **Project name** field, enter the name of your project. The name must start with a lowercase or uppercase letter (`a-zA-Z`), digit (`0-9`), emoji, or underscore (`_`). It can also contain dots (`.`), pluses (`+`), dashes (`-`), or spaces. - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. diff --git a/doc/user/project/integrations/apple_app_store.md b/doc/user/project/integrations/apple_app_store.md index 62b25bf8191..1b41dd0b669 100644 --- a/doc/user/project/integrations/apple_app_store.md +++ b/doc/user/project/integrations/apple_app_store.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Apple App Store integration **(FREE)** +# Apple App Store **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104888) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `apple_app_store_integration`. Disabled by default. diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index 97fb4e7c463..8bc1a984e3d 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Asana integration **(FREE)** +# Asana **(FREE)** This integration adds commit messages as comments to Asana tasks. Once enabled, commit messages are checked for Asana task URLs (for example, diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index db90bafaaa5..12039a70d0e 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Atlassian Bamboo integration **(FREE)** +# Atlassian Bamboo **(FREE)** You can automatically trigger builds in Atlassian Bamboo when you push changes to your project in GitLab. @@ -71,7 +71,7 @@ and Bamboo build variables to: For example: -1. Create an [access token](../../../api/index.md#personalprojectgroup-access-tokens) in GitLab with `:api` permissions. +1. Create an [access token](../../../api/rest/index.md#personalprojectgroup-access-tokens) in GitLab with `:api` permissions. 1. Save the token as a `$GITLAB_TOKEN` variable in Bamboo. 1. Add the following script as a final task to the Bamboo plan's jobs: diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 9221250e17f..2933203c593 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Bugzilla service **(FREE)** +# Bugzilla **(FREE)** [Bugzilla](https://www.bugzilla.org/) is a web-based general-purpose bug tracking system and testing tool. @@ -37,8 +37,8 @@ After you configure and enable Bugzilla, a link appears on the GitLab project pages. This link takes you to the appropriate Bugzilla project. 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#configure-project-visibility-features-and-permissions). +For more information about the steps and consequences of disabling GitLab issues, see +[Configure project visibility, features, and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). ## Reference Bugzilla issues in GitLab diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 9439e480484..0163bce3496 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -4,9 +4,9 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Discord Notifications service **(FREE)** +# Discord Notifications **(FREE)** -The Discord Notifications service sends event notifications from GitLab to the channel for which the webhook was created. +The Discord Notifications integration sends event notifications from GitLab to the channel for which the webhook was created. To send GitLab event notifications to a Discord channel, [create a webhook in Discord](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) and configure it in GitLab. @@ -24,7 +24,7 @@ and configure it in GitLab. ## Configure created webhook in GitLab -With the webhook URL created in the Discord channel, you can set up the Discord Notifications service in GitLab. +With the webhook URL created in the Discord channel, you can set up the Discord Notifications integration in GitLab. 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index ff255cbba51..c3134e986d3 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -4,9 +4,9 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Enabling emails on push **(FREE)** +# Emails on push **(FREE)** -By enabling this service, you receive email notifications for every change +When you enable emails on push, you receive email notifications for every change that is pushed to your project. To enable emails on push: diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index d972509c0f6..c2371d32853 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -4,13 +4,13 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# IBM Engineering Workflow Management (EWM) Integration **(FREE)** +# Engineering Workflow Management (EWM) **(FREE)** -This service allows you to go from GitLab to EWM work items mentioned in merge request +This integration 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. -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. +This IBM product was [formerly named Rational Team Concert (RTC)](https://jazz.net/blog/index.php/2019/04/23/renaming-the-ibm-continuous-engineering-portfolio/). This integration is compatible with all versions of RTC and EWM. To enable the EWM integration, in a project: @@ -51,5 +51,5 @@ You can use the following keywords: - `work item` - `workitem` -Avoid using the keyword `#`. Learn more in the EWM documentation page +Avoid using the keyword `#`. For more information, see [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/github.md b/doc/user/project/integrations/github.md index 603ed8b4c05..990d0839581 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitHub project integration **(PREMIUM)** +# GitHub **(PREMIUM)** You can update GitHub with pipeline status updates from GitLab. This integration can help you if you use GitLab for CI/CD. diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 50b52421a5a..649b0c51818 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -7,16 +7,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab for Slack app **(FREE SAAS)** NOTE: -The GitLab for Slack app is only configurable for GitLab.com. It does **not** -work for on-premises installations where you can configure -[Slack slash commands](slack_slash_commands.md) instead. See -[Slack application integration for self-managed instances](https://gitlab.com/groups/gitlab-org/-/epics/1211) -for our plans to make the app configurable for all GitLab installations. +This feature is only configurable on GitLab.com. +For self-managed GitLab instances, use +[Slack slash commands](slack_slash_commands.md) and [Slack notifications](slack.md) instead. +For more information about our plans to make this feature configurable for all GitLab installations, +see [epic 1211](https://gitlab.com/groups/gitlab-org/-/epics/1211). Slack provides a native application that you can enable with your project's integrations on GitLab.com. -## Slack App Directory +## Installation + +### Through the Slack App Directory To enable the GitLab for Slack app for your workspace, install the [GitLab application](https://slack-platform.slack.com/apps/A676ADMV5-gitlab) @@ -25,7 +27,7 @@ from the [Slack App Directory](https://slack.com/apps). On the [GitLab for Slack app landing page](https://gitlab.com/-/profile/slack/edit), you can select a GitLab project to link with your Slack workspace. -## Configuration +### Through GitLab project settings Alternatively, you can configure the GitLab for Slack app with your project's integration settings. @@ -44,9 +46,44 @@ To enable the GitLab integration for your Slack workspace: You can also select **Reinstall GitLab for Slack app** to update the app in your Slack workspace to the latest version. See [Version history](#version-history) for details. -## Create a project alias for Slack +## Slash commands + +After installing the GitLab for Slack app, everyone in your Slack workspace can use slash commands. + +Replace `<project>` with the project full path, or create a shorter [project alias](#create-a-project-alias-for-slash-commands) for the slash commands. + +| Command | Effect | +| ------- | ------ | +| `/gitlab help` | Shows all available slash commands. | +| `/gitlab <project> issue new <title> <shift+return> <description>` | Creates a new issue with the title `<title>` and description `<description>`. | +| `/gitlab <project> issue show <id>` | Shows the issue with the ID `<id>`. | +| `/gitlab <project> issue close <id>` | Closes the issue with the ID `<id>`. | +| `/gitlab <project> issue search <query>` | Shows up to 5 issues matching `<query>`. | +| `/gitlab <project> issue move <id> to <project>` | Moves the issue with the ID `<id>` to `<project>`. | +| `/gitlab <project> issue comment <id> <shift+return> <comment>` | Adds a new comment with the comment body `<comment>` to the issue with the ID `<id>`. | +| `/gitlab <project> deploy <from> to <to>` | [Deploys](#the-deploy-slash-command) from the `<from>` environment to the `<to>` environment. | +| `/gitlab <project> run <job name> <arguments>` | Executes the [ChatOps](../../../ci/chatops/index.md) job `<job name>` on the default branch. | + +### The deploy slash command + +To deploy to an environment, GitLab tries to find a deployment +manual action in the pipeline. + +If there's only one action for a given environment, it is triggered. +If more than one action is defined, GitLab finds an action +name that matches the environment name to deploy to. + +The command returns an error if no matching action is found. + +### User authorization + +When you perform your first slash command, you must +authorize your Slack user on GitLab.com. + +### Create a project alias for slash commands -To create a project alias on GitLab.com for Slack integration: +By default, slash commands expect a project full path. To use a shorter alias +instead: 1. Go to your project's home page. 1. Go to **Settings > Integrations** (only visible on GitLab.com). @@ -55,43 +92,107 @@ To create a project alias on GitLab.com for Slack integration: select **Edit**. 1. Enter your desired alias, and select **Save changes**. -Some Slack commands require a project alias and fail with the following error -if the project alias is incorrect or missing from the command: +## Slack notifications -```plaintext -GitLab error: project or alias not found -``` +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381012) in GitLab 15.9. -## Usage +With Slack notifications, GitLab can send messages to Slack workspace channels for certain GitLab [events](#events-for-slack-notifications) (for example, when an issue is created). -After installing the app, everyone in your Slack workspace can -use the [slash commands](../../../integration/slash_commands.md). -When you perform your first slash command, you are asked to -authorize your Slack user on GitLab.com. +### Configure notifications -The only difference with the [manually configurable Slack slash commands](slack_slash_commands.md) -is that you must prefix all commands with the `/gitlab` keyword. For example, -to show the issue number `1001` under the `gitlab-org/gitlab` -project, you must run the following command: +To configure Slack notifications: -```plaintext -/gitlab gitlab-org/gitlab issue show 1001 -``` +1. On the top bar, select **Main menu > Projects** and find a project for which the GitLab for Slack app has been [installed](#installation). +1. On the left sidebar, select **Settings > Integrations**. +1. Select **GitLab for Slack app**. +1. In the **Trigger** section, select the checkbox for each GitLab + event you want to receive a notification for in Slack. For a full list, see + [Events for Slack notifications](#events-for-slack-notifications). +1. For each checkbox you select, enter the name of the channel that receives the notifications (for example, `#my-channel`). + - To send notifications to multiple Slack channels, enter up to 10 channel names separated by commas (for example, `#channel-one, #channel-two`). -## Version history + NOTE: + If the channel is private, you must also [add the GitLab for Slack app to the private channel](#receive-notifications-to-a-private-channel). + +1. Select the **Notify only broken pipelines** checkbox to notify only on failures. +1. From the **Branches for which notifications are to be sent** dropdown list, select which branches you want to receive notifications (if relevant to your events). +1. Leave the **Labels to be notified** text box blank to receive all notifications, or + add labels the issue or merge request must have to trigger a + notification. +1. Select **Save changes**. + +Your Slack workspace can now start receiving GitLab event notifications. + +### Receive notifications to a private channel -In GitLab 15.0 and later, the GitLab for Slack app is updated to [Slack's new granular permissions model](https://medium.com/slack-developer-blog/more-precision-less-restrictions-a3550006f9c3). While there is no change in functionality, you should reinstall the app. +To receive notifications to a private Slack channel, you must add the GitLab for Slack app to the channel: + +1. Mention the app in the channel by typing `@GitLab` and pressing <kbd>Enter</kbd>. +1. Select **Add to Channel**. + +### Events for Slack notifications + +The following events are available for Slack notifications: + +| Event name | Description | +|--------------------------------------------------------------------------|------------------------------------------------------| +| **Push** | A push to the repository. | +| **Issue** | An issue is created, updated, or closed. | +| **Confidential issue** | A confidential issue is created, updated, or closed. | +| **Merge request** | A merge request is created, updated, or merged. | +| **Note** | A comment is added. | +| **Confidential note** | A confidential note is added. | +| **Tag push** | A new tag is pushed to the repository. | +| **Pipeline** | A pipeline status changed. | +| **Wiki page** | A wiki page is created or updated. | +| **Deployment** | A deployment starts or finishes. | +| **Alert** | A new, unique alert is recorded. | +| [**Vulnerability**](../../application_security/vulnerabilities/index.md) | A new, unique vulnerability is recorded. | ## Troubleshooting -When you work with the GitLab for Slack app, the -[App Home](https://api.slack.com/start/overview#app_home) might not display properly. -As a workaround, ensure your app is up to date. +### Update the GitLab for Slack app + +New releases of the app might require permissions to be authorized before some features work in your Slack workspace. You should ensure the app is up to date in your Slack workspace to enjoy all the latest features. -To update an existing Slack integration: +To update your GitLab for Slack app: -1. Go to your [chat settings](https://gitlab.com/-/profile/chat_names). -1. Next to your project, select **GitLab for Slack app**. +1. On the top bar, select **Main menu > Projects** and find a project for which the GitLab for Slack app has been configured. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **GitLab for Slack app**. 1. Select **Reinstall GitLab for Slack app**. +The GitLab for Slack app is updated for all projects that use the integration. + Alternatively, you can [configure a new Slack integration](https://about.gitlab.com/solutions/slack/). + +### Project or alias not found + +Some Slack commands must have a project full path or alias and fail with the following error +if the project cannot be found: + +```plaintext +GitLab error: project or alias not found +``` + +As a workaround, ensure: + +- The project full path is correct. +- If using a [project alias](#create-a-project-alias-for-slash-commands), the alias is correct. +- The GitLab for Slack app integration is [enabled for the project](#through-gitlab-project-settings). + +### Notifications are not received to a channel + +If you're not receiving notifications to a Slack channel, ensure: + +- The channel name you configured is correct. +- If the channel is private, you've [added the GitLab for Slack app to the channel](#receive-notifications-to-a-private-channel). + +### The App Home does not display properly + +If the [App Home](https://api.slack.com/start/overview#app_home) does not display properly, ensure your [app is up to date](#update-the-gitlab-for-slack-app). + +## Version history + +In GitLab 15.0 and later, the GitLab for Slack app is updated to [Slack's new granular permissions model](https://medium.com/slack-developer-blog/more-precision-less-restrictions-a3550006f9c3). +Although there is no change in functionality, you should [reinstall the app](#update-the-gitlab-for-slack-app). diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index c6e102b1d74..3537033902d 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Google Chat integration **(FREE)** +# Google Chat **(FREE)** Integrate your project to send notifications from GitLab to a room of your choice in [Google Chat](https://chat.google.com/) (former Google @@ -28,7 +28,7 @@ notifications to Google Chat: To enable the integration in Google Chat: 1. Enter the room where you want to receive notifications from GitLab. -1. Open the room dropdown list on the top-left and select **Manage webhooks**. +1. Open the room dropdown list in the upper 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**. diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index d75f10e0e11..596821ba12b 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Harbor container registry integration **(FREE)** +# Harbor **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80999) in GitLab 14.9. diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 769a45fc6ff..57947e21736 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -90,7 +90,7 @@ You can configure a project webhook to listen for specific events like pushes, issues, or merge requests. When the webhook is triggered, GitLab sends a POST request with data to a specified webhook URL. -Learn more [about webhooks](webhooks.md). +For more information, see [Webhooks](webhooks.md). ## Push hooks limit @@ -104,7 +104,7 @@ You can change the number of supported branches or tags by changing the ## Troubleshooting integrations -Some integrations use hooks to integrate with external applications. To confirm which ones use integration hooks, see the [available integrations](#available-integrations). Learn more about [troubleshooting integration hooks](webhooks.md#troubleshoot-webhooks). +Some integrations use hooks to integrate with external applications. To confirm which ones use integration hooks, see the [available integrations](#available-integrations). For more information, see [Troubleshooting webhooks](webhooks.md#troubleshoot-webhooks). ### `Test Failed. Save Anyway` error diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 70f48e4647a..23525c33e84 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -4,10 +4,10 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# irker IRC Gateway **(FREE)** +# irker (IRC gateway) **(FREE)** GitLab provides a way to push update messages to an irker server. When -configured, pushes to a project trigger the service to send data directly +configured, pushes to a project trigger the integration to send data directly to the irker server. See also the [irker integration API documentation](../../../api/integrations.md). diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 39b89cd87a9..fcc364724b7 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -4,9 +4,9 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Mattermost notifications service **(FREE)** +# Mattermost notifications **(FREE)** -Use the Mattermost notifications service to send notifications for GitLab events +Use the Mattermost notifications integration to send notifications for GitLab events (for example, `issue created`) to Mattermost. You must configure both [Mattermost](#configure-mattermost-to-receive-gitlab-notifications) and [GitLab](#configure-gitlab-to-send-notifications-to-mattermost). @@ -36,6 +36,8 @@ Display name override is not enabled by default, you need to ask your administra ## Configure GitLab to send notifications to Mattermost +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106760) in GitLab 15.9 to limit Mattermost channels to 10 per event. + After the Mattermost instance has an incoming webhook set up, you can set up GitLab to send the notifications: diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index cedb5af144f..fc5d4d3cc80 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -4,9 +4,9 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Microsoft Teams service **(FREE)** +# Microsoft Teams notifications **(FREE)** -You can integrate Microsoft Teams with GitLab, and display notifications about GitLab projects +You can integrate Microsoft Teams notifications with GitLab and display notifications about GitLab projects in Microsoft Teams. To integrate the services, you must: 1. [Configure Microsoft Teams](#configure-microsoft-teams) to enable a webhook diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index 64ee4521ce4..ae1737f8d3f 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -4,10 +4,10 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Mock CI Service **(FREE)** +# Mock CI **(FREE)** NOTE: -This service is only listed if you are in a [development environment](https://gitlab.com/gitlab-org/gitlab-mock-ci-service#setup-mockci-integration)! +This integration only appears if you're in a [development environment](https://gitlab.com/gitlab-org/gitlab-mock-ci-service#setup-mockci-integration). To set up the mock CI service server, respond to the following endpoints diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index 79a00725470..034be8ab3d8 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -4,9 +4,9 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Pivotal Tracker service **(FREE)** +# Pivotal Tracker **(FREE)** -This service adds commit messages as comments to Pivotal Tracker stories. +This integration adds commit messages as comments to Pivotal Tracker stories. Once enabled, commit messages are checked for square brackets containing a hash mark followed by the story ID (for example, `[#555]`). Every story ID found gets the commit comment added to it. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index dfa5a4593d8..cd92e49cada 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -4,7 +4,7 @@ group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Prometheus integration **(FREE)** +# Prometheus **(FREE)** GitLab offers powerful integration with [Prometheus](https://prometheus.io) for monitoring key metrics of your apps, directly in GitLab. diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index 4ef3a847ef1..afefe80271e 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -35,7 +35,7 @@ GitLab retrieves performance data from the configured Prometheus server, and attempts to identifying the presence of known metrics. Once identified, GitLab then needs to be able to map the data to a particular environment. -In order to isolate and only display relevant metrics for a given environment, +To isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do that, GitLab uses the defined queries and fills in the environment specific variables. Typically this involves looking for the diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 0795c110deb..34a6823f007 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -42,7 +42,7 @@ Prometheus needs to be deployed into the cluster and configured properly to gath ## Specifying the Environment -In order to isolate and only display relevant CPU and Memory metrics for a given environment, GitLab needs a method to detect which containers it is running. Because these metrics are tracked at the container level, traditional Kubernetes labels are not available. +To isolate and only display relevant CPU and Memory metrics for a given environment, GitLab needs a method to detect which containers it is running. Because these metrics are tracked at the container level, traditional Kubernetes labels are not available. Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/index.md#predefined-cicd-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index e6f2ac2753a..f8057866592 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -42,6 +42,6 @@ Managing these settings depends on how NGINX Ingress has been deployed. If you h ## Specifying the Environment label -In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. In this case, the `upstream` label must be of the form `<KUBE_NAMESPACE>-<CI_ENVIRONMENT_SLUG>-*`. +To isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. In this case, the `upstream` label must be of the form `<KUBE_NAMESPACE>-<CI_ENVIRONMENT_SLUG>-*`. If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format is used automatically and metrics are detected with no action on your part. diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index e9752d7ce6c..0a399d3481f 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Redmine service **(FREE)** +# Redmine **(FREE)** Use [Redmine](https://www.redmine.org/) as the issue tracker. @@ -37,8 +37,8 @@ For example, this is a configuration for a project named `gitlab-ci`: - New issue URL: `https://redmine.example.com/projects/gitlab-ci/issues/new` 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#configure-project-visibility-features-and-permissions). +For more information about the steps and consequences of disabling GitLab issues, see +[Configure project visibility, features, and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). ## Reference Redmine issues in GitLab diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md index fcc8db7cb87..a34655c8e35 100644 --- a/doc/user/project/integrations/servicenow.md +++ b/doc/user/project/integrations/servicenow.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# ServiceNow integration **(FREE)** +# ServiceNow **(FREE)** ServiceNow offers several integrations to help centralize and automate your management of GitLab workflows. diff --git a/doc/user/project/integrations/shimo.md b/doc/user/project/integrations/shimo.md index 28cb53f8bf6..ca09de06dc6 100644 --- a/doc/user/project/integrations/shimo.md +++ b/doc/user/project/integrations/shimo.md @@ -4,7 +4,14 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Shimo Workspace integration **(FREE)** +<!--- start_remove The following content will be removed on remove_date: '2023-05-22' --> + +# Shimo (deprecated) **(FREE)** + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/377824) in GitLab 15.7 +and is planned for removal in 16.0. +This change is a breaking change. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343386) in GitLab 14.5 with a feature flag named `shimo_integration`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/345356) in GitLab 15.4. @@ -14,11 +21,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Configure settings in GitLab -To enable the Shimo Workspace integration for your group or project: +To enable the Shimo integration for your group or project: 1. On the top bar, select **Main menu** and find your group or project. 1. On the left sidebar, select **Settings > Integrations**. -1. In **Add an integration**, select **Shimo Workspace**. +1. In **Add an integration**, select **Shimo**. 1. In **Enable integration**, ensure the **Active** checkbox is selected. 1. Provide the **Shimo Workspace URL** you want to link to your group or project (for example, `https://shimo.im/space/aBAYV6VvajUP873j`). 1. Select **Save changes**. @@ -32,3 +39,5 @@ To view the Shimo Workspace from your group or project: 1. On the top bar, select **Main menu** and find your group or project. 1. On the left sidebar, select **Shimo**. 1. On the **Shimo Workspace** page, select **Go to Shimo Workspace**. + +<!--- end_remove --> diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 5c1006b9044..09e7189d4f5 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -4,7 +4,13 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Slack notifications integration **(FREE)** +# Slack notifications **(FREE)** + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/372411) on GitLab.com +in GitLab 15.9 and is [planned for removal](https://gitlab.com/groups/gitlab-org/-/epics/8673). +For GitLab.com, use the [GitLab for Slack app](gitlab_slack_application.md) instead. +For self-managed GitLab instances, you can continue to use this feature. The Slack notifications integration enables your GitLab project to send events (such as issue creation) to your existing Slack team as notifications. Setting up @@ -22,6 +28,8 @@ to control GitLab from Slack. Slash commands are configured separately. ## Configure GitLab +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106760) in GitLab 15.9 to limit Slack channels to 10 per event. + 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. 1. Select **Slack notifications**. @@ -58,13 +66,13 @@ The following triggers are available for Slack notifications: | Trigger name | Trigger event | |--------------------------------------------------------------------------|------------------------------------------------------| | **Push** | A push to the repository. | -| **Issue** | An issue is created, updated, or closed. | -| **Incident** | An incident is created, updated, or closed. | -| **Confidential issue** | A confidential issue is created, updated, or closed. | -| **Merge request** | A merge request is created, updated, or merged. | +| **Issue** | An issue is created, closed, or reopened. | +| **Incident** | An incident is created, closed, or reopened. | +| **Confidential issue** | A confidential issue is created, closed, or reopened.| +| **Merge request** | A merge request is created, merged, closed, or reopened.| | **Note** | A comment is added. | -| **Confidential note** | A confidential note is added. | -| **Tag push** | A new tag is pushed to the repository. | +| **Confidential note** | An internal note or comment on a confidential issue is added.| +| **Tag push** | A new tag is pushed to the repository or removed. | | **Pipeline** | A pipeline status changed. | | **Wiki page** | A wiki page is created or updated. | | **Deployment** | A deployment starts or finishes. | diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index f4c789239f3..2563cec2b05 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -6,6 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Slack slash commands **(FREE SELF)** +NOTE: +This feature is only configurable on self-managed GitLab instances. +For GitLab.com, use the [GitLab for Slack app](gitlab_slack_application.md) instead. + If you want to control and view GitLab content while you're working in Slack, you can use Slack slash commands. To use Slack slash commands, you must configure both Slack and GitLab. @@ -13,9 +17,6 @@ To use Slack slash commands, you must configure both Slack and GitLab. GitLab can also send events (for example, `issue created`) to Slack as notifications. The [Slack notifications service](slack.md) is configured separately. -NOTE: -For GitLab.com, use the [GitLab for Slack app](gitlab_slack_application.md) instead. - ## Configure GitLab and Slack Slack slash command integrations diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index 77530b4b417..d465b4e50f0 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -4,9 +4,9 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Unify Circuit service **(FREE)** +# Unify Circuit **(FREE)** -The Unify Circuit service sends notifications from GitLab to a Circuit conversation. +The Unify Circuit integration sends notifications from GitLab to a Circuit conversation. ## Set up Unify Circuit service diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index be4528ba70d..233209966aa 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Webex Teams service **(FREE)** +# Webex Teams **(FREE)** You can configure GitLab to send notifications to a Webex Teams space: diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 0f462ad41b0..53177004888 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -1784,7 +1784,7 @@ Payload example: "links": [ { "id": 1, - "external": true, + "external": true, // deprecated in GitLab 15.9, will be removed in GitLab 16.0. "link_type": "other", "name": "Changelog", "url": "https://example.net/changelog" diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 3d45e947c4c..3d971af5c2a 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -258,15 +258,17 @@ For more information about supported events for Webhooks, go to [Webhook events] ## Delivery headers -> `X-Gitlab-Instance` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31333) in GitLab 15.5. +> - `X-Gitlab-Event-UUID` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329743) in GitLab 14.8. +> - `X-Gitlab-Instance` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31333) in GitLab 15.5. Webhook requests to your endpoint include the following headers: | Header | Description | Example | | ------ | ------ | ------ | | `User-Agent` | In the format `"Gitlab/<VERSION>"`. | `"GitLab/15.5.0-pre"` | -| `X-Gitlab-Event` | Name of the webhook type. Corresponds to [event types](webhook_events.md) but in the format `"<EVENT> Hook"`. | `"Push Hook"` | | `X-Gitlab-Instance` | Hostname of the GitLab instance that sent the webhook. | `"https://gitlab.com"` | +| `X-Gitlab-Event` | Name of the webhook type. Corresponds to [event types](webhook_events.md) but in the format `"<EVENT> Hook"`. | `"Push Hook"` | +| `X-Gitlab-Event-UUID` | Unique ID per webhook that is not recursive. A hook is recursive if triggered by an earlier webhook that hit the GitLab instance. Recursive webhooks have the same value for this header. | `"13792a34-cac6-4fda-95a8-c58e00a3954e"` | ## Troubleshoot webhooks @@ -287,7 +289,7 @@ To view the table: 1. Each [failing webhook](#failing-webhooks) has a badge listing it as: - **Failed to connect** if it is misconfigured, and needs manual intervention to re-enable it. - - **Fails to connect** if it is temporarily disabled and will retry later. + - **Fails to connect** if it is temporarily disabled and is retrying later.  @@ -334,9 +336,9 @@ GitLab expects a response in [10 seconds](../../../user/gitlab_com/index.md#othe > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365535) in GitLab 15.7. Feature flag `webhooks_failed_callout` removed. If a webhook is failing, a banner displays at the top of the edit page explaining -why it is disabled, and when it will be automatically re-enabled. For example: +why it is disabled, and when it is automatically re-enabled. For example: - + In the case of a failed webhook, an error banner is displayed: diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index fb6807aeeb0..a020cc61533 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# YouTrack service **(FREE)** +# YouTrack **(FREE)** JetBrains [YouTrack](https://www.jetbrains.com/youtrack/) is a web-based issue tracking and project management platform. @@ -28,8 +28,8 @@ After you configure and enable YouTrack, a link appears on the GitLab project pages. This link takes you to the appropriate YouTrack project. 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#configure-project-visibility-features-and-permissions). +For more information about the steps and consequences of disabling GitLab issues, see +[Configure project visibility, features, and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). ## Reference YouTrack issues in GitLab diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md index 17727ba22b1..ca25c1214b7 100644 --- a/doc/user/project/integrations/zentao.md +++ b/doc/user/project/integrations/zentao.md @@ -4,7 +4,14 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# ZenTao product integration **(PREMIUM)** +<!--- start_remove The following content will be removed on remove_date: '2023-05-22' --> + +# ZenTao (deprecated) **(PREMIUM)** + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/377825) in GitLab 15.7 +and is planned for removal in 16.0. +This change is a breaking change. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338178) in GitLab 14.5. @@ -47,3 +54,5 @@ Complete these steps in GitLab: 1. To verify the ZenTao connection is working, select **Test settings**. 1. Select **Save changes**. + +<!--- end_remove --> diff --git a/doc/user/project/issues/create_issues.md b/doc/user/project/issues/create_issues.md index 3c2e20c1250..5ebb2fc2e1c 100644 --- a/doc/user/project/issues/create_issues.md +++ b/doc/user/project/issues/create_issues.md @@ -31,7 +31,7 @@ To create an issue: 1. On the top bar, select **Main menu > Projects** and find your project. 1. Either: - - On the left sidebar, select **Issues**, and then, in the top right corner, select **New issue**. + - On the left sidebar, select **Issues**, and then, in the upper-right corner, select **New issue**. - On the top bar, select the plus sign (**{plus-square}**) and then, under **This project**, select **New issue**. @@ -53,7 +53,7 @@ To create an issue from a group: 1. On the top bar, select **Main menu > Groups** and find your group. 1. On the left sidebar, select **Issues**. -1. In the top right corner, select **Select project to create issue**. +1. In the upper-right corner, select **Select project to create issue**. 1. Select the project you'd like to create an issue for. The button now reflects the selected project. 1. Select **New issue in `<project name>`**. @@ -127,7 +127,7 @@ You can send an email to create an issue in a project on the project's Prerequisites: - Your GitLab instance must have [incoming email](../../../administration/incoming_email.md) - configured. + configured with [email sub-addressing or catch-all mailbox](../../../administration/incoming_email.md#requirements). - There must be at least one issue in the issue list. - You must have at least the Guest role for the project. @@ -165,10 +165,10 @@ HTML page to create issues with certain fields prefilled. | Field | URL parameter | Notes | | -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| Title | `issue[title]` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | +| Title | `issue[title]` | Must be [URL-encoded](../../../api/rest/index.md#namespaced-path-encoding). | | Issue type | `issue[issue_type]` | Either `incident` or `issue`. | -| Description template | `issuable_template` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | -| Description | `issue[description]` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). If used in combination with `issuable_template` or a [default issue template](../description_templates.md#set-a-default-template-for-merge-requests-and-issues), the `issue[description]` value is appended to the template. | +| Description template | `issuable_template` | Must be [URL-encoded](../../../api/rest/index.md#namespaced-path-encoding). | +| Description | `issue[description]` | Must be [URL-encoded](../../../api/rest/index.md#namespaced-path-encoding). If used in combination with `issuable_template` or a [default issue template](../description_templates.md#set-a-default-template-for-merge-requests-and-issues), the `issue[description]` value is appended to the template. | | Confidential | `issue[confidential]` | If `true`, the issue is marked as confidential. | | Relate to… | `add_related_issue` | A numeric issue ID. If present, the issue form shows a [**Relate to…** checkbox](#from-another-issue-or-incident) to optionally link the new issue to the specified existing issue. | diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index 0b5605bb767..52da1acd32a 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -24,6 +24,13 @@ add `#xxx` to the commit message, where `xxx` is the issue number. git commit -m "this is my commit message. Ref #xxx" ``` +Since commit messages cannot usually begin with a `#` character, you may use +the alternative `GL-xxx` notation as well: + +```shell +git commit -m "GL-xxx: this is my commit message" +``` + If they are in different projects, but in the same group, add `projectname#xxx` to the commit message. diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 83265d3e954..9b131372672 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -15,9 +15,6 @@ notification email address as an attachment. collected from issues into a **[comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values)** (CSV) file, which stores tabular data in plain text. -> _CSVs are a way of getting data from one program to another where one -program cannot read the other ones normal output._ [Ref](https://www.quora.com/What-is-a-CSV-file-and-its-uses) - <!-- vale gitlab.Spelling = NO --> CSV files can be used with any plotter or spreadsheet-based program, such as diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index d01f22d03c9..8a6683a55b5 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -36,7 +36,7 @@ To import issues: 1. Go to your project's Issues list page. 1. Open the import feature, depending if the project has issues: - - Existing issues are present: Select the import icon at the top right, next to **Edit issues**. + - Existing issues are present: Select the import icon in the upper right, next to **Edit issues**. - Project has no issues: Select **Import CSV** in the middle of the page. 1. Select the file you want to import, and then select **Import issues**. @@ -50,7 +50,7 @@ To import issues, GitLab requires CSV files have a specific format: | Element | Format | |------------------------|--------| | header row | CSV files must include the following headers: `title` and `description`. The case of the headers does not matter. | -| columns | Data from columns beyond `title` and `description` are not imported. | +| columns | Data from columns outside of `title`, `description`, and `due_date` are not imported. | | separators | The column separator is detected from the header row. Supported separator characters are commas (`,`), semicolons (`;`), and tabs (`\t`). The row separator can be either `CRLF` or `LF`. | | double-quote character | The double-quote (`"`) character is used to quote fields, enabling the use of the column separator in a field (see the third line in the sample CSV data below). To insert a double-quote (`"`) in a quoted field use two double-quote characters in succession (`""`). | | data rows | After the header row, following rows must use the same column order. The issue title is required, but the description is optional. | @@ -58,12 +58,16 @@ To import issues, GitLab requires CSV files have a specific format: If you have special characters (for example, `,` or `\n`) or multiple lines in a field (for example, when using [quick actions](../quick_actions.md)), surround the characters with double quotes (`"`). -When using [quick actions](../quick_actions.md), each action must be on a separate line. +Also when using [quick actions](../quick_actions.md): + +- Each action must be on a separate line. +- For quick actions like `/label` and `/milestone`, the label or milestone must already exist in the project. +- The user you assign the issue to must be a member of the project. Sample CSV data: ```plaintext -title,description,due date +title,description,due_date My Issue Title,My Issue Description,2022-06-28 Another Title,"A description, with a comma", "One More Title","One More Description", diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 27d935d0ed1..f43f87119a6 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -92,12 +92,12 @@ The design you selected opens. You can then [zoom in](#zoom-in-on-a-design) on i When viewing a design, you can move to other designs. To do so, either: -- In the top-right corner, select **Go to previous design** (**{chevron-lg-left}**) or **Go to next design** (**{chevron-lg-right}**). +- In the upper-right corner, select **Go to previous design** (**{chevron-lg-left}**) or **Go to next design** (**{chevron-lg-right}**). - Press <kbd>Left</kbd> or <kbd>Right</kbd> on your keyboard. To return to the issue view, either: -- In the top-left corner, select the close icon (**{close}**). +- In the upper-left corner, select the close icon (**{close}**). - Press <kbd>Esc</kbd> on your keyboard. When a design is added, a green icon (**{plus-square}**) is displayed on the image @@ -186,7 +186,7 @@ Prerequisites: To archive a single design: 1. Select the design to view it enlarged. -1. In the top right corner, select **Archive design** (**{archive}**). +1. In the upper-right corner, select **Archive design** (**{archive}**). 1. Select **Archive designs**. To archive multiple designs at once: @@ -235,7 +235,7 @@ When you're done discussing part of a design, you can resolve the discussion thr To mark a thread as resolved or unresolved, either: -- In the top-right corner of the first comment of the discussion, select **Resolve thread** or **Unresolve thread** (**{check-circle}**). +- In the upper-right corner of the first comment of the discussion, select **Resolve thread** or **Unresolve thread** (**{check-circle}**). - Add a new comment to the thread and select or clear the **Resolve thread** checkbox. Resolving a discussion thread also marks any pending [to-do items](../../todos.md) related to notes diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index a5399b70c8f..953d08ea903 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -22,6 +22,28 @@ To edit an issue: 1. Edit the available fields. 1. Select **Save changes**. +### Remove a task list item + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377307) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `work_items_mvc`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. +To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `work_items_mvc`. +On GitLab.com, this feature is not available. +The feature is not ready for production use. + +Prerequisites: + +- You must have at least the Reporter role for the project, or be the author or assignee of the issue. + +In an issue description with task list items: + +1. Hover over a task list item and select the options menu (**{ellipsis_v}**). +1. Select **Delete**. + +The task list item is removed from the issue description. +Any nested task list items are moved up a nested level. + ## Bulk edit issues from a project > - Assigning epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. @@ -150,7 +172,7 @@ To do it: issues.each do |issue| if issue.state != "closed" && issue.moved_to.nil? - Issues::MoveService.new(project: project, current_user: admin_user).execute(issue, target_project) + Issues::MoveService.new(container: project, current_user: admin_user).execute(issue, target_project) else puts "issue with id: #{issue.id} and title: #{issue.title} was not moved" end @@ -174,10 +196,10 @@ Prerequisites: To reorder list items, when viewing an issue: -1. Hover over the list item row to make the drag icon (**{drag-vertical}**) visible. -1. Select and hold the drag icon. +1. Hover over the list item row to make the grip icon (**{grip}**) visible. +1. Select and hold the grip icon. 1. Drag the row to the new position in the list. -1. Release the drag icon. +1. Release the grip icon. ## Close an issue @@ -204,9 +226,11 @@ A reopened issue is no different from any other open issue. ### Closing issues automatically -You can close issues automatically by using certain words in the commit message or MR description. +You can close issues automatically by using certain words, called a _closing pattern_, +in a commit message or merge request description. Administrators of self-managed GitLab instances +can [change the default closing pattern](../../../administration/issue_closing_pattern.md). -If a commit message or merge request description contains text matching the [defined pattern](#default-closing-pattern), +If a commit message or merge request description contains text matching the [closing pattern](#default-closing-pattern), all issues referenced in the matched text are closed when either: - The commit is pushed to a project's [**default** branch](../repository/branches/default.md). @@ -218,7 +242,7 @@ description: - Issues `#4` and `#6` are closed automatically when the MR is merged. - Issue `#5` is marked as a [related issue](related_issues.md), but it's not closed automatically. -Alternatively, when you [create a merge request from an issue](../merge_requests/getting_started.md#merge-requests-to-close-issues), +Alternatively, when you [create a merge request from an issue](../merge_requests/creating_merge_requests.md#from-an-issue), it inherits the issue's milestone and labels. For performance reasons, automatic issue closing is disabled for the very first @@ -382,7 +406,7 @@ To view all issues assigned to you: Or: - To use a [keyboard shortcut](../../shortcuts.md), press <kbd>Shift</kbd> + <kbd>i</kbd>. -- On the top bar, on the top right, select **{issues}** **Issues**. +- On the top bar, in the upper right, select **{issues}** **Issues**. ## Filter the list of issues @@ -413,11 +437,12 @@ GitLab displays the results on-screen, but you can also > - OR filtering for author and assignee was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23532) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default. > - OR filtering for label was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23532) in GitLab 15.8 [with a flag](../../../administration/feature_flags.md) named `or_issuable_queries`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104292) in GitLab 15.9. FLAG: -On self-managed GitLab, by default this feature is not available. -To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `or_issuable_queries`. -The feature is not ready for production use. +On self-managed GitLab, by default this feature is available. +To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `or_issuable_queries`. +On GitLab.com, this feature is available. When this feature is enabled, you can use the OR operator (**is one of: `||`**) when you [filter the list of issues](#filter-the-list-of-issues) by: @@ -460,7 +485,7 @@ Read more about issue references in [GitLab-Flavored Markdown](../../markdown.md You can create a comment in an issue by sending an email. Sending an email to this address creates a comment that contains the email body. -To learn more about creating comments by sending an email and the necessary configuration, see +For more information about creating comments by sending an email and the necessary configuration, see [Reply to a comment by sending email](../../discussions/index.md#reply-to-a-comment-by-sending-email). To copy the issue's email address: diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 1a8f19b80ba..43acaaf9c2f 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -15,7 +15,7 @@ The relationship only shows up in the UI if the user can see both issues. When y issue that has open blockers, a warning is displayed. NOTE: -To manage linked issues through our API, visit the [issue links API documentation](../../../api/issue_links.md). +To manage linked issues through our API, see [Issue links API](../../../api/issue_links.md). ## Add a linked issue @@ -57,7 +57,7 @@ them categorized so their relationships can be better understood visually.  You can also add a linked issue from a commit message or the description in another issue or MR. -[Learn more about crosslinking issues](crosslinking_issues.md). +For more information, see [Crosslinking issues](crosslinking_issues.md). ## Remove a linked issue diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 0b0184db14c..c7d45b0bd15 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -10,12 +10,16 @@ Members are the users and groups who have access to your project. Each member gets a role, which determines what they can do in the project. -Project members can: +## Membership types -1. Be [direct members](#add-users-to-a-project) of the project. -1. [Inherit membership](#inherited-membership) of the project from the project's group. -1. Be a member of a group that was [shared](share_project_with_groups.md) with the project. -1. Be a member of a group that was [shared with the project's group](../../group/manage.md#share-a-group-with-another-group). +Users can become members of a group or project in different ways, which define their membership type. + +| Membership type | Membership process | +| --------------------------------------------- | ------------------ | +| [Direct](#add-users-to-a-project) | The user is added directly to the current group or project. | +| [Inherited](#inherited-membership) | The user is a member of an ancestor group or project that is added to the current group or project. | +| [Direct shared](share_project_with_groups.md) | The user is a member of a group or project that is shared into the current group or project. | +| [Inherited shared](../../group/manage.md#share-a-group-with-another-group) | The user is a member of an ancestor of a group or project that is shared into the current group or project. | ```mermaid flowchart RL @@ -41,13 +45,71 @@ flowchart RL G-->|Group C shared with Project A|E ``` +### Inherited membership + +When your project belongs to a group, project members inherit their role +from the group. + + + +In this example: + +- Three members have access to the project. +- **User 0** is a Reporter and has inherited their role in the project from the **demo** group, + which contains the project. +- **User 1** belongs directly to the project. In the **Source** column, they are listed + as a **Direct member**. +- **Administrator** is the [Owner](../../permissions.md) and member of all groups. + They have inherited their role in the project from the **demo** group. + +If a user is: + +- A direct member of a project, the **Expiration** and **Max role** fields can be updated directly on the project. +- An inherited member from a parent group, the **Expiration** and **Max role** fields must be updated on the parent group. + +### Membership and visibility rights + +Depending on their membership type, members of groups or projects are granted different visibility levels +and rights into the group or project. + +| Action | Direct group member | Inherited group member | Direct shared group member | Inherited shared group member | +| --- | ------------------- | ---------------------- | -------------------------- | ----------------------------- | +| Generate boards | ✓ | ✓ | ✓ | ✓ | +| View issues of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | +| View labels of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | +| View milestones of groups higher in the hierarchy | ✓ | ✓ | ✓ | ✓ | +| Be shared into other groups | ✓ | | | | +| Be shared into other projects | ✓ | ✓ | | | +| Share the group with other members | ✓ | | | | + +In the following example, `User` is a: + +- Direct member of `subgroup`. +- Inherited member of `subsubgroup`. +- Indirect member of `subgroup-2` and `subgroup-3`. +- Indirect inherited member of `subsubgroup-2` and `subsubgroup-3`. + +```mermaid +graph TD + classDef user stroke:green,color:green; + + root --> subgroup --> subsubgroup + root-2 --> subgroup-2 --> subsubgroup-2 + root-3 --> subgroup-3 --> subsubgroup-3 + subgroup -. shared .-> subgroup-2 -. shared .-> subgroup-3 + + User-. member .- subgroup + + class User user +``` + ## Add users to a project > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal window [with a flag](../../feature_flags.md). Disabled by default. > - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 14.8. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. -Add users to a project so they become members and have permission +Add users to a project so they become direct members and have permission to perform actions. Prerequisite: @@ -59,7 +121,12 @@ To add a user to a project: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Members**. 1. Select **Invite members**. -1. Enter an email address and select a [role](../../permissions.md). +1. If the user: + + - Has a GitLab account, enter their username. + - Doesn't have a GitLab account, enter their email address. + +1. Select a [role](../../permissions.md). 1. Optional. Select an **Access expiration date**. From that date onward, the user can no longer access the project. @@ -69,16 +136,12 @@ To add a user to a project: to extend their own time in the Maintainer role. 1. Select **Invite**. + If you invited the user using their: -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. - -If the invitation is not accepted, GitLab sends reminder emails two, -five, and ten days later. Unaccepted invites are automatically -deleted after 90 days. - -If the user does not have a GitLab account, they are prompted to create an account -using the email address the invitation was sent to. + - GitLab username, they are added to the members list. + - Email address, an invitation is sent to their email address, and they are prompted to create an account. + If the invitation is not accepted, GitLab sends reminder emails two, five, and ten days later. + Unaccepted invites are automatically deleted after 90 days. ### Which roles you can assign @@ -97,14 +160,14 @@ The Owner [role](../../permissions.md#project-members-permissions) can be added > - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 14.8. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. -When you add a group to a project, each user in the group gets access to the project. -Each user's access is based on: +When you add a group to a project, every group member (direct or inherited) gets access to the project. +Each member's access is based on the: -- The role they're assigned in the group. -- The maximum role you choose when you invite the group. +- Role they're assigned in the group. +- Maximum role you choose when you invite the group. -If a user has a group role with fewer permissions than the maximum project role, the user keeps the permissions of their group role. -For example, if you add a user with the Guest role to a project with a maximum role of Maintainer, the user has only the permissions of the Guest role. +If a group member has a role in the group with fewer permissions than the maximum project role, the member keeps the permissions of their group role. +For example, if you add a member with the Guest role to a project with a maximum role of Maintainer, the member has only the permissions of the Guest role in the project. Prerequisites: @@ -128,10 +191,10 @@ The **Members** tab shows: - Members who are directly assigned to the project. - If the project was created in a group [namespace](../../namespace/index.md), members of that group. -## Import users from another project +## Import members 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. +You can import another project's members to your own project. +Imported project members retain the same permissions as the project you import them from. Prerequisite: @@ -147,37 +210,16 @@ To import users: After the success message displays, refresh the page to view the new members. -## Inherited membership - -When your project belongs to a group, group members inherit their role -from the group. - - - -In this example: - -- Three members have access to the project. -- **User 0** is a Reporter and has inherited their role from the **demo** group, - which contains the project. -- **User 1** belongs directly to the project. In the **Source** column, they are listed - as a **Direct member**. -- **Administrator** is the [Owner](../../permissions.md) and member of all groups. - They have inherited their role from the **demo** group. - -If a user is a: - -- Direct member of a project, the **Expiration** and **Max role** fields can be updated directly on the project. -- Inherited member from a parent group, the **Expiration** and **Max role** fields must be updated on the parent group. - ## Remove a member from a project -If a user is a direct member of a project, you can remove them. -If membership is inherited from a parent group, then the member can be removed only from the parent -group itself. +If a user is: + +- A direct member of a project, you can remove them directly from the project. +- An inherited member from a parent group, you can only remove them from the parent group itself. Prerequisites: -- To remove direct members with the: +- To remove direct members that have the: - Maintainer, Developer, Reporter, or Guest role, you must have the Maintainer role. - Owner role, you must have the Owner role. - Optional. Unassign the member from all issues and merge requests that @@ -191,7 +233,7 @@ To remove a member from a project: 1. Optional. In the confirmation box, select the **Also unassign this user from related issues and merge requests** checkbox. 1. To prevent leaks of sensitive information from private projects, verify the - user has not forked the private repository or created webhooks. Existing forks continue to receive + member has not forked the private repository or created webhooks. Existing forks continue to receive changes from the upstream project, and webhooks continue to receive updates. You may also want to configure your project to prevent projects in a group [from being forked outside their group](../../group/access_and_permissions.md#prevent-project-forking-outside-group). diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index d1ee42f723d..4dda68a6d08 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -4,60 +4,41 @@ group: Organization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Share projects with other groups **(FREE)** +# Share a project with a group **(FREE)** -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. +When you want a group to have access to your project, +you can invite [a group](../../group/index.md) to the project. +The group's members get access to the project, which becomes a *shared project*. -For example, if `Project A` belongs to `Group 1`, the members of `Group 1` have access to the project. -If `Project A` already belongs to another `Group 2`, the owner of `Group 2` can share `Project A` -with `Group 1`, so that both members of `Group 1` and `Group 2` have access to the project. +## Example -When a project is shared with a group: +For a project that was created by `Group 1`: -- All group members, including members of subgroups or projects that belong to the group, - are assigned the same role in the project. - Each member's role is displayed in **Project information > Members**, in the **Max role** column. - When sharing a project with a group, a user's assigned **Max role** is the lowest - of either: +- The members of `Group 1` have access to the project. +- The owner of `Group 1` can invite `Group 2` to the project. +This way, members of both `Group 1` and `Group 2` have access to the shared project. - - The role assigned in the group membership. - - The maximum role selected when sharing the project with the group. +## Prerequisites - Assigning a higher maximum role to the group doesn't give group users higher roles than - the roles already assigned to them in the group. -- The group is listed in the **Groups** tab. -- The project is listed on the group dashboard. +To invite a group to a project, you must be at least one of the following: -Be aware of the restrictions that apply when you share projects with: +- Explicitly defined as a [member](index.md) of the project. +- Explicitly defined as a member of a group or subgroup that has access to the project. +- An administrator. -- [Groups with a more restrictive visibility level](#share-projects-with-groups-with-a-more-restrictive-visibility-level). -- [Restricted sharing](#prevent-project-sharing). +In addition: -## Share projects with groups with a more restrictive visibility level +- The group you're inviting must have a more restrictive + [visibility level](../../public_access.md#project-and-group-visibility) + than the project. For example, you can invite: + - A private group to a public project. + - An internal group to a public project. + - A private group to an internal project. -You can share projects only down the group's organization structure. -This means you can share a project with a group that has a more restrictive -[visibility level](../../public_access.md#project-and-group-visibility) than the project, -but not with a group that has a less restrictive visibility level. - -For example, you can share: - -- A public project with a private group. -- A public project with an internal group. -- An internal project with a private group. - -This restriction applies to subgroups as well. For example, `group/subgroup01/project`: - -- Can't be shared with `group`. -- Can be shared with `group/subgroup02` or `group/subgroup01/subgroup03`. - -When you share a project with a group that has a more restrictive visibility level than the project: - -- The group name is visible to all users that can view the project members page. -- Owners of the project have access to members of the group when they mention them in issues or merge requests. -- Project members who are direct or indirect members of the group can see -group members listed in addition to members of the project. +- The group or subgroup must be in the project's [namespace](../../namespace/index.md). + For example, a project in the namespace `group/subgroup01/project`: + - Can be shared with `group/subgroup02` or `group/subgroup01/subgroup03`. + - Cannot be shared with `group`. ## Share a project with a group @@ -68,22 +49,57 @@ group members listed in addition to members of the project. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. -You can share a project only with groups: +You can share a project with a group by inviting that group to the project. -- Where you have an explicitly defined [membership](index.md). -- That contain a nested subgroup or project you have an explicitly defined role for. -- You are an administrator of. - -To share a project with a group: +To invite a group to a project: 1. On the top bar, select **Main menu > Projects** and find your project. -1. In the left navigation menu, select **Project information > Members**. +1. On the left sidebar, select **Project information > Members**. 1. Select **Invite a group**. 1. **Select a group** you want to add to the project. 1. **Select a role** you want to assign to the group. 1. Optional. Select an **Access expiration date**. 1. Select **Invite**. -## Prevent project sharing +All group members, members of subgroups, and members of other projects the group has access to +are given access to the project. In addition: + +- On the group's page, the project is listed on the **Shared projects** tab. +- On the project's **Members** page, the group is listed on the **Groups** tab. +- Each user is assigned a maximum role. + +## Maximum role + +When multiple groups contain the same members, and the groups +have access to the same project, the group members are +given the most restrictive role for the project. + +This most restrictive role is called the *maximum role*, or **Max role**. + +The member's **Max role** is the more restrictive of: + +- The role the user is assigned for the group. +- The role you chose when you invited the group to the project. + +### View the member's Max role + +To view the maximum role assigned to a member: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Members**. +1. In the **Max role** column, view the user's maximum assigned role. + +## View a group's shared projects + +In a group, a shared project is a project to which the group members gained access through the [**Invite group**](#share-a-project-with-a-group) action. + +To view a group's shared projects: + +1. On the top bar, select **Main menu > Group** and find your group. +1. On the group page, select the **Shared projects** tab. + +A list of shared projects is displayed. + +## Related topics -For more information, see [Prevent a project from being shared with groups](../../group/access_and_permissions.md#prevent-a-project-from-being-shared-with-groups). +- [Prevent a project from being shared with groups](../../group/access_and_permissions.md#prevent-a-project-from-being-shared-with-groups). diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index d3d95a5bf61..0729e024df4 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Collaborate on merge requests across forks **(FREE)** -When you open a merge request from your fork, you can allow upstream +When you open a merge request from your [fork](../repository/forking_workflow.md), you can allow upstream members to collaborate with you on your branch. When you enable this option, members who have permission to merge to the target branch get permission to write to the merge request's source branch. @@ -15,7 +15,7 @@ The members of the upstream project can then make small fixes or rebase branches before merging. This feature is available for merge requests across forked projects that are -publicly accessible. +[publicly accessible](../../public_access.md). ## Allow commits from upstream members diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 92ff78082e3..21e2055cb61 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -8,8 +8,6 @@ disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/appro # Merge request approvals **(FREE)** -> Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in GitLab 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. While [GitLab Free](https://about.gitlab.com/pricing/) allows all users with Developer or greater [permissions](../../../permissions.md) to diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 51f7254bfda..0a5e7c29860 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -254,6 +254,15 @@ the API. For more information about this validation error, read [issue 285129](https://gitlab.com/gitlab-org/gitlab/-/issues/285129). +### Groups need explicit or inherited Developer role on a project + +A group created to handle approvals may be created in a different area of the +project hierarchy than the project requiring review. If this happens, the approvals group +isn't recognized as a valid Code Owner for the project, nor does it display in the +project's **Approvals** list. To fix this problem, add the approval group as a shared group +high enough in the shared hierarchy so the project requiring review inherits this +group of users. + ## Security Approvals **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357021) in GitLab 15.0. diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index a8acab3898b..1ab564c108b 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -87,8 +87,7 @@ to a merge request may or may not be able to approve the work: [code owners](../../code_owners.md) who commit to a merge request cannot approve it, when the merge request affects 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. +For more information, see the [official Git documentation](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History). ## Prevent editing approval rules in merge requests @@ -121,13 +120,17 @@ permission enables an electronic signature for approvals, such as the one define ## Remove all approvals when commits are added to the source branch -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: +By default, an approval on a merge request is removed when you add more changes +after the approval. In GitLab Premium and higher tiers, to keep existing approvals +after more changes are added to the merge request: 1. On the left sidebar, select **Settings > Merge requests**. 1. In the **Merge request approvals** section, scroll to **Approval settings** and - select **Remove all approvals**. + clear the **Remove all approvals** checkbox. + + NOTE: + This setting is not available in GitLab Free. + 1. Select **Save changes**. Approvals aren't removed when a merge request is [rebased from the UI](../methods/index.md#rebasing-in-semi-linear-merge-methods) @@ -155,7 +158,7 @@ To do this: You can require specific approvals if a merge request would result in a decline in code test coverage. -To learn more, see [Coverage check approval rule](../../../../ci/pipelines/settings.md#coverage-check-approval-rule). +For more information, see [Coverage check approval rule](../../../../ci/pipelines/settings.md#coverage-check-approval-rule). ## Settings cascading diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index 07ee2ef90c4..8f6b1a32424 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -57,7 +57,7 @@ clear your browser's cookies or change this behavior again. To view one file at a time for all of your merge requests: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Preferences**. 1. Scroll to the **Behavior** section and select the **Show one file at a time on merge request's Changes tab** checkbox. 1. Select **Save changes**. diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 388c6fb55ac..9fac872ac4b 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -55,7 +55,7 @@ by the merge request: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests**, and find your merge request. 1. Scroll to the merge request reports section, and find the **Merged by** report. -1. In the top right, select **Cherry-pick**: +1. In the upper right, select **Cherry-pick**:  1. In the modal window, select the project and branch to cherry-pick into. @@ -87,7 +87,7 @@ list of commits included in a merge request: 1. On the left sidebar, select **Merge requests**, and find your merge request. 1. In the merge request's secondary menu, select **Commits** to display the commit details page. 1. Select the title of the commit you want to cherry-pick. -1. In the top right corner, select **Options > Cherry-pick** to show the cherry-pick modal. +1. In the upper-right corner, select **Options > Cherry-pick** to show the cherry-pick modal. 1. In the modal window, select the project and branch to cherry-pick into. 1. Optional. Select **Start a new merge request with these changes**. 1. Select **Cherry-pick**. @@ -101,7 +101,7 @@ when you view that file in your project's Git repository: 1. On the left sidebar, select **Repository > Files** and go to the file changed by the commit. 1. Select **History**, then select the title of the commit you want to cherry-pick. -1. In the top right corner, select **Options > Cherry-pick** to show the cherry-pick modal. +1. In the upper-right corner, select **Options > Cherry-pick** to show the cherry-pick modal. 1. In the modal window, select the project and branch to cherry-pick into. 1. Optional. Select **Start a new merge request with these changes**. 1. Select **Cherry-pick**. @@ -115,7 +115,7 @@ You can cherry-pick merge requests from the same project, or forks of the same project, from the GitLab user interface: 1. In the merge request's secondary menu, select **Commits** to display the commit details page. -1. In the top right corner, select **Options > Cherry-pick** to show the cherry-pick modal. +1. In the upper-right corner, select **Options > Cherry-pick** to show the cherry-pick modal. 1. In **Pick into project** and **Pick into branch**, select the destination project and branch:  1. Optional. Select **Start a new merge request** if you're ready to create a merge request. diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index a14d8bddd24..f8c24e4067b 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -89,7 +89,7 @@ Commit message templates support these variables: | `%{approved_by}` | Line-separated list of the merge request approvers in a `Approved-by` Git commit trailer format. | `Approved-by: Sidney Jones <sjones@example.com>` <br> `Approved-by: Zhang Wei <zwei@example.com>` | | `%{merged_by}` | User who merged the merge request. | `Alex Garcia <agarcia@example.com>` | | `%{co_authored_by}` | Names and emails of commit authors in a `Co-authored-by` Git commit trailer format. Limited to authors of 100 most recent commits in merge request. | `Co-authored-by: Zane Doe <zdoe@example.com>` <br> `Co-authored-by: Blake Smith <bsmith@example.com>` | -| `%{all_commits}` | Messages from all commits in the merge request. Limited to 100 most recent commits. Skips commit bodies exceeding 100KiB and merge commit messages. | `* Feature introduced` <br><br> `This commit implements feature` <br> `Changelog:added` <br><br> `* Bug fixed` <br><br> `* Documentation improved` <br><br>`This commit introduced better docs.`| +| `%{all_commits}` | Messages from all commits in the merge request. Limited to 100 most recent commits. Skips commit bodies exceeding 100 KiB and merge commit messages. | `* Feature introduced` <br><br> `This commit implements feature` <br> `Changelog:added` <br><br> `* Bug fixed` <br><br> `* Documentation improved` <br><br>`This commit introduced better docs.`| Any line containing only an empty variable is removed. If the line to be removed is both preceded and followed by an empty line, the preceding empty line is also removed. diff --git a/doc/user/project/merge_requests/conflicts.md b/doc/user/project/merge_requests/conflicts.md index 6063d64a721..932eec5e631 100644 --- a/doc/user/project/merge_requests/conflicts.md +++ b/doc/user/project/merge_requests/conflicts.md @@ -59,7 +59,8 @@ in the user interface, and you can also resolve conflicts locally through the co To resolve less-complex conflicts from the GitLab user interface: -1. Go to your merge request. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and find the merge request. 1. Select **Overview**, and scroll to the merge request reports section. 1. Find the merge conflicts message, and select **Resolve conflicts**. GitLab shows a list of files with merge conflicts. The conflicts are @@ -83,7 +84,8 @@ Some merge conflicts are more complex, requiring you to manually modify lines to resolve their conflicts. Use the merge conflict resolution editor to resolve complex conflicts in the GitLab interface: -1. Go to your merge request. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and find the merge request. 1. Select **Overview**, and scroll to the merge request reports section. 1. Find the merge conflicts message, and select **Resolve conflicts**. GitLab shows a list of files with merge conflicts. diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 542edc11c44..875312bbb7c 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -19,7 +19,7 @@ You can create a merge request from the list of merge requests. 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left menu, select **Merge requests**. -1. In the top right, select **New merge request**. +1. In the upper right, select **New merge request**. 1. Select a source and target branch and then **Compare branches and continue**. 1. Fill out the fields and select **Create merge request**. @@ -35,14 +35,14 @@ If your development workflow requires an issue for every merge request, you can create a branch directly from the issue to speed the process up. The new branch, and later its merge request, are marked as related to this issue. After merging the merge request, the issue is closed automatically, unless [automatic issue closing is disabled](../issues/managing_issues.md#disable-automatic-issue-closing). -You can see a **Create merge request** dropdown below the issue description. +You can see a **Create merge request** dropdown list below the issue description. NOTE: In GitLab 14.8 and later, selecting **Create merge request** [redirects to the merge request creation form](https://gitlab.com/gitlab-org/gitlab/-/issues/349566) instead of immediately creating the merge request. -The **Create merge request** button doesn't display if: +**Create merge request** doesn't display if: - A branch with the same name already exists. - A merge request already exists for this branch. @@ -54,15 +54,14 @@ To make this button appear, one possible workaround is to After removal, the fork relationship cannot be restored. This project can no longer be able to receive or send merge requests to the source project, or other forks. -This dropdown contains the options **Create merge request and branch** and **Create branch**. +The dropdown list contains the options **Create merge request and branch** and **Create branch**. After selecting one of these options, a new branch or branch and merge request is created based on your project's [default branch](../repository/branches/default.md). -The branch name is based on an internal ID, and the issue title. The example -screenshot above creates a branch named -`2-make-static-site-auto-deploy-and-serve`. +The branch name is based on your project's branch name template. The default template +is `%{id}-%{title}`. Supported variables for branch name templates are `%{id}` and `%{title}`. -When you select the **Create branch** button in an empty +When you select **Create branch** in an empty repository project, GitLab performs these actions: - Creates a default branch. @@ -82,7 +81,7 @@ merge request is merged. You can create a merge request when you add, edit, or upload a file to a repository. -1. Add, edit, or upload a file to the repository. +1. [Add, edit, or upload](../repository/web_editor.md) a file to the repository. 1. In the **Commit message**, enter a reason for the commit. 1. Select the **Target branch** or create a new branch by typing the name (without spaces, capital letters, or special chars). 1. Select the **Start a new merge request with these changes** checkbox or toggle. This checkbox or toggle is visible only @@ -172,7 +171,7 @@ To create a merge request by sending an email: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left menu, select **Merge requests**. -1. In the top right, select **Email a new merge request to this project**. +1. In the upper right, select **Email a new merge request to this project**. An email address is displayed. Copy this address. Ensure you keep this address private. 1. Open an email and compose a message with the following information: diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index 662189c5e40..9028a9411ea 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -14,7 +14,7 @@ To export merge requests to a CSV file: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests** . -1. Add any searches or filters. This can help you keep the size of the CSV file under the 15MB limit. The limit ensures +1. Add any searches or filters. This can help you keep the size of the CSV file under the 15 MB limit. The limit ensures the file can be emailed to a variety of email providers. 1. Select **Export as CSV** (**{export}**). 1. Confirm the correct number of merge requests are to be exported. diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index 0bc9b337e3b..62820988701 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -21,12 +21,13 @@ the **Merge** button until you remove the **Draft** flag: > - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/228685) all support for using **WIP** in GitLab 14.8. > - **Mark as draft** and **Mark as ready** buttons [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227421) in GitLab 13.5. > `/draft` quick action as a toggle [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92654) in GitLab 15.4. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108073) the draft status to use a checkbox in GitLab 15.8. There are several ways to flag a merge request as a draft: -- **Viewing a merge request**: In the top right corner of the merge request, select **Mark as draft**. +- **Viewing a merge request**: In the upper-right corner of the merge request, select **Mark as draft**. - **Creating or editing a merge request**: Add `[Draft]`, `Draft:` or `(Draft)` to - the beginning of the merge request's title, or select **Start the title with Draft:** + the beginning of the merge request's title, or select **Mark as draft** below the **Title** field. - **Commenting in an existing merge request**: Add the `/draft` [quick action](../quick_actions.md#issues-merge-requests-and-epics) @@ -40,14 +41,14 @@ There are several ways to flag a merge request as a draft: When a merge request is ready to be merged, you can remove the `Draft` flag in several ways: -- **Viewing a merge request**: In the top right corner of the merge request, select **Mark as ready**. +- **Viewing a merge request**: In the upper-right corner of the merge request, select **Mark as ready**. Users with at least the Developer role can also scroll to the bottom of the merge request description and select **Mark as ready**:  - **Editing an existing merge request**: Remove `[Draft]`, `Draft:` or `(Draft)` - from the beginning of the title, or select **Remove the Draft: prefix from the title** + from the beginning of the title, or clear **Mark as draft** below the **Title** field. - **Commenting in an existing merge request**: Add the `/ready` [quick action](../quick_actions.md#issues-merge-requests-and-epics) diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 58750cdf5bc..4125d8e8fdb 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -1,147 +1,11 @@ --- -stage: Create -group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -description: "Getting started with merge requests." +redirect_to: 'index.md' +remove_date: '2023-03-31' --- -# Getting started with merge requests **(FREE)** +This document was moved to [another location](index.md). -A merge request (**MR**) is the basis of GitLab as a tool for code -collaboration and version control. - -When working in a Git-based platform, you can use branching -strategies to collaborate on code. - -A repository is composed by its _default branch_, which contains -the major version of the codebase, from which you create minor -branches, also called _feature branches_, to propose changes to -the codebase without introducing them directly into the major -version of the codebase. - -Branching is especially important when collaborating with others, -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**, -which is essentially a _request_ to merge one branch into another. - -The branch you added your changes into is called _source branch_ -while the branch you request to merge your changes into is -called _target branch_. - -The target branch can be the default or any other branch, depending -on the branching strategies you choose. - -In a merge request, beyond visualizing the differences between the -original content and your proposed changes, you can execute a -[significant number of tasks](#what-you-can-do-with-merge-requests) -before concluding your work and merging the merge request. - -You can watch our [GitLab Flow video](https://www.youtube.com/watch?v=InKNIvky2KE) for -a quick overview of working with merge requests. - -## What you can do with merge requests - -When you start a new merge request, you can immediately include the following -options. You can also add them later by either selecting **Edit** on the merge -request's page at the top-right side, or by using -[keyboard shortcuts for merge requests](../../shortcuts.md#merge-requests): - -- [Assign](index.md#assign-a-user-to-a-merge-request) the merge request to a colleague for review. With [multiple assignees](index.md#assign-multiple-users), 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](approvals/index.md#required-approvals) from your team. -- [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. -- Set the merge request as a [**Draft**](drafts.md) to avoid accidental merges before it is ready. - -After you have created the merge request, you can also: - -- [Discuss](../../discussions/index.md) your implementation with your team in the merge request thread. -- [Perform inline code reviews](reviews/index.md). -- Add [merge request dependencies](dependencies.md) to restrict it to be merged only when other merge requests have been merged. -- Preview continuous integration [pipelines on the merge request widget](widgets.md). -- Preview how your changes look directly on your deployed application with [Review Apps](widgets.md#live-preview-with-review-apps). -- [Allow collaboration on merge requests across forks](allow_collaboration.md). -- 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 options can be set: - -- From the merge request page, with [keyboard shortcuts](../../shortcuts.md#merge-requests). -- When pushing changes from the command line, with [Git push options](../push_options.md). - -See also other [features associated to merge requests](reviews/index.md#associated-features). - -### Reviewer - -WARNING: -Requesting a code review is an important part of contributing code. However, deciding who should review -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 -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 -who may only be involved in one aspect of the merge request, such as a peer review. - -To request a review of a merge request, expand the **Reviewers** select box in -the right-hand sidebar. Search for the users you want to request a review from. -When selected, GitLab creates a [to-do list item](../../todos.md) for each reviewer. - -To learn more, read [Review a merge request](reviews/index.md). - -### Merge requests to close issues - -To create a merge request to close an issue when it's merged, you can either: - -- [Add a note in the MR description](../issues/managing_issues.md#closing-issues-automatically). -- In the issue, select **Create a merge request**. Then, you can either: - - - Create a new branch and [a draft merge request](../merge_requests/drafts.md) - in one action. The branch is named `issuenumber-title` by default, but you can - choose any name, and GitLab verifies that it's not already in use. The merge request - inherits the milestone and labels of the issue, and is set to automatically - close the issue when it is merged. - - Create a [new branch](creating_merge_requests.md#from-an-issue) - only, with its name starting with the issue number. - -If the issue is [confidential](../issues/confidential_issues.md), -you may want to use a different workflow for -[merge requests for confidential issues](confidential.md) -to prevent confidential information from being exposed. - -### Deleting the source branch - -When creating a merge request, select the -**Delete source branch when merge request accepted** option, and the source -branch is deleted when the merge request is merged. To make this option -enabled by default for all new merge requests, enable it in the -[project's settings](../settings/index.md#configure-merge-request-settings-for-a-project). - -This option is also visible in an existing merge request next to -the merge request button and can be selected or cleared before merging. -It is only visible to users with the Maintainer role -in the source project. - -If the user viewing the merge request does not have the correct -permissions to delete the source branch and the source branch -is set for deletion, the merge request widget displays the -**Deletes source branch** text. - - - -## 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 - at once. By doing so, you save CI/CD minutes. -- Delete feature branches on merge or after merging them to keep your repository clean. -- Take one thing at a time and ship the smallest changes possible. By doing so, - reviews are faster and your changes are less prone to errors. -- Do not use capital letters nor special chars in branch names. +<!-- This redirect file can be deleted after <2023-03-31>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 21651fd645c..a633366cc62 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -7,8 +7,9 @@ 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. +To incorporate changes from a source branch to a target branch, you use a *merge request* (MR). + +When you open a merge request, you can visualize and collaborate on the changes before merge. Merge requests include: - A description of the request. @@ -17,7 +18,9 @@ Merge requests include: - A comment section for discussion threads. - The list of commits. -Read more about [how to get started](getting_started.md). +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a quick overview of merge requests, +view [this GitLab Flow video](https://www.youtube.com/watch?v=InKNIvky2KE). ## Create a merge request @@ -62,7 +65,7 @@ or: or: -1. On the top bar, on the top right, select **{merge-request-open}** **Merge requests**. +1. On the top bar, in the upper right, select **{merge-request-open}** **Merge requests**. 1. From the dropdown list, select **Assigned to you**. ## Filter the list of merge requests @@ -205,6 +208,15 @@ To delete a merge request: 1. Go to the merge request you want to delete, and select **Edit**. 1. Scroll to the bottom of the page, and select **Delete merge request**. +### Delete the source branch on merge + +You can delete the source branch for a merge request: + +- When you create a merge request, by selecting **Delete source branch when merge request accepted**. +- When you merge a merge request, if you have the Maintainer role, by selecting **Delete source branch**. + +An administrator can make this option the default in the project's settings. + ### Update merge requests when target branch merges **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. @@ -243,10 +255,10 @@ like in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87727/diffs?diff_i FLAG: On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `moved_mr_sidebar`. -On GitLab.com, this feature is not available. +On GitLab.com, this feature is enabled in the following projects: `gitlab-org/gitlab`, `gitlab-com/www-gitlab-com`, and `gitlab-org/customers-gitlab-com`. When this feature flag is enabled, you can find the following actions in -**Merge request actions** (**{ellipsis_v}**) on the top right: +**Merge request actions** (**{ellipsis_v}**) in the upper right: - The [notifications](../../profile/notifications.md#edit-notification-settings-for-issues-merge-requests-and-epics) toggle - Mark merge request as ready or [draft](../merge_requests/drafts.md) @@ -366,5 +378,5 @@ with a backup of the instance ready to be restored, just in case. u = User.find_by_username('<username>') p = Project.find_by_full_path('<namespace/project>') m = p.merge_requests.find_by(iid: <iid>) -Issuable::DestroyService.new(project: m.project, current_user: u).execute(m) +Issuable::DestroyService.new(container: m.project, current_user: u).execute(m) ``` diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index b1d07a740bf..1f7e15ee982 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -199,7 +199,7 @@ In these merge methods, you can merge only when your source branch is up-to-date If a fast-forward merge is not possible but a conflict-free rebase is possible, GitLab provides: -- The [`/rebase` quick action](../../../../topics/git/git_rebase.md#rebase-from-the-gitlab-ui). +- The [`/rebase` quick action](../../../../topics/git/git_rebase.md#from-the-gitlab-ui). - The option to select **Rebase** in the user interface. You must rebase the source branch locally before a fast-forward merge if both diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 76f351f1346..5878873f209 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -62,7 +62,7 @@ To do this: 1. If you don't know the merge request the commit originated from: 1. On the left sidebar, select **Repository > Commits**. 1. Select the title of the commit to display full information about the commit. -1. In the top right corner, select **Options**, then select **Revert**. +1. In the upper-right corner, select **Options**, then select **Revert**. 1. In **Revert in branch**, select the branch to revert your changes into. 1. Optional. Select **Start a new merge request** to start a new merge request with the new revert commit. 1. Select **Revert**. diff --git a/doc/user/project/merge_requests/reviews/data_usage.md b/doc/user/project/merge_requests/reviews/data_usage.md index f17015aef4e..dd07f0b4a6e 100644 --- a/doc/user/project/merge_requests/reviews/data_usage.md +++ b/doc/user/project/merge_requests/reviews/data_usage.md @@ -15,21 +15,21 @@ Suggested Reviewers is the first user-facing GitLab machine learning (ML) powere When a Project Maintainer or Owner enables Suggested Reviewers in project settings GitLab kicks off a data extraction job for the project which leverages the Merge Request API to understand pattern of review including recency, domain experience, and frequency to suggest an appropriate reviewer. -This data extraction job can take a few hours to complete (possibly up to a day), which is largely dependent on the size of the project. The process is automated and no action is needed during this process. Once data extraction is complete, you will start getting suggestions in merge requests. +This data extraction job can take a few hours to complete (possibly up to a day), which is largely dependent on the size of the project. The process is automated and no action is needed during this process. Once data extraction is complete, you start getting suggestions in merge requests. ### Generating suggestions -Once Suggested Reviewers is enabled and the data extraction is complete, new merge requests or new commits to existing merge requests will automatically trigger a Suggested Reviewers ML model inference and generate up to 5 suggested reviewers. These suggestions are contextual to the changes in the merge request. Additional commits to merge requests may change the reviewer suggestions which will automatically update in the reviewer dropdown list. +Once Suggested Reviewers is enabled and the data extraction is complete, new merge requests or new commits to existing merge requests automatically trigger a Suggested Reviewers ML model inference and generate up to 5 suggested reviewers. These suggestions are contextual to the changes in the merge request. Additional commits to merge requests may change the reviewer suggestions, which are automatically updated in the reviewer dropdown list. ## Progressive enhancement -This feature is designed as a progressive enhancement to the existing GitLab Reviewers functionality. The GitLab Reviewer UI will only offer suggestions if the ML engine is able to provide a recommendation. In the event of an issue or model inference failure, the feature will gracefully degrade. At no point with the usage of Suggested Reviewers prevent a user from being able to manually set a reviewer. +This feature is designed as a progressive enhancement to the existing GitLab Reviewers functionality. The GitLab Reviewer UI only offers suggestions if the ML engine is able to provide a recommendation. In the event of an issue or model inference failure, the feature gracefully degrades. At no point with the usage of Suggested Reviewers prevent a user from being able to manually set a reviewer. ## Model Accuracy -Organizations use many different processes for code review. Some focus on senior engineers reviewing junior engineer's code, others have hierarchical organizational structure based reviews. Suggested Reviewers is focused on contextual reviewers based on historical merge request activity by users. While we will continue evolving the underlying ML model to better serve various code review use cases and processes Suggested Reviewers does not replace the usage of other code review features like Code Owners and [Approval Rules](../approvals/rules.md). Reviewer selection is highly subjective therefore, we do not expect Suggested Reviewers to provide perfect suggestions every time. +Organizations use many different processes for code review. Some focus on senior engineers reviewing junior engineer's code, others have hierarchical organizational structure based reviews. Suggested Reviewers is focused on contextual reviewers based on historical merge request activity by users. While we continue evolving the underlying ML model to better serve various code review use cases and processes Suggested Reviewers does not replace the usage of other code review features like Code Owners and [Approval Rules](../approvals/rules.md). Reviewer selection is highly subjective therefore, we do not expect Suggested Reviewers to provide perfect suggestions every time. -Through analysis of beta customer usage, we find that the Suggested Reviewers ML model provides suggestions that are adopted in 60% of cases. We will be introducing a feedback mechanism into the Suggested Reviewers feature in the future to allow users to flag bad reviewer suggestions to help improve the model. Additionally we will be offering an opt-in feature in the future which will allow the model to use your project's data for training the underlying model. +Through analysis of beta customer usage, we find that the Suggested Reviewers ML model provides suggestions that are adopted in 60% of cases. We plan to introduce a feedback mechanism into the Suggested Reviewers feature in the future to allow users to flag bad reviewer suggestions to help improve the model. Additionally we plan to offer an opt-in feature in the future which allows the model to use your project's data for training the underlying model. ## Off by default diff --git a/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v13_8.png b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v13_8.png Binary files differdeleted file mode 100644 index c2aa0689d65..00000000000 --- a/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v13_8.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v15_9.png b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v15_9.png Binary files differnew file mode 100644 index 00000000000..6839c675625 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v15_9.png diff --git a/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v13_8.png b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v13_8.png Binary files differdeleted file mode 100644 index 3828868965b..00000000000 --- a/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v13_8.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v15_9.png b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v15_9.png Binary files differnew file mode 100644 index 00000000000..c7942d1e36d --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v15_9.png diff --git a/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_4.png b/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_4.png Binary files differdeleted file mode 100644 index aae75b0736c..00000000000 --- a/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_4.png +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_9.png b/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_9.png Binary files differnew file mode 100644 index 00000000000..70db0d79eaf --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggested_reviewers_v15_9.png diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 9a75c038dbc..5291a845437 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -25,21 +25,27 @@ review merge requests in Visual Studio Code. > [Introduced](https://gitlab.com/groups/gitlab-org/modelops/applied-ml/review-recommender/-/epics/3) in GitLab 15.4. -GitLab can recommend reviewers with Suggested Reviewers. Using the changes in a merge request and a project's contribution graph, machine learning powered suggestions appear in the reviewer section of the right merge request sidebar. +GitLab can suggest reviewers. Using the changes in a merge request and a project's contribution graph, machine learning suggestions appear in the reviewer section of the right sidebar. - + This feature is currently in [Open Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#open-beta) behind a [feature flag](https://gitlab.com/gitlab-org/gitlab/-/issues/368356). -Learn more about [how suggested reviewers works and data privacy](data_usage.md). +For more information, see [Data usage in Suggested Reviewers](data_usage.md). ### Enable suggested reviewers -Project Maintainers or Owners can enable suggested reviewers by visiting the [project settings](../../settings/index.md). +Project Maintainers or Owners can enable suggested reviewers by visiting +the [project settings](../../settings/index.md). -Enabling suggested reviewers will trigger GitLab to create an ML model for your project that will be used to generate reviewers. The larger your project, the longer this can take, but usually, the model will be ready to generate suggestions within a few hours. +Enabling suggested reviewers triggers GitLab to create an ML model for your +project that is used to generate reviewers. The larger your project, the longer +this process can take. Usually, the model is ready to generate suggestions +within a few hours. -No action is required once the feature is enabled. Once the model is ready, recommendations will populate the Reviewer dropdown list in the right-hand sidebar of a merge request with new commits. +No action is required after the feature is enabled. After the model is ready, +recommendations populate the **Reviewer** dropdown list in the right-hand sidebar +of a merge request with new commits. ## Review a merge request @@ -51,8 +57,8 @@ 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). + For more information about navigating the diffs displayed in this tab, see + [Changes in merge requests](../changes.md). 1. Select the **{comment}** **comment** icon in the gutter to expand the diff lines and display a comment box. In GitLab version 13.2 and later, you can [select multiple lines](#comment-on-multiple-lines). @@ -78,7 +84,7 @@ To download the changes included in a merge request as a diff: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests**. 1. Select your merge request. -1. On the top right, select **Code > Plain diff**. +1. In the upper right, select **Code > Plain diff**. If you know the URL of the merge request, you can also download the diff from the command line by appending `.diff` to the URL. This example downloads the diff @@ -101,7 +107,7 @@ To download the changes included in a merge request as a patch file: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Merge requests**. 1. Select your merge request. -1. On the top right, select **Code > Email patches**. +1. In the upper right, select **Code > Email patches**. If you know the URL of the merge request, you can also download the patch from the command line by appending `.patch` to the URL. This example downloads the patch @@ -147,7 +153,7 @@ To resolve or unresolve a thread when replying to a comment: Pending comments display information about the action to be taken when the comment is published: -- **{check-circle-filled}** Thread will be resolved. +- **{check-circle-filled}** Thread is resolved. - **{check-circle}** Thread stays unresolved. ### Add a new comment @@ -170,11 +176,11 @@ below the name of each suggested reviewer. [Code Owners](../../code_owners.md) a This example shows reviewers and approval rules when creating a new merge request: - + This example shows reviewers and approval rules in a merge request sidebar: - + ### Request a new review @@ -194,7 +200,7 @@ them a notification email. ## 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. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49875) select-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 diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 2894b71e7e6..62a2baa049b 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -22,25 +22,23 @@ respond with an associated status. This status is then displayed as a non-blocki widget within the merge request to surface this status to the merge request author or reviewers at the merge request level itself. -The lack of a status check response does not block the merging of a merge request. - You can configure merge request status checks for each individual project. These are not shared between projects. -To learn more about use cases, feature discovery, and development timelines, -see the [external status checks epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). +For more information about use cases, feature discovery, and development timelines, +see [epic 3869](https://gitlab.com/groups/gitlab-org/-/epics/3869). ## Block merges of merge requests unless all status checks have passed > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/369859) in GitLab 15.5 [with a flag](../../../administration/feature_flags.md) named `only_allow_merge_if_all_status_checks_passed`. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/372340) in GitLab 15.8. +> - Enabled on self-managed and feature flag [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111492) in GitLab 15.9. -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to -[enable the feature flag](../../../administration/feature_flags.md) named `only_allow_merge_if_all_status_checks_passed`. On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. +By default, merge requests in projects can be merged even if external status checks fail. To block the merging of merge requests when external checks fail: -By default, merge requests in projects can be merged even if external status checks fail. To block the merging of merge requests when external checks fail, enable this feature -using the [project API](../../../api/projects.md#edit-project). You must also [enable the feature flag](../../../administration/feature_flags.md) named -`only_allow_merge_if_all_status_checks_passed` on self-managed GitLab. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. +1. Select the **Status checks must succeed** checkbox. +1. Select **Save changes**. ## Lifecycle @@ -63,7 +61,7 @@ Merge requests return a `409 Conflict` error to any responses that do not refer External status checks have the following states: -- `pending` - The default state. No response can been received by the merge request from the external service. +- `pending` - The default state. No response has been received by the merge request from the external service. - `passed` - A response from the external service has been received and approved by it. - `failed` - A response from the external service has been received and denied by it. @@ -146,7 +144,7 @@ The **Remove status check?** modal is then shown. To complete the deletion of the status check you must select the **Remove status check** button. This **permanently** deletes -the status check and it **will not** be recoverable. +the status check and it **is not** recoverable. ## Status checks widget diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index bbe4aadc50d..5f9a2961df5 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -48,8 +48,7 @@ In a group, GitLab displays milestones that belong to the group and all projects If a project has issue tracking [turned off](../settings/index.md#configure-project-visibility-features-and-permissions), -you can get to the milestones page -by going to its URL. +to get to the milestones page, enter its URL. To do so: diff --git a/doc/user/project/organize_work_with_projects.md b/doc/user/project/organize_work_with_projects.md index 0ff354562fd..2b4ce6d2fd0 100644 --- a/doc/user/project/organize_work_with_projects.md +++ b/doc/user/project/organize_work_with_projects.md @@ -14,6 +14,7 @@ built-in CI/CD to deploy your app. Projects can be available [publicly, internally, or privately](../public_access.md). GitLab does not limit the number of private projects you can create. +- [Create a project](index.md) - [Manage projects](working_with_projects.md) - [Project visibility](../public_access.md) - [Project settings](../project/settings/index.md) @@ -28,6 +29,5 @@ GitLab does not limit the number of private projects you can create. - [Deploy keys](../../user/project/deploy_keys/index.md) - [Deploy tokens](../../user/project/deploy_tokens/index.md) - [File finder](../../user/project/repository/file_finder.md) -- [GitLab Pages](../../user/project/pages/index.md) - [Migrating projects](../../user/project/import/index.md) - [Migrate projects by using file exports](../../user/project/settings/import_export.md) diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 197524f2fc5..e55cf337d16 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -21,7 +21,7 @@ GitLab Pages with your own (sub)domain, you need to access your domain's registrar control panel to add a DNS record pointing it back to your GitLab Pages site. -Note that **how to** add DNS records depends on which server your domain +How to add DNS records depends on which server your domain is hosted on. Every control panel has its own place to do it. If you are not an administrator of your domain, and don't have access to your registrar, you must ask the technical support of your hosting service diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index 2f814bb0e65..24e9e6e15a4 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -56,8 +56,11 @@ To add your custom domain to GitLab Pages: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Pages**. -1. In the top right, select **New Domain**. -1. In **Domain**, enter your domain. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). +1. In the upper-right corner, select **New Domain**. +1. In **Domain**, enter the domain name. 1. Optional. In **Certificate**, turn off the **Automatic certificate management using Let's Encrypt** toggle to add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). You can also add the certificate and key later. 1. Select **Create New Domain**. @@ -102,7 +105,7 @@ server running on your instance).  WARNING: -Note that if you use your root domain for your GitLab Pages website +If you use your root domain for your GitLab Pages website **only**, and if your domain registrar supports this feature, you can add a DNS apex `CNAME` record instead of an `A` record. The main advantage of doing so is that when GitLab Pages IP on GitLab.com @@ -122,7 +125,7 @@ Subdomains (`subdomain.example.com`) require: | `subdomain.example.com` | `ALIAS`/`CNAME` | `namespace.gitlab.io` | | `_gitlab-pages-verification-code.subdomain.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | -Note that, whether it's a user or a project website, the DNS record +Whether it's a user or a project website, the DNS record should point to your Pages domain (`namespace.gitlab.io`), without any `/project-name`. @@ -165,10 +168,13 @@ If you're using Cloudflare, check Once you have added all the DNS records: -1. Go back at your project's **Settings > Pages** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). -1. Locate your domain name and select **Details**. -1. Select the **Retry verification** button to activate your new domain. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). +1. Next to the domain name, select **Edit**. +1. In **Verification status**, select **Retry verification** (**{retry}**).  @@ -184,7 +190,7 @@ from the GitLab project. > - Domain verification is **required for GitLab.com users**; for GitLab self-managed instances, your GitLab administrator has the option to [disabled custom domain verification](../../../../administration/pages/index.md#custom-domain-verification). -> - [DNS propagation may take some time (up to 24h)](https://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/complete-guide-to-dns-records/), +> - [DNS propagation may take some time (up to 24 hours)](https://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/complete-guide-to-dns-records/), although it's usually a matter of minutes to complete. Until it does, verification fails, and attempts to visit your domain result in a 404. > - Once your domain has been verified, leave the verification record @@ -287,12 +293,28 @@ meet these requirements. #### Steps -- To add the certificate at the time you add a new domain, go to your - project's **Settings > Pages > New Domain** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)), add the domain name and the - certificate. -- To add the certificate to a domain previously added, go to your - project's **Settings > Pages**, locate your domain name, select **Details** and **Edit** to add the certificate. +- To add the certificate at the time you add a new domain: + + 1. On the top bar, select **Main menu > Projects** and find your project. + 1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). + 1. In the upper-right corner, select **New Domain**. + 1. In **Domain**, enter the domain name. + 1. In **Certificate**, turn off the **Automatic certificate management using Let's Encrypt** toggle to add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). + 1. Select **Create New Domain**. + +- To add the certificate to a domain previously added: + + 1. On the top bar, select **Main menu > Projects** and find your project. + 1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). + 1. Next to the domain name, select **Edit**. + 1. In **Certificate**, turn off the **Automatic certificate management using Let's Encrypt** toggle to add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). + 1. Select **Save changes**. NOTE: The Pages menu entry may also be located at **Deployments > Pages**, [more information](../index.md#menu-position-test) @@ -319,9 +341,13 @@ domain (as long as you've set a valid certificate for it). To enable this setting: -1. Navigate to your project's **Settings > Pages** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). -1. Tick the checkbox **Force HTTPS (requires valid certificates)**. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). +1. Select the **Force HTTPS (requires valid certificates)** checkbox. +1. Select **Save changes**. If you use Cloudflare CDN in front of GitLab Pages, make sure to set the SSL connection setting to `full` instead of `flexible`. For more details, see the [Cloudflare CDN directions](https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes#h_4e0d1a7c-eb71-4204-9e22-9d3ef9ef7fef). diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index 770fb4f450a..95ac2e50f29 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -42,11 +42,13 @@ For **self-managed** GitLab instances, make sure your administrator has Once you've met the requirements, enable Let's Encrypt integration: -1. Navigate to your project's **Settings > Pages** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). -1. Find your domain and select **Details**. -1. Select **Edit** in the top-right corner. -1. Enable Let's Encrypt integration by switching **Automatic certificate management using Let's Encrypt**: +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). +1. Next to the domain name, select **Edit**. +1. Turn on the **Automatic certificate management using Let's Encrypt** toggle.  @@ -60,7 +62,7 @@ associated Pages domain. GitLab also renews it automatically. > - Issuing the certificate and updating Pages configuration > **can take up to an hour**. > - If you already have an SSL certificate in domain settings it -> continues to work until replaced by the Let's Encrypt's certificate. +> continues to work until replaced by the Let's Encrypt certificate. ## Troubleshooting @@ -70,31 +72,37 @@ associated Pages domain. GitLab also renews it automatically. If you get an error **Something went wrong while obtaining the Let's Encrypt certificate**, first, make sure that your pages site is set to "Everyone" in your project's **Settings > General > Visibility**. This allows the Let's Encrypt Servers reach your pages site. Once this is confirmed, you can try obtaining the certificate again by following these steps: -1. Go to your project's **Settings > Pages** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). -1. Select **Edit** on your domain. -1. Select **Retry**. -1. If you're still seeing the same error: - 1. Make sure you have properly set only one `CNAME` or `A` DNS record for your domain. - 1. Make sure your domain **doesn't have** an `AAAA` DNS record. - 1. If you have a `CAA` DNS record for your domain or any higher level domains, make sure [it includes `letsencrypt.org`](https://letsencrypt.org/docs/caa/). - 1. Make sure [your domain is verified](index.md#1-add-a-custom-domain). - 1. Go to step 1. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). +1. Next to the domain name, select **Edit**. +1. In **Verification status**, select **Retry verification** (**{retry}**). +1. If you're still getting the same error: + 1. Make sure you have properly set only one `CNAME` or `A` DNS record for your domain. + 1. Make sure your domain **doesn't have** an `AAAA` DNS record. + 1. If you have a `CAA` DNS record for your domain or any higher level domains, make sure [it includes `letsencrypt.org`](https://letsencrypt.org/docs/caa/). + 1. Make sure [your domain is verified](index.md#1-add-a-custom-domain). + 1. Go to step 1. ### Message "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later." hangs for more than an hour If you've enabled Let's Encrypt integration, but a certificate is absent after an hour and you see the message, "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later.", try to remove and add the domain for GitLab Pages again by following these steps: -1. Go to your project's **Settings > Pages** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). -1. Select **Remove** on your domain. -1. [Add the domain again and verify it](index.md#1-add-a-custom-domain). +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). +1. Next to the domain name, select **Remove**. +1. [Add the domain again, and verify it](index.md#1-add-a-custom-domain). 1. [Enable Let's Encrypt integration for your domain](#enabling-lets-encrypt-integration-for-your-custom-domain). -1. If you still see the same message after some time: - 1. Make sure you have properly set only one `CNAME` or `A` DNS record for your domain. - 1. Make sure your domain **doesn't have** an `AAAA` DNS record. - 1. If you have a `CAA` DNS record for your domain or any higher level domains, make sure [it includes `letsencrypt.org`](https://letsencrypt.org/docs/caa/). - 1. Go to step 1. +1. If you're still getting the same error: + 1. Make sure you have properly set only one `CNAME` or `A` DNS record for your domain. + 1. Make sure your domain **doesn't have** an `AAAA` DNS record. + 1. If you have a `CAA` DNS record for your domain or any higher level domains, make sure [it includes `letsencrypt.org`](https://letsencrypt.org/docs/caa/). + 1. Go to step 1. <!-- 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 diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md index b9d2f8cb9a6..398d8dc6e1e 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -29,7 +29,7 @@ This might be your first question. If our sites are hosted by GitLab Pages, they are static, hence we are not dealing with server-side scripts nor credit card transactions, then why do we need secure connections? -Back in the 1990s, where HTTPS came out, [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0.2C_2.0_and_3.0) was considered a "special" +When HTTPS came out in 1990, [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0.2C_2.0_and_3.0) was considered a "special" security measure, necessary just for big companies like banks and shopping sites with financial transactions. @@ -60,7 +60,7 @@ reiterating the importance of HTTPS. GitLab Pages accepts certificates provided in the [PEM](https://knowledge.digicert.com/quovadis.html) format, issued by [Certificate Authorities](https://en.wikipedia.org/wiki/Certificate_authority) or as -[self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate). Note that [self-signed certificates are typically not used](https://www.mcafee.com/blogs/other-blogs/mcafee-labs/self-signed-certificates-secure-so-why-ban/) +[self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate). [Self-signed certificates are typically not used](https://www.mcafee.com/blogs/other-blogs/mcafee-labs/self-signed-certificates-secure-so-why-ban/) for public websites for security reasons and to ensure that browsers trust your site's certificate. There are various kinds of certificates, each one diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index e0448621c6a..f596e418b02 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -27,9 +27,11 @@ these steps, you may have to do additional configuration for the Pages site to g If everything is configured correctly, the site can take approximately 30 minutes to deploy. To view the pipeline, go to **CI/CD > Pipelines**. + When the pipeline is finished, go to **Settings > Pages** to find the link to -your Pages website. (Note: this may also be -located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) +your Pages website. +If this path is not visible, select **Deployments > Pages**. +[This location is part of an experiment](../index.md#menu-position-test). For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md index e1a245851cb..509609e9b89 100644 --- a/doc/user/project/pages/getting_started/pages_forked_sample_project.md +++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md @@ -19,14 +19,15 @@ To fork a sample project and create a Pages website: 1. View the sample projects by navigating to the [GitLab Pages examples](https://gitlab.com/pages) group. 1. Select the name of the project you want to [fork](../../repository/forking_workflow.md#creating-a-fork). -1. In the top right, select **Fork** and then choose a namespace to fork to. +1. In the upper right, select **Fork** and then choose a namespace to fork to. 1. For your project, on the left sidebar, select **CI/CD > Pipelines** and then **Run pipeline**. GitLab CI/CD builds and deploys your site. The site can take approximately 30 minutes to deploy. -When the pipeline is finished, go to **Settings > Pages** to find the link -to your website from your project. (Note: this may also be -located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) +When the pipeline is finished, go to **Settings > Pages** to find the link to +your Pages website. +If this path is not visible, select **Deployments > Pages**. +[This location is part of an experiment](../index.md#menu-position-test). For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index 82e544b0701..a3d6c8f75f9 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -175,10 +175,11 @@ deploy your website: 1. Save and commit the `.gitlab-ci.yml` file. 1. Go to **CI/CD > Pipelines** to watch the pipeline. -1. When the pipeline succeeds, go to **Settings > Pages** - to view the URL where your site is now available. (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) +1. When the pipeline is finished, go to **Settings > Pages** to find the link to + your Pages website. + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). When this `pages` job completes successfully, a special `pages:deploy` job appears in the pipeline view. It prepares the content of the website for the GitLab Pages daemon. GitLab runs it in the background and doesn't use a runner. diff --git a/doc/user/project/pages/getting_started/pages_new_project_template.md b/doc/user/project/pages/getting_started/pages_new_project_template.md index a9988b1fb99..a301d2b64be 100644 --- a/doc/user/project/pages/getting_started/pages_new_project_template.md +++ b/doc/user/project/pages/getting_started/pages_new_project_template.md @@ -24,8 +24,9 @@ configured to generate a Pages site. site. When the pipeline is finished, go to **Settings > Pages** to find the link to -your Pages website. (Note: this may also be -located at **Deployments > Pages**, [more information](../index.md#menu-position-test)) +your Pages website. +If this path is not visible, select **Deployments > Pages**. +[This location is part of an experiment](../index.md#menu-position-test). For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md index 984c8e5c619..91c2c532a9a 100644 --- a/doc/user/project/pages/getting_started/pages_ui.md +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -34,8 +34,10 @@ a pipeline deploys your Pages website. To complete the setup and generate a GitLab Pages deployment: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages** (Note: this may also be - located at **Deployments > Pages**, [more information](../index.md#menu-position-test)). +1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](../index.md#menu-position-test). A **Get Started with Pages** form appears. If this form is not available, see [Troubleshooting](#if-the-get-started-with-pages-form-is-not-available). 1. For **Step 1**, enter an image name and verify that your files are in a `public` folder. @@ -61,10 +63,10 @@ and on the right side, select **Download artifacts**. ### If the `Get Started with Pages` form is not available -When you go to **Settings > Pages**, the form is not available if you: +The `Get Started with Pages` form is not available if you: - Deployed a GitLab Pages site before. -- Committed a `.gitlab-ci.yml` through the forms at least one time. +- Committed `.gitlab-ci.yml` through the forms at least one time. To fix this issue: diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 89d8fd093b2..691757e3eca 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -31,8 +31,8 @@ like Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo, or Brunch. You can also publish any website written directly in plain HTML, CSS, and JavaScript. Pages does not support dynamic server-side processing, for instance, as `.php` and `.asp` requires. -Learn more about -[static websites compared to dynamic websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/). +For more information, see +[Static vs dynamic websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/). ## Menu Position Test @@ -63,7 +63,7 @@ To update a GitLab Pages website: | [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) | Secure your Pages sites with Let's Encrypt certificates, which are automatically obtained and renewed by GitLab. | | [Redirects](redirects.md) | Set up HTTP redirects to forward one page to another. | -Learn more and see examples: +For more information, see: | Document | Description | |----------|-------------| diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index a9b8960d629..51c42eeecb8 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -59,8 +59,8 @@ If the case of `404.html`, there are different scenarios. For example: ## Redirects in GitLab Pages -You can configure redirects for your site using a `_redirects` file. To learn more, read -the [redirects documentation](redirects.md). +You can configure redirects for your site using a `_redirects` file. For more information, see +[Create redirects for GitLab Pages](redirects.md). ## Remove your pages @@ -68,6 +68,9 @@ To remove your pages: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Pages**. + + If this path is not visible, select **Deployments > Pages**. + [This location is part of an experiment](index.md#menu-position-test). 1. Select **Remove pages**. ## Subdomains of subdomains @@ -253,12 +256,12 @@ instead. Here are some examples of what happens given the above Pages site: | `/info/details` | `200 OK`: `public/info/details.html` | | `/info/details.html` | `200 OK`: `public/info/details.html` | -Note that when `public/data/index.html` exists, it takes priority over the `public/data.html` file +When `public/data/index.html` exists, it takes priority over the `public/data.html` file for both the `/data` and `/data/` URL paths. ## Known issues -For a list of known issues, visit the GitLab [public issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name[]=Category%3APages). +For a list of known issues, see the GitLab [public issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name[]=Category%3APages). ## Troubleshooting diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index b98772a6702..248a74a8abc 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -34,7 +34,7 @@ For a demonstration, see [Pages access controls](https://www.youtube.com/watch?v - **Only project members**: Only project members are able to browse the website. - **Everyone with access**: Everyone, both logged into and logged out of GitLab, is able to browse the website, no matter their project membership. -1. Select **Save changes**. Note that your changes may not take effect immediately. GitLab Pages uses +1. Select **Save changes**. Your changes may not take effect immediately. GitLab Pages uses a caching mechanism for efficiency. Your changes may not take effect until that cache is invalidated, which usually takes less than a minute. diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md index 8c9f1cbec86..751db136e34 100644 --- a/doc/user/project/pages/public_folder.md +++ b/doc/user/project/pages/public_folder.md @@ -17,7 +17,7 @@ for the following frameworks. For Eleventy, you should do one of the following: -- Add the `--output=public` flag in Eleventy's build commands, for example: +- Add the `--output=public` flag in the Eleventy build commands, for example: `npx @11ty/eleventy --input=path/to/sourcefiles --output=public` diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index cf0c0dbff82..f5447fd67ca 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -41,13 +41,11 @@ this test suite! To create redirects, create a configuration file named `_redirects` in the `public/` directory of your GitLab Pages site. -Note that: - - All paths must start with a forward slash `/`. - A default status code of `301` is applied if no [status code](#http-status-codes) is provided. - The `_redirects` file has a file size limit and a maximum number of rules per project, configured at the instance level. Only the first matching rules within the configured maximum are processed. - The default file size limit is 64KB, and the default maximum number of rules is 1,000. + The default file size limit is 64 KB, and the default maximum number of rules is 1,000. - If your GitLab Pages site uses the default domain name (such as `namespace.gitlab.io/projectname`) you must prefix every rule with the project name: @@ -74,7 +72,7 @@ is ignored because `hello.html` exists: /projectname/hello.html /projectname/world.html 302 ``` -GitLab doesn't support Netlify's +GitLab does not support Netlify [force option](https://docs.netlify.com/routing/redirects/rewrites-proxies/#shadowing) to change this behavior. @@ -231,7 +229,7 @@ rule 10: valid rule 11: valid ``` -## Differences from Netlify's implementation +## Differences from Netlify implementation Most supported `_redirects` rules behave the same in both GitLab and Netlify. However, there are some minor differences: diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index b0754e74314..da53fe2f5e9 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -10,6 +10,14 @@ 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. +A protected branch controls: + +- Which users can merge into the branch. +- Which users can push to the branch. +- If users can force push to the branch. +- If changes to files listed in the CODEOWNERS file can be pushed directly to the branch. +- Which users can unprotect the branch. + The [default branch](repository/branches/default.md) for your repository is protected by default. ## Who can modify a protected branch diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 9e5413b020e..1f85490795f 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -4,7 +4,7 @@ group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Push Options **(FREE)** +# Push options **(FREE)** GitLab supports using client-side [Git push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) to perform various actions at the same time as pushing changes. Additionally, [Push Rules](repository/push_rules.md) offer server-side control and enforcement options. @@ -36,7 +36,7 @@ You can use push options to skip a CI/CD pipeline, or pass CI/CD variables. | Push option | Description | Introduced in version | | ------------------------------ | ------------------------------------------------------------------------------------------- |---------------------- | | `ci.skip` | Do not create a CI pipeline for the latest push. Only skips branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). | [11.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) | -| `ci.variable="<name>=<value>"` | Provide [CI/CD variables](../../ci/variables/index.md) to be used in a CI pipeline, if one is created due to the push. | [12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/27983) | +| `ci.variable="<name>=<value>"` | Provide [CI/CD variables](../../ci/variables/index.md) to be used in a CI pipeline, if one is created due to the push. Only passes variables to branch pipelines and not [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md). | [12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/27983) | An example of using `ci.skip`: diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index d12a71c9ab3..90da47f7995 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -71,10 +71,10 @@ threads. Some quick actions might not be available to all subscription tiers. | `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. | | `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to do as done. | | `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [draft status](merge_requests/drafts.md). Use for toggling the draft status ([deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/92654) in GitLab 15.4.) | -| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | +| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. See [Chronic](https://gitlab.com/gitlab-org/ruby/gems/gitlab-chronic#examples) for more examples. | | `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue. Mark as a duplicate of, and related to, issue `<#issue>`. | | `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | -| `/estimate <time>` or `/estimate_time <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. Learn more about [time tracking](time_tracking.md). Alias `/estimate_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | +| `/estimate <time>` or `/estimate_time <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. For more information, see [Time tracking](time_tracking.md). Alias `/estimate_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | | `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). | | `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants` and is not yet supported in issue templates. | | `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196795) in GitLab 13.1). | @@ -108,7 +108,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | | `/severity <severity>` | **{check-circle}** Yes | **{check-circle}** No | **{check-circle}** No | Set the severity. Issue type must be `Incident`. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334045) in GitLab 14.2. | | `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | -| `/spend <time> [<date>]` or `/spend_time <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. Learn more about [time tracking](time_tracking.md). Alias `/spend_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | +| `/spend <time> [<date>]` or `/spend_time <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. For more information, see [Time tracking](time_tracking.md). Alias `/spend_time` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16501) in GitLab 15.6. | | `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8041) in GitLab 12.7). | | `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. | | `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | @@ -129,6 +129,34 @@ threads. Some quick actions might not be available to all subscription tiers. | `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. | | `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add a Zoom meeting to this issue or incident. In [GitLab 15.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/230853) users on GitLab Premium can add a short description when [adding a Zoom link to an incident](../../operations/incident_management/linked_resources.md#link-zoom-meetings-from-an-incident).| +## Work items + +The following quick actions can be applied through the description field when editing work items. + +| Command | Task | Objective | Key Result | Action | +|:-------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | +| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | +| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | +| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | +| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | +| `/cc @user` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mention a user. In GitLab 15.0 and later, this command performs no action. You can instead type `CC @user` or only `@user`. [In GitLab 14.9 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/31200), mentioning a user at the start of a line creates a specific type of to-do item notification. | +| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Assign one or more users. | +| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Assign yourself. | +| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Remove specific assignees. | +| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** Yes | Remove all assignees. | +| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** Yes | Replace current assignees with those specified. | +| `/label ~label1 ~label2` or `/labels ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | +| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. | +| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. | +| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. | +| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** Yes | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | +| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** Yes | Remove due date. | +| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk`. | +| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** Yes | **{dotted-circle}** Yes | Clear [health status](issues/managing_issues.md#health-status). | +| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, and `2`. | +| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | + ## Commit messages The following quick actions are applicable for commit messages: diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 7c2d5088f17..dca34af41b4 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -194,7 +194,7 @@ Prerequisites: In the UI: 1. On the left sidebar, select **Deployments > Releases**. -1. In the top-right corner of the release you want to modify, select **Edit this release** (the pencil icon). +1. In the upper-right corner of the release you want to modify, select **Edit this release** (the pencil icon). 1. On the **Edit Release** page, change the release's details. 1. Select **Save changes**. @@ -216,7 +216,7 @@ In the UI: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Deployments > Releases**. -1. In the top-right corner of the release you want to delete, select **Edit this release** +1. In the upper-right corner of the release you want to delete, select **Edit this release** (**{pencil}**). 1. On the **Edit Release** page, select **Delete**. 1. Select **Delete release**. @@ -236,7 +236,7 @@ the [Releases API](../../../api/releases/index.md#create-a-release). In the user interface, to associate milestones to a release: 1. On the left sidebar, select **Deployments > Releases**. -1. In the top-right corner of the release you want to modify, select **Edit this release** (the pencil icon). +1. In the upper-right corner of the release you want to modify, select **Edit this release** (the pencil icon). 1. From the **Milestones** list, select each milestone you want to associate. You can select multiple milestones. 1. Select **Save changes**. @@ -435,7 +435,7 @@ release evidence. If you [schedule release evidence collection](#schedule-release-evidence-collection), some artifacts may already be expired by the time of evidence collection. To avoid this you can use the [`artifacts:expire_in`](../../../ci/yaml/index.md#artifactsexpire_in) -keyword. Learn more in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/222351). +keyword. For more information, see [issue 222351](https://gitlab.com/gitlab-org/gitlab/-/issues/222351). ### Schedule release evidence collection diff --git a/doc/user/project/releases/release_fields.md b/doc/user/project/releases/release_fields.md index c06e746268f..120bbe32a63 100644 --- a/doc/user/project/releases/release_fields.md +++ b/doc/user/project/releases/release_fields.md @@ -34,7 +34,7 @@ Every release has a description. You can add any text you like, but we recommend including a changelog to describe the content of your release. This helps users quickly scan the differences between each release you publish. -[Git's tagging messages](https://git-scm.com/book/en/v2/Git-Basics-Tagging) can +[Tagging messages in Git](https://git-scm.com/book/en/v2/Git-Basics-Tagging) can be included in Release note descriptions by selecting **Include tag message in the release notes**. diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index 87caeee73e3..b33dc4450a9 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -44,7 +44,7 @@ To update the default branch for an individual [project](../../index.md): 1. On the top bar, select **Main menu > Projects** and find your project. 1. In the left navigation menu, go to **Settings > Repository**. -1. Expand **Default branch**. For **Initial default branch name**, select a new default branch. +1. Expand **Branch defaults**. For **Default branch**, select a new default branch. 1. Optional. Select the **Auto-close referenced issues on default branch** checkbox to close issues when a merge request [uses a closing pattern](../../issues/managing_issues.md#closing-issues-automatically). diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 4e3510c49b7..60504b94502 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -145,6 +145,38 @@ To view the **Branch rules overview** list: ## Troubleshooting +### Multiple branches containing the same commit + +At a deeper technical level, Git branches aren't separate entities, but labels +attached to a set of commit SHAs. When GitLab determines whether or not a branch has been +merged, it checks the target branch for the existence of those commit SHAs. +This behavior can cause unexpected results when two merge requests contain the same +commits. In this example, branches `B` and `C` both start from the same commit (`3`) +on branch `A`: + +```mermaid +gitGraph + commit id:"a" + branch "branch A" + commit id:"b" + commit id:"c" type: HIGHLIGHT + branch "branch B" + commit id:"d" + checkout "branch A" + branch "branch C" + commit id:"e" + checkout main + merge "branch B" id:"merges commits b, c, d" +``` + +If you merge branch `B`, branch `A` also appears as merged (without any action from you) +because all commits from branch `A` now appear in the target branch `main`. Branch `C` +remains unmerged, because commit `5` wasn't part of branch `A` or `B`. + +Merge request `A` remains merged, even if you attempt to push new commits +to its branch. If any changes in merge request `A` remain unmerged (because they +weren't part of merge request `A`), open a new merge request for them. + ### Error: ambiguous `HEAD` branch exists In versions of Git earlier than 2.16.0, you could create a branch named `HEAD`. diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index fae6e210a6c..929751b7247 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -13,7 +13,7 @@ if you do not have write access for the repository you want to contribute to, yo can create a fork. A fork is a personal copy of the repository and all its branches, which you create -in a namespace of your choice. This way you can make changes in your own fork and +in a namespace of your choice. Make changes in your own fork and submit them through a merge request to the repository you don't have access to. ## Creating a fork @@ -23,7 +23,7 @@ submit them through a merge request to the repository you don't have access to. To fork an existing project in GitLab: -1. On the project's home page, in the top right, select **{fork}** **Fork**: +1. On the project's home page, in the upper right, select **{fork}** **Fork**:  1. Optional. Edit the **Project name**. 1. For **Project URL**, select the [namespace](../../namespace/index.md) @@ -37,19 +37,82 @@ To fork an existing project in GitLab: GitLab creates your fork, and redirects you to the new fork's page. -## Repository mirroring +## Update your fork -You can use [repository mirroring](mirror/index.md) to keep your fork synced with the original repository. You can also use `git remote add upstream` to achieve the same result. +To copy the latest changes from the upstream repository into your fork, update it +[from the command line](#from-the-command-line). GitLab Premium and higher tiers can also +[configure forks as pull mirrors](#with-repository-mirroring) +of the upstream repository. -The main difference is that with repository mirroring, your remote fork is automatically kept up-to-date. +### From the command line -Without mirroring, to work locally you must use `git pull` to update your local repository -with the upstream project, then push the changes back to your fork to update it. +To update your fork from the command line, first ensure that you have configured +an `upstream` remote repository for your fork: -WARNING: -With mirroring, before approving a merge request, you are asked to sync. We recommend you automate it. +1. Clone your fork locally, if you have not already done so. For more information, see + [Clone a repository](../../../gitlab-basics/start-using-git.md#clone-a-repository). +1. View the remotes configured for your fork: + + ```shell + git remote -v + ``` + +1. If your fork does not have a remote pointing to the original repository, + use one of these examples to configure a remote called `upstream`: + + ```shell + # Use this line to set any repository as your upstream after editing <upstream_url> + git remote add upstream <upstream_url> + + # Use this line to set the main GitLab repository as your upstream + git remote add upstream https://gitlab.com/gitlab-org/gitlab.git + ``` + + After ensuring your local copy has the extra remote configured, you are ready to update your fork. + +1. In your local copy, ensure you have checked out the [default branch](branches/default.md), + replacing `main` with the name of your default branch: + + ```shell + git checkout main + ``` + + If Git identifies unstaged changes, commit or stash them before continuing. + +1. Fetch the changes to the upstream repository: + + ```shell + git fetch upstream + ``` -Read more about [How to keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/). +1. Pull the changes into your fork, replacing `main` with the name of the branch + you are updating: + + ```shell + git pull upstream main + ``` + +1. Push the changes to your fork repository on the server (GitLab.com or self-managed): + + ```shell + git push origin main + ``` + +### With repository mirroring **(PREMIUM)** + +A fork can be configured as a mirror of the upstream if all these conditions are met: + +1. Your subscription is **(PREMIUM)** or a higher tier. +1. You create all changes in branches (not `main`). +1. You do not work on [merge requests for confidential issues](../merge_requests/confidential.md), + which requires changes to `main`. + +[Repository mirroring](mirror/index.md) keeps your fork synced with the original repository. +This method updates your fork once per hour, with no manual `git pull` required. +For instructions, read [Configure pull mirroring](mirror/pull.md#configure-pull-mirroring). + +WARNING: +With mirroring, before approving a merge request, you are asked to sync. You should automate it. ## Merging upstream @@ -60,7 +123,7 @@ choose your forked project's branch. For **Target branch**, choose the original NOTE: When creating a merge request, if the forked project's visibility is more restrictive than the parent project (for example the fork is private, the parent is public), the target branch defaults to the forked project's default branch. This prevents potentially exposing the private code of the forked project. - + Then you can add labels, a milestone, and assign the merge request to someone who can review your changes. Then select **Submit merge request** to conclude the process. When successfully merged, your @@ -69,3 +132,8 @@ changes are added to the repository and branch you're merging into. ## Removing a fork relationship You can unlink your fork from its upstream project in the [advanced settings](../settings/index.md#remove-a-fork-relationship). + +## Related topics + +- GitLab blog post: [How to keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/). +- GitLab community forum: [Refreshing a fork](https://forum.gitlab.com/t/refreshing-a-fork/). diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 6b67ffd0e59..64f19d1a92c 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -43,7 +43,7 @@ To view a user's public GPG key, you can either: - Go to `https://gitlab.example.com/<USERNAME>.gpg`. GitLab displays the GPG key, if the user has configured one, or a blank page for users without a configured GPG key. -- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the top right +- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the upper right of the user's profile, select **View public GPG keys** (**{key}**). ## Configure commit signing @@ -119,7 +119,7 @@ If you don't already have a GPG key, create one: To add a GPG key to your user settings: 1. Sign in to GitLab. -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **GPG Keys** (**{key}**). 1. In **Key**, paste your _public_ key. @@ -180,6 +180,47 @@ you can sign individual commits manually, or configure Git to default to signed git config --global commit.gpgsign true ``` +#### Set signing key conditionally + +If you maintain signing keys for separate purposes, such as work and personal +use, use an `IncludeIf` statement in your `.gitconfig` file to set which key +you sign commits with. + +Prerequisites: + +- Requires Git version 2.13 or later. + +1. In the same directory as your main `~/.gitconfig` file, create a second file, + such as `.gitconfig-gitlab`. +1. In your main `~/.gitconfig` file, add your Git settings for work in non-GitLab projects. +1. Append this information to the end of your main `~/.gitconfig` file: + + ```ini + # The contents of this file are included only for GitLab.com URLs + [includeIf "hasconfig:remote.*.url:https://gitlab.com/**"] + + # Edit this line to point to your alternate configuration file + path = ~/.gitconfig-gitlab + ``` + +1. In your alternate `.gitconfig-gitlab` file, add the configuration overrides to + use when you're committing to a GitLab repository. All settings from your + main `~/.gitconfig` file are retained unless you explicitly override them. + In this example, + + ```ini + # Alternate ~/.gitconfig-gitlab file + # These values are used for repositories matching the string 'gitlab.com', + # and override their corresponding values in ~/.gitconfig + + [user] + email = you@example.com + signingkey = <KEY ID> + + [commit] + gpgsign = true + ``` + ## Verify commits You can review commits for a merge request, or for an entire project: @@ -212,7 +253,7 @@ If a GPG key becomes compromised, revoke it. Revoking a key changes both future To revoke a GPG key: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **GPG Keys** (**{key}**). 1. Select **Revoke** next to the GPG key you want to delete. @@ -227,7 +268,7 @@ When you remove a GPG key from your GitLab account: To remove a GPG key from your account: -1. In the top-right corner, select your avatar. +1. In the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **GPG Keys** (**{key}**). 1. Select **Remove** (**{remove}**) next to the GPG key you want to delete. diff --git a/doc/user/project/repository/img/forking_workflow_branch_select.png b/doc/user/project/repository/img/forking_workflow_branch_select.png Binary files differdeleted file mode 100644 index 0ea5410f832..00000000000 --- a/doc/user/project/repository/img/forking_workflow_branch_select.png +++ /dev/null diff --git a/doc/user/project/repository/img/forking_workflow_branch_select_v15_9.png b/doc/user/project/repository/img/forking_workflow_branch_select_v15_9.png Binary files differnew file mode 100644 index 00000000000..6b15abd8460 --- /dev/null +++ b/doc/user/project/repository/img/forking_workflow_branch_select_v15_9.png diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 3c33467df3f..5b4e1b14489 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -86,13 +86,28 @@ Visual Studio Code: - From the GitLab interface: 1. Go to the project's overview page. 1. Select **Clone**. - 1. Under either the **HTTPS** or **SSH** method, select **Clone with Visual Studio Code**. + 1. Under **Open in your IDE**, select **Visual Studio Code (SSH)** or **Visual Studio Code (HTTPS)**. 1. Select a folder to clone the project into. After Visual Studio Code clones your project, it opens the folder. - From Visual Studio Code, with the [extension](vscode.md) installed, use the extension's [`Git: Clone` command](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#clone-gitlab-projects). +### Clone and open in IntelliJ IDEA + +All projects can be cloned into [IntelliJ IDEA](https://www.jetbrains.com/idea/) +from the GitLab user interface. + +Prerequisites: + +- The [Jetbrains Toolbox App](https://www.jetbrains.com/toolbox-app/) must be also be installed. + +To do this: + +1. Go to the project's overview page. +1. Select **Clone**. +1. Under **Open in your IDE**, select **IntelliJ IDEA (SSH)** or **IntelliJ IDEA (HTTPS)**. + ## Download the code in a repository > 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. @@ -111,6 +126,9 @@ You can download the source code that's stored in a repository. - **Artifacts:** Download the artifacts from the latest CI job. +The checksums of generated archives can change even if the repository itself doesn't +change. This can occur, for example, if Git or a third-party library that GitLab uses changes. + ## Repository languages For the default branch of each repository, GitLab determines which programming languages diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index bc0073e6ec8..7a50c294dfc 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -55,7 +55,7 @@ Prerequisite: When mirroring the repository, GitLab confirms at least one of the stored host keys matches before connecting. This check can protect your mirror from malicious code injections, or your password from being stolen. -1. Select an **Authentication method**. To learn more, read +1. Select an **Authentication method**. For more information, see [Authentication methods for mirrors](#authentication-methods-for-mirrors). 1. If you authenticate with SSH host keys, [verify the host key](#verify-a-host-key) to ensure it is correct. @@ -65,7 +65,7 @@ Prerequisite: If you select `SSH public key` as your authentication method, GitLab generates a public key for your GitLab repository. You must provide this key to the non-GitLab server. -To learn more, read [Get your SSH public key](#get-your-ssh-public-key). +For more information, see [Get your SSH public key](#get-your-ssh-public-key). ## Update a mirror diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index 1923d8e2ae7..0eb51f40208 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -65,9 +65,14 @@ Prerequisite: 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Enter the **Git repository URL**. Include the username - in the URL, if required: `https://MYUSERNAME@github.com/GROUPNAME/PROJECTNAME.git` + in the URL, if required: `https://MYUSERNAME@gitlab.com/GROUPNAME/PROJECTNAME.git` + + NOTE: + To mirror the `gitlab` repository, use `git@gitlab.com:gitlab-org/gitlab.git` + or `https://gitlab.com/gitlab-org/gitlab.git`. + 1. In **Mirror direction**, select **Pull**. -1. In **Authentication method**, select your authentication method. To learn more, read +1. In **Authentication method**, select your authentication method. For more information, see [Authentication methods for mirrors](index.md#authentication-methods-for-mirrors). 1. Select any of the options you need: - [**Overwrite diverged branches**](#overwrite-diverged-branches) diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index 11d53b0c1d1..f06dd747897 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -38,7 +38,7 @@ To set up push mirroring for an existing project: 1. Expand **Mirroring repositories**. 1. Enter a repository URL. 1. In the **Mirror direction** dropdown list, select **Push**. -1. Select an **Authentication method**. To learn more, read +1. Select an **Authentication method**. For more information, see [Authentication methods for mirrors](index.md#authentication-methods-for-mirrors). 1. Select **Only mirror protected branches**, if necessary. 1. Select **Keep divergent refs**, if desired. diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index a8a79591e9e..cf7d4f44aad 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -110,7 +110,7 @@ To purge files from a GitLab repository: for more examples and the complete documentation. 1. Because you are trying to remove internal refs, - you'll later rely on `commit-map` files produced by each run + you need the `commit-map` files produced by each run to tell you which internal refs to remove. Every `git filter-repo` run creates a new `commit-map`, and overwrites the `commit-map` from the previous run. @@ -174,7 +174,7 @@ To clean up a repository: 1. Upload a list of objects. For example, a `commit-map` file created by `git filter-repo` which is located in the `filter-repo` directory. - If your `commit-map` file is larger than about 250KB or 3000 lines, the file can be split and uploaded piece by piece: + If your `commit-map` file is larger than about 250 KB or 3000 lines, the file can be split and uploaded piece by piece: ```shell split -l 3000 filter-repo/commit-map filter-repo/commit-map- diff --git a/doc/user/project/repository/ssh_signed_commits/index.md b/doc/user/project/repository/ssh_signed_commits/index.md index 85d2ce1d480..f2ce80263c8 100644 --- a/doc/user/project/repository/ssh_signed_commits/index.md +++ b/doc/user/project/repository/ssh_signed_commits/index.md @@ -19,8 +19,8 @@ You may use the same SSH keys for `git+ssh` authentication to GitLab and signing commit signatures as long as their usage type is **Authentication & Signing**. It can be verified on the page for [adding an SSH key to your GitLab account](../../../ssh.md#add-an-ssh-key-to-your-gitlab-account). -To learn more about managing the SSH keys associated with your GitLab account, read -[use SSH keys to communicate with GitLab](../../../ssh.md). +For more information about managing the SSH keys associated with your GitLab account, see +[Use SSH keys to communicate with GitLab](../../../ssh.md). ## Configure Git to sign commits with your SSH key @@ -160,8 +160,19 @@ for Git to associate SSH public keys with users: ## Revoke an SSH key for signing commits -You can't revoke an SSH key used for signing commits. To learn more, read -[Add revocation for SSH keys](https://gitlab.com/gitlab-org/gitlab/-/issues/382984). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108344) in GitLab 15.9. + +If an SSH key becomes compromised, revoke it. Revoking a key changes both future and past commits: + +- Past commits signed by this key are marked as unverified. +- Future commits signed by this key are marked as unverified. + +To revoke an SSH key: + +1. In the upper-right corner, select your avatar. +1. Select **Edit profile**. +1. On the left sidebar, select (**{key}**) **SSH Keys**. +1. Select **Revoke** next to the SSH key you want to delete. ## Related topics diff --git a/doc/user/project/repository/vscode.md b/doc/user/project/repository/vscode.md index 4afdb3be0bd..9260d59bc3a 100644 --- a/doc/user/project/repository/vscode.md +++ b/doc/user/project/repository/vscode.md @@ -1,6 +1,6 @@ --- stage: Create -group: Code Review +group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -15,8 +15,9 @@ do more day-to-day tasks in Visual Studio Code, such as: from the Visual Studio Code [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette). - Create and [review](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#merge-request-reviews) merge requests directly from Visual Studio Code. -- [Validate your GitLab CI configuration](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#validate-gitlab-ci-configuration). +- [Validate your GitLab CI/CD configuration](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#validate-gitlab-cicd-configuration). - [View the status of your pipeline](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#information-about-your-branch-pipelines-mr-closing-issue). +- [View the output of CI/CD jobs](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#view-the-job-output). - [Create](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#create-snippet) and paste snippets to, and from, your editor. - [Browse repositories](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#browse-a-repository-without-cloning) diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index b5b2b8aaae9..80b0ada6f7b 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -6,10 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Web Editor **(FREE)** -You can use the Web Editor to make changes directly from the GitLab UI instead of -cloning a project and using the command line. +You can use the Web Editor to make changes to a single file directly from the +GitLab UI. To make changes to multiple files, see [Web IDE](../web_ide/index.md). -From the project dashboard or repository, you can: +In the Web Editor, you can: - [Create a file](#create-a-file). - [Edit a file](#edit-a-file). @@ -18,8 +18,8 @@ From the project dashboard or repository, you can: - [Create a branch](#create-a-branch). - [Create a tag](#create-a-tag). -Your [primary email address](../../../user/profile/index.md#change-the-email-displayed-on-your-commits) -is used by default for any change you commit through the Web Editor. +Your [primary email address is used by default](../../../user/profile/index.md#change-the-email-displayed-on-your-commits) +for any change you commit through the Web Editor. ## Create a file @@ -28,18 +28,22 @@ To create a text file in the Web Editor: 1. On the top bar, select **Main menu > Projects** and find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **New file**. -1. Complete the fields. - - From the **Select a template type** dropdown list, you can apply a template to the new file. - - To create a merge request with the new file, ensure the **Start a new merge request with these changes** checkbox is selected. +1. Complete the fields. To create a merge request with the new file, ensure the **Start a new merge request with these changes** checkbox is selected. 1. Select **Commit changes**. ## Edit a file -To edit a file in the Web Editor: +To edit a text file in the Web Editor: 1. On the top bar, select **Main menu > Projects** and find your project. 1. Go to your file. -1. Next to the display buttons, select **Edit**. +1. In the upper-right corner of the file, select **Edit**. + + If **Edit** is not visible: + + 1. Next to **Open in Web IDE** or **Open in Gitpod**, select the down arrow (**{chevron-lg-down}**). + 1. From the dropdown list, select **Edit** as your default setting. + 1. Select **Edit**. ### Keyboard shortcuts diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 922accf9d28..b04905e6b34 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -236,7 +236,7 @@ To import requirements: 1. In a project, go to **Issues > Requirements**. - If the project already has existing requirements, select the import icon (**{import}**) in the - top right. + upper right. - For a project without any requirements, select **Import CSV** in the middle of the page. 1. Select the file and select **Import requirements**. @@ -296,7 +296,7 @@ Prerequisite: To export requirements: 1. In a project, go to **Issues > Requirements**. -1. In the top right, select the **Export as CSV** icon (**{export}**). +1. In the upper right, select the **Export as CSV** icon (**{export}**). A confirmation modal appears. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index cc195c3c959..22297149561 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -67,7 +67,7 @@ one from the selector menu to append it to all Service Desk issues. To enable Service Desk in your project: 1. (GitLab self-managed only) [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. - We recommend using [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing), + You should use [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing), but you can also use [catch-all mailboxes](../../administration/incoming_email.md#catch-all-mailbox). 1. In a project, in the left sidebar, go to **Settings > General** and expand the **Service Desk** section. 1. Enable the **Activate Service Desk** toggle. This reveals a unique email address to email issues @@ -80,7 +80,7 @@ WARNING: Anyone in your project can use the Service Desk email address to create an issue in this project, **regardless of their access level** to your GitLab instance. -To improve your project's security, we recommend the following: +To improve your project's security, you should: - Put the Service Desk email address behind an alias on your email system so you can change it later. - [Enable Akismet](../../integration/akismet.md) on your GitLab instance to add spam checking to this service. @@ -95,6 +95,7 @@ displayed in the information note. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2460) in GitLab 12.7. > - Moved from GitLab Premium to GitLab Free in 13.2. +> - `UNSUBSCRIBE_URL`, `SYSTEM_HEADER`, `SYSTEM_FOOTER`, and `ADDITIONAL_TEXT` placeholders [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285512) in GitLab 15.9. An email is sent to the author when: @@ -128,6 +129,10 @@ You can use these placeholders to be automatically replaced in each email: - `%{ISSUE_ID}`: issue IID - `%{ISSUE_PATH}`: project path appended with the issue IID +- `%{UNSUBSCRIBE_URL}`: unsubscribe URL +- `%{SYSTEM_HEADER}`: [system header message](../admin_area/appearance.md#system-header-and-footer-messages) +- `%{SYSTEM_FOOTER}`: [system footer message](../admin_area/appearance.md#system-header-and-footer-messages) +- `%{ADDITIONAL_TEXT}`: [custom additional text](../admin_area/settings/email.md#custom-additional-text) Because Service Desk issues are created as [confidential](issues/confidential_issues.md) (only project members can see them), the response email does not contain the issue link. @@ -142,6 +147,10 @@ You can use these placeholders to be automatically replaced in each email: - `%{ISSUE_ID}`: issue IID - `%{ISSUE_PATH}`: project path appended with the issue IID - `%{NOTE_TEXT}`: note text +- `%{UNSUBSCRIBE_URL}`: unsubscribe URL +- `%{SYSTEM_HEADER}`: [system header message](../admin_area/appearance.md#system-header-and-footer-messages) +- `%{SYSTEM_FOOTER}`: [system footer message](../admin_area/appearance.md#system-header-and-footer-messages) +- `%{ADDITIONAL_TEXT}`: [custom additional text](../admin_area/settings/email.md#custom-additional-text) #### New Service Desk issues @@ -154,7 +163,7 @@ You can set description templates at various levels: - A specific [group or subgroup](description_templates.md#set-group-level-description-templates). - A specific [project](description_templates.md#set-a-default-template-for-merge-requests-and-issues). -The templates are inherited. For example, in a project, you can also access templates set for the instance or the project's parent groups. +The templates are inherited. For example, in a project, you can also access templates set for the instance, or the project's parent groups. To use a custom description template with Service Desk: @@ -217,9 +226,9 @@ To configure a custom mailbox for Service Desk with IMAP, add the following snip NOTE: In GitLab 15.3 and later, Service Desk uses `webhook` (internal API call) by default instead of enqueuing a Sidekiq job. To use `webhook` on an Omnibus installation running GitLab 15.3, you must generate a secret file. -For more context, visit [Omnibus GitLab MR 5927](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5927). +For more information, see [merge request 5927](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5927). In GitLab 15.4, reconfiguring an Omnibus installation generates this secret file automatically, so no secret file configuration setting is needed. -For details, visit [issue 1462](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1462). +For more information, see [issue 1462](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1462). ```ruby gitlab_rails['service_desk_email_enabled'] = true @@ -260,13 +269,141 @@ service_desk_email: The configuration options are the same as for configuring [incoming email](../../administration/incoming_email.md#set-it-up). +##### Use encrypted credentials + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108279) in GitLab 15.9. + +Instead of having the Service Desk email credentials stored in plaintext in the configuration files, you can optionally +use an encrypted file for the Incoming email credentials. + +Prerequisites: + +- To use encrypted credentials, you must first enable the + [encrypted configuration](../../administration/encrypted_configuration.md). + +The supported configuration items for the encrypted file are: + +- `user` +- `password` + +::Tabs + +:::TabTitle Linux package (Omnibus) + +1. If initially your Service Desk configuration in `/etc/gitlab/gitlab.rb` looked like: + + ```ruby + gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com" + gitlab_rails['service_desk_email_password'] = "examplepassword" + ``` + +1. Edit the encrypted secret: + + ```shell + sudo gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=vim + ``` + +1. Enter the unencrypted contents of the Service Desk email secret: + + ```yaml + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `/etc/gitlab/gitlab.rb` and remove the `service_desk` settings for `email` and `password`. +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +Use a Kubernetes secret to store the Service Desk email password. For more information, +read about [Helm IMAP secrets](https://docs.gitlab.com/charts/installation/secrets.html#imap-password-for-service-desk-emails). + +:::TabTitle Docker + +1. If initially your Service Desk configuration in `docker-compose.yml` looked like: + + ```yaml + version: "3.6" + services: + gitlab: + image: 'gitlab/gitlab-ee:latest' + restart: always + hostname: 'gitlab.example.com' + environment: + GITLAB_OMNIBUS_CONFIG: | + gitlab_rails['service_desk_email_email'] = "service-desk-email@mail.example.com" + gitlab_rails['service_desk_email_password'] = "examplepassword" + ``` + +1. Get inside the container, and edit the encrypted secret: + + ```shell + sudo docker exec -t <container_name> bash + gitlab-rake gitlab:service_desk_email:secret:edit EDITOR=editor + ``` + +1. Enter the unencrypted contents of the Service Desk secret: + + ```yaml + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `docker-compose.yml` and remove the `service_desk` settings for `email` and `password`. +1. Save the file and restart GitLab: + + ```shell + docker compose up -d + ``` + +:::TabTitle Self-compiled (source) + +1. If initially your Service Desk configuration in `/home/git/gitlab/config/gitlab.yml` looked like: + + ```yaml + production: + service_desk_email: + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit the encrypted secret: + + ```shell + bundle exec rake gitlab:service_desk_email:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production + ``` + +1. Enter the unencrypted contents of the Service Desk secret: + + ```yaml + user: 'service-desk-email@mail.example.com' + password: 'examplepassword' + ``` + +1. Edit `/home/git/gitlab/config/gitlab.yml` and remove the `service_desk_email:` settings for `user` and `password`. +1. Save the file and restart GitLab and Mailroom + + ```shell + # For systems running systemd + sudo systemctl restart gitlab.target + + # For systems running SysV init + sudo service gitlab restart + ``` + +::EndTabs + ##### Microsoft Graph > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214900) in GitLab 13.11. > - Alternative Azure deployments [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5978) in GitLab 14.9. Service Desk can be configured to read Microsoft Exchange Online mailboxes with the Microsoft -Graph API instead of IMAP. Follow the [documentation in the incoming email section for setting up an OAuth2 application for Microsoft Graph](../../administration/incoming_email.md#microsoft-graph). +Graph API instead of IMAP. Follow the [documentation in the incoming email section for setting up an OAuth 2.0 application for Microsoft Graph](../../administration/incoming_email.md#microsoft-graph). - Example for Omnibus GitLab installations: @@ -358,12 +495,10 @@ issues created through customer support requests, and filter or interact with th Messages from the end user are shown as coming from the special [Support Bot user](../../subscriptions/self_managed/index.md#billable-users). -You can read and write comments as you normally do in GitLab: +You can read and write comments as you usually do in GitLab:  -Note that: - - The project's visibility (private, internal, public) does not affect Service Desk. - The path to the project, including its group or namespace, is shown in emails. @@ -378,12 +513,34 @@ On GitLab.com, this feature is not available. If a comment contains any attachments and their total size is less than or equal to 10 MB, these attachments are sent as part of the email. In other cases, the email contains links to the attachments. +#### Special HTML formatting in HTML emails + +<!-- When the feature flag is removed, delete this topic and add as a line in version history under one of the topics above this one.--> + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372301) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. +On GitLab.com, this feature is not available. + +When this feature is enabled, HTML emails correctly show additional HTML formatting, such as: + +- Tables +- Blockquotes +- Images +- Collapsible sections + #### Privacy considerations +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108901) the minimum required role to view the creator's and participant's email in GitLab 15.9. + Service Desk issues are confidential, but the project owner can [make an issue public](issues/confidential_issues.md#modify-issue-confidentiality). -When a Service Desk issue becomes public, the issue creator's email address is disclosed -to everyone who can view the project. +When a Service Desk issue becomes public, the issue creator's and participants' email addresses are +visible to signed-in users with at least the Reporter role for the project. + +In GitLab 15.8 and earlier, when a Service Desk issue becomes public, the issue creator's email +address is disclosed to everyone who can view the project. ### Support Bot user diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index b85f52d43bb..3715eef08e0 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -14,7 +14,7 @@ then imported into a new GitLab instance. You can also: GitLab maps user contributions correctly when an admin access token is used to perform the import. -As a result, migrating projects using file exports does not map user contributions correctly when you are importing +Consequently, migrating projects using file exports does not map user contributions correctly when you are importing projects from a self-managed instance to GitLab.com. Instead, all GitLab user associations (such as comment author) are changed to the user importing the project. For more @@ -27,6 +27,30 @@ To preserve contribution history, [migrate using direct transfer](../../group/im If you migrate from GitLab.com to self-managed GitLab, an administrator can create users on the self-managed GitLab instance. +## Compatibility + +FLAG: +On self-managed GitLab by default project, file exports are in NDJSON format. To make GitLab produce project file +exports in JSON format, ask an administrator to [disable the feature flags](../../../administration/feature_flags.md) +named `project_export_as_ndjson`. To allow GitLab to import project file exports in JSON format, ask an administrator to +[disable the feature flags](../../../administration/feature_flags.md) named `project_import_ndjson`. On GitLab.com, +project file exports are in NDJSON format only. + +Project file exports are in NDJSON format. Before version 14.0, GitLab produced project file exports in JSON format. +To support transitions, you can still import JSON-formatted project file exports if you configure the relevant feature +flags. + +From GitLab 13.0, GitLab can import project file exports that were exported from a version of GitLab up to two +[minor](../../../policy/maintenance.md#versioning) versions behind, which is similar to our process for +[security releases](../../../policy/maintenance.md#security-releases). + +For example: + +| Destination version | Compatible source versions | +|:--------------------|:---------------------------| +| 13.0 | 13.0, 12.10, 12.9 | +| 13.1 | 13.1, 13.0, 12.10 | + ## Configure file exports as an import source **(FREE SELF)** Before you can migrate projects on a self-managed GitLab instance using file exports, GitLab administrators must: @@ -47,7 +71,7 @@ To enable file exports as an import source for the destination instance: ## Between CE and EE You can export projects from the [Community Edition to the Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/) -and vice versa. This assumes [version history](#version-history) requirements are met. +and vice versa, assuming [compatibility](#compatibility) is met. If you're exporting a project from the Enterprise Edition to the Community Edition, you may lose data that is retained only in the Enterprise Edition. For more information, see @@ -127,10 +151,11 @@ Items that are **not** exported include: - Pipeline triggers - Webhooks - Any encrypted tokens -- [Number of required approvals](https://gitlab.com/gitlab-org/gitlab/-/issues/221088) +- [Number of required approvals](https://gitlab.com/gitlab-org/gitlab/-/issues/221087) - Repository size limits - Deploy keys allowed to push to protected branches - Secure Files +- [Activity logs for Git-related events](https://gitlab.com/gitlab-org/gitlab/-/issues/214700). For example, pushing and creating tags ## Import a project and its data @@ -145,7 +170,7 @@ Prerequisites: - You must have [exported the project and its data](#export-a-project-and-its-data). - Compare GitLab versions and ensure you are importing to a GitLab version that is the same or later than the GitLab version you exported to. -- Review the [Version history](#version-history) for compatibility issues. +- Review [compatibility](#compatibility) for any issues. - At least the Maintainer role on the destination group to migrate to. Using the Developer role for this purpose was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in GitLab 16.0. @@ -220,32 +245,6 @@ To help avoid abuse, by default, users are rate limited to: | Download export | 1 download per group per minute | | Import | 6 projects per minute | -## Version history - -### 15.8+ - -Starting with GitLab 15.8, importing groups from a JSON export is no longer supported. Groups must be imported -in NDJSON format. - -### 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. -**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). - -For example: - -| Current version | Can import bundles exported from | -|-----------------|----------------------------------| -| 13.0 | 13.0, 12.10, 12.9 | -| 13.1 | 13.1, 13.0, 12.10 | - ## Related topics - [Project import and export API](../../../api/project_import_export.md) diff --git a/doc/user/project/settings/import_export_troubleshooting.md b/doc/user/project/settings/import_export_troubleshooting.md index 81ceba7139b..00edeef5cfa 100644 --- a/doc/user/project/settings/import_export_troubleshooting.md +++ b/doc/user/project/settings/import_export_troubleshooting.md @@ -153,7 +153,8 @@ Rather than attempting to push all changes at once, this workaround: You usually export a project through [the web interface](import_export.md#export-a-project-and-its-data) or through [the API](../../../api/project_import_export.md). Exporting using these methods can sometimes fail without giving enough information to troubleshoot. In these cases, -[open a rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) +[open a rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) and loop through +[all the defined exporters](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/projects/import_export/export_service.rb). Execute each line individually, rather than pasting the entire block at once, so you can see any errors each command returns. @@ -197,7 +198,7 @@ Read through the current performance problems using the Import/Export below. ### OOM errors -Out of memory (OOM) errors are normally caused by the [Sidekiq Memory Killer](../../../administration/sidekiq/sidekiq_memory_killer.md): +Out of memory (OOM) errors are usually caused by the [Sidekiq Memory Killer](../../../administration/sidekiq/sidekiq_memory_killer.md): ```shell SIDEKIQ_MEMORY_KILLER_MAX_RSS = 2000000 diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 3798643549d..ed4eea56514 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -158,7 +158,7 @@ Configure your project's merge request settings: - Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). - Enable [merge only when all threads are resolved](../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved). - 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). +- Enable [**Delete source branch when merge request is accepted** option by default](#delete-the-source-branch-on-merge-by-default). - Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions). - Configure [merge and squash commit message templates](../merge_requests/commit_templates.md). - Configure [the default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks. @@ -230,6 +230,18 @@ To rename a repository: 1. In the **Change path** text box, edit the path. 1. Select **Change path**. +## Delete the source branch on merge by default + +In merge requests, you can change the default behavior so that the +**Delete the source branch** checkbox is always selected. + +To set this default: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. +1. Select **Enable "Delete source branch" option by default**. +1. Select **Save changes**. + ## Transfer a project to another namespace When you transfer a project to another namespace, you move the project to a different group. @@ -241,6 +253,7 @@ Prerequisites: - The group must allow creation of new projects. - The project must not contain any [container images](../../packages/container_registry/index.md#move-or-rename-container-registry-repositories). - Remove any npm packages. If you transfer a project to a different root namespace, the project must not contain any npm packages. When you update the path of a user or group, or transfer a subgroup or project, you must remove any npm packages first. You cannot update the root namespace of a project with npm packages. Make sure you update your .npmrc files to follow the naming convention and run npm publish if necessary. +- If a security policy is assigned to the project, it is automatically unassigned during the transfer. To transfer a project: diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index cb7ba2a7df2..f9218a228ca 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -17,7 +17,7 @@ select a limited role, and provide an expiry date. Use a project access token to authenticate: -- With the [GitLab API](../../../api/index.md#personalprojectgroup-access-tokens). +- With the [GitLab API](../../../api/rest/index.md#personalprojectgroup-access-tokens). - With Git, when using HTTP Basic Authentication, use: - Any non-blank value as a username. - The project access token as the password. diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 186ca0ba9f0..d5f0b7e6180 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -42,7 +42,8 @@ You can see the estimated time remaining when you hover over the time tracking i Prerequisites: -- You must have at least the Reporter role for the project. +- In issues, you must have at least the Reporter role for the project. +- In merge requests, you must have at least the Developer role for the project. To enter an estimate, use the `/estimate` [quick action](quick_actions.md), followed by the time. @@ -57,7 +58,8 @@ Every time you enter a new time estimate, it overwrites the previous value. Prerequisites: -- You must have at least the Reporter role for the project. +- In issues, you must have at least the Reporter role for the project. +- In merge requests, you must have at least the Developer role for the project. To remove an estimate entirely, use the `/remove_estimate` [quick action](quick_actions.md). @@ -171,10 +173,10 @@ The following time units are available: | Time unit | What to type | Conversion rate | | --------- | --------------------------- | --------------- | -| Month | `mo`, `month`, or `months` | 4w (160h) | -| Week | `w`, `week`, or `weeks` | 5d (40h) | -| Day | `d`, `day`, or `days` | 8h | -| Hour | `h`, `hour`, or `hours` | 60m | +| Month | `mo`, `month`, or `months` | 4 w (160 h) | +| Week | `w`, `week`, or `weeks` | 5 d (40 h) | +| Day | `d`, `day`, or `days` | 8 h | +| Hour | `h`, `hour`, or `hours` | 60 m | | Minute | `m`, `minute`, or `minutes` | | ### Limit displayed units to hours **(FREE SELF)** diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 4648df7dbd7..5e9f648daba 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -6,9 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Web IDE **(FREE)** -The Web Integrated Development Environment (IDE) editor streamlines the process -to contribute changes to your projects, by providing an advanced editor with -commit staging. +The Web IDE is an advanced editor with commit staging. +You can use the Web IDE to make changes to multiple files directly from the +GitLab UI. For a more basic implementation, see [Web Editor](../repository/web_editor.md). NOTE: The Web IDE is being updated to use VS Code. For details, @@ -175,8 +175,8 @@ access to the selected branch, you see a warning, but can still create a new branch and start a merge request. To discard a change in a particular file, select **Discard changes** on that -file in the changes tab. To discard all the changes, select the trash icon on the -top-right corner of the changes sidebar. +file in the changes tab. To discard all the changes, select the trash icon in the +upper-right corner of the changes sidebar.  @@ -238,7 +238,13 @@ There are two ways to preview Markdown content in the Web IDE: 1. Right-click or use the keyboard shortcut `Command/Control + Shift + P` and select **Preview Markdown** to toggle a live Markdown preview panel. -## Live Preview +<!--- start_remove The following content will be removed on remove_date: '2023-02-01' --> + +## Live Preview (removed) + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108627) in GitLab 15.8 +and is planned for removal in 15.9. This change is a breaking change. > [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/213853) from _Client Side Evaluation_ to _Live Preview_ in GitLab 13.0. @@ -283,6 +289,8 @@ An example `package.json`: } ``` +<!--- end_remove --> + ## Interactive Web Terminals for the Web IDE > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) from GitLab Ultimate to GitLab Free in 13.1. diff --git a/doc/user/project/web_ide_beta/index.md b/doc/user/project/web_ide_beta/index.md index 4f84110a038..fe110baf578 100644 --- a/doc/user/project/web_ide_beta/index.md +++ b/doc/user/project/web_ide_beta/index.md @@ -40,7 +40,7 @@ or a merge request. To open the Web IDE Beta from a file or the repository file list: -- On the top right of the page, select **Open in Web IDE**. +- In the upper right of the page, select **Open in Web IDE**. If **Open in Web IDE** is not visible: @@ -88,7 +88,7 @@ For details, see the [VS Code documentation](https://code.visualstudio.com/docs/ If you do not want to use the Web IDE Beta, you can change your personal preferences. -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Preferences**. 1. In the **Web IDE** section, select the **Opt out of the Web IDE Beta** checkbox. 1. Select **Save changes**. @@ -96,7 +96,7 @@ If you do not want to use the Web IDE Beta, you can change your personal prefere ## Known issues The [Web Terminal](../web_ide/index.md#interactive-web-terminals-for-the-web-ide) -and [Live Preview](../web_ide/index.md#live-preview) are not available in the Web IDE Beta. +and [Live Preview](../web_ide/index.md#live-preview-removed) are not available in the Web IDE Beta. These features might become available at a later date. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 04a6f9bee80..f01331ac784 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -252,7 +252,7 @@ replaces the default sidebar navigation: - For project wikis, select **Projects** and find your project. - For group wikis, select **Groups** and find your group. 1. On the left sidebar, select **Wiki**. -1. In the top right corner of the page, select **Edit sidebar**. +1. In the upper-right corner of the page, select **Edit sidebar**. 1. When complete, select **Save changes**. A `_sidebar` example, formatted with Markdown: @@ -269,8 +269,6 @@ A `_sidebar` example, formatted with Markdown: - [Sidebar](_sidebar) ``` -Support for displaying a generated table of contents with a custom side navigation is being considered. - ## Enable or disable a project wiki Wikis are enabled by default in GitLab. Project [administrators](../../permissions.md) diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 92db90d66dc..a0e6a78dfe2 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -87,7 +87,7 @@ called `my-project` under your username, the project is created at `https://gitl To view your personal projects: 1. On the top bar, select **Main menu > Projects > View all projects**. -1. In the **Your projects** tab, select **Personal**. +1. In the **Yours** tab, select **Personal**. ## Delete a project @@ -157,6 +157,18 @@ You can sort projects by: You can also choose to hide or show archived projects. +### Filter projects by language + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385465) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `project_language_search`. Enabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110956) in GitLab 15.9. Feature flag `project_language_search` removed. + +You can filter projects by the programming language they use. To do this: + +1. On the top bar, select **Main menu > Projects > View all projects**. +1. From the **Language** dropdown list, select the language you want to filter projects by. + +A list of projects that use the selected language is displayed. + ## Change the visibility of individual features in a project You can change the visibility of individual features in a project. diff --git a/doc/user/public_access.md b/doc/user/public_access.md index 773c14c9ec8..2a9a9fb84fe 100644 --- a/doc/user/public_access.md +++ b/doc/user/public_access.md @@ -7,63 +7,49 @@ type: reference # Project and group visibility **(FREE)** -If you have the Owner role, you can set a project's or group's visibility as: +A project in GitLab can be private, internal, or public. -- **Public** -- **[Internal](#internal-projects-and-groups)** -- **Private** - -These visibility levels affect who can see the project in the public access directory -(for example, <https://gitlab.com/public>). - -For more granular control, you can determine -[which features in a project are visible](project/working_with_projects.md#change-the-visibility-of-individual-features-in-a-project). - -The visibility setting of a project must be at least as restrictive -as the visibility of its parent group. -For example, a private group can include only private projects, -while a public group can include private, internal, and public projects. - -## Public projects and groups - -Public projects can be cloned **without any** authentication over HTTPS. +## Private projects and groups -They are listed in the public access directory (`/public`) for all users. +For private projects, only project members can: -Public groups can have public, internal, or private subgroups. +- Clone the project. +- View the public access directory (`/public`). -**Any authenticated user** has the Guest role on the repository. +Users with the Guest role cannot clone the project. -NOTE: -By default, `/public` is visible to unauthenticated users. However, if the -[**Public** visibility level](admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels) -is restricted, `/public` is visible only to authenticated users. +Private groups can have private subgroups only. ## Internal projects and groups **(FREE SELF)** -Internal projects can be cloned by any authenticated user except -[external users](admin_area/external_users.md). +For internal projects, **any authenticated user**, including users with the Guest role, can: -They are also listed in the public access directory (`/public`), but only for authenticated users. +- Clone the project. +- View the public access directory (`/public`). -Internal groups can have internal or private subgroups. +[External users](admin_area/external_users.md) cannot clone the project. -Any signed-in users except [external users](admin_area/external_users.md) have the -Guest role on the repository. +Internal groups can have internal or private subgroups. NOTE: From July 2019, the `Internal` visibility setting is disabled for new projects, groups, and snippets on GitLab.com. Existing projects, groups, and snippets using the `Internal` -visibility setting keep this setting. You can read more about the change in the -[relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/12388). +visibility setting keep this setting. For more information, see +[issue 12388](https://gitlab.com/gitlab-org/gitlab/-/issues/12388). -## Private projects and groups +## Public projects and groups -Private projects can only be cloned and viewed by project members (except for guests). +For public projects, **users who are not authenticated**, including users with the Guest role, can: -They appear in the public access directory (`/public`) for project members only. +- Clone the project. +- View the public access directory (`/public`). -Private groups can only have private subgroups. +Public groups can have public, internal, or private subgroups. + +NOTE: +If an administrator restricts the +[**Public** visibility level](admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels), +then `/public` is visible only to authenticated users. ## Change project visibility @@ -77,6 +63,8 @@ Prerequisite: 1. On the left sidebar, select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Change **Project visibility** to either **Private**, **Internal**, or **Public**. + The visibility setting for a project must be at least as restrictive + as the visibility of its parent group. 1. Select **Save changes**. ## Change group visibility @@ -94,15 +82,21 @@ Prerequisites: 1. On the left sidebar, select **Settings > General**. 1. Expand **Naming, visibility**. 1. Under **Visibility level** select either **Private**, **Internal**, or **Public**. + The visibility setting for a project must be at least as restrictive + as the visibility of its parent group. 1. Select **Save changes**. ## Restrict use of public or internal projects **(FREE SELF)** -You can restrict the use of visibility levels for users when they create a project or a snippet. -This is useful to prevent users from publicly exposing their repositories by accident. The -restricted visibility settings do not apply to administrators. +Administrators can restrict which visibility levels users can choose when they create a project or a snippet. +This setting can help prevent users from publicly exposing their repositories by accident. + +For more information, see [Restrict visibility levels](admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels). + +## Related topics -For details, see [Restricted visibility levels](admin_area/settings/visibility_and_access_controls.md#restrict-visibility-levels). +- For more granular control of project features, you can + [change the visibility of features](project/working_with_projects.md#change-the-visibility-of-individual-features-in-a-project). <!-- ## Troubleshooting diff --git a/doc/user/read_only_namespaces.md b/doc/user/read_only_namespaces.md index 345a3a87189..63d7f18f70c 100644 --- a/doc/user/read_only_namespaces.md +++ b/doc/user/read_only_namespaces.md @@ -19,7 +19,7 @@ information, see [Restricted actions](#restricted-actions). ## Remove the read-only state -To restore a namespace to its normal state, you can: +To restore a namespace to its standard state, you can: - For exceeded free user limits: - [Reduce the number of members](free_user_limit.md#manage-members-in-your-namespace) in your namespace. diff --git a/doc/user/report_abuse.md b/doc/user/report_abuse.md index fde839c3ba4..aabc9c5dff1 100644 --- a/doc/user/report_abuse.md +++ b/doc/user/report_abuse.md @@ -27,7 +27,8 @@ You can report a user through their: To report abuse from a user's profile page: 1. Anywhere in GitLab, select the name of the user. -1. In the top right corner of the user's profile, select **Report abuse to administrator** (**{information-o}**). +1. In the upper-right corner of the user's profile, select **Report abuse to administrator** (**{information-o}**). +1. Select a reason for reporting the user. 1. Complete an abuse report. 1. Select **Send report**. @@ -35,8 +36,9 @@ To report abuse from a user's profile page: To report abuse from a user's comment: -1. In the comment, in the top right corner, select **More actions** (**{ellipsis_v}**). +1. In the comment, in the upper-right corner, select **More actions** (**{ellipsis_v}**). 1. Select **Report abuse to administrator**. +1. Select a reason for reporting the user. 1. Complete an abuse report. 1. Select **Send report**. @@ -46,16 +48,18 @@ A URL to the reported user's comment is pre-filled in the abuse report's ## Report abuse from an issue -1. On the issue, in the top right corner, select the vertical ellipsis (**{ellipsis_v}**). +1. On the issue, in the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**). 1. Select **Report abuse to administrator**. -1. Submit an abuse report. +1. Select a reason for reporting the user. +1. Complete an abuse report. 1. Select **Send report**. ## Report abuse from a merge request -1. On the merge request, in the top right corner, select the vertical ellipsis (**{ellipsis_v}**). +1. On the merge request, in the upper-right corner, select the vertical ellipsis (**{ellipsis_v}**). 1. Select **Report abuse to administrator**. -1. Submit an abuse report. +1. Select a reason for reporting this user. +1. Complete an abuse report. 1. Select **Send report**. ## Related topics diff --git a/doc/user/search/exact_code_search.md b/doc/user/search/exact_code_search.md new file mode 100644 index 00000000000..14dca6d4a12 --- /dev/null +++ b/doc/user/search/exact_code_search.md @@ -0,0 +1,28 @@ +--- +stage: Data Stores +group: Global Search +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" +type: reference +--- + +# Exact Code Search **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105049) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `index_code_with_zoekt` and `search_code_with_zoekt` which enables indexing and searching respectively. Both are disabled by default. + +WARNING: +Exact Code Search is an MVC. For the Exact Code Search feature roadmap, see [epic 9404](https://gitlab.com/groups/gitlab-org/-/epics/9404). +When this feature reaches the [**Alpha**](../../policy/alpha-beta-support.md#alpha-features) version, GitLab will dogfood it, and roll it out only to specific customers on GitLab.com who request access to it. +On self-managed GitLab, this feature is available and can be enabled. However, GitLab does not provide support or documentation at this development stage. + +## Usage + +When performing any Code search in GitLab it will choose to use "Exact Code +Search" powered by [Zoekt](https://github.com/sourcegraph/zoekt) if the project +is part of an enabled Group. + +The main differences between Zoekt and [Advanced Search](advanced_search.md) +are that Zoekt provides exact substring matching as well as allows you to +search for regular expressions. Since it allows searching for regular +expressions, certain special characters will require escaping. Backslash can +escape special characters and wrapping in double quotes can be used for phrase +searches. diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 9536f7fe40a..dc07b4c9215 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -50,7 +50,7 @@ Global search only flags with an error any search that includes more than: ## Perform a search -To start a search, type your search query in the search bar on the top-right of the screen. +To start a search, type your search query in the search bar in the upper right of the screen. You must type at least two characters.  @@ -84,6 +84,23 @@ where the results were found.  +## Search for projects by full path + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108906) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `full_path_project_search`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. +To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `full_path_project_search`. +On GitLab.com, this feature is not available. + +You can search for a project by entering its full path (including the namespace it belongs to) in the search box. +As you type the project path, [autocomplete suggestions](#autocomplete-suggestions) are displayed. + +For example, the search query: + +- `gitlab-org/gitlab` searches for the `gitlab` project in the `gitlab-org` namespace. +- `gitlab-org/` displays autocomplete suggestions for projects that belong to the `gitlab-org` namespace. + ## Search for a SHA You can search for a commit SHA. @@ -113,7 +130,7 @@ You can filter issues and merge requests by specific terms included in titles or issues for `included in titles` is same as `included titles` - Search is limited to 4096 characters and 64 terms per query. - When searching issues, partial matches are not allowed. For example: searching for `play` will - not return issues that have the word `display`. But variations of words will still match, so searching + not return issues that have the word `display`. But variations of words match, so searching for `displays` also returns issues that have the word `display`. ## Retrieve search results as feed @@ -149,7 +166,7 @@ To delete filter tokens one at a time, the <kbd>⌥</kbd> (Mac) / <kbd>Control</ In the search bar, you can view autocomplete suggestions for: -- Projects and groups +- [Projects](#search-for-projects-by-full-path) and groups - Users - Various help pages (try and type **API help**) - Project feature pages (try and type **milestones**) diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index 64f9b53f891..d67c595512a 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 application, select **Keyboard shortcuts**. +- In the Help menu in the upper right of the application, select **Keyboard shortcuts**. Although [global shortcuts](#global-shortcuts) work from any area of GitLab, you must be in specific pages for the other shortcuts to be available, as @@ -333,6 +333,13 @@ To disable keyboard shortcuts: press <kbd>?</kbd> to display the list of shortcuts. 1. Select **Toggle shortcuts**. +## Enable keyboard shortcuts + +To enable keyboard shortcuts: + +1. On the top bar, select the Help menu (**{question}**), then **Keyboard shortcuts**. +1. Select **Toggle shortcuts**. + ## Troubleshooting ### Linux shortcuts diff --git a/doc/user/snippets.md b/doc/user/snippets.md index 70669748cd8..0532ed27010 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -149,7 +149,7 @@ by a Git repository), through the [Snippets API](../api/snippets.md), and in the To add a new file to your snippet through the GitLab UI: 1. Go to your snippet in the GitLab UI. -1. Select **Edit** in the top right corner. +1. Select **Edit** in the upper-right corner. 1. Select **Add another file**. 1. Add your content to the file in the form fields provided. 1. Select **Save changes**. @@ -157,7 +157,7 @@ To add a new file to your snippet through the GitLab UI: To delete a file from your snippet through the GitLab UI: 1. Go to your snippet in the GitLab UI. -1. Select **Edit** in the top right corner. +1. Select **Edit** in the upper-right corner. 1. Select **Delete file** alongside the filename of each file you wish to delete. 1. Select **Save changes**. diff --git a/doc/user/ssh.md b/doc/user/ssh.md index b71b120d246..d44e6a0e071 100644 --- a/doc/user/ssh.md +++ b/doc/user/ssh.md @@ -13,6 +13,23 @@ GitLab uses the SSH protocol to securely communicate with Git. When you use SSH keys to authenticate to the GitLab remote server, you don't need to supply your username and password each time. +## What are SSH keys + +SSH uses two keys, a public key and a private key. + +- The public key can be distributed. +- The private key should be protected. + +When you need to copy or upload your SSH public key, make sure you do not accidentally copy or upload your private key instead. + +You cannot expose data by uploading your public key. When you need to copy or upload your SSH public key, make sure you do not accidentally copy or upload your private key instead. + +You can use your private key to [sign commits](project/repository/ssh_signed_commits/index.md), +which makes your use of GitLab and your data even more secure. +This signature then can be verified by anyone using your public key. + +For details, see [Asymmetric cryptography, also known as public-key cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography). + ## Prerequisites To use SSH to communicate with GitLab, you need: @@ -262,7 +279,7 @@ You can use [1Password](https://1password.com/) and the [1Password browser exten - Use an existing SSH in your 1Password vault to authenticate with GitLab. 1. Sign in to GitLab. -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **SSH Keys**. 1. Select **Key**, and you should see the 1Password helper appear. @@ -274,7 +291,7 @@ You can use [1Password](https://1password.com/) and the [1Password browser exten 1. Optional. Update **Expiration date** to modify the default expiration date. 1. Select **Add key**. -To learn more about using 1Password with SSH keys, see [1Password's documentation](https://developer.1password.com/docs/ssh/get-started). +For more information about using 1Password with SSH keys, see the [1Password documentation](https://developer.1password.com/docs/ssh/get-started). ## Add an SSH key to your GitLab account @@ -307,7 +324,7 @@ To use SSH with GitLab, copy your public key to your GitLab account: Replace `id_ed25519.pub` with your filename. For example, use `id_rsa.pub` for RSA. 1. Sign in to GitLab. -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Preferences**. 1. On the left sidebar, select **SSH Keys**. 1. In the **Key** box, paste the contents of your public key. @@ -377,6 +394,24 @@ git config core.sshCommand "ssh -o IdentitiesOnly=yes -i ~/.ssh/private-key-file This command does not use the SSH Agent and requires Git 2.10 or later. For more information on `ssh` command options, see the `man` pages for both `ssh` and `ssh_config`. +## View your account's SSH keys + +1. Sign in to GitLab. +1. On the top bar, in the upper-right corner, select your avatar. +1. Select **Preferences**. +1. On the left sidebar, select **SSH Keys**. + +Your existing SSH keys are listed at the bottom of the page. The information includes: + +- The key's: + - Name. + - Public fingerprint. + - Expiry date. + - Permitted usage types. +- The time a key was last used. On GitLab.com this value is unavailable, and you are unable to see if or when an SSH key has been used. For more information, see [issue 324764](https://gitlab.com/gitlab-org/gitlab/-/issues/324764). + +Select **Delete** to permanently delete an SSH key. + ## Use different accounts on a single GitLab instance You can use multiple accounts to connect to a single instance of GitLab. You diff --git a/doc/user/tasks.md b/doc/user/tasks.md index aad53f4165c..42a3975a9d2 100644 --- a/doc/user/tasks.md +++ b/doc/user/tasks.md @@ -58,6 +58,28 @@ To create a task: 1. Enter the task title. 1. Select **Create task**. +### Create a task from a task list item + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377307) in GitLab 15.9 [with a flag](../administration/feature_flags.md) named `work_items_mvc`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. +To make it available, ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `work_items_mvc`. +On GitLab.com, this feature is not available. +The feature is not ready for production use. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +In an issue description with task list items: + +1. Hover over a task list item and select the options menu (**{ellipsis_v}**). +1. Select **Convert to task**. + +The task list item is removed from the issue description and a task is created in the tasks widget from its contents. +Any nested task list items are moved up a nested level. + ## Add existing tasks to an issue > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381868) in GitLab 15.6. diff --git a/doc/user/todos.md b/doc/user/todos.md index 221e89d658c..50b60dc5b4b 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -21,7 +21,7 @@ You can use the To-Do List to track [actions](#actions-that-create-to-do-items) To access your To-Do List: -On the top bar, in the top right, select To-Do List (**{task-done}**). +On the top bar, in the upper right, select To-Do List (**{task-done}**). ## Search the To-Do List @@ -117,17 +117,28 @@ Hi, please message @frank :incoming_envelope: ## Actions that mark a to-do item as done -Any action to an issue, merge request, or epic marks its +Various actions on the to-do item object (like issue, merge request, or epic) mark its corresponding to-do item as done. -Actions that dismiss to-do items include: +To-do items are marked as done if you: -- Changing the assignee -- Changing the milestone -- Closing the issue or merge request -- Adding or removing a label -- Commenting on the issue -- Resolving a [design discussion thread](project/issues/design_management.md#resolve-a-discussion-thread-on-a-design) +- Add an award emoji to the description or comment. +- Add or remove a label. +- Change the assignee. +- Change the milestone. +- Close the to-do item's object. +- Create a comment. +- Edit the description. +- Resolve a [design discussion thread](project/issues/design_management.md#resolve-a-discussion-thread-on-a-design). +- Accept or deny a project or group membership request. + +To-do items are **not** marked as done if you: + +- Add a linked item (like a [linked issue](project/issues/related_issues.md)). +- Add a child item (like [child epic](group/epics/manage_epics.md#multi-level-child-epics) or [task](tasks.md)). +- Add a [time entry](project/time_tracking.md). +- Assign yourself. +- Change the [health status](project/issues/managing_issues.md#health-status). If someone else closes, merges, or takes action on an issue, merge request, or epic, your to-do item remains pending. @@ -147,7 +158,7 @@ There are two ways to do this: You can mark all your to-do items as done at the same time. -In the To-Do List, in the top right, select **Mark all as done**. +In the To-Do List, in the upper right, select **Mark all as done**. ## How a user's To-Do List is affected when their access changes diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index c6c27f36618..0740108a168 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -35,6 +35,13 @@ is updated every 90 minutes. If your namespace shows `'Not applicable.'`, push a commit to any project in the namespace to recalculate the storage. +### Container Registry usage **(FREE SAAS)** + +Container Registry usage is available only for GitLab.com. This feature requires a +[new version](https://about.gitlab.com/blog/2022/04/12/next-generation-container-registry/) +of the GitLab Container Registry. To learn about the proposed release for self-managed +installations, see [epic 5521](https://gitlab.com/groups/gitlab-org/-/epics/5521). + ### Storage usage statistics > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68898) project-level graph in GitLab 14.4 [with a flag](../administration/feature_flags.md) named `project_storage_ui`. Disabled by default. @@ -66,8 +73,8 @@ Depending on your role, to manage your transfer usage you can [reduce Container ## Project storage limit -Projects on GitLab SaaS have a 10GB storage limit on their Git repository and LFS storage. -After namespace-level storage limits are applied, the project limit will be removed. A namespace has either a namespace-level storage limit or a project-level storage limit, but not both. +Projects on GitLab SaaS have a 10 GB storage limit on their Git repository and LFS storage. +After namespace-level storage limits are applied, the project limit is removed. A namespace has either a namespace-level storage limit or a project-level storage limit, but not both. When a project's repository and LFS reaches the quota, the project is locked. You cannot push changes to a locked project. To monitor the size of each @@ -122,7 +129,7 @@ available decreases. All projects remain unlocked because 40 GB purchased storag ## Namespace storage limit Namespaces on GitLab SaaS have a storage limit. For more information, see our [pricing page](https://about.gitlab.com/pricing/). -This limit is not visible on the **Usage quotas** page, but will be prior to the limit being [applied](#namespace-storage-limit-application-schedule). Self-managed deployments are not affected. +This limit is not visible on the **Usage quotas** page, but is prior to the limit being [applied](#namespace-storage-limit-application-schedule). Self-managed deployments are not affected. Storage types that add to the total namespace storage are: @@ -137,15 +144,21 @@ Storage types that add to the total namespace storage are: If your total namespace storage exceeds the available namespace storage quota, all projects under the namespace become read-only. Your ability to write new data is restricted until the read-only state is removed. For more information, see [Restricted actions](../user/read_only_namespaces.md#restricted-actions). +To notify you that you have nearly exceeded your namespace storage quota: + +- In the command line interface, a notification displays after each `git push` action when you've reached 95% and 100% of your namespace storage quota. +- In the GitLab UI, a notification displays when you've reached 75%, 95%, and 100% of your namespace storage quota. +- GitLab sends an email to members with the Owner role to notify them when namespace storage usage is at 70%, 85%, 95%, and 100%. + To prevent exceeding the namespace storage quota, you can: - Reduce storage consumption by following the suggestions in the [Manage Your Storage Usage](#manage-your-storage-usage) section of this page. - Apply for [GitLab for Education](https://about.gitlab.com/solutions/education/join/), [GitLab for Open Source](https://about.gitlab.com/solutions/open-source/join/), or [GitLab for Startups](https://about.gitlab.com/solutions/startups/) if you meet the eligibility requirements. - Consider using a [self-managed instance](../subscriptions/self_managed/index.md) of GitLab which does not have these limits on the free tier. -- [Purchase additional storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer) units at $60/year for 10GB of storage. +- [Purchase additional storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer) units at $60/year for 10 GB of storage. - [Start a trial](https://about.gitlab.com/free-trial/) or [upgrade to GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) which include higher limits and features that enable growing teams to ship faster without sacrificing on quality. -- [Talk to an expert](https://page.gitlab.com/usage_limits_help.html) to learn more about your options and ask questions. +- [Talk to an expert](https://page.gitlab.com/usage_limits_help.html) for more information about your options. ### Namespace storage limit application schedule -Information on when namespace-level storage limits will be applied is available on these FAQ pages for the [Free](https://about.gitlab.com/pricing/faq-efficient-free-tier/#storage-limits-on-gitlab-saas-free-tier) and [Paid](https://about.gitlab.com/pricing/faq-paid-storage-transfer/) tier. +Information on when namespace-level storage limits are applied is available on these FAQ pages for the [Free](https://about.gitlab.com/pricing/faq-efficient-free-tier/#storage-limits-on-gitlab-saas-free-tier) and [Paid](https://about.gitlab.com/pricing/faq-paid-storage-transfer/) tier. |
