diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-06-20 14:10:13 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-06-20 14:10:13 +0300 |
| commit | 0ea3fcec397b69815975647f5e2aa5fe944a8486 (patch) | |
| tree | 7979381b89d26011bcf9bdc989a40fcc2f1ed4ff /doc/user | |
| parent | 72123183a20411a36d607d70b12d57c484394c8e (diff) | |
Add latest changes from gitlab-org/gitlab@15-1-stable-eev15.1.0-rc42
Diffstat (limited to 'doc/user')
245 files changed, 2729 insertions, 2093 deletions
diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index 2083cb06f93..4c3bdde223b 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -7,7 +7,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/customization/branded_login_page. # GitLab Appearance **(FREE SELF)** -There are several options for customizing the appearance of a self-managed instance +Several options are available for customizing the appearance of a self-managed instance of GitLab. To access these settings: 1. On the top bar, select **Menu > Admin**. @@ -19,11 +19,13 @@ By default, the navigation bar has the GitLab logo, but this can be customized w any image desired. It is optimized for images 28px high (any width), but any image can be used (less than 1 MB) and it is automatically resized. -After you select and upload an image, click **Update appearance settings** at the bottom +After you select and upload an image, select **Update appearance settings** at the bottom of the page to activate it in the GitLab instance. NOTE: -GitLab pipeline emails also display the custom logo. +GitLab pipeline emails also display the custom logo, unless the logo is in SVG format. If the +custom logo is in SVG format, the default logo is used instead because the SVG format is not +supported by many email clients. ## Favicon @@ -31,7 +33,7 @@ By default, the favicon (used by the browser as the tab icon, as well as the CI uses the GitLab logo, but this can be customized with any icon desired. It must be a 32x32 `.png` or `.ico` image. -After you select and upload an icon, click **Update appearance settings** at the bottom +After you select and upload an icon, select **Update appearance settings** at the bottom of the page to activate it in the GitLab instance. ## System header and footer messages @@ -48,7 +50,7 @@ as the header and footer messages can only be a single line. If desired, you can select **Enable header and footer in emails** to have the text of the header and footer added to all emails sent by the GitLab instance. -After you add a message, click **Update appearance settings** at the bottom of the page +After you add a message, select **Update appearance settings** at the bottom of the page to activate it in the GitLab instance. ## Sign in / Sign up pages @@ -60,8 +62,8 @@ The optimal size for the logo is 640x360px, but any image can be used (below 1MB and it is resized automatically. The logo image appears between the title and the description, on the left of the sign-up page. -After you add a message, click **Update appearance settings** at the bottom of the page -to activate it in the GitLab instance. You can also click on the **Sign-in page** button, +After you add a message, select **Update appearance settings** at the bottom of the page +to activate it in the GitLab instance. You can also select **Sign-in page**, to review the saved appearance settings: NOTE: @@ -75,9 +77,9 @@ You can make full use of [Markdown](../markdown.md) in the description: The message is displayed below the **New Project** message, on the left side of the **New project page**. -After you add a message, click **Update appearance settings** at the bottom of the page -to activate it in the GitLab instance. You can also click on the **New project page** -button, which brings you to the new project page so you can review the change. +After you add a message, select **Update appearance settings** at the bottom of the page +to activate it in the GitLab instance. You can also select **New project page**, +which brings you to the new project page so you can review the change. ## Libravatar diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index 9d6dcf30908..9d4c1ffe375 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -70,7 +70,7 @@ To add a broadcast message: 1. Select the **Dismissable** checkbox to enable users to dismiss the broadcast message. 1. Optional. Select **Target roles** to only show the broadcast message to users with the selected roles. The message displays on group, subgroup, and project pages, and does not display in Git remote responses. 1. If required, add a **Target Path** to only show the broadcast message on URLs matching that path. You can use the wildcard character `*` to match multiple URLs, for example `mygroup/myproject*`. -1. Select a date for the message to start and end. +1. Select a date and time (UTC) for the message to start and end. 1. Select **Add broadcast message**. When a broadcast message expires, it no longer displays in the user interface but is still listed in the @@ -78,7 +78,7 @@ list of broadcast messages. ## Edit a broadcast message -If you need to make changes to a broadcast message, you can edit it. +If you must make changes to a broadcast message, you can edit it. To edit a broadcast message: diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index 976d8e4efcf..c3c580a91c3 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -17,7 +17,7 @@ Every project in the group, but not its subgroups, can be selected when a new pr is created, based on the user's access permissions: - Public projects can be selected by any signed-in user as a template for a new project, - if all enabled [project features](../project/settings/index.md#sharing-and-permissions) + if all enabled [project features](../project/settings/index.md#configure-project-visibility-features-and-permissions) except for **GitLab Pages** and **Security & Compliance** are set to **Everyone With Access**. The same applies to internal projects. - Private projects can be selected only by users who are members of the projects. diff --git a/doc/user/admin_area/geo_nodes.md b/doc/user/admin_area/geo_nodes.md index 43dce1921f4..3c33578b88f 100644 --- a/doc/user/admin_area/geo_nodes.md +++ b/doc/user/admin_area/geo_nodes.md @@ -1,5 +1,5 @@ --- -stage: Enablement +stage: Systems group: Geo info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 262bb2cc931..8f36021084e 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -105,7 +105,7 @@ To filter only projects in that namespace, select from the **Namespace** dropdow You can combine the filter options. For example, to list only public projects with `score` in their name: -1. Click the **Public** tab. +1. Select the **Public** tab. 1. Enter `score` in the **Filter by name...** input box. ### Administering Users @@ -115,7 +115,7 @@ You can administer all users in the GitLab instance from the Admin Area's Users 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. -To list users matching a specific criteria, click on one of the following tabs on the **Users** page: +To list users matching a specific criteria, select one of the following tabs on the **Users** page: - **Active** - **Admins** @@ -135,13 +135,13 @@ For each user, the following are listed: 1. Date of account creation 1. Date of last activity -To edit a user, click the **Edit** button in that user's -row. To delete the user, or delete the user and their contributions, click the cog dropdown in +To edit a user, select the **Edit** button in that user's +row. To delete the user, or delete the user and their contributions, select the cog dropdown in that user's row, and select the desired option. To change the sort order: -1. Click the sort dropdown. +1. Select the sort dropdown. 1. Select the desired order. By default the sort dropdown shows **Name**. @@ -240,17 +240,17 @@ To access the Groups page: 1. On the left sidebar, select **Overview > Groups**. For each group, the page displays their name, description, size, number of projects in the group, -number of members, and whether the group is private, internal, or public. To edit a group, click -the **Edit** button in that group's row. To delete the group, click the **Delete** button in +number of members, and whether the group is private, internal, or public. To edit a group, select +the **Edit** button in that group's row. To delete the group, select the **Delete** button in that group's row. -To change the sort order, click the sort dropdown and select the desired order. The default +To change the sort order, select the sort dropdown and select the desired order. The default sort order is by **Last created**. To search for groups by name, enter your criteria in the search field. The group search is case insensitive, and applies partial matching. -To [Create a new group](../group/index.md#create-a-group) click **New group**. +To [Create a new group](../group/index.md#create-a-group) select **New group**. ### Administering Topics @@ -286,7 +286,7 @@ To access the Jobs page: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Jobs**. All jobs are listed, in descending order of job ID. -1. Click the **All** tab to list all jobs. Click the **Pending**, **Running**, or **Finished** +1. Select the **All** tab to list all jobs. Select the **Pending**, **Running**, or **Finished** tab to list only jobs of that status. For each job, the following details are listed: @@ -313,14 +313,7 @@ To access the **Runners** page: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Runners**. -The **Runners** page features: - -- A description of runners and their possible states. -- Instructions on installing a runner. -- A list of all registered runners. - -Runners are listed in descending order by the date they were created, by default. You can change -the sort order to *Last Contacted* from the dropdown beside the search field. +#### Search and filter runners To search runners' descriptions: @@ -336,20 +329,18 @@ You can also filter runners by status, type, and tag. To filter:  +#### Runner attributes + For each runner, the following attributes are listed: | Attribute | Description | |--------------|-------------| -| Type/State | One or more of the following states: shared, group, specific, locked, or paused | -| Runner token | Partial token used to identify the runner, and which the runner uses to communicate with the GitLab instance | -| Runner ID | Numerical ID of the runner | -| Description | Description given to the runner | -| Version | GitLab Runner version | -| IP address | IP address of the host on which the runner is registered | -| Projects | Number of projects to which the runner is assigned | -| Jobs | Total of jobs run by the runner | -| Tags | Tags associated with the runner | -| Last contact | Timestamp indicating when the runner last contacted the GitLab instance | +| Status | The status of the runner. In [GitLab 15.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/22224), for the **Ultimate** tier, the upgrade status is available. | +| Runner details | Information about the runner, including partial token and details about the computer the runner was registered from. | +| Version | GitLab Runner version. | +| Jobs | Total number of jobs run by the runner. | +| Tags | Tags associated with the runner. | +| Last contact | Timestamp indicating when the runner last contacted the GitLab instance. | You can also edit, pause, or remove each runner. diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index 773f91d3076..ac5e5ded859 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -36,7 +36,7 @@ To activate your instance with an activation code: The subscription is activated. -If you have an offline or air gapped environment, +If you have an offline environment, [activate GitLab EE with a license file or key](license_file.md) instead. If you have questions or need assistance activating your instance, @@ -64,6 +64,6 @@ This error occurs when you use an activation code to activate your instance, but You may have connectivity issues due to the following reasons: -- **You have an offline or air gapped environment**: Configure your setup to allow connection to GitLab servers. If connection to GitLab servers is not possible, contact [GitLab support](https://about.gitlab.com/support/#contact-support) to request a license key. +- **You have an offline environment**: Configure your setup to allow connection to GitLab servers. If connection to GitLab servers is not possible, contact [GitLab support](https://about.gitlab.com/support/#contact-support) to request a license key. - **Firewall settings**: Enable an encrypted HTTPS connection from your GitLab instance to `customers.gitlab.com` (with IP addresses 104.18.26.123 and 104.18.27.123) on port 443. - **Customers Portal is not operational**: To check for performance or service disruptions, check the Customers Portal [status](https://status.gitlab.com/). diff --git a/doc/user/admin_area/license_file.md b/doc/user/admin_area/license_file.md index ff9e87680f9..be1b1a16e29 100644 --- a/doc/user/admin_area/license_file.md +++ b/doc/user/admin_area/license_file.md @@ -4,6 +4,8 @@ group: Provision info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- +<!-- To promote the workflow described in license.md, this page is not included in global left nav. --> + # Activate GitLab EE with a license file or key If you receive a license file from GitLab (for example, for a trial), you can @@ -47,6 +49,17 @@ WARNING: These methods only add a license at the time of installation. To renew or upgrade a license, add the license in the **Admin Area** in the web user interface. +## Submit license usage data + +If you use a license file or key to activate your instance in an offline environment, you must submit your license +usage data monthly. +To submit the data, [export your license usage](../../subscriptions/self_managed/index.md#export-your-license-usage) +and send it by email to the renewals service, `renewals-service@customers.gitlab.com`. + +If you don't submit your data each month after your subscription start date, a banner displays to remind you to +submit your data. The banner displays in the **Admin Area** on the **Dashboard** and on the **Subscription** +pages. You can only dismiss it until the following month after you submit your license usage data. + ## What happens when your license expires Fifteen days before the license expires, a notification banner with the upcoming expiration diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index ed7fdfe2111..526e8cd17da 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -22,7 +22,7 @@ To enable merge request approval settings for an instance: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **{push-rules}** **Push Rules**, and expand **Merge request approvals**. 1. Choose the required options. -1. Click **Save changes**. +1. Select **Save changes**. ## Available rules @@ -38,4 +38,4 @@ Merge request approval settings that can be set at an instance level are: See also the following, which are affected by instance-level rules: - [Project merge request approval rules](../project/merge_requests/approvals/index.md). -- [Group merge request approval settings](../group/index.md#group-approval-settings) available in GitLab 13.9 and later. +- [Group merge request approval settings](../group/index.md#group-merge-request-approval-settings) available in GitLab 13.9 and later. diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index 53c08d8cbc1..dc6ff96c31f 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -171,8 +171,12 @@ Users can also be deactivated using the [GitLab API](../../api/users.md#deactiva > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320875) in GitLab 14.0. -Administrators can enable automatic deactivation of users who have not signed in, or have no activity -in the last 90 days. To do this: +Administrators can enable automatic deactivation of users who either: + +- Were created more than a week ago and have not signed in. +- Have no activity in the last 90 days. + +To do this: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. @@ -246,3 +250,33 @@ A banned user can be unbanned using the Admin Area. To do this: The user's state is set to active and they consume a [seat](../../subscriptions/self_managed/index.md#billable-users). + +### Delete a user + +Use the Admin Area to delete users. + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Users**. +1. Select the **Banned** tab. +1. Optional. Select a user. +1. Select the **{settings}** **User administration** dropdown list. +1. Select **Delete user**. +1. Type the username. +1. Select **Delete user**. + +NOTE: +You can only delete a user if there are inherited or direct owners of a group. You cannot delete a user if they are the only group owner. + +You can also delete a user and their contributions, such as merge requests, issues, and groups of which they are the only group owner. + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Users**. +1. Select the **Banned** tab. +1. Optional. Select a user. +1. Select the **{settings}** **User administration** dropdown list. +1. Select **Delete user and contributions**. +1. Type the username. +1. Select **Delete user and contributions**. + +NOTE: +Before 15.1, additionally groups of which deleted user were the only owner among direct members were deleted. diff --git a/doc/user/admin_area/monitoring/background_migrations.md b/doc/user/admin_area/monitoring/background_migrations.md index b666c0c5ad2..53d5056bb65 100644 --- a/doc/user/admin_area/monitoring/background_migrations.md +++ b/doc/user/admin_area/monitoring/background_migrations.md @@ -1,5 +1,5 @@ --- -stage: Enablement +stage: Data Stores group: Database info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 213bddec325..84c7fa3c419 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -12,14 +12,14 @@ database connection, Redis connection, and access to the file system. These endpoints [can be provided to schedulers like Kubernetes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/) to hold traffic until the system is ready or restart the container as needed. -## IP whitelist +## IP allowlist -To access monitoring resources, the requesting client IP needs to be included in a whitelist. -For details, see [how to add IPs to a whitelist for the monitoring endpoints](../../../administration/monitoring/ip_whitelist.md). +To access monitoring resources, the requesting client IP needs to be included in the allowlist. +For details, see [how to add IPs to the allowlist for the monitoring endpoints](../../../administration/monitoring/ip_whitelist.md). ## Using the endpoints locally -With default whitelist settings, the probes can be accessed from localhost using the following URLs: +With default allowlist settings, the probes can be accessed from localhost using the following URLs: ```plaintext GET http://localhost/-/health diff --git a/doc/user/admin_area/reporting/spamcheck.md b/doc/user/admin_area/reporting/spamcheck.md index b1ec203cffc..2360c1f2899 100644 --- a/doc/user/admin_area/reporting/spamcheck.md +++ b/doc/user/admin_area/reporting/spamcheck.md @@ -1,5 +1,5 @@ --- -stage: Enablement +stage: Systems group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md index 9905298784a..bedd648b3e7 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -112,7 +112,7 @@ To change the default global prefix: 1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Personal Access Token prefix** field. -1. Click **Save changes**. +1. Select **Save changes**. You can also configure the prefix by using the [settings API](../../../api/settings.md). @@ -148,17 +148,17 @@ These settings can be found in: - Each project's settings: 1. From the Project's homepage, navigate to **Settings > General**. 1. Fill in the **Repository size limit (MB)** field in the **Naming, topics, avatar** section. - 1. Click **Save changes**. + 1. Select **Save changes**. - Each group's settings: 1. From the Group's homepage, navigate to **Settings > General**. 1. Fill in the **Repository size limit (MB)** field in the **Naming, visibility** section. - 1. Click **Save changes**. + 1. Select **Save changes**. - GitLab global settings: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Size limit per repository (MB)** field. - 1. Click **Save changes**. + 1. Select **Save changes**. The first push of a new project, including LFS objects, is checked for size. If the sum of their sizes exceeds the maximum allowed repository size, the push @@ -186,13 +186,13 @@ To set a limit on how long these sessions are valid: 1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Session duration for Git operations when 2FA is enabled (minutes)** field. -1. Click **Save changes**. +1. Select **Save changes**. ## Limit the lifetime of SSH keys **(ULTIMATE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1007) in GitLab 14.6 [with a flag](../../../administration/feature_flags.md) named `ff_limit_ssh_key_lifetime`. Disabled by default. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/346753) in GitLab 14.6. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/1007) in GitLab 14.7. [Feature flag ff_limit_ssh_key_lifetime](https://gitlab.com/gitlab-org/gitlab/-/issues/347408) removed. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/1007) in GitLab 14.7. [Feature flag `ff_limit_ssh_key_lifetime`](https://gitlab.com/gitlab-org/gitlab/-/issues/347408) removed. Users can optionally specify a lifetime for [SSH keys](../../ssh.md). @@ -213,7 +213,7 @@ To set a lifetime on how long SSH keys are valid: 1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Maximum allowable lifetime for SSH keys (days)** field. -1. Click **Save changes**. +1. Select **Save changes**. Once a lifetime for SSH keys is set, GitLab: @@ -261,7 +261,7 @@ To set a lifetime on how long access tokens are valid: 1. On the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Maximum allowable lifetime for access tokens (days)** field. -1. Click **Save changes**. +1. Select **Save changes**. Once a lifetime for access tokens is set, GitLab: @@ -328,4 +328,4 @@ Your push has been rejected, because this repository has exceeded its size limit To resolve this problem, either of these options helps in the short- to middle-term: - Increase the [repository size limit](#repository-size-limit). -- [Reduce the repo size](../../project/repository/reducing_the_repo_size_using_git.md). +- [Reduce the repository size](../../project/repository/reducing_the_repo_size_using_git.md). diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 170d3cf4c90..7f37c99259a 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -39,6 +39,23 @@ You can set all new projects to have the instance's shared runners available by Any time a new project is created, the shared runners are available. +## Shared runners CI/CD minutes + +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 + +To enable a specific runner for one or more projects: + +1. On the top bar, select **Menu > Admin**. +1. From the left sidebar, select **Overview > Runners**. +1. Select the runner you want to edit. +1. In the top right, select **Edit** (**{pencil}**). +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. + ## Add a message for shared runners To display details about the instance's shared runners in all projects' @@ -143,10 +160,6 @@ A new pipeline must run before the latest artifacts can expire and be deleted. NOTE: All application settings have a [customizable cache expiry interval](../../../administration/application_settings_cache.md) which can delay the settings affect. -## Shared runners CI/CD minutes - -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. - ## Archive jobs Archiving jobs is useful for reducing the CI/CD footprint on the system by removing some diff --git a/doc/user/admin_area/settings/floc.md b/doc/user/admin_area/settings/floc.md index 6bfc6dfbebd..dccab461b85 100644 --- a/doc/user/admin_area/settings/floc.md +++ b/doc/user/admin_area/settings/floc.md @@ -26,7 +26,7 @@ To enable it: 1. On the left sidebar, select **Settings > General**. 1. Expand **Federated Learning of Cohorts**. 1. Check the box. -1. Click **Save changes**. +1. Select **Save changes**. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 970897fd8da..034a432c570 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -79,7 +79,7 @@ The **Geo** setting contains: The **Integrations** settings contain: -- [Elasticsearch](../../../integration/elasticsearch.md#enable-advanced-search) - +- [Elasticsearch](../../../integration/advanced_search/elasticsearch.md#enable-advanced-search) - Elasticsearch integration. Elasticsearch AWS IAM. - [Kroki](../../../administration/integration/kroki.md#enable-kroki-in-gitlab) - Allow rendering of diagrams in AsciiDoc and Markdown documents using [kroki.io](https://kroki.io). @@ -160,7 +160,7 @@ The **Preferences** settings contain: The **Reporting** settings contain: - [Spam and Anti-bot Protection](../../../integration/recaptcha.md) - - Enable anti-spam services, like reCAPTCHA, Akismet or [Spamcheck](../reporting/spamcheck.md), and set IP limits. + Enable anti-spam services, like reCAPTCHA, Akismet, or [Spamcheck](../reporting/spamcheck.md), and set IP limits. - [Abuse reports](../review_abuse_reports.md) - Set notification email for abuse reports. ### Repository diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index aadabe4d6ad..010ba6a12fc 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -25,7 +25,7 @@ Only the complete settings for an integration can be inherited. Per-field inheri 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Integrations**. 1. Select an integration. -1. Enter configuration details and click **Save changes**. +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 @@ -57,7 +57,7 @@ integration on all non-configured groups and projects by default. 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Integrations**. 1. Select an integration. -1. Click **Reset** and confirm. +1. Select **Reset** and confirm. Resetting an instance-level default setting removes the integration from all projects that have the integration set to use default settings. @@ -79,7 +79,7 @@ for an integration. 1. Navigate to the group's **Settings > Integrations**. 1. Select an integration. -1. Enter configuration details and click **Save changes**. +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. @@ -112,7 +112,7 @@ integration on all non-configured groups and projects by default. 1. Navigate to the group's **Settings > Integrations**. 1. Select an integration. -1. Click **Reset** and confirm. +1. Select **Reset** and confirm. Resetting a group-level default setting removes integrations that use default settings and belong to a project or subgroup of the group. @@ -124,7 +124,7 @@ Resetting a group-level default setting removes integrations that use default se 1. Choose the integration you want to enable or update. 1. From the drop-down, select **Use default settings**. 1. Ensure the toggle is set to **Enable integration**. -1. Click **Save changes**. +1. Select **Save changes**. ## Use custom settings for a group or project integration @@ -132,4 +132,4 @@ Resetting a group-level default setting removes integrations that use default se 1. Choose the integration you want to enable or update. 1. From the drop-down, select **Use custom settings**. 1. Ensure the toggle is set to **Enable integration** and enter all required settings. -1. Click **Save changes**. +1. Select **Save changes**. 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 2819a18d361..fce6179f5cf 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 @@ -31,3 +31,4 @@ To limit the number of pipeline requests: 1. Expand **Pipelines Rate Limits**. 1. Under **Max requests per minute**, enter a value greater than `0`. 1. Select **Save changes**. +1. Enable `ci_enforce_throttle_pipelines_creation` feature flag to enable the rate limit. diff --git a/doc/user/admin_area/settings/rate_limit_on_users_api.md b/doc/user/admin_area/settings/rate_limit_on_users_api.md index 7954055f38b..5eed989f73f 100644 --- a/doc/user/admin_area/settings/rate_limit_on_users_api.md +++ b/doc/user/admin_area/settings/rate_limit_on_users_api.md @@ -1,7 +1,7 @@ --- type: reference stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index 693b3e6c7b6..870fa7ad18e 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -23,7 +23,7 @@ To enforce acceptance of a Terms of Service and Privacy Policy: 1. Check the **All users must accept the Terms of Service and Privacy Policy to access GitLab** checkbox. 1. Input the text of the **Terms of Service and Privacy Policy**. You can use [Markdown](../../markdown.md) in this text box. -1. Click **Save changes**. +1. Select **Save changes**. For each update to the terms, a new version is stored. When a user accepts or declines the terms, GitLab records which version they accepted or declined. diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index ce949999fb8..c74906c2762 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -48,7 +48,7 @@ tier. Users can continue to access the features in a paid tier without sharing u ### Features available in 14.4 and later - [Repository size limit](../settings/account_and_limit_settings.md#repository-size-limit). -- [Restrict group access by IP address](../../group/index.md#restrict-group-access-by-ip-address). +- [Group access restriction by IP address](../../group/index.md#group-access-restriction-by-ip-address). NOTE: Registration is not yet required for participation, but may be added in a future milestone. 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 3eae0d0ff90..8a9db68b34f 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -33,49 +33,70 @@ on the instance. To alter which roles have permission to create projects: - Developers and Maintainers. 1. Select **Save changes**. -## Restrict project deletion to Administrators **(PREMIUM SELF)** +## Restrict project deletion to administrators **(PREMIUM SELF)** -Anyone with the **Owner** role, either at the project or group level, can -delete a project. To allow only users with administrator access to delete projects: +> User interface [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. -1. Sign in to GitLab as a user with Administrator access level. +By default both administrators and anyone with the **Owner** role can delete a project. To restrict project deletion to only administrators: + +1. Sign in to GitLab as a user with administrator access. 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. -1. Scroll to **Default project deletion protection**, and select **Only admins can delete project**. +1. Scroll to: + - (GitLab 15.1 and later) **Allowed to delete projects**, and select **Administrators**. + - (GitLab 15.0 and earlier) **Default project deletion projection** and select **Only admins can delete project**. 1. Select **Save changes**. -## Default delayed project deletion **(PREMIUM SELF)** +## Deletion protection **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255449) in GitLab 14.2 for groups created after August 12, 2021. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255449) in GitLab 14.2 for groups created after August 12, 2021. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) from default delayed project deletion in GitLab 15.1. +> - [Enabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89466) in GitLab 15.1. -[Delayed project deletion](../../project/settings/index.md#delayed-project-deletion) allows projects in a group (not a personal namespace) -to be deleted after a period of delay. +Instance-level protection against accidental deletion of groups and projects. -To enable delayed project deletion by default in new groups: +### Retention period -1. Check the **Default delayed project deletion** checkbox. -1. Select **Save changes**. +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. -## Default deletion delay **(PREMIUM SELF)** +Groups and projects will 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. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. +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. -By default, a project marked for deletion is permanently removed with immediate effect. -See [delayed project deletion](../../project/settings/index.md#delayed-project-deletion) to learn more. -By default, a group marked for deletion is permanently removed after seven days. +### Delayed project deletion -WARNING: -The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to -[Immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. +> 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. + +To configure delayed project deletion: + +1. Sign in to GitLab as a user with administrator access. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. +1. Expand the **Visibility and access controls** section. +1. Scroll to: + - (GitLab 15.1 and later) **Deletion projection** and select keep deleted groups and projects, and select a retention period. + - (GitLab 15.0 and earlier) **Default delayed project projection** and select **Enable delayed project deletion by + default for newly-created groups.** Then set a retention period in **Default deletion delay**. +1. Select **Save changes**. + +Deletion protection is not available for projects only (without being also being enabled for groups). + +In GitLab 15.1, and later this setting is enforced on groups when disabled and it cannot be overridden. + +### Delayed group deletion -The default period is seven days, and can be changed. Setting this period to `0` enables immediate removal -of projects or groups. +> User interface [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. -To change this period: +Groups will remain restorable if the retention period is `1` or more days. -1. Select the desired option. -1. Click **Save changes**. +In GitLab 15.1 and later, delayed group deletion can be enabled by setting **Deletion projection** to **Keep deleted**. ### Override defaults and delete immediately @@ -95,7 +116,7 @@ To set the default [visibility levels for new projects](../../public_access.md): 1. Expand the **Visibility and access controls** section. 1. Select the desired default project visibility: - **Private** - Project access must be granted explicitly to each user. If this - project is part of a group, access will be granted to members of the group. + project is part of a group, access is granted to members of the group. - **Internal** - The project can be accessed by any logged in user except external users. - **Public** - The project can be accessed without any authentication. 1. Select **Save changes**. @@ -142,7 +163,9 @@ To restrict visibility levels for projects, snippets, and selected pages: 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 logged in users via the Web interface. - - User attributes are only visible to authenticated users via the GraphQL API. + - 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. 1. Select **Save changes**. For more details on project visibility, see @@ -226,7 +249,7 @@ For example, if: To specify a custom Git clone URL for HTTP(S): 1. Enter a root URL for **Custom Git clone URL for HTTP(S)**. -1. Click on **Save changes**. +1. Select **Save changes**. NOTE: SSH clone URLs can be customized in `gitlab.rb` by setting `gitlab_rails['gitlab_ssh_host']` and @@ -239,7 +262,7 @@ These options specify the permitted types and lengths for SSH keys. To specify a restriction for each key type: 1. Select the desired option from the dropdown. -1. Click **Save changes**. +1. Select **Save changes**. For more details, see [SSH key restrictions](../../../security/ssh_keys_restrictions.md). @@ -251,6 +274,33 @@ work in every repository. They can only be re-enabled by an administrator user o  +## Configure globally-allowed IP address ranges + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87579) in GitLab 15.1 [with a flag](../../../administration/feature_flags.md) named `group_ip_restrictions_allow_global`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available +per group, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) +named `group_ip_restrictions_allow_global`. +On GitLab.com, this feature is available. + +This setting allows you to set IP address ranges to be combined with group-level IP allowlists. +It helps administrators prevent aspects of the GitLab installation from being blocked +from working as intended when an IP allowlist is used. + +For example, if the GitLab Pages daemon runs on the `10.0.0.0/24` range, specify that range in this +field, as otherwise any group-level restrictions that don't include that range cause the Pages +daemon to be unable to fetch artifacts from the pipeline runs. + +To add a IP address range to the group-level allowlist: + +1. Sign in to GitLab as a user with Administrator access level. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. +1. Expand the **Visibility and access controls** section. +1. In **Globally-allowed IP ranges**, provide a value. +1. Select **Save changes**. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index f0de1e58891..920b651c094 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -6,13 +6,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w # CI/CD analytics **(FREE)** -## Pipeline success and duration charts +Use the CI/CD analytics page to view pipeline success rates and duration, and the history of [DORA metrics](index.md#devops-research-and-assessment-dora-key-metrics) over time. -> [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/38318) to CI/CD Analytics in GitLab 12.8. +## Pipeline success and duration charts CI/CD analytics shows the history of your pipeline successes and failures, as well as how long each pipeline ran. +Pipeline statistics are gathered by collecting all available pipelines for the +project, regardless of status. The data available for each individual day is based +on when the pipeline was created. + +The total pipeline calculation includes child +pipelines and pipelines that failed with an invalid YAML. To filter pipelines based on other attributes, use the [Pipelines API](../../api/pipelines.md#list-project-pipelines). + View successful pipelines:  @@ -21,12 +28,6 @@ View pipeline duration history:  -Pipeline statistics are gathered by collecting all available pipelines for the -project regardless of status. The data available for each individual day is based -on when the pipeline was created. The total pipeline calculation includes child -pipelines and pipelines that failed with invalid YAML. If you are interested in -filtering pipelines based on other attributes, consider using the [Pipelines API](../../api/pipelines.md#list-project-pipelines). - ## View CI/CD analytics To view CI/CD analytics: @@ -43,6 +44,8 @@ frequency to the `production` environment. The environment must be part of the [production deployment tier](../../ci/environments/index.md#deployment-tier-of-environments) for its deployment information to appear on the graphs. + Deployment frequency is one of the four [DORA metrics](index.md#devops-research-and-assessment-dora-key-metrics) that DevOps teams use for measuring excellence in software delivery. + The deployment frequency chart is available for groups and projects. To view the deployment frequency chart: @@ -65,6 +68,8 @@ merge requests to be deployed to a production environment. This chart is availab - For time periods in which no merge requests were deployed, the charts render a red, dashed line. + lead time for changes is one of the four [DORA metrics](index.md#devops-research-and-assessment-dora-key-metrics) that DevOps teams use for measuring excellence in software delivery. + To view the lead time for changes chart: 1. On the top bar, select **Menu > Projects** and find your project. @@ -72,3 +77,19 @@ To view the lead time for changes chart: 1. Select the **Lead time** tab.  + +## View time to restore service chart **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356959) in GitLab 15.1 + +The time to restore service chart shows information about the median time an incident was open in a production environment. This chart is available for groups and projects. + +Time to restore service is one of the four [DORA metrics](index.md#devops-research-and-assessment-dora-key-metrics) that DevOps teams use for measuring excellence in software delivery. + +To view the time to restore service chart: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > CI/CD Analytics**. +1. Select the **Time to restore service** tab. + + diff --git a/doc/user/analytics/img/time_to_restore_service_charts_v15_1.png b/doc/user/analytics/img/time_to_restore_service_charts_v15_1.png Binary files differnew file mode 100644 index 00000000000..25aac385750 --- /dev/null +++ b/doc/user/analytics/img/time_to_restore_service_charts_v15_1.png diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 017a0c46570..91d9bd918b6 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -81,7 +81,7 @@ Deployment frequency displays in several charts: Lead time for changes measures the time to deliver a feature once it has been developed, as described in [Measuring DevOps Performance](https://devops.com/measuring-devops-performance/). -Lead time for changes displays in several charts: +Lead time for changes displays in several charts: - [Group-level value stream analytics](../group/value_stream_analytics/index.md) - [Project-level value stream analytics](value_stream_analytics.md) @@ -89,7 +89,7 @@ Lead time for changes displays in several charts: ### Time to restore service -Time to restore service measures how long it takes an organization to recover from a failure in production. +Time to restore service measures how long it takes an organization to recover from a failure in production. GitLab measures this as the average time required to close the incidents in the given time period. This assumes: @@ -97,9 +97,15 @@ in the given time period. This assumes: - Incidents and deployments have a strictly one-to-one relationship. An incident is related to only one production deployment, and any production deployment is related to no more than one incident). +Time to restore service displays in several charts: + +- [Group-level value stream analytics](../group/value_stream_analytics/index.md) +- [Project-level value stream analytics](value_stream_analytics.md) +- [CI/CD analytics](ci_cd_analytics.md) + To retrieve metrics for time to restore service, use the [GraphQL](../../api/graphql/reference/index.md) or the [REST](../../api/dora/metrics.md) APIs. -### Change failure rate +### Change failure rate Change failure rate measures the percentage of deployments that cause a failure in production. GitLab measures this as the number of incidents divided by the number of deployments to a diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index 039d33a1ad8..c0f97369740 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -43,9 +43,8 @@ To view value stream analytics for your project: - In the **From** field, select a start date. - In the **To** field, select an end date. 1. Optional. Sort results by ascending or descending: - - To sort by most recent or oldest workflow item, select the **Merge requests** or **Issues** - header. The header name differs based on the stage you select. - - To sort by most or least amount of time spent in each stage, select the **Time** header. + - To sort by most recent or oldest workflow item, select the **Last event** header. + - To sort by most or least amount of time spent in each stage, select the **Duration** header. The table shows a list of related workflow items for the selected stage. Based on the stage you choose, this can be: @@ -119,7 +118,7 @@ The **Lead Time for Changes** metrics display below the **Filter results** text To view deployment metrics, you must have a [production environment configured](../../ci/environments/index.md#deployment-tier-of-environments). -Value stream analytics shows the following deployment metrics for your project: +Value stream analytics shows the following deployment metrics for your project: - Deploys: The number of successful deployments in the date range. - Deployment Frequency: The average number of successful deployments per day in the date range. 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 1ba19359fde..bc987c56fe8 100644 --- a/doc/user/application_security/api_fuzzing/create_har_files.md +++ b/doc/user/application_security/api_fuzzing/create_har_files.md @@ -151,7 +151,7 @@ export it as a HAR file. 1. Select **Preserve log**. 1. Browse pages that call the API. 1. Select one or more requests. -1. Right click and select **Save all as HAR with content**. +1. Right-click and select **Save all as HAR with content**. 1. Enter a filename and select **Save**. 1. To append additional requests, select and save them to the same file. @@ -170,7 +170,7 @@ and export it as a HAR file. `Perform a request or Reload the page to see detailed information about network activity`, select **Reload** to start recording requests. 1. Select one or more requests. -1. Right click and select **Save All As HAR**. +1. Right-click and select **Save All As HAR**. 1. Enter a filename and select **Save**. 1. To append additional requests, select and save them to the same file. diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index f97e09f33bb..cbe20ecde30 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -65,7 +65,7 @@ Requirements: - Postman Collection v2.0 or v2.1 WARNING: - **NEVER** run fuzz testing against a production server. Not only can it perform *any* function that + **Never** run fuzz testing against a production server. Not only can it perform *any* function that the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting data. Only run fuzzing against a test server. @@ -586,7 +586,7 @@ profile increases as the number of tests increases. | CI/CD variable | Description | |-------------------------------------------------------------|-------------| | `SECURE_ANALYZERS_PREFIX` | Specify the Docker registry base address from which to download the analyzer. | -| `FUZZAPI_VERSION` | Specify API Fuzzing container version. Defaults to `1`. | +| `FUZZAPI_VERSION` | Specify API Fuzzing container version. Defaults to `2`. | | `FUZZAPI_IMAGE_SUFFIX` | Specify a container image suffix. Defaults to none. | | `FUZZAPI_TARGET_URL` | Base URL of API testing target. | | `FUZZAPI_CONFIG` | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/276395) in GitLab 13.12, replaced with default `.gitlab/gitlab-api-fuzzing-config.yml`. API Fuzzing configuration file. | @@ -883,7 +883,7 @@ Adding some basic logging to your overrides script is useful in case the script Following our example, we provided `renew_token.py` in the environmental variable `FUZZAPI_OVERRIDES_CMD`. Please notice two things in the script: - Log file is saved in the location indicated by the environment variable `CI_PROJECT_DIR`. -- Log file name should match `gl-*.log`. +- Log filename should match `gl-*.log`. ```python #!/usr/bin/env python @@ -1296,7 +1296,7 @@ variables: The `api-fuzzing-exclude-parameters.json` is a JSON document that follows the structure of [exclude parameters document](#exclude-parameters-using-a-json-document). -### Exclude URLS +### Exclude URLs > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357195) in GitLab 14.10. @@ -1476,9 +1476,9 @@ Follow these steps to view details of a fuzzing fault: - In a project, go to the project's **{shield}** **Security & Compliance > Vulnerability Report** page. This page shows all vulnerabilities from the default branch only. - - In a merge request, go the merge request's **Security** section and click the **Expand** + - 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 - **API Fuzzing detected N potential vulnerabilities**. Click the title to display the fault + **API Fuzzing detected N potential vulnerabilities**. Select the title to display the fault details. 1. Select the fault's title to display the fault's details. The table below describes these details. @@ -1652,11 +1652,11 @@ Steps: The Docker image for API Fuzzing must be pulled (downloaded) from the public registry and then pushed (imported) into a local registry. The GitLab container registry can be used to locally host the Docker image. This process can be performed using a special template. See [loading Docker images onto your offline host](../offline_deployments/index.md#loading-docker-images-onto-your-offline-host) for instructions. -Once the Docker image is hosted locally, the `SECURE_ANALYZERS_PREFIX` variable is set with the location of the local registry. The variable must be set such that concatenating `/api-fuzzing:1` results in a valid image location. +Once the Docker image is hosted locally, the `SECURE_ANALYZERS_PREFIX` variable is set with the location of the local registry. The variable must be set such that concatenating `/api-security:2` results in a valid image location. -For example, the below line sets a registry for the image `registry.gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing:1`: +For example, the below line sets a registry for the image `registry.gitlab.com/security-products/api-security:2`: -`SECURE_ANALYZERS_PREFIX: "registry.gitlab.com/gitlab-org/security-products/analyzers"` +`SECURE_ANALYZERS_PREFIX: "registry.gitlab.com/security-products"` NOTE: Setting `SECURE_ANALYZERS_PREFIX` changes the Docker image registry location for all GitLab Secure templates. diff --git a/doc/user/application_security/cluster_image_scanning/index.md b/doc/user/application_security/cluster_image_scanning/index.md index aba28a5ca89..e7a59d70b25 100644 --- a/doc/user/application_security/cluster_image_scanning/index.md +++ b/doc/user/application_security/cluster_image_scanning/index.md @@ -1,321 +1,11 @@ --- -type: reference, howto -stage: Protect -group: Container Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: '../../clusters/agent/vulnerabilities.md' +remove_date: '2022-08-19' --- -# Cluster Image Scanning **(ULTIMATE)** +This document was moved to [another location](../../clusters/agent/vulnerabilities.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/) in GitLab 14.1. - -WARNING: -This analyzer is in [Alpha](../../../policy/alpha-beta-support.md#alpha-features) -and is unstable. The JSON report and CI/CD configuration may be subject to change or breakage -across GitLab releases. - -Your Kubernetes cluster may run workloads based on images that the Container Security analyzer -didn't scan. These images may therefore contain known vulnerabilities. By including an extra job in -your pipeline that scans for those security risks and displays them in the vulnerability report, you -can use GitLab to audit your Kubernetes workloads and environments. - -GitLab provides integration with open-source tools for vulnerability analysis in Kubernetes clusters: - -- [Starboard](https://github.com/aquasecurity/starboard) - -To integrate GitLab with security scanners other than those listed here, see -[Security scanner integration](../../../development/integrations/secure.md). - -You can use cluster image scanning through the following methods: - -<!--- start_remove The following content will be removed on remove_date: '2022-08-22' --> -- [The cluster image scanning analyzer](#use-the-cluster-image-scanning-analyzer-removed) ([Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/356465) in GitLab 15.0. Use [the GitLab agent](#cluster-image-scanning-with-the-gitlab-agent) instead.) -<!--- end_remove --> -- [The GitLab agent](#cluster-image-scanning-with-the-gitlab-agent) - -<!--- start_remove The following content will be removed on remove_date: '2022-08-22' --> - -## Use the cluster image scanning analyzer (removed) - -This feature was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/356465) in GitLab 15.0. -Use [the GitLab agent](#cluster-image-scanning-with-the-gitlab-agent) instead. - -You can use the cluster image scanning analyzer to run cluster image scanning with [GitLab CI/CD](../../../ci/index.md). -To enable the cluster image scanning analyzer, [include the CI job](#configuration) -in your existing `.gitlab-ci.yml` file. - -### Prerequisites - -To enable cluster image scanning in your pipeline, you need the following: - -- Cluster Image 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. -- [GitLab Runner](https://docs.gitlab.com/runner/) - with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) - or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) - executor on Linux/amd64. -- Docker `18.09.03` or later installed on the same computer as the runner. If you're using the - shared runners on GitLab.com, then this is already the case. -- [Starboard Operator](https://aquasecurity.github.io/starboard/v0.10.3/operator/installation/kubectl/) - installed and configured in your cluster. -- The configuration for accessing your Kubernetes cluster stored in the `CIS_KUBECONFIG` - [configuration variable](#cicd-variables-for-cluster-image-scanning) - with the type set to `File` (see [Configuring the cluster](#configuring-the-cluster)). - -### Configuring the cluster - -1. Create a new service account. - - To properly fetch vulnerabilities from the cluster and to limit analyzer access to the workload, - you must create a new service account with the cluster role limited to `get`, `list`, and `watch` - `vulnerabilityreports` in the Kubernetes cluster: - - ```shell - kubectl apply -f https://gitlab.com/gitlab-org/security-products/analyzers/cluster-image-scanning/-/raw/main/gitlab-vulnerability-viewer-service-account.yaml - ``` - -1. Obtain the Kubernetes API URL. - - Get the API URL by running this command: - - ```shell - API_URL=$(kubectl cluster-info | grep -E 'Kubernetes master|Kubernetes control plane' | awk '/http/ {print $NF}') - ``` - -1. Obtain the CA certificate: - - 1. List the secrets with `kubectl get secrets`. One should have a name similar to - `default-token-xxxxx`. Copy that token name for use below. - - 1. Run this command to get the certificate: - - ```shell - CA_CERTIFICATE=$(kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}") - ``` - -1. Obtain the service account token: - - ```shell - TOKEN=$(kubectl -n kube-system get secret $(kubectl -n kube-system get secret | grep gitlab-vulnerability-viewer | awk '{print $1}') -o jsonpath="{.data.token}" | base64 --decode) - ``` - -1. Generate the value for the `CIS_KUBECONFIG` variable. Copy the printed value from the output: - - ```shell - echo " - --- - apiVersion: v1 - kind: Config - clusters: - - name: gitlab-vulnerabilities-viewer - cluster: - server: $API_URL - certificate-authority-data: $CA_CERTIFICATE - contexts: - - name: gitlab-vulnerabilities-viewer - context: - cluster: gitlab-vulnerabilities-viewer - namespace: default - user: gitlab-vulnerabilities-viewer - current-context: gitlab-vulnerabilities-viewer - users: - - name: gitlab-vulnerabilities-viewer - user: - token: $TOKEN - " - ``` - -1. Set the CI/CD variable: - - 1. Navigate to your project's **Settings > CI/CD**. - - 1. Expand the **Variables** section. - - 1. Select **Add variable** and fill in the details: - - - **Key**: `CIS_KUBECONFIG`. - - **Value**: `generated value` - - **Type**: `File` - -WARNING: -The `CIS_KUBECONFIG` variable is accessible by all jobs executed for your project. Mark the -`Protect variable` flag to export this variable to pipelines running on protected branches and tags -only. You can apply additional protection to your cluster by -[restricting service account access to a single namespace](https://kubernetes.io/docs/reference/access-authn-authz/rbac/), -and [configuring Starboard Operator](https://aquasecurity.github.io/starboard/v0.10.3/operator/configuration/#install-modes) -to install in restricted mode. - -### Configuration - -To include the `Cluster-Image-Scanning.gitlab-ci.yml` template (GitLab 14.1 and later), add the -following to your `.gitlab-ci.yml` file: - -```yaml -include: - - template: Security/Cluster-Image-Scanning.gitlab-ci.yml -``` - -The included template: - -- Creates a `cluster_image_scanning` job in your CI/CD pipeline. -- Connects to your Kubernetes cluster with credentials provided in the `CIS_KUBECONFIG` variable and - fetches vulnerabilities found by [Starboard Operator](https://aquasecurity.github.io/starboard/v0.10.3/operator/). - -GitLab saves the results as a -[Cluster Image Scanning report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportscluster_image_scanning) -that you can download and analyze later. When downloading, you always receive the most recent -artifact. - -#### Customize the cluster image scanning settings - -You can customize how GitLab scans your cluster. For example, to restrict the analyzer to get -results for only a certain workload, use the [`variables`](../../../ci/yaml/index.md#variables) -parameter in your `.gitlab-ci.yml` to set [CI/CD variables](#cicd-variables-for-cluster-image-scanning). -The variables you set in your `.gitlab-ci.yml` overwrite those in -`Cluster-Image-Scanning.gitlab-ci.yml`. - -##### CI/CD variables for cluster image scanning - -You can [configure](#customize-the-cluster-image-scanning-settings) analyzers by using the following CI/CD variables: - -| CI/CD Variable | Default | Description | -| ------------------------------ | ------------- | ----------- | -| `CIS_KUBECONFIG` | `""` | File used to configure access to the Kubernetes cluster. See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) for more details. | -| `CIS_CONTAINER_NAMES` | `""` | A comma-separated list of container names used in the Kubernetes resources you want to filter vulnerabilities for. For example, `alpine,postgres`. | -| `CIS_RESOURCE_NAMES` | `""` | A comma-separated list of Kubernetes resources you want to filter vulnerabilities for. For example, `nginx,redis`. | -| `CIS_RESOURCE_NAMESPACES` | `""` | A comma-separated list of namespaces of the Kubernetes resources you want to filter vulnerabilities for. For example, `production,staging`. | -| `CIS_RESOURCE_KINDS` | `""` | A comma-separated list of the kinds of Kubernetes resources to filter vulnerabilities for. For example, `deployment,pod`. | -| `CIS_CLUSTER_IDENTIFIER` | `""` | ID of the Kubernetes cluster integrated with GitLab. This is used to map vulnerabilities to the cluster so they can be filtered in the Vulnerability Report page. | -| `CIS_CLUSTER_AGENT_IDENTIFIER` | `""` | ID of the Kubernetes cluster agent integrated with GitLab. This maps vulnerabilities to the agent so they can be filtered in the Vulnerability Report page. | - -#### Override the cluster image scanning template - -If you want to override the job definition (for example, to change properties like `variables`), you -must declare and override a job after the template inclusion, and then -specify any additional keys. - -This example sets `CIS_RESOURCE_NAME` to `nginx`: - -```yaml -include: - - template: Security/Cluster-Image-Scanning.gitlab-ci.yml - -cluster_image_scanning: - variables: - CIS_RESOURCE_NAME: nginx -``` - -#### Connect with Kubernetes cluster associated to the project - -If you want to connect to the Kubernetes cluster associated with the project and run Cluster Image Scanning jobs without -configuring the `CIS_KUBECONFIG` variable, you must extend `cluster_image_scanning` and specify the environment you want to scan. - -This example configures the `cluster_image_scanning` job to scan the Kubernetes cluster connected with the `staging` environment: - -```yaml -cluster_image_scanning: - environment: - name: staging - action: prepare -``` - -### Reports JSON format - -The cluster image scanning tool emits a JSON report file. For more information, see the -[schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/container-scanning-report-format.json). - -Here's an example cluster image scanning report: - -```json-doc -{ - "version": "14.0.2", - "scan": { - "scanner": { - "id": "starboard_trivy", - "name": "Trivy (using Starboard Operator)", - "url": "https://github.com/aquasecurity/starboard", - "vendor": { - "name": "GitLab" - }, - "version": "0.16.0" - }, - "start_time": "2021-04-28T12:47:00Z", - "end_time": "2021-04-28T12:47:00Z", - "type": "cluster_image_scanning", - "status": "success" - }, - "vulnerabilities": [ - { - "id": "c15f22205ee842184c2d55f1a207b3708283353f85083d66c34379c709b0ac9d", - "category": "cluster_image_scanning", - "message": "CVE-2011-3374 in apt", - "description": "", - "cve": "library/nginx:1.18:apt:CVE-2011-3374", - "severity": "Low", - "confidence": "Unknown", - "solution": "Upgrade apt from 1.8.2.2", - "scanner": { - "id": "starboard_trivy", - "name": "Trivy (using Starboard Operator)" - }, - "location": { - "dependency": { - "package": { - "name": "apt" - }, - "version": "1.8.2.2" - }, - "operating_system": "library/nginx:1.18", - "image": "index.docker.io/library/nginx:1.18" - }, - "identifiers": [ - { - "type": "cve", - "name": "CVE-2011-3374", - "value": "CVE-2011-3374", - "url": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2011-3374" - } - ], - "links": [ - "https://avd.aquasec.com/nvd/cve-2011-3374" - ] - } - ] -} -``` - -<!--- end_remove --> -## Cluster image scanning with the GitLab agent - -You can use the [GitLab agent](../../clusters/agent/index.md) to -scan images from within your Kubernetes cluster and record the vulnerabilities in GitLab. - -### Prerequisites - -- [GitLab agent](../../clusters/agent/install/index.md) - set up in GitLab, installed in your cluster, and configured using a configuration repository. - -### Configuration - -The agent runs the cluster image scanning once the `starboard` -directive is added to your [agent's configuration repository](../../clusters/agent/vulnerabilities.md). - -## Security Dashboard - -The [Security Dashboard](../security_dashboard/index.md) shows you an overview of all -the security vulnerabilities in your groups, projects, and pipelines. - -## Interacting with the vulnerabilities - -After you find a vulnerability, you can address it in the [vulnerability report](../vulnerabilities/index.md) -or the [GitLab agent's](../../clusters/agent/vulnerabilities.md) -details section. -<!--- start_remove The following content will be removed on remove_date: '2022-08-22' --> - -## Troubleshooting - -### Getting warning message `gl-cluster-image-scanning-report.json: no matching files` - -For information on this error, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). - -<!--- end_remove --> +<!-- This redirect file can be deleted after <2022-08-19>. --> +<!-- 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 (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/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 61a2121b9c6..09292dcb92b 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -52,8 +52,8 @@ You can configure the following security controls: - Select **Configure with a merge request** to create a merge request with the changes required to enable Container Scanning. For more details, see [Enable Container Scanning through an automatic merge request](../container_scanning/index.md#enable-container-scanning-through-an-automatic-merge-request). -- [Cluster Image Scanning](../cluster_image_scanning/index.md) - - Can be configured with `.gitlab-ci.yml`. For more details, read [Cluster Image Scanning](../../../user/application_security/cluster_image_scanning/#configuration). +- [Operational Container Scanning](../../clusters/agent/vulnerabilities.md) + - Can be configured by adding a configuration block to your agent configuration. For more details, read [Operational Container Scanning](../../clusters/agent/vulnerabilities.md#enable-cluster-vulnerability-scanning). - [Secret Detection](../secret_detection/index.md) - Select **Configure with a merge request** to create a merge request with the changes required to enable Secret Detection. For more details, read [Enable Secret Detection via an automatic merge request](../secret_detection/index.md#enable-secret-detection-via-an-automatic-merge-request). diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 2828b56a5d1..c41385a3569 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -260,7 +260,7 @@ Support depends on which scanner is used: | Distribution | Grype | Trivy | | -------------- | ----- | ----- | | Alma Linux | | ✅ | -| Alpine Linux | ✅ | | +| Alpine Linux | ✅ | ✅ | | Amazon Linux | ✅ | ✅ | | BusyBox | ✅ | | | CentOS | ✅ | ✅ | @@ -450,7 +450,7 @@ To allowlist specific vulnerabilities, follow these steps: the format described in [`vulnerability-allowlist.yml` data format](#vulnerability-allowlistyml-data-format). 1. Add the `vulnerability-allowlist.yml` file to the root folder of your project's Git repository. -#### vulnerability-allowlist.yml data format +#### `vulnerability-allowlist.yml` data format The `vulnerability-allowlist.yml` file is a YAML file that specifies a list of CVE IDs of vulnerabilities that are **allowed** to exist, because they're _false positives_, or they're _not applicable_. diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 14e98766f0f..b2b7dd85468 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -145,7 +145,7 @@ You can download the JSON report file from the CI/CD pipelines page. For more in ## Corpus registry > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5017) in GitLab 14.8. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/347187) in GitLab 14.9. [Feature flags `corpus_management` and `corpus_management_ui`](https://gitlab.com/gitlab-org/gitlab/-/issues/328418) removed. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/347187) in GitLab 14.9. [Feature flags `corpus_management` and `corpus_management_ui`](https://gitlab.com/gitlab-org/gitlab/-/issues/328418) removed. The corpus registry is a library of corpuses. Corpuses in a project's registry are available to all jobs in that project. A project-wide registry is a more efficient way to manage corpuses than @@ -313,6 +313,10 @@ This creates two jobs: The `covfuzz-ci.yml` is the same as that in the [original synchronous example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example#running-go-fuzz-from-ci). +## FIPS-enabled binary + +[Starting in GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/352549) the coverage fuzzing binary is compiled with `golang-fips` on Linux x86 and uses OpenSSL as the cryptographic backend. For more details, see [FIPS compliance at GitLab with Go](../../../development/fips_compliance.md#go). + ## Offline environment To use coverage fuzzing in an offline environment: diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index 4cde1847419..ffcd496e2c3 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -111,7 +111,7 @@ a page fully loaded. Browser-based scans consider a page loaded when: 1. The [DOMContentLoaded](https://developer.mozilla.org/en-US/docs/Web/API/Window/DOMContentLoaded_event) event has fired. 1. There are no open or outstanding requests that are deemed important, such as JavaScript and CSS. Media files are usually deemed unimportant. 1. Depending on whether the browser executed a navigation, was forcibly transitioned, or action: - + - There are no new Document Object Model (DOM) modification events after the `DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT`, `DAST_BROWSER_STABILITY_TIMEOUT`, or `DAST_BROWSER_ACTION_STABILITY_TIMEOUT` durations. After these events have occurred, browser-based scans consider the page loaded and ready, and attempt the next action. diff --git a/doc/user/application_security/dast/checks/1004.1.md b/doc/user/application_security/dast/checks/1004.1.md index 9626973eb36..72af1156b95 100644 --- a/doc/user/application_security/dast/checks/1004.1.md +++ b/doc/user/application_security/dast/checks/1004.1.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w The {cookie_name} cookie was transmitted in a `Set-Cookie` header without the `HttpOnly` attribute set. To prevent JavaScript being able to access the cookie value - usually via `document.cookies` - all -cookies that are used for authorization or contain sensitive information should have the `HttpOnly` attribute +cookies that are used for authorization should have the `HttpOnly` attribute set. ## Remediation diff --git a/doc/user/application_security/dast/checks/16.7.md b/doc/user/application_security/dast/checks/16.7.md new file mode 100644 index 00000000000..a02fb3a451f --- /dev/null +++ b/doc/user/application_security/dast/checks/16.7.md @@ -0,0 +1,42 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Strict-Transport-Security header missing or invalid + +## Description + +The `Strict-Transport-Security` header was found to be missing or invalid. The `Strict-Transport-Security` +header allows web site operators to force communications to occur over a TLS connection. By enabling this +header, websites can protect their users from various forms of network eavesdropping or interception attacks. +While most browsers prevent mixed-content (loading resources from HTTP when navigating from an HTTPS site), +this header also ensures that all resource requests are only ever initiated over a secure transport. + +## Remediation + +Only three directives are applicable for the `Strict-Transport-Security` header. + +1. `max-age`: This required directive specifies how long (in seconds) after receiving the response it should communicate only over a secure transport. +1. `includeSubDomains`: This optional, valueless directive signals that the policy applies to this host as well as any subdomains found under this host's domain. +1. `preload`: While not part of the specification, setting this optional value allows major browser organizations to add this site into the browser's preloaded set of HTTPS sites. This requires further action on behalf of the website operator to submit their domain to the browser's HSTS preload list. See [hstspreload.org](https://hstspreload.org/) for more information. + +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). + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 16.7 | true | 16 | Passive | Low | + +## Links + +- [CWE](https://cwe.mitre.org/data/definitions/16.html) +- [Deployment Recommendations](https://hstspreload.org/#deployment-recommendations) +- [OWASP](https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Strict_Transport_Security_Cheat_Sheet.html) +- [RFC](https://datatracker.ietf.org/doc/html/rfc6797) diff --git a/doc/user/application_security/dast/checks/200.1.md b/doc/user/application_security/dast/checks/200.1.md index 9795ad11b0b..fcd329c3f2b 100644 --- a/doc/user/application_security/dast/checks/200.1.md +++ b/doc/user/application_security/dast/checks/200.1.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Description -A private RFC 1918 was identified in the target application. Public facing websites should not be issuing +A private RFC 1918/RFC 4193 address was identified in the target application. Public facing websites should not be issuing requests to private IP Addresses. Attackers attempting to execute subsequent attacks, such as Server-Side Request Forgery (SSRF), may be able to use this information to identify additional internal targets. @@ -27,3 +27,4 @@ facing version, or remove the reference from the target application. - [CWE](https://cwe.mitre.org/data/definitions/200.html) - [RFC](https://datatracker.ietf.org/doc/html/rfc1918) +- [RFC](https://datatracker.ietf.org/doc/html/rfc4193) diff --git a/doc/user/application_security/dast/checks/209.1.md b/doc/user/application_security/dast/checks/209.1.md new file mode 100644 index 00000000000..2e4163bdec0 --- /dev/null +++ b/doc/user/application_security/dast/checks/209.1.md @@ -0,0 +1,43 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Generation of error message containing sensitive information + +## Description + +The application was found to return error data such as stack traces. Depending on the data contained within the error message, +this information could be used by an attacker to conduct further attacks. While stack traces are helpful during development +and debugging, they should not be presented to users when an error occurs. + +## Remediation + +Applications should handle exception conditions internally and map known failure types to error codes that can be displayed +to a user. These error codes should be customized to the application and returned along with the relevant HTTP error code. + +When an error occurs, the application identifies the error type or class, and displays a numerical value to the +user. Requests should also be tracked so when a user is presented with an error code, it has a corresponding request ID. +Support teams can then correlate the HTTP error, the customized error code, and the request ID in the log files to +determine the root cause of the error without leaking details to the end user. + +Example of returning customized errors: + +```plaintext +HTTP/1.1 500 Internal Server Error +... +Error [0004] Occurred, please contact support or re-try your request again shortly. +Request ID [a4bc91def12] +... +``` + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 209.1 | false | 209 | Passive | Low | + +## Links + +- [CWE](https://cwe.mitre.org/data/definitions/209.html) diff --git a/doc/user/application_security/dast/checks/319.1.md b/doc/user/application_security/dast/checks/319.1.md new file mode 100644 index 00000000000..d598fb70ce3 --- /dev/null +++ b/doc/user/application_security/dast/checks/319.1.md @@ -0,0 +1,37 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Mixed Content + +## Description + +The target application was found to request resources over insecure transport protocols (HTTP). This is usually due to HTML +elements which load resources using the `http://` scheme instead of `https://`. It should be noted that most modern browsers +block these requests automatically so there is limited risk. + +Some parts of the application may not behave correctly since these files are not being properly loaded. + +## Remediation + +Ensure all HTML elements which load resources from a URL (JavaScript, stylesheets, images, video and other media) are set to +use the `https://` scheme instead of `http://`. Alternatively, developers may use the `//` scheme, which will only load resources +over the same protocol that the originating page was loaded. + +A browser visiting the website `https://example.com` with the HTML loading a file using +`<script src="//example.com/cdn/bundle.js"></script>`, would ensure the `example.com/cdn/bundle.js` file was loaded over +HTTPS. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 319.1 | true | 319 | Passive | Info | + +## Links + +- [OWASP](https://owasp.org/www-community/vulnerabilities/Insecure_Transport) +- [CWE](https://cwe.mitre.org/data/definitions/319.html) +- [MDN](https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content) diff --git a/doc/user/application_security/dast/checks/352.1.md b/doc/user/application_security/dast/checks/352.1.md new file mode 100644 index 00000000000..4daba908331 --- /dev/null +++ b/doc/user/application_security/dast/checks/352.1.md @@ -0,0 +1,41 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Absence of anti-CSRF tokens + +## Description + +The application failed to protect against Cross-Site Request Forgery (CSRF) by using +secure application tokens or `SameSite` cookie directives. + +The vulnerability can be exploited by an attacker creating a link or form on a third +party site and tricking an authenticated victim to access them. + +## Remediation + +Consider setting all session cookies to have the `SameSite=Strict` attribute. However, +it should be noted that this may impact usability when sharing links across other mediums. +It is recommended that a two cookie based approach is taken, as outlined in the +[Top level navigations](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-08#section-8.8.2) section +of the RFC. + +If the application is using a common framework, there is a chance that Anti-CSRF protection +is built in but needs to be enabled. Consult your application framework documentation for +details. + +If neither of the above are applicable, it is **strongly** recommended that a third party library is used. +Implementing a secure Anti-CSRF system is a significant investment and difficult to do correctly. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 352.1 | true | 352 | Passive | Medium | + +## Links + +- [OWASP](https://owasp.org/www-community/attacks/csrf) +- [CWE](https://cwe.mitre.org/data/definitions/352.html) diff --git a/doc/user/application_security/dast/checks/359.1.md b/doc/user/application_security/dast/checks/359.1.md index af1fdf8a596..076ab2da0d5 100644 --- a/doc/user/application_security/dast/checks/359.1.md +++ b/doc/user/application_security/dast/checks/359.1.md @@ -8,8 +8,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Description -The target application was found to return credit card information in the response. Organizations -found returning such information may be in violation of industry regulations and could face fines. +The target application was found to return credit card information in the response. Organizations +found returning such information may be in violation of industry regulations and could face fines. ## Remediation @@ -17,7 +17,7 @@ PII such as credit cards should never be directly returned to the user. The majo the last few digits or characters of the identifier. For example, credit card numbers should only return the last four digits: `****-****-****-1234`. Ensure this masking is done on the server and only then send the masked data back to the client. Do not rely on client side JavaScript or other methods -to mask these values as the data could still be intercepted or unmasked. +to mask these values as the data could still be intercepted or unmasked. Additionally, credit card information should never be stored un-encrypted in files or databases. diff --git a/doc/user/application_security/dast/checks/359.2.md b/doc/user/application_security/dast/checks/359.2.md index beb99e26097..2c59b5e321f 100644 --- a/doc/user/application_security/dast/checks/359.2.md +++ b/doc/user/application_security/dast/checks/359.2.md @@ -8,16 +8,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Description -The target application was found to return social security number (SSN) information in the response. Organizations -found returning such information may be in violation of (United States) state or federal laws and may face stiff penalties. +The target application was found to return social security number (SSN) information in the response. Organizations +found returning such information may be in violation of (United States) state or federal laws and may face stiff penalties. ## Remediation -PII such as social security numbers should never be directly returned to the user. The majority of the information +PII such as social security numbers should never be directly returned to the user. The majority of the information should masked except the last few digits or characters of the identifier. For example, social security numbers only be displayed with the last four digits: `***-**-1234`. Ensure this masking is done on the server and only then send the masked data back to the client. Do not rely on client side JavaScript or other methods -to mask these values as the data could still be intercepted or unmasked. +to mask these values as the data could still be intercepted or unmasked. Additionally, social security numbers should never be stored un-encrypted in files or databases. diff --git a/doc/user/application_security/dast/checks/548.1.md b/doc/user/application_security/dast/checks/548.1.md index d6371c5491d..1da2ce58247 100644 --- a/doc/user/application_security/dast/checks/548.1.md +++ b/doc/user/application_security/dast/checks/548.1.md @@ -39,7 +39,7 @@ indexing. ## Links -- [CWE](https://cwe.mitre.org/data/definitions/598.html) +- [CWE](https://cwe.mitre.org/data/definitions/548.html) - [Apache Options](https://httpd.apache.org/docs/2.4/mod/core.html#options) - [NGINX autoindex](https://nginx.org/en/docs/http/ngx_http_autoindex_module.html) - [IIS directoryBrowse element](https://docs.microsoft.com/en-us/iis/configuration/system.webserver/directorybrowse) diff --git a/doc/user/application_security/dast/checks/598.2.md b/doc/user/application_security/dast/checks/598.2.md index f6c6787128d..05d04b71cf0 100644 --- a/doc/user/application_security/dast/checks/598.2.md +++ b/doc/user/application_security/dast/checks/598.2.md @@ -16,7 +16,7 @@ be able to gain access to the target account. ## Remediation Passwords should never be sent in GET requests. When authenticating users or requesting users -reset their passwords, always use POST requests to transmit sensitive data. +reset their passwords, always use `POST` requests to transmit sensitive data. ## Details diff --git a/doc/user/application_security/dast/checks/598.3.md b/doc/user/application_security/dast/checks/598.3.md index fa6fdf43e1c..be17fdcaef6 100644 --- a/doc/user/application_security/dast/checks/598.3.md +++ b/doc/user/application_security/dast/checks/598.3.md @@ -17,7 +17,7 @@ target account. ## Remediation Authorization header details should never be sent in GET requests. When transmitting sensitive information -such as JWT tokens, always use POST requests or headers to transmit the sensitive data. +such as JWT tokens, always use `POST` requests or headers to transmit the sensitive data. ## Details diff --git a/doc/user/application_security/dast/checks/601.1.md b/doc/user/application_security/dast/checks/601.1.md new file mode 100644 index 00000000000..26ccd877104 --- /dev/null +++ b/doc/user/application_security/dast/checks/601.1.md @@ -0,0 +1,34 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# URL redirection to untrusted site ('open redirect') + +## Description + +This site was found to allow open redirects from user supplied input. Open redirects are commonly +abused in phishing attacks where the original domain or URL looks like a legitimate link, but then +redirects a user to a malicious site. An example would be +`https://example.com/redirect?url=https://%62%61%64%2e%63%6f%6d%2f%66%61%6b%65%6c%6f%67%69%6e` which, +when decoded turns into `bad.com/fakelogin`. + +## Remediation + +Never redirect a client based on user input found in a `GET` request. It is recommended that the list +of target links to redirect a user to are contained server side, and retrieved using a numerical value +as an index to return the link to be redirected to. For example, `/redirect?id=1` would cause the +application to look up the `1` index and return a URL such as `https://example.com`. This URL would +then be used to redirect the user, using the 301 response code and `Location` header. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 601.1 | true | 601 | Passive | Low | + +## Links + +- [OWASP](https://owasp.org/www-project-cheat-sheets/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.html) +- [CWE](https://cwe.mitre.org/data/definitions/601.html) diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md index 629ff1c3a8d..e2947d5b120 100644 --- a/doc/user/application_security/dast/checks/index.md +++ b/doc/user/application_security/dast/checks/index.md @@ -17,13 +17,18 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | [16.4](16.4.md) | X-Backend-Server header exposes server information | Info | Passive | | [16.5](16.5.md) | AspNet header exposes version information | Low | Passive | | [16.6](16.6.md) | AspNetMvc header exposes version information | Low | Passive | +| [16.7](16.7.md) | Strict-Transport-Security header missing or invalid | Low | Passive | | [200.1](200.1.md) | Exposure of sensitive information to an unauthorized actor (private IP address) | Low | Passive | +| [209.1](209.1.md) | Generation of error message containing sensitive information | Low | Passive | +| [319.1](319.1.md) | Mixed Content | Info | Passive | +| [352.1](352.1.md) | Absence of anti-CSRF tokens | Medium | Passive | | [359.1](359.1.md) | Exposure of Private Personal Information (PII) to an unauthorized actor (credit card) | Medium | Passive | | [359.2](359.2.md) | Exposure of Private Personal Information (PII) to an unauthorized actor (United States social security number) | Medium | Passive | | [548.1](548.1.md) | Exposure of information through directory listing | Low | Passive | | [598.1](598.1.md) | Use of GET request method with sensitive query strings (session ID) | Medium | Passive | | [598.2](598.2.md) | Use of GET request method with sensitive query strings (password) | Medium | Passive | | [598.3](598.3.md) | Use of GET request method with sensitive query strings (Authorization header details) | Medium | Passive | +| [601.1](601.1.md) | URL redirection to untrusted site ('open redirect') | Low | Passive | | [614.1](614.1.md) | Sensitive cookie without Secure attribute | Low | Passive | | [693.1](693.1.md) | Missing X-Content-Type-Options: nosniff | Low | Passive | | [829.1](829.1.md) | Inclusion of Functionality from Untrusted Control Sphere | Low | Passive | diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md index 9969526c906..50570b89920 100644 --- a/doc/user/application_security/dast/dast_troubleshooting.md +++ b/doc/user/application_security/dast/dast_troubleshooting.md @@ -89,6 +89,16 @@ include: - template: DAST.latest.gitlab-ci.yml ``` +## Getting error `shell not found` when using DAST CI/CD template + +When including the DAST CI/CD template as described in the documentation, the job may fail, with an error like the following recorded in the job logs: + +```shell +shell not found +``` + +To avoid this error, make sure you are using the latest stable version of Docker. More information is available in [issue 358847](https://gitlab.com/gitlab-org/gitlab/-/issues/358847). + ## Lack of IPv6 support Due to the underlying [ZAProxy engine not supporting IPv6](https://github.com/zaproxy/zaproxy/issues/3705), DAST is unable to scan or crawl IPv6-based applications. diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 1389db65713..25b4b705025 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -178,7 +178,8 @@ To enable DAST to run automatically, either: #### Include the DAST template -> This template was [updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62597) to DAST_VERSION: 2 in GitLab 14.0. +> - This template was [updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62597) to DAST_VERSION: 2 in GitLab 14.0. +> - This template was [updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87183) to DAST_VERSION: 3 in GitLab 15.0. If you want to manually add DAST to your application, the DAST job is defined in a CI/CD template file. Updates to the template are provided with GitLab @@ -333,7 +334,7 @@ Vulnerability rules in an API scan are different than those in a normal website A new DAST API scanning engine is available in GitLab 13.12 and later. For more details, see [DAST API scanning engine](../dast_api). The new scanning engine supports REST, SOAP, GraphQL, and generic APIs using forms, XML, and JSON. Testing can be performed using OpenAPI, Postman Collections, and HTTP Archive (HAR) documents. -The target API instance’s base URL is provided by using the `DAST_API_TARGET_URL` variable or an `environment_url.txt` file. +The target API instance's base URL is provided by using the `DAST_API_TARGET_URL` variable or an `environment_url.txt` file. #### Specification format @@ -493,7 +494,7 @@ To perform a [full scan](#full-scan) on the listed paths, use the `DAST_FULL_SCA ### List URLs scanned When DAST completes scanning, the merge request page states the number of URLs scanned. -Click **View details** to view the web console output which includes the list of scanned URLs. +Select **View details** to view the web console output which includes the list of scanned URLs.  @@ -574,7 +575,7 @@ DAST scan with both configured exits with an error. By default, several rules are disabled because they either take a long time to run or frequently generate false positives. The complete list of disabled rules -can be found in [exclude_rules.yml](https://gitlab.com/gitlab-org/security-products/dast/-/blob/main/src/config/exclude_rules.yml). +can be found in [`exclude_rules.yml`](https://gitlab.com/gitlab-org/security-products/dast/-/blob/main/src/config/exclude_rules.yml). The lists for `DAST_EXCLUDE_RULES` and `DAST_ONLY_INCLUDE_RULES` **must** be enclosed in double quotes (`"`), otherwise they are interpreted as numeric values. @@ -737,7 +738,7 @@ by the application as correctly authenticated. Authentication supports single form logins, multi-step login forms, and authenticating to URLs outside of the configured target URL. WARNING: -**NEVER** run an authenticated scan against a production server. When an authenticated +**Never** run an authenticated scan against a production server. When an authenticated scan is run, it may perform *any* function that the authenticated user can. This includes actions like modifying and deleting data, submitting forms, and following links. Only run an authenticated scan against a test server. @@ -846,7 +847,7 @@ Many web applications show the user the login form in a pop-up (modal) window. For these applications, navigating to the form requires both: - A starting URL. -- A list of elements to click to display the modal window. +- A list of elements to select to display the modal window. When `DAST_BROWSER_PATH_TO_LOGIN_FORM` is present, like in this example: @@ -1327,7 +1328,7 @@ class DastWebsiteTargetView(View): ##### Node (with Express) example for on-demand scan Here's how you can add a -[custom header in Node (with Express)](http://expressjs.com/en/5x/api.html#res.append): +[custom header in Node (with Express)](https://expressjs.com/en/5x/api.html#res.append): ```javascript app.get('/dast-website-target', function(req, res) { @@ -1399,17 +1400,19 @@ and DAST site profiles are included in the [audit log](../../../administration/a ## Reports -The DAST tool outputs a report file in JSON format by default. However, this tool can also generate reports in -Markdown, HTML, and XML. For more information, see the [schema for DAST reports](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/dast-report-format.json). +The DAST tool outputs a `gl-dast-report.json` report file containing details of the scan and its results. +This file is included in the job's artifacts. JSON is the default format, but +you can output the report in Markdown, HTML, and XML formats. To specify an alternative +format, use a [CI/CD variable](#available-cicd-variables). You can also use a CI/CD variable +to configure the job to output the `gl-dast-debug-auth-report.html` file which helps when debugging +authentication issues. -### JSON +For details of the report's schema, see the [schema for DAST reports](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/dast-report-format.json). Example reports can be found in the +[DAST repository](https://gitlab.com/gitlab-org/security-products/dast/-/tree/main/test/end-to-end/expect). WARNING: -The JSON report artifacts are not a public API of DAST and their format is expected to change in the future. - -The DAST tool always emits a JSON report file called `gl-dast-report.json` and -sample reports can be found in the -[DAST repository](https://gitlab.com/gitlab-org/security-products/dast/-/tree/main/test/end-to-end/expect). +The JSON report artifacts are not a public API of DAST and their format is expected to change in the +future. ## Optimizing DAST diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index a1b19c52b20..9128576bf29 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -538,7 +538,7 @@ can be added, removed, and modified by creating a custom configuration. | CI/CD variable | Description | |------------------------------------------------------|--------------------| | `SECURE_ANALYZERS_PREFIX` | Specify the Docker registry base address from which to download the analyzer. | -| `DAST_API_VERSION` | Specify DAST API container version. Defaults to `1`. | +| `DAST_API_VERSION` | Specify DAST API container version. Defaults to `2`. | | `DAST_API_IMAGE_SUFFIX` | Specify a container image suffix. Defaults to none. | | `DAST_API_TARGET_URL` | Base URL of API testing target. | |[`DAST_API_CONFIG`](#configuration-files) | DAST API configuration file. Defaults to `.gitlab-dast-api.yml`. | @@ -837,7 +837,7 @@ Adding some basic logging to your overrides script is useful in case the script Following our example, we provided `renew_token.py` in the environment variable `DAST_API_OVERRIDES_CMD`. Please notice two things in the script: - Log file is saved in the location indicated by the environmental variable `CI_PROJECT_DIR`. -- Log file name should match `gl-*.log`. +- Log filename should match `gl-*.log`. ```python #!/usr/bin/env python @@ -1021,6 +1021,19 @@ variables: DAST_API_EXCLUDE_PATHS=/auth*;/v1/* ``` +To exclude one or more nested levels within a path we use `**`. In this example we are testing API endpoints. We are testing `/api/v1/` and `/api/v2/` of a data query requesting `mass`, `brightness` and `coordinates` data for `planet`, `moon`, `star`, and `satellite` objects. Example paths that could be scanned include, but are not limited to: + +- `/api/v2/planet/coordinates` +- `/api/v1/star/mass` +- `/api/v2/satellite/brightness` + +In this example we test the `brightness` endpoint only: + +```yaml +variables: + DAST_API_EXCLUDE_PATHS=/api/**/mass;/api/**/coordinates +``` + ### Exclude parameters > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292196) in GitLab 14.10. @@ -1250,7 +1263,7 @@ variables: The `dast-api-exclude-parameters.json` is a JSON document that follows the structure of [exclude parameters document](#exclude-parameters-using-a-json-document). -### Exclude URLS +### Exclude URLs > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357195) in GitLab 14.10. @@ -1332,12 +1345,12 @@ Follow these steps to view details of a vulnerability: - In a project, go to the project's **{shield}** **Security & Compliance > Vulnerability Report** page. This page shows all vulnerabilities from the default branch only. - - In a merge request, go the merge request's **Security** section and click the **Expand** + - 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 - **DAST detected N potential vulnerabilities**. Click the title to display the vulnerability + **DAST detected N potential vulnerabilities**. Select the title to display the vulnerability details. -1. Click the vulnerabilities title to display the details. The table below describes these details. +1. Select the vulnerabilities title to display the details. The table below describes these details. | Field | Description | |:--------------------|:----------------------------------------------------------------------------------------| @@ -1489,14 +1502,14 @@ Steps: The Docker image for DAST API must be pulled (downloaded) from the public registry and then pushed (imported) into a local registry. The GitLab container registry can be used to locally host the Docker image. This process can be performed using a special template. See [loading Docker images onto your offline host](../offline_deployments/index.md#loading-docker-images-onto-your-offline-host) for instructions. -Once the Docker image is hosted locally, the `SECURE_ANALYZERS_PREFIX` variable is set with the location of the local registry. The variable must be set such that concatenating `/api-fuzzing:1` results in a valid image location. +Once the Docker image is hosted locally, the `SECURE_ANALYZERS_PREFIX` variable is set with the location of the local registry. The variable must be set such that concatenating `/api-security:2` results in a valid image location. NOTE: -DAST API and API Fuzzing both use the same underlying Docker image `api-fuzzing:1`. +DAST API and API Fuzzing both use the same underlying Docker image `api-security:2`. -For example, the below line sets a registry for the image `registry.gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing:1`: +For example, the below line sets a registry for the image `registry.gitlab.com/security-products/api-security:2`: -`SECURE_ANALYZERS_PREFIX: "registry.gitlab.com/gitlab-org/security-products/analyzers"` +`SECURE_ANALYZERS_PREFIX: "registry.gitlab.com/security-products"` NOTE: Setting `SECURE_ANALYZERS_PREFIX` changes the Docker image registry location for all GitLab Secure templates. diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 78de740c96d..03c97c85dbc 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Use the dependency list to review your project's dependencies and key details about those dependencies, including their known vulnerabilities. It is a collection of dependencies in your project, including existing and new findings. -To see the dependency list, go to your project and select **Security & Compliance > Dependency List**. +To see the dependency list, go to your project and select **Security & Compliance > Dependency list**. This information is sometimes referred to as a Software Bill of Materials, SBOM, or BOM. diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 87689572866..08e2dcd2e7e 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -17,6 +17,24 @@ aspects of inspecting the items your code uses. These items typically include ap dependencies that are almost always imported from external sources, rather than sourced from items you wrote yourself. +If you're using [GitLab CI/CD](../../../ci/index.md), you can use dependency scanning to analyze +your dependencies for known vulnerabilities. GitLab scans all dependencies, including transitive +dependencies (also known as nested dependencies). You can take advantage of dependency scanning by +either: + +- [Including the dependency scanning template](#configuration) + in your existing `.gitlab-ci.yml` file. +- Implicitly using + the [auto dependency scanning](../../../topics/autodevops/stages.md#auto-dependency-scanning) + provided by [Auto DevOps](../../../topics/autodevops/index.md). + +GitLab checks the dependency scanning report, compares the found vulnerabilities +between the source and target branches, and shows the information on the +merge request. The results are sorted by the [severity](../vulnerabilities/severities.md) of the +vulnerability. + + + ## Dependency Scanning compared to Container Scanning GitLab offers both Dependency Scanning and Container Scanning @@ -58,26 +76,6 @@ The following table summarizes which types of dependencies each scanning tool ca 1. Lock file must be present in the image to be detected. 1. Binary file must be present in the image to be detected. -## Overview - -If you're using [GitLab CI/CD](../../../ci/index.md), you can use dependency scanning to analyze -your dependencies for known vulnerabilities. GitLab scans all dependencies, including transitive -dependencies (also known as nested dependencies). You can take advantage of dependency scanning by -either: - -- [Including the dependency scanning template](#configuration) - in your existing `.gitlab-ci.yml` file. -- Implicitly using - the [auto dependency scanning](../../../topics/autodevops/stages.md#auto-dependency-scanning) - provided by [Auto DevOps](../../../topics/autodevops/index.md). - -GitLab checks the dependency scanning report, compares the found vulnerabilities -between the source and target branches, and shows the information on the -merge request. The results are sorted by the [severity](../vulnerabilities/severities.md) of the -vulnerability. - - - ## Requirements Dependency Scanning runs in the `test` stage, which is available by default. If you redefine the @@ -95,7 +93,7 @@ is **not** `19.03.0`. See [troubleshooting information](#error-response-from-dae WARNING: Dependency Scanning does not support run-time installation of compilers and interpreters. -If you have need of this, please explain why by filling out the survey [here](https://docs.google.com/forms/d/e/1FAIpQLScKo7xEYA65rOjPTGIufAyfjPGnCALSJZoTxBlvskfFMEOZMw/viewform). +If you need it, please explain why by filling out [the survey](https://docs.google.com/forms/d/e/1FAIpQLScKo7xEYA65rOjPTGIufAyfjPGnCALSJZoTxBlvskfFMEOZMw/viewform). ## Supported languages and package managers @@ -110,6 +108,8 @@ maximum of two directory levels from the repository's root. For example, the `gemnasium-dependency_scanning` job is enabled if a repository contains either `Gemfile`, `api/Gemfile`, or `api/client/Gemfile`, but not if the only supported dependency file is `api/v1/client/Gemfile`. +When a supported dependency file is detected, all dependencies, including transitive dependencies are analyzed. There is no limit to the depth of nested or transitive dependencies that are analyzed. + The following languages and dependency managers are supported: <style> @@ -154,7 +154,7 @@ table.supported-languages ul { <tbody> <tr> <td>Ruby</td> - <td>N/A</td> + <td>Not applicable</td> <td><a href="https://bundler.io/">Bundler</a></td> <td> <ul> @@ -167,7 +167,7 @@ table.supported-languages ul { </tr> <tr> <td>PHP</td> - <td>N/A</td> + <td>Not applicable</td> <td><a href="https://getcomposer.org/">Composer</a></td> <td><code>composer.lock</code></td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> @@ -175,7 +175,7 @@ table.supported-languages ul { </tr> <tr> <td>C</td> - <td rowspan="2">N/A</td> + <td rowspan="2">Not applicable</td> <td rowspan="2"><a href="https://conan.io/">Conan</a></td> <td rowspan="2"><a href="https://docs.conan.io/en/latest/versioning/lockfiles.html"><code>conan.lock</code></a></td> <td rowspan="2"><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> @@ -186,7 +186,7 @@ table.supported-languages ul { </tr> <tr> <td>Go</td> - <td>N/A</td> + <td>Not applicable</td> <td><a href="https://go.dev/">Go</a></td> <td><code>go.sum</code></td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> @@ -194,8 +194,16 @@ table.supported-languages ul { </tr> <tr> <td rowspan="2">Java</td> - <td rowspan="2">8, 11, 13, 14, 15, 16, or 17</td> - <td><a href="https://gradle.org/">Gradle</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-1">1</a></b></sup></td> + <td rowspan="2"> + 8, + 11, + 13<sup><b><a href="#notes-regarding-supported-languages-and-package-managers-1">1</a></b></sup>, + 14<sup><b><a href="#notes-regarding-supported-languages-and-package-managers-1">1</a></b></sup>, + 15<sup><b><a href="#notes-regarding-supported-languages-and-package-managers-1">1</a></b></sup>, + 16<sup><b><a href="#notes-regarding-supported-languages-and-package-managers-1">1</a></b></sup>, + or 17 + </td> + <td><a href="https://gradle.org/">Gradle</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-2">2</a></b></sup></td> <td> <ul> <li><code>build.gradle</code></li> @@ -213,7 +221,7 @@ table.supported-languages ul { </tr> <tr> <td rowspan="2">JavaScript</td> - <td>N/A</td> + <td>Not applicable</td> <td><a href="https://www.npmjs.com/">npm</a></td> <td> <ul> @@ -225,7 +233,7 @@ table.supported-languages ul { <td>Y</td> </tr> <tr> - <td>N/A</td> + <td>Not applicable</td> <td><a href="https://classic.yarnpkg.com/en/">yarn</a></td> <td><code>yarn.lock</code></td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> @@ -233,7 +241,7 @@ table.supported-languages ul { </tr> <tr> <td>.NET</td> - <td rowspan="2">N/A</td> + <td rowspan="2">Not applicable</td> <td rowspan="2"><a href="https://www.nuget.org/">NuGet</a></td> <td rowspan="2"><a href="https://docs.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"><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> @@ -267,22 +275,22 @@ table.supported-languages ul { <td> <ul> <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile</code></a></li> - <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile.lock</code></a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-2">2</a></b></sup></li> + <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile.lock</code></a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-3">3</a></b></sup></li> </ul> </td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>N</td> </tr> <tr> - <td><a href="https://python-poetry.org/">Poetry</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-4">4</a></b></sup></td> + <td><a href="https://python-poetry.org/">Poetry</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-5">5</a></b></sup></td> <td><code>poetry.lock</code></td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>N</td> </tr> <tr> <td>Scala</td> - <td>N/A</td> - <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-3">3</a></b></sup></td> + <td>Not applicable</td> + <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-4">4</a></b></sup></td> <td><code>build.sbt</code></td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> <td>N</td> @@ -294,13 +302,19 @@ table.supported-languages ul { <li> <a id="notes-regarding-supported-languages-and-package-managers-1"></a> <p> + This version of Java is not supported by the FIPS-enabled image of <code>gemnasium-maven</code>. + </p> + </li> + <li> + <a id="notes-regarding-supported-languages-and-package-managers-2"></a> + <p> Although Gradle with Java 8 is supported, there are other issues such that Android project builds are not supported at this time. Please see the backlog issue <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/336866">Android support for Dependency Scanning (gemnasium-maven)</a> for more details. </p> </li> <li> - <a id="notes-regarding-supported-languages-and-package-managers-2"></a> + <a id="notes-regarding-supported-languages-and-package-managers-3"></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 @@ -313,13 +327,13 @@ table.supported-languages ul { </p> </li> <li> - <a id="notes-regarding-supported-languages-and-package-managers-3"></a> + <a id="notes-regarding-supported-languages-and-package-managers-4"></a> <p> Support for <a href="https://www.scala-sbt.org/">sbt</a> 1.3 and above was added in GitLab 13.9. </p> </li> <li> - <a id="notes-regarding-supported-languages-and-package-managers-4"></a> + <a id="notes-regarding-supported-languages-and-package-managers-5"></a> <p> Support for <a href="https://python-poetry.org/">Poetry</a> projects with a <code>poetry.lock</code> file was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/7006">added in GitLab 15.0</a>. Support for projects without a <code>poetry.lock</code> file is tracked in issue: @@ -342,10 +356,10 @@ The following package managers use lockfiles that GitLab analyzers are capable o | Package Manager | Supported File Format Versions | Tested Versions | | ------ | ------ | ------ | -| Bundler | N/A | [1.17.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/ruby-bundler/default/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | -| Composer | N/A | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/php-composer/default/composer.lock) | +| Bundler | Not applicable | [1.17.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/ruby-bundler/default/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | +| Composer | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/php-composer/default/composer.lock) | | Conan | 0.4 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/c-conan/default/conan.lock) | -| Go | N/A | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/go-modules/default/go.sum) | +| Go | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/go-modules/default/go.sum) | | 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 | [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) | | yarn | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/default/yarn.lock#L2) | @@ -420,6 +434,8 @@ GitLab relies on [`rules:exists`](../../../ci/yaml/index.md#rulesexists) to star The current detection logic limits the maximum search depth to two levels. For example, the `gemnasium-dependency_scanning` job is enabled if a repository contains either a `Gemfile.lock`, `api/Gemfile.lock`, or `api/client/Gemfile.lock`, but not if the only supported dependency file is `api/v1/client/Gemfile.lock`. +When a supported dependency file is detected, all dependencies, including transitive dependencies are analyzed. There is no limit to the depth of nested or transitive dependencies that are analyzed. + ### How multiple files are processed NOTE: @@ -597,7 +613,7 @@ The following variables are used for configuring specific analyzers (used for a | `GEMNASIUM_DB_REF_NAME` | `gemnasium` | `master` | Branch name for remote repository database. `GEMNASIUM_DB_REMOTE_URL` is required. | | `DS_REMEDIATE` | `gemnasium` | `"true"` | Enable automatic remediation of vulnerable dependencies. | | `GEMNASIUM_LIBRARY_SCAN_ENABLED` | `gemnasium` | `"true"` | Enable detecting vulnerabilities in vendored JavaScript libraries. For now, `gemnasium` leverages [`Retire.js`](https://github.com/RetireJS/retire.js) to do this job. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350512) in GitLab 14.8. | -| `DS_JAVA_VERSION` | `gemnasium-maven` | `17` | Version of Java. Available versions: `8`, `11`, `13`, `14`, `15`, `16`, `17`. | +| `DS_JAVA_VERSION` | `gemnasium-maven` | `17` | Version of Java. Available versions: `8`, `11`, `13`, `14`, `15`, `16`, `17`. Available versions in FIPS-enabled image: `8`, `11`, `17`. | | `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that are passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repositories). | | `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that are passed to `gradle` by the analyzer. | | `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer passes to `sbt`. | @@ -606,6 +622,7 @@ The following variables are used for configuring specific analyzers (used for a | `PIP_REQUIREMENTS_FILE` | `gemnasium-python` | | Pip requirements file to be scanned. | | `DS_PIP_VERSION` | `gemnasium-python` | | Force the install of a specific pip version (example: `"19.3"`), otherwise the pip installed in the Docker image is used. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12811) in GitLab 12.7) | | `DS_PIP_DEPENDENCY_PATH` | `gemnasium-python` | | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12412) in GitLab 12.2) | +| `DS_INCLUDE_DEV_DEPENDENCIES` | `gemnasium` | `"true"` | When set to `"false"`, development dependencies and their vulnerabilities are not reported. Only NPM projects are supported. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227861) in GitLab 15.1. | #### Other variables @@ -668,6 +685,9 @@ Gemnasium scanning jobs automatically use FIPS-enabled image when FIPS mode is e To manually switch to FIPS-enabled images, set the variable `DS_IMAGE_SUFFIX` to `"-fips"`. +To ensure compliance with FIPS, the FIPS-enabled image of `gemnasium-maven` uses the OpenJDK packages for RedHat UBI. +As a result, it only supports Java 8, 11, and 17. + ## Interacting with the vulnerabilities Once a vulnerability is found, you can interact with it. Read more on how to @@ -1030,7 +1050,7 @@ ensure that it can reach your private repository. Here is an example configurati setuptools.ssl_support.cert_paths = ['internal.crt'] ``` -## Hosting a copy of the gemnasium_db advisory database +## Hosting a copy of the `gemnasium_db` advisory database The [`gemnasium_db`](https://gitlab.com/gitlab-org/security-products/gemnasium-db) Git repository is used by `gemnasium`, `gemnasium-maven`, and `gemnasium-python` as the source of vulnerability data. @@ -1225,7 +1245,7 @@ version `58.1.0+`, which doesn't support `2to3`. Therefore, a `setuptools` depen error in <dependency name> setup command: use_2to3 is invalid ``` -To work around this error, downgrade the analyzer's version of `setuptools` (e.g. `v57.5.0`): +To work around this error, downgrade the analyzer's version of `setuptools` (for example, `v57.5.0`): ```yaml gemnasium-python-dependency_scanning: diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index b5d39f3b32a..d449fbb9a6c 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -12,35 +12,69 @@ GitLab can check your application for security vulnerabilities including: - Data leaks. - Denial of Service (DoS) attacks. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview of GitLab application security, see [Shifting Security Left](https://www.youtube.com/watch?v=XnYstHObqlA&t). + Statistics and details on vulnerabilities are included in the merge request. Providing actionable information _before_ changes are merged enables you to be proactive. -GitLab also provides high-level statistics of vulnerabilities across projects and groups: +To help with the task of managing and addressing vulnerabilities, GitLab provides a security +dashboard you can access from your project or group. For more details, see +[Security Dashboard](security_dashboard/index.md). -- The [Security Dashboard](security_dashboard/index.md) provides a - high-level view of vulnerabilities detected in your projects, pipeline, and groups. +## Application coverage -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview of GitLab application security, see [Shifting Security Left](https://www.youtube.com/watch?v=XnYstHObqlA&t). +GitLab analyzes various details of your application, either as part of your CI/CD pipeline or on a +schedule. Coverage includes: + +- Source code. +- Dependencies in your projects or container images. +- Vulnerabilities in a running web application. +- Infrastructure as code configuration. + +### Source code analysis + +Source code analysis occurs on every code commit. Details of vulnerabilities detected are provided +in the merge request. + +A source code analysis can: + +- Analyze source code for vulnerabilities - [Static Application Security Testing (SAST)](sast/index.md). +- Analyze the Git repository's history for secrets - [Secret Detection](secret_detection/index.md). + +### Analysis of the running web application + +Analysis of the web application occurs on every code commit. As part of the CI/CD pipeline, your +application is built, deployed to a test environment, and subjected to the following tests: + +- Test for known application vectors - [Dynamic Application Security Testing (DAST)](dast/index.md). +- Analysis of APIs for known attack vectors - [DAST API](dast_api/index.md). +- Analysis of web APIs for unknown bugs and vulnerabilities - [API fuzzing](api_fuzzing/index.md). -## Security scanning tools - -GitLab uses the following tools to scan and report known vulnerabilities found in your project. - -| Secure scanning tool | Description | -| :------------------------------------------------------------- | :------------------------------------------------------------------ | -| [Container Scanning](container_scanning/index.md) | Scan Docker containers for known vulnerabilities. | -| [Dependency List](dependency_list/index.md) | View your project's dependencies and their known vulnerabilities. | -| [Dependency Scanning](dependency_scanning/index.md) | Analyze your dependencies for known vulnerabilities. | -| [Dynamic Application Security Testing (DAST)](dast/index.md) | Analyze running web applications for known vulnerabilities. | -| [DAST API](dast_api/index.md) | Analyze running web APIs for known vulnerabilities. | -| [API fuzzing](api_fuzzing/index.md) | Find unknown bugs and vulnerabilities in web APIs with fuzzing. | -| [Secret Detection](secret_detection/index.md) | Analyze Git history for leaked secrets. | -| [Security Dashboard](security_dashboard/index.md) | View vulnerabilities in all your projects and groups. | -| [Static Application Security Testing (SAST)](sast/index.md) | Analyze source code for known vulnerabilities. | -| [Infrastructure as Code (IaC) Scanning](iac_scanning/index.md) | Analyze your IaC configuration files for known vulnerabilities. | -| [Coverage fuzzing](coverage_fuzzing/index.md) | Find unknown bugs and vulnerabilities with coverage-guided fuzzing. | -| [Cluster Image Scanning](cluster_image_scanning/index.md) | Scan Kubernetes clusters for known vulnerabilities. | +### Dependency analysis + +Dependency analysis occurs on every code commit. Your application's dependencies are collated and +checked against a database of known vulnerabilities. + +Dependency analysis can run: + +- At build time - [Dependency Scanning](dependency_scanning/index.md). +- For projects that use container images, also after the final container + image is built - [Container Scanning](container_scanning/index.md). + +For more details, see +[Dependency Scanning compared to Container Scanning](dependency_scanning/index.md#dependency-scanning-compared-to-container-scanning). + +Additionally, dependencies in operational container images can be analyzed for vulnerabilities +on a regular schedule or cadence. For more details, see [Cluster Image Scanning](cluster_image_scanning/index.md). + +### Infrastructure analysis + +Your application's infrastructure is a source of potential vulnerabilities. To help defend +against this, infrastructure analysis occurs on every merge request. Checks are run against: + +- Infrastructure as Code (IaC) configuration files that define your application's deployment + environment - [Infrastructure as Code (IaC) Scanning](iac_scanning/index.md). ## Vulnerability scanner maintenance @@ -102,15 +136,17 @@ variables: DAST_WEBSITE: https://staging.example.com ``` -For more details about each of the security scanning tools, see their respective -[documentation sections](#security-scanning-tools). - ### Override the default registry base address By default, GitLab security scanners use `registry.gitlab.com/security-products` as the -base address for Docker images. You can override this globally by setting the CI/CD variable +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. +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 +the instructions for [Running container scanning in an offline +environment](container_scanning/index.md#running-container-scanning-in-an-offline-environment). + ### Use security scanning tools with merge request pipelines By default, the application security jobs are configured to run for branch pipelines only. @@ -126,19 +162,19 @@ rules: ### Secure jobs in your pipeline -If you add the security scanning jobs as described in [Security scanning with Auto DevOps](#security-scanning-with-auto-devops) or [Security scanning without Auto DevOps](#security-scanning-without-auto-devops) to your `.gitlab-ci.yml` each added [security scanning tool](#security-scanning-tools) behave as described below. +If you add the security scanning jobs as described in [Security scanning with Auto DevOps](#security-scanning-with-auto-devops) or [Security scanning without Auto DevOps](#security-scanning-without-auto-devops) to your `.gitlab-ci.yml` each added [security scanning tool](#application-coverage) behave as described below. For each compatible analyzer, a job is created in the `test`, `dast` or `fuzz` stage of your pipeline and runs on the next new branch pipeline. Features such as the [Security Dashboard](security_dashboard/index.md), [Vulnerability Report](vulnerability_report/index.md), and [Dependency List](dependency_list/index.md) that rely on this scan data only show results from pipelines on the default branch, only if all jobs are finished, including manual ones. One tool might use many analyzers. -Our language and package manager specific jobs attempt to assess which analyzer(s) they should run for your project so that you can do less configuration. +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. ### Secure job status -Jobs pass if they are able to complete a scan. A _pass_ result does NOT indicate if they did, or did not, identify findings. The only exception is coverage fuzzing, which fails if it identifies findings. +Jobs pass if they are able to complete a scan. A _pass_ result does not indicate if they did, or did not, identify findings. The only exception is coverage fuzzing, which fails if it identifies findings. Jobs fail if they are unable to complete a scan. You can view the pipeline logs for more information. @@ -169,11 +205,11 @@ reports are available to download. To download a report, select ### Ultimate -A merge request contains a security widget which displays a summary of the NEW results. New results are determined by comparing the current findings against existing findings in the target (default) branch (if there are prior findings). +A merge request contains a security widget which displays a summary of the new results. New results are determined by comparing the current findings against existing findings in the target (default) branch (if there are prior findings). We recommend you run a scan of the `default` branch before enabling feature branch scans for your developers. Otherwise, there is no base for comparison and all feature branches display the full scan results in the merge request security widget. -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. +The merge request security widget displays only a subset of the vulnerabilities in the generated JSON artifact because it contains both new and existing findings. From the merge request security widget, select **Expand** to unfold the widget, displaying any new and no longer detected (removed) findings by scan type. Select **View full report** to go directly to the **Security** tab in the latest branch pipeline. @@ -213,9 +249,9 @@ security issues: ### Migration of existing Vulnerability-Check rules -If your projects have rules that have a security orchestration project, a new MR with +If your projects have rules that have a security orchestration project, a new MR with the existing rule's content is created automatically against the default branch belonging -to the security orchestration project. To maintain the same security approval rules you +to the security orchestration project. To maintain the same security approval rules you had before GitLab 15.0, we recommend merging this new MR. If your projects have rules without a security orchestration project, a new security orchestration project is created automatically with the content of the existing rule. No additional action is required. @@ -360,10 +396,17 @@ Self managed installations can also run the security scanners on a GitLab Runner You can enforce validation of the security report artifacts before ingesting the vulnerabilities. This prevents ingestion of broken vulnerability data into the database. GitLab validates the artifacts based on the [report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/tree/master/dist). - -In GitLab 14.0 and later, when artifact validation is enabled, the pipeline's **Security** tab lists +When artifact validation is enabled, the pipeline's **Security** tab lists any report artifacts that failed validation. +Validation depends on the schema: + +- If your security report does not specify which schema version it uses, GitLab attempts to verify it against the earliest supported schema version for that report type. Validation fails but it's attempted anyway because it may identify other problems present in the report. +- If your security report uses a version that is not supported, GitLab attempts to validate it against the earliest supported schema version for that report type. Validation fails but will identify the differences between the schema version used and the earliest supported version. +- If your security report uses a deprecated version, GitLab attempts validation against that version and adds a warning to the validation result. + +You can always find supported and deprecated schema versions in the [source code](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/parsers/security/validators/schema_validator.rb#L9). + ### Enable security report validation > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/354928) in GitLab 14.9, and planned for removal in GitLab 15.0. @@ -553,18 +596,18 @@ When overriding the template to control job execution, previous instances of [`only` or `except`](../../ci/yaml/index.md#only--except) are no longer compatible and must be transitioned to [the `rules` syntax](../../ci/yaml/index.md#rules). -If your override is aimed at limiting jobs to only run on `master`, the previous syntax +If your override is aimed at limiting jobs to only run on `main`, the previous syntax would look similar to: ```yaml include: - template: Security/SAST.gitlab-ci.yml -# Ensure that the scanning is only executed on master or merge requests +# Ensure that the scanning is only executed on main or merge requests spotbugs-sast: only: refs: - - master + - main - merge_requests ``` @@ -575,10 +618,10 @@ would be written as follows: include: - template: Security/SAST.gitlab-ci.yml -# Ensure that the scanning is only executed on master or merge requests +# Ensure that the scanning is only executed on main or merge requests spotbugs-sast: rules: - - if: $CI_COMMIT_BRANCH == "master" + - if: $CI_COMMIT_BRANCH == "main" - if: $CI_MERGE_REQUEST_ID ``` @@ -659,6 +702,3 @@ These security pages can be populated by running the jobs from the manual step o 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 [contributions are welcomed](https://about.gitlab.com/community/contribute/). - doc/user/project/merge_requests/approvals/settings.md -+ -0 diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index f790164d9a0..27a6f867ae2 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -121,6 +121,10 @@ Additionally, if you are a project owner and a security policy project has not b associated with this project, then a new project is created and associated automatically at the same time that the first policy merge request is created. +## Managing projects in bulk via a script + +You can use the [Vulnerability-Check Migration](https://gitlab.com/gitlab-org/gitlab/-/snippets/2328089) script to bulk create policies or associate security policy projects with development projects. For instructions and a demonstration of how to use the Vulnerability-Check Migration script, see [this video](https://youtu.be/biU1N26DfBc). + ## Scan execution policies See [Scan execution policies](scan-execution-policies.md). diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index aa23ad30a73..5beb6912877 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -47,7 +47,8 @@ The policy editor currently only supports the YAML mode. The Rule mode is tracke The YAML file with scan execution policies consists of an array of objects matching scan execution policy schema nested under the `scan_execution_policy` key. You can configure a maximum of 5 -policies under the `scan_execution_policy` key. +policies under the `scan_execution_policy` key. Any other policies configured after +the first 5 are not applied. When you save a new policy, GitLab validates its contents against [this JSON schema](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/validators/json_schemas/security_orchestration_policy.json). If you're not familiar with how to read [JSON schemas](https://json-schema.org/), @@ -85,9 +86,8 @@ This rule enforces the defined actions and schedules a scan on the provided date | `type` | `string` | `schedule` | The rule's type. | | `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | | `cadence` | `string` | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. | -| `agents` | `object` | | The name of the [GitLab agents](../../clusters/agent/index.md) where [cluster image scanning](../../clusters/agent/vulnerabilities.md) will run. The key of the object is the name of the Kubernetes cluster configured for your project in GitLab. In the optionally provided value of the object, you can precisely select Kubernetes resources that are scanned. | <!--- start_remove The following content will be removed on remove_date: '2022-08-22' --> -| `clusters` (removed) | `object` | | This field was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/356465) in 15.0. Use the `agents` field instead. The cluster where the given policy enforces running selected scans (only for `container_scanning`/`cluster_image_scanning` scans). The key of the object is the name of the Kubernetes cluster configured for your project in GitLab. In the optionally provided value of the object, you can precisely select Kubernetes resources that are scanned. | -<!--- end_remove --> +| `agents` | `object` | | The name of the [GitLab agents](../../clusters/agent/index.md) where [cluster image scanning](../../clusters/agent/vulnerabilities.md) will run. The key of the object is the name of the Kubernetes cluster configured for your project in GitLab. In the optionally provided value of the object, you can precisely select Kubernetes resources that are scanned. <!--- start_remove The following content will be removed on remove_date: '2022-08-22' --> | +| `clusters` (removed) | `object` | | This field was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/356465) in 15.0. Use the `agents` field instead. The cluster where the given policy enforces running selected scans (only for `container_scanning`/`cluster_image_scanning` scans). The key of the object is the name of the Kubernetes cluster configured for your project in GitLab. In the optionally provided value of the object, you can precisely select Kubernetes resources that are scanned. <!--- end_remove --> | GitLab supports the following types of CRON syntax for the `cadence` field: @@ -152,7 +152,7 @@ Note the following: mode when executed as part of a scheduled scan. - A container scanning and cluster image scanning scans configured for the `pipeline` rule type ignores the cluster defined in the `clusters` object. They use predefined CI/CD variables defined for your project. Cluster selection with the `clusters` object is supported for the `schedule` rule type. - Cluster with name provided in `clusters` object must be created and configured for the project. To be able to successfully perform the `container_scanning`/`cluster_image_scanning` scans for the cluster you must follow instructions for the [Cluster Image Scanning feature](../cluster_image_scanning/index.md#prerequisites). + A cluster with a name provided in the `clusters` object must be created and configured for the project. - The SAST scan uses the default template and runs in a [child pipeline](../../../ci/pipelines/parent_child_pipelines.md). ## Example security policies project diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index 232a5c9f91c..3da884aca6a 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -91,7 +91,7 @@ the defined policy. Requirements and limitations: -- You must add the respective [security scanning tools](../index.md#security-scanning-tools). +- You must add the respective [security scanning tools](../index.md#application-coverage). Otherwise, scan result policies won't have any effect. - The maximum number of policies is five. - Each policy can have a maximum of five rules. diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 661f564828a..0f9e3343072 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -63,35 +63,6 @@ content directly. Instead, it enhances the results with additional properties, i - Location tracking fields. - A means of identifying false positives or insignificant findings. **(ULTIMATE)** -## Data provided by analyzers - -Each analyzer provides data about the vulnerabilities it detects. The following table details the -data available from each analyzer. The values provided by these tools are heterogeneous so they are sometimes -normalized into common values, for example, `severity` and `confidence`. - -| Property / tool | Apex | Bandit | Brakeman | ESLint security | SpotBugs | Flawfinder | Gosec | Kubesec Scanner | MobSF | NodeJsScan | PHP CS Security Audit | Security code Scan (.NET) | Semgrep | Sobelow | -|--------------------------------|------|--------|----------|-----------------|----------|------------|-------|-----------------|-------|------------|-----------------------|---------------------------|---------|---------| -| Affected item (for example, class or package) | ✓ | ✗ | ✓ | ✗ | ✓ | ✓ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | -| Confidence | ✗ | ✓ | ✓ | ✗ | ✓ | x | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ⚠ | ✓ | -| Description | ✓ | ✗ | ✗ | ✓ | ✓ | ✗ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✓ | ✓ | -| End column | ✓ | ✗ | ✗ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | -| End line | ✓ | ✓ | ✗ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | -| External ID (for example, CVE) | ✗ | ✗ | ⚠ | ✗ | ⚠ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ⚠ | ✗ | -| File | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Internal doc/explanation | ✓ | ⚠ | ✓ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ | -| Internal ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ | -| Severity | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ⚠ | ✗ | -| Solution | ✓ | ✗ | ✗ | ✗ | ⚠ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ⚠ | ✗ | -| Source code extract | ✗ | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | -| Start column | ✓ | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✓ | ✓ | ✓ | ✗ | -| Start line | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Title | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| URLs | ✓ | ✗ | ✓ | ✗ | ⚠ | ✗ | ⚠ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | - -- ✓ => Data is available. -- ⚠ => Data is available, but it's partially reliable, or it has to be extracted from unstructured content. -- ✗ => Data is not available or it would require specific, inefficient or unreliable, logic to obtain it. - ## Transition to Semgrep-based scanning SAST includes a [Semgrep-based analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) that covers [multiple languages](index.md#supported-languages-and-frameworks). @@ -120,10 +91,10 @@ The Vulnerability Management system automatically moves vulnerabilities from the However, you'll see old vulnerabilities re-created based on Semgrep results 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 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. -When a vulnerability is re-created, the original vulnerability is marked as “no longer detected” in the Vulnerability Report. +When a vulnerability is re-created, the original vulnerability is marked as "no longer detected" in the Vulnerability Report. A new vulnerability is then created based on the Semgrep finding. ### Activating Semgrep-based scanning early @@ -184,7 +155,7 @@ variables: You can disable all default SAST analyzers, leaving only [custom analyzers](#custom-analyzers) enabled. -To disable all default analyzers, set the CI/CD variable `SAST_DISABLED` to `true` in your +To disable all default analyzers, set the CI/CD variable `SAST_DISABLED` to `"true"` in your `.gitlab-ci.yml` file. Example: @@ -194,7 +165,7 @@ include: - template: Security/SAST.gitlab-ci.yml variables: - SAST_DISABLED: true + SAST_DISABLED: "true" ``` ### Disable specific default analyzers @@ -241,3 +212,32 @@ csharp-sast: reports: sast: gl-sast-report.json ``` + +## Data provided by analyzers + +Each analyzer provides data about the vulnerabilities it detects. The following table details the +data available from each analyzer. The values provided by these tools are heterogeneous so they are sometimes +normalized into common values, for example, `severity` and `confidence`. + +| Property / tool | Apex | Bandit | Brakeman | ESLint security | SpotBugs | Flawfinder | Gosec | Kubesec Scanner | MobSF | NodeJsScan | PHP CS Security Audit | Security code Scan (.NET) | Semgrep | Sobelow | +|--------------------------------|------|--------|----------|-----------------|----------|------------|-------|-----------------|-------|------------|-----------------------|---------------------------|---------|---------| +| Affected item (for example, class or package) | ✓ | ✗ | ✓ | ✗ | ✓ | ✓ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | +| Confidence | ✗ | ✓ | ✓ | ✗ | ✓ | x | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ⚠ | ✓ | +| Description | ✓ | ✗ | ✗ | ✓ | ✓ | ✗ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✓ | ✓ | +| End column | ✓ | ✗ | ✗ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | +| End line | ✓ | ✓ | ✗ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | +| External ID (for example, CVE) | ✗ | ✗ | ⚠ | ✗ | ⚠ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ⚠ | ✗ | +| File | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Internal doc/explanation | ✓ | ⚠ | ✓ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ | +| Internal ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ | +| Severity | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ⚠ | ✗ | +| Solution | ✓ | ✗ | ✗ | ✗ | ⚠ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ⚠ | ✗ | +| Source code extract | ✗ | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | +| Start column | ✓ | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✓ | ✓ | ✓ | ✗ | +| Start line | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Title | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| URLs | ✓ | ✗ | ✓ | ✗ | ⚠ | ✗ | ⚠ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | + +- ✓ => Data is available. +- ⚠ => Data is available, but it's partially reliable, or it has to be extracted from unstructured content. +- ✗ => Data is not available or it would require specific, inefficient or unreliable, logic to obtain it. diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 38f26b7578d..d4dd8059c6a 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -13,7 +13,7 @@ The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab. explains how 4 of the top 6 attacks were application based. Download it to learn how to protect your organization. -If you’re using [GitLab CI/CD](../../../ci/index.md), you can use Static Application Security +If you're using [GitLab CI/CD](../../../ci/index.md), you can use Static Application Security Testing (SAST) to check your source code for known vulnerabilities. You can run SAST analyzers in any GitLab tier. The analyzers output JSON-formatted reports as job artifacts. @@ -182,6 +182,7 @@ as shown in the following table: | [Configure SAST in the UI](#configure-sast-in-the-ui) | **{dotted-circle}** | **{check-circle}** | | [Customize SAST rulesets](#customize-rulesets) | **{dotted-circle}** | **{check-circle}** | | [Detect False Positives](#false-positive-detection) | **{dotted-circle}** | **{check-circle}** | +| [Track moved vulnerabilities](#advanced-vulnerability-tracking) | **{dotted-circle}** | **{check-circle}** | ## Contribute your scanner @@ -524,7 +525,7 @@ defined for the `nodejs-scan` scanner: ''' ``` -##### File passthrough for gosec +##### File passthrough for Gosec Provide the name of the file containing a custom analyzer configuration. In this example, customized rules for the `gosec` scanner are contained in the @@ -539,7 +540,7 @@ file `gosec-config.json`: value = "gosec-config.json" ``` -##### Passthrough chain for semgrep +##### Passthrough chain for Semgrep In the below example, we generate a custom configuration under the `/sgrules` target directory with a total `timeout` of 60 seconds. @@ -560,7 +561,7 @@ Several passthrouh types generate a configuration for the target analyzer: - The `url` entry fetches a configuration made available through a URL and stores it in the `/sgrules/gosec.yml` file. -Afterwards, semgrep is invoked with the final configuration located under +Afterwards, Semgrep is invoked with the final configuration located under `/sgrules`. ```toml @@ -632,12 +633,12 @@ created when preceding passthroughs in the chain find a naming collision. If `mode` is set to `append`, a passthrough appends data to the files created by its predecessors instead of overwriting. -In the below semgrep configuration,`/sgrules/insecure.yml` assembles two passthroughs. The rules are: +In the below Semgrep configuration,`/sgrules/insecure.yml` assembles two passthroughs. The rules are: - `insecure` - `secret` -These rules add a search pattern to the analyzer and extends semgrep capabilities. +These rules add a search pattern to the analyzer and extends Semgrep capabilities. For passthrough chains we recommend that you enable validation. To enable validation, you can either: @@ -696,6 +697,32 @@ rules: Vulnerabilities that have been detected and are false positives will be flagged as false positives in the security dashboard. +False positive detection is available in a subset of the [supported languages](#supported-languages-and-frameworks) and [analyzers](analyzers.md): + +- Ruby, in the Brakeman-based analyzer + +### Advanced vulnerability tracking **(ULTIMATE)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5144) in GitLab 14.2. + +Source code is volatile; as developers make changes, source code may move within files or between files. +Security analyzers may have already reported vulnerabilities that are being tracked in the [Vulnerability Report](../vulnerability_report/). +These vulnerabilities are linked to specific problematic code fragments so that they can be found and fixed. +If the code fragments are not tracked reliably as they move, vulnerability management is harder because the same vulnerability could be reported again. + +GitLab SAST uses an advanced vulnerability tracking algorithm to more accurately identify when the same vulnerability has moved within a file due to refactoring or unrelated changes. + +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 +- Java, in the Semgrep-based analyzer only +- JavaScript, in the Semgrep-based analyzer only +- Python, in the Semgrep-based analyzer only +- Ruby, in the Brakeman-based analyzer + +Support for more languages and analyzers is tracked in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/5144). + ### Using CI/CD variables to pass credentials for private repositories Some analyzers require downloading the project's dependencies in order to diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 3937cbd77b6..9805fb3b67c 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -197,7 +197,8 @@ Secret Detection can be customized by defining available CI/CD variables: |-----------------------------------|---------------|-------------| | `SECRET_DETECTION_EXCLUDED_PATHS` | "" | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225273) in GitLab 13.3. | | `SECRET_DETECTION_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. | -| `SECRET_DETECTION_IMAGE_SUFFIX` | Suffix added to the image name. If set to `-fips`, `FIPS-enabled` images are used for scan. See [FIPS-enabled images](#fips-enabled-images) for more details. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355519) in GitLab 14.10. | +| `SECRET_DETECTION_IMAGE_SUFFIX` | "" | Suffix added to the image name. If set to `-fips`, `FIPS-enabled` images are used for scan. See [FIPS-enabled images](#fips-enabled-images) for more details. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355519) in GitLab 14.10. | +| `SECRET_DETECTION_LOG_OPTIONS` | "" | [`git log`](https://git-scm.com/docs/git-log) options used to define commit ranges. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350660) in GitLab 15.1.| In previous GitLab versions, the following variables were also available: @@ -220,7 +221,7 @@ simultaneously: - [Disabling predefined rules](index.md#disable-predefined-analyzer-rules). - [Overriding predefined rules](index.md#override-predefined-analyzer-rules). -- Modifying the default behavior of the Secret Detection analyzer by [synthesizing and passing a custom configuration](index.md#synthesize-a-custom-configuration). Available for only `nodejs-scan`, `gosec`, and `semgrep`. +- Modifying the default behavior of the Secret Detection analyzer by [synthesizing and passing a custom configuration](index.md#synthesize-a-custom-configuration). Customization allows replacing the default secret detection rules with rules that you define. diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 577606885ca..3cb4bd4a02d 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -7,13 +7,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Security Dashboards and Security Center **(ULTIMATE)** -You can use Security Dashboards to view details about vulnerabilities -detected by [security scanners](../index.md#security-scanning-tools). -These details are shown in pipelines, projects, and groups. +You can use Security Dashboards to view trends about vulnerabilities +detected by [security scanners](../index.md#application-coverage). +These trends are shown in projects, groups, and the Security Center. To use the Security Dashboards, you must: -- Configure at least one [security scanner](../index.md#security-scanning-tools) in a project. +- Configure at least one [security scanner](../index.md#application-coverage) in a project. - Configure jobs to use the [`reports` syntax](../../../ci/yaml/index.md#artifactsreports). - Use [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or later. If you use the shared runners on GitLab.com, you are using the correct version. diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index 8277c30b81f..392bfa1dde2 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -96,6 +96,106 @@ A finding's location fingerprint is a text value that's unique for each location surface. Each Secure product defines this according to its type of attack surface. For example, SAST incorporates file path and line number. +### Package managers + +A Package manager is a system that manages your project dependencies. + +The package manager provides a method to install new dependencies (also referred to as "packages"), manage where packages are stored on your file system, and offer capabilities for you to publish your own packages. + +### Package types + +Each package manager, platform, type, or ecosystem has its own conventions and protocols to identify, locate, and provision software packages. + +The following table is a non-exhaustive list of some of the package managers and types referenced in GitLab documentation and software tools. + +<style> +table.package-managers-and-types tr:nth-child(even) { + background-color: transparent; +} + +table.package-managers-and-types td { + border-left: 1px solid #dbdbdb; + border-right: 1px solid #dbdbdb; + border-bottom: 1px solid #dbdbdb; +} + +table.package-managers-and-types tr td:first-child { + border-left: 0; +} + +table.package-managers-and-types tr td:last-child { + border-right: 0; +} + +table.package-managers-and-types ul { + font-size: 1em; + list-style-type: none; + padding-left: 0px; + margin-bottom: 0px; +} +</style> + +<table class="package-managers-and-types"> + <thead> + <tr> + <th>Package Type</th> + <th>Package Manager</th> + </tr> + </thead> + <tbody> + <tr> + <td>gem</td> + <td><a href="https://bundler.io/">bundler</a></td> + </tr> + <tr> + <td>packagist</td> + <td><a href="https://getcomposer.org/">composer</a></td> + </tr> + <tr> + <td>conan</td> + <td><a href="https://conan.io/">conan</a></td> + </tr> + <tr> + <td>go</td> + <td><a href="https://go.dev/blog/using-go-modules">go</a></td> + </tr> + <tr> + <td rowspan="3">maven</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><a href="https://www.scala-sbt.org">sbt</a></td> + </tr> + <tr> + <td rowspan="2">npm</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>nuget</td> + <td><a href="https://www.nuget.org/">nuget</a></td> + </tr> + <tr> + <td rowspan="4">pypi</td> + <td><a href="https://setuptools.pypa.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> + </tbody> +</table> + ### Pipeline Security tab A page that displays findings discovered in the associated CI pipeline. diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 87344e4ff65..f5b1192269d 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -4,13 +4,14 @@ group: Threat Insights info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Vulnerability Pages **(ULTIMATE)** +# Vulnerability Page **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13561) in GitLab 13.0. -Each vulnerability in a project has a Vulnerability Page. This page contains details of the -vulnerability. The details included vary according to the type of vulnerability. Details of each -vulnerability include: +Each vulnerability in a project has a Vulnerability Page, containing details of the +vulnerability. The details included vary according to the type of vulnerability. + +Details of each vulnerability include: - Description - When it was detected @@ -24,32 +25,41 @@ alert message is included at the top of the vulnerability's page. On the vulnerability's page, you can: -- [Change the vulnerability's status](#change-vulnerability-status). -- [Create an issue](#create-an-issue-for-a-vulnerability). -- [Link issues to the vulnerability](#linked-issues). -- [Resolve a vulnerability](#resolve-a-vulnerability) if a solution is +- [Change the vulnerability's status](#change-status-of-a-vulnerability). +- [Create an issue](#creating-an-issue-for-a-vulnerability). +- [Link issues to the vulnerability](#linking-a-vulnerability-to-issues). +- [Resolve the vulnerability](#resolve-a-vulnerability) if a solution is available. - [View security training specific to the detected vulnerability](#view-security-training-for-a-vulnerability). ## Vulnerability status values -A vulnerability's status can be one of the following: +A vulnerability's status can be: + +- **Detected**: The default state for a newly discovered vulnerability. Appears as "Needs triage" in the UI. +- **Confirmed**: A user has seen this vulnerability and confirmed it to be accurate. +- **Dismissed**: A user has seen this vulnerability and dismissed it because it is not accurate or otherwise not to be resolved. +- **Resolved**: The vulnerability has been fixed or is no longer present. -| Status | Description | -|:----------|:------------| -| Detected | The default state for a newly discovered vulnerability. Appears as "Needs triage" in the UI. | -| Confirmed | A user has seen this vulnerability and confirmed it to be accurate. | -| Dismissed | A user has seen this vulnerability and dismissed it because it is not accurate or otherwise not to be resolved. | -| Resolved | The vulnerability has been fixed or is no longer present. | +Dismissed vulnerabilities are ignored if detected in subsequent scans. Resolved vulnerabilities that +are reintroduced and detected by subsequent scans have a _new_ vulnerability record created. When an +existing vulnerability is no longer detected in a project's `default` branch, you should change its +status to **Resolved**. This ensures that if it is accidentally reintroduced in a future merge, it +is reported again as a new record. You can use the Vulnerability Report's +[Activity filter](../vulnerability_report/#activity-filter) to select all vulnerabilities that are +no longer detected, and change their status. -Dismissed vulnerabilities are ignored if detected in subsequent scans. Resolved vulnerabilities that are reintroduced and detected by subsequent scans have a _new_ vulnerability record created. When an existing vulnerability is no longer detected in a project's `default` branch, you should change its status to Resolved. This ensures that if it is accidentally reintroduced in a future merge, it will be visible again as a new record. You can use the [Activity filter](../vulnerability_report/#activity-filter) to select all vulnerabilities that are no longer detected, and [change their status](../vulnerability_report#change-status-of-vulnerabilities). +## Change status of a vulnerability -## Change vulnerability status +To change a vulnerability's status from its Vulnerability Page: -To change a vulnerability's status, select a new value from the **Status** dropdown then select -**Change status**. Optionally, add a comment to the log entry at the bottom of the page. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Vulnerability report**. +1. Select the vulnerability's description. +1. From the **Status** dropdown list select a status, then select **Change status**. +1. Optionally, at the bottom of the page, add a comment to the log entry. -## Create an issue for a vulnerability +## Creating an issue for a vulnerability From a vulnerability's page you can create an issue to track all action taken to resolve or mitigate it. @@ -67,7 +77,9 @@ that when Jira integration is enabled, the GitLab issue feature is not available To create a GitLab issue for a vulnerability: -1. In GitLab, go to the vulnerability's page. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Vulnerability report**. +1. Select the vulnerability's description. 1. Select **Create issue**. An issue is created in the project, pre-populated with information from the vulnerability report. @@ -80,73 +92,85 @@ The issue is then opened so you can take further action. Prerequisites: -- [Enable Jira integration](../../../integration/jira/index.md). - The **Enable Jira issue creation from vulnerabilities** option must be selected as part of the configuration. -- Each user must have a personal Jira user account with permission to create issues in the target project. +- [Enable Jira integration](../../../integration/jira/index.md). The **Enable Jira issue creation + from vulnerabilities** option must be selected as part of the configuration. +- Each user must have a personal Jira user account with permission to create issues in the target + project. To create a Jira issue for a vulnerability: -1. Go to the vulnerability's page. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Vulnerability report**. +1. Select the vulnerability's description. 1. Select **Create Jira issue**. 1. If you're not already logged in to Jira, log in. The Jira issue is created and opened in a new browser tab. The **Summary** and **Description** fields are pre-populated from the vulnerability's details. -Unlike GitLab issues, the status of whether a Jira issue is open or closed does not display in the GitLab user interface. +Unlike GitLab issues, the status of whether a Jira issue is open or closed does not display in the +GitLab user interface. -## Linked issues +## Linking a vulnerability to issues NOTE: If Jira issue support is enabled, GitLab issues are disabled so this feature is not available. -You can link one or more existing GitLab issues to a vulnerability. Adding a link helps track +You can link a vulnerability to one or more existing GitLab issues. Adding a link helps track the issue that resolves or mitigates a vulnerability. Issues linked to a vulnerability are shown in the Vulnerability Report and the vulnerability's page. Be aware of the following conditions between a vulnerability and a linked issue: -- The vulnerability page shows related issues, but the issue page doesn't show the vulnerability it's related to. +- The vulnerability page shows related issues, but the issue page doesn't show the vulnerability + it's related to. - An issue can only be related to one vulnerability at a time. - Issues can be linked across groups and projects. -## Link to existing issues +## Link a vulnerability to existing issues To link a vulnerability to existing issues: -1. Go to the vulnerability's page. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Vulnerability report**. +1. Select the vulnerability's description. 1. In the **Linked issues** section, select the plus icon (**{plus}**). 1. For each issue to be linked, either: - Paste a link to the issue. - Enter the issue's ID (prefixed with a hash `#`). 1. Select **Add**. -The selected issues are added to the **Linked issues** section, and the linked issues counter is updated. +The selected issues are added to the **Linked issues** section, and the linked issues counter is +updated. ## Resolve a vulnerability For some vulnerabilities a solution is already known. In those instances, a vulnerability's page includes a **Resolve with merge request** option. -To resolve a vulnerability, you can either: - -- [Resolve a vulnerability with a merge request](#resolve-a-vulnerability-with-a-merge-request). -- [Resolve a vulnerability manually](#resolve-a-vulnerability-manually). - -The following scanners are supported: +The following scanners are supported by this feature: - [Dependency Scanning](../dependency_scanning/index.md). Automatic Patch creation is only available for Node.js projects managed with `yarn`. - [Container Scanning](../container_scanning/index.md). +To resolve a vulnerability, you can either: + +- [Resolve a vulnerability with a merge request](#resolve-a-vulnerability-with-a-merge-request). +- [Resolve a vulnerability manually](#resolve-a-vulnerability-manually). +  ### Resolve a vulnerability with a merge request -To resolve the vulnerability with a merge request, go to the vulnerability's page and from the -**Resolve with merge request** dropdown select **Resolve with merge request**. +To resolve the vulnerability with a merge request: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Vulnerability report**. +1. Select the vulnerability's description. +1. From the **Resolve with merge request** dropdown list, select **Resolve with merge request**. A merge request is created which applies the patch required to resolve the vulnerability. Process the merge request according to your standard workflow. @@ -155,11 +179,15 @@ Process the merge request according to your standard workflow. To manually apply the patch that GitLab generated for a vulnerability: -1. Go to the vulnerability's page and from the **Resolve with merge request** dropdown select - **Download patch to resolve**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Vulnerability report**. +1. Select the vulnerability's description. +1. From the **Resolve with merge request** dropdown list, select **Download patch to resolve**. 1. Ensure your local project has the same commit checked out that was used to generate the patch. 1. Run `git apply remediation.patch`. 1. Verify and commit the changes to your branch. +1. Create a merge request to apply the changes to your main branch. +1. Process the merge request according to your standard workflow. ## Enable security training for vulnerabilities diff --git a/doc/user/application_security/vulnerabilities/severities.md b/doc/user/application_security/vulnerabilities/severities.md index 967a6d9fa89..987dac677e7 100644 --- a/doc/user/application_security/vulnerabilities/severities.md +++ b/doc/user/application_security/vulnerabilities/severities.md @@ -39,17 +39,17 @@ the following tables: |----------------------------------------------------------------------------------------------------------|--------------------------|----------------------------|------------------------------------| | [`security-code-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) | **{check-circle}** Yes | String | `CRITICAL`, `HIGH`, `MEDIUM` in [analyzer version 3.2.0 and later](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan/-/blob/master/CHANGELOG.md#v320). In earlier versions, hardcoded to `Unknown`. | | [`brakeman`](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) | **{check-circle}** Yes | String | `HIGH`, `MEDIUM`, `LOW` | -| [`sobelow`](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Unknown` | +| [`sobelow`](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) | **{check-circle}** Yes | Not applicable | Hardcodes all severity levels to `Unknown` | | [`nodejs-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan) | **{check-circle}** Yes | String | `INFO`, `WARNING`, `ERROR` | | [`flawfinder`](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder) | **{check-circle}** Yes | Integer | `0`, `1`, `2`, `3`, `4`, `5` | -| [`eslint`](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Unknown` | +| [`eslint`](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | **{check-circle}** Yes | Not applicable | Hardcodes all severity levels to `Unknown` | | [`SpotBugs`](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) | **{check-circle}** Yes | Integer | `1`, `2`, `3`, `11`, `12`, `18` | | [`gosec`](https://gitlab.com/gitlab-org/security-products/analyzers/gosec) | **{check-circle}** Yes | String | `HIGH`, `MEDIUM`, `LOW` | | [`bandit`](https://gitlab.com/gitlab-org/security-products/analyzers/bandit) | **{check-circle}** Yes | String | `HIGH`, `MEDIUM`, `LOW` | | [`phpcs-security-audit`](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit) | **{check-circle}** Yes | String | `ERROR`, `WARNING` | | [`pmd-apex`](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) | **{check-circle}** Yes | Integer | `1`, `2`, `3`, `4`, `5` | | [`kubesec`](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec) | **{check-circle}** Yes | String | `CriticalSeverity`, `InfoSeverity` | -| [`secrets`](https://gitlab.com/gitlab-org/security-products/analyzers/secrets) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Critical` | +| [`secrets`](https://gitlab.com/gitlab-org/security-products/analyzers/secrets) | **{check-circle}** Yes | Not applicable | Hardcodes all severity levels to `Critical` | | [`semgrep`](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) | **{check-circle}** Yes | String | `error`, `warning`, `note`, `none` | ## Dependency Scanning diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index e499ddbbd6b..15a287356f8 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -23,7 +23,7 @@ The **Activity** column contains icons to indicate the activity, if any, taken o in that row: - Issues **{issues}**: Links to issues created for the vulnerability. For more details, read - [Create an issue for a vulnerability](../vulnerabilities/index.md#create-an-issue-for-a-vulnerability). + [Create an issue for a vulnerability](../vulnerabilities/index.md#creating-an-issue-for-a-vulnerability). - Wrench **{admin}**: The vulnerability has been remediated. - False positive **{false-positive}**: The scanner determined this vulnerability to be a false positive. @@ -105,7 +105,7 @@ When using the tool filter, you can choose: - Individual GitLab-provided tools. - Any integrated third-party tool. -For details of each of the available tools, see [Security scanning tools](../index.md#security-scanning-tools). +For details of each of the available tools, see [Security scanning tools](../index.md#application-coverage). ### Project filter @@ -249,7 +249,7 @@ To add a new vulnerability finding from your project level Vulnerability Report 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Vulnerability Report**. -1. Click on **Submit Vulnerability**. +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 @@ -259,7 +259,7 @@ Group, Project, and Security Center Vulnerability Reports. To filter them, use t > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6345) in GitLab 14.6. -The **Operational vulnerabilities** tab lists vulnerabilities found by the `cluster_image_scanner`. +The **Operational vulnerabilities** tab lists vulnerabilities found by [Operational container scanning](../../clusters/agent/vulnerabilities.md). This tab appears on the project, group, and Security Center vulnerability reports.  diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index 80c85358fcb..b55a55eebe5 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -235,7 +235,7 @@ v1.0, 2019-01-01 NOTE: [Wiki pages](project/wiki/index.md#create-a-new-wiki-page) created with the AsciiDoc format are saved with the file extension `.asciidoc`. When working with AsciiDoc wiki -pages, change the file name from `.adoc` to `.asciidoc`. +pages, change the filename from `.adoc` to `.asciidoc`. ```plaintext include::basics.adoc[] @@ -381,9 +381,9 @@ comment - content which is not included in the output document It's possible to have color written in `HEX`, `RGB`, or `HSL` format rendered with a color indicator. Supported formats (named colors are not supported): -- HEX: `` `#RGB[A]` `` or `` `#RRGGBB[AA]` `` -- RGB: `` `RGB[A](R, G, B[, A])` `` -- HSL: `` `HSL[A](H, S, L[, A])` `` +- `HEX`: `` `#RGB[A]` `` or `` `#RRGGBB[AA]` `` +- `RGB`: `` `RGB[A](R, G, B[, A])` `` +- `HSL`: `` `HSL[A](H, S, L[, A])` `` Color written inside backticks is followed by a color "chip": @@ -399,10 +399,10 @@ Color written inside backticks is followed by a color "chip": - `HSLA(540,70%,50%,0.3)` ``` -### STEM +### Equations and Formulas (STEM) -To activate equation and formula support, -set the `stem` attribute in the document's header to `latexmath`. +If you need to include Science, Technology, Engineering and Math (STEM) +expressions, set the `stem` attribute in the document's header to `latexmath`. Equations and formulas are rendered using [KaTeX](https://katex.org/): ```plaintext diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index 644a753e282..c04c5a1f7ec 100644 --- a/doc/user/clusters/agent/ci_cd_workflow.md +++ b/doc/user/clusters/agent/ci_cd_workflow.md @@ -235,6 +235,10 @@ The identity can be specified with the following keys: See the [official Kubernetes documentation for details](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation). +## Related topics + +- [Self-paced classroom workshop](https://gitlab-for-eks.awsworkshop.io) (Uses AWS EKS, but you can use for other Kubernetes clusters) + ## Troubleshooting ### `kubectl` commands not supported diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md index 6ca9d855b44..64eae308bec 100644 --- a/doc/user/clusters/agent/gitops.md +++ b/doc/user/clusters/agent/gitops.md @@ -65,7 +65,7 @@ gitops: - id: gitlab-org/cluster-integration/gitlab-agent default_namespace: my-ns paths: - # Read all YAML files from this directory. + # Read all YAML files from this directory. - glob: '/team1/app1/*.yaml' # Read all .yaml files from team2/apps and all subdirectories. - glob: '/team2/apps/**/*.yaml' @@ -124,10 +124,10 @@ As a result, every field in a resource can have different managers. Only fields are checked for drift. This facilitates the use of in-cluster controllers to modify resources like [Horizontal Pod Autoscalers](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/). -## Additional resources - -The following documentation and examples can help you get started with a GitOps workflow. +## Related topics +- [GitOps working examples for training and demos](https://gitlab.com/groups/guided-explorations/gl-k8s-agent/gitops/-/wikis/home) +- [Self-paced classroom workshop](https://gitlab-for-eks.awsworkshop.io) (Uses AWS EKS, but you can use for other Kubernetes clusters) - [Managing Kubernetes secrets in a GitOps workflow](gitops/secrets_management.md) - [Application and manifest repository example](https://gitlab.com/gitlab-examples/ops/gitops-demo/hello-world-service-gitops) diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index d54d432f0f5..5a69da28632 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -66,8 +66,11 @@ Read about how to [migrate to the agent for Kubernetes](../../infrastructure/clu ## Related topics - [GitOps workflow](gitops.md) +- [GitOps examples and learning materials](gitops.md#related-topics) - [GitLab CI/CD workflow](ci_cd_workflow.md) - [Install the agent](install/index.md) - [Work with the agent](repository.md) - [Troubleshooting](troubleshooting.md) +- [Guided explorations for a production ready GitOps setup](https://gitlab.com/groups/guided-explorations/gl-k8s-agent/gitops/-/wikis/home#gitlab-agent-for-kubernetes-gitops-working-examples) +- [CI/CD for Kubernetes examples and learning materials](ci_cd_workflow.md#related-topics) - [Contribute to the agent's development](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/doc) diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index f747c6c0e25..6c839f5ffc6 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -20,29 +20,51 @@ Before you can install the agent in your cluster, you need: - [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine/docs/quickstart) - [Amazon Elastic Kubernetes Service (EKS)](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html) - [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/`. +- 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/`. On GitLab.com, the agent server is available at `wss://kas.gitlab.com`. ## Installation steps To install the agent in your cluster: -1. [Choose a name for the agent](#agent-naming-convention). +1. Optional. [Create an agent configuration file](#create-an-agent-configuration-file). 1. [Register the agent with GitLab](#register-the-agent-with-gitlab). 1. [Install the agent in your cluster](#install-the-agent-in-the-cluster). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a GitLab 14.2 [walk-through of this process](https://www.youtube.com/watch?v=XuBpKtsgGkE). -### Agent naming convention +### Create an agent configuration file + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the agent configuration file can be added to multiple directories (or subdirectories) of the repository. +> - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. + +The agent uses a YAML file for configuration settings. You must create this file if: + +- You use [a GitOps workflow](../gitops.md#gitops-workflow-steps). +- You use [a GitLab CI/CD workflow](../ci_cd_workflow.md#gitlab-cicd-workflow-steps) and want to authorize a different project to use the agent. + +To create an agent configuration file: + +1. Choose a name for your agent. The agent name follows the + [DNS label standard from RFC 1123](https://tools.ietf.org/html/rfc1123). The name must: + + - Be unique in the project. + - Contain at most 63 characters. + - Contain only lowercase alphanumeric characters or `-`. + - Start with an alphanumeric character. + - End with an alphanumeric character. + +1. In the repository, create a directory in this location: -The agent name must follow the [DNS label standard from RFC 1123](https://tools.ietf.org/html/rfc1123). -The name must: + ```plaintext + .gitlab/agents/<agent-name> + ``` -- Be unique in the project. -- Contain at most 63 characters. -- Contain only lowercase alphanumeric characters or `-`. -- Start with an alphanumeric character. -- End with an alphanumeric character. +1. In the directory, create a `config.yaml` file. Ensure the filename ends in `.yaml`, not `.yml`. + +You can leave the file blank for now, and [configure it](#configure-your-agent) later. ### Register the agent with GitLab @@ -64,34 +86,13 @@ You must register an agent before you can install the agent in your cluster. To it must be in this project. Your cluster manifest files should also be in this project. 1. From the left sidebar, select **Infrastructure > Kubernetes clusters**. 1. Select **Connect a cluster (agent)**. - - If you want to create a configuration with CI/CD defaults, type a name that meets [the naming convention](#agent-naming-convention). + - If you want to create a configuration with CI/CD defaults, type a name. - If you already have an [agent configuration file](#create-an-agent-configuration-file), select it from the list. 1. Select **Register an agent**. -1. GitLab generates an access token for the agent. Securely store this token. You need it to install the agent in your cluster and to [update the agent](#update-the-agent-version) to another version. -1. Copy the command under **Recommended installation method**. You need it when you use the one-liner installation method to install the agent in your cluster. - -### Create an agent configuration file - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the agent configuration file can be added to multiple directories (or subdirectories) of the repository. -> - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. - -The agent uses a YAML file for configuration settings. You need a configuration file if: - -- You want to use [a GitOps workflow](../gitops.md#gitops-configuration-reference). -- You want to authorize a different project to use the agent for a [GitLab CI/CD workflow](../ci_cd_workflow.md#authorize-the-agent). - -To create an agent configuration file: - -1. In the repository, create a directory in this location. The `<agent-name>` must meet [the naming convention](#agent-naming-convention). - - ```plaintext - .gitlab/agents/<agent-name> - ``` - -1. In the directory, create a `config.yaml` file. Ensure the filename ends in `.yaml`, not `.yml`. -1. Add content to the `config.yaml` file: - - For a GitOps workflow, view [the configuration reference](../gitops.md#gitops-configuration-reference) for details. - - For a GitLab CI/CD workflow, view [the configuration reference](../ci_cd_workflow.md) for details. +1. GitLab generates an access token for the agent. Securely store this token. You need it to install the agent + in your cluster and to [update the agent](#update-the-agent-version) to another version. +1. Copy the command under **Recommended installation method**. You need it when you use + the one-liner installation method to install the agent in your cluster. ### Install the agent in the cluster @@ -128,21 +129,45 @@ By default, the Helm installation command generated by GitLab: To see the full list of customizations available, see the Helm chart's [default values file](https://gitlab.com/gitlab-org/charts/gitlab-agent/-/blob/main/values.yaml). +##### Use the agent behind an HTTP proxy + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351867) in GitLab 15.0, the GitLab agent Helm chart supports setting environment variables. + +To configure an HTTP proxy when using the Helm chart, you can use the environment variables `HTTP_PROXY`, `HTTPS_PROXY`, +and `NO_PROXY`. Upper and lowercase are both acceptable. + +You can set these variables by using the `extraEnv` value, as a list of objects with keys `name` and `value`. +For example, to set only the environment variable `HTTPS_PROXY` to the value `https://example.com/proxy`, you can run: + +```shell +helm upgrade --install gitlab-agent gitlab/gitlab-agent \ + --set extraEnv[0].name=HTTPS_PROXY \ + --set extraEnv[0].value=https://example.com/proxy \ + ... +``` + #### 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. +### Configure your agent + +To configure your agent, add content to the `config.yaml` file: + +- [View the configuration reference](../gitops.md#gitops-configuration-reference) for a GitOps workflow. +- [View the configuration reference](../ci_cd_workflow.md) for a GitLab CI/CD workflow. + ## Install multiple agents in your cluster To install a second agent in your cluster, you can follow the [previous steps](#register-the-agent-with-gitlab) a second time. To avoid resource name collisions within the cluster, you must either: -- Use a different release name for the agent, e.g. `second-gitlab-agent`: +- Use a different release name for the agent, for example, `second-gitlab-agent`: ```shell helm upgrade --install second-gitlab-agent gitlab/gitlab-agent ... ``` -- Or, install the agent in a different namespace, e.g. `different-namespace`: +- Or, install the agent in a different namespace, for example, `different-namespace`: ```shell helm upgrade --install gitlab-agent gitlab/gitlab-agent \ @@ -163,7 +188,7 @@ The following example projects can help you get started with the agent. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340882) in GitLab 14.8, GitLab warns you on the agent's list page to update the agent version installed on your cluster. -For the best experience, the version of the agent installed in your cluster should match the GitLab major and minor version. The previous minor version is also supported. For example, if your GitLab version is v14.9.4 (major version 14, minor version 9), then versions v14.9.0 and v14.9.1 of the agent are ideal, but any v14.8.x version of the agent is also supported. See [this page](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/releases) of releases of the GitLab agent. +For the best experience, the version of the agent installed in your cluster should match the GitLab major and minor version. The previous minor version is also supported. For example, if your GitLab version is v14.9.4 (major version 14, minor version 9), then versions v14.9.0 and v14.9.1 of the agent are ideal, but any v14.8.x version of the agent is also supported. See [the release page](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/releases) of the GitLab agent. ### Update the agent version diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md index 69f5b1d9063..706ed122f7b 100644 --- a/doc/user/clusters/agent/vulnerabilities.md +++ b/doc/user/clusters/agent/vulnerabilities.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Container vulnerability scanning **(ULTIMATE)** +# Operational Container Scanning **(ULTIMATE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6346) in GitLab 14.8. @@ -16,8 +16,6 @@ You can also configure your agent so the vulnerabilities are displayed with othe Prerequisite: - You must have at least the Developer role. -- [Cluster image scanning](../../application_security/cluster_image_scanning/index.md) - must be part of your build process. To view vulnerability information in GitLab: @@ -28,6 +26,8 @@ To view vulnerability information in GitLab:  +This information can also be found under [operational vulnerabilities](../../../user/application_security/vulnerability_report/index.md#operational-vulnerabilities). + ## Enable cluster vulnerability scanning **(ULTIMATE)** You can use [cluster image scanning](../../application_security/cluster_image_scanning/index.md) @@ -39,8 +39,7 @@ containing a CRON expression for when the scans will be run. ```yaml starboard: - vulnerability_report: - cadence: '0 0 * * *' # Daily at 00:00 (Kubernetes cluster time) + cadence: '0 0 * * *' # Daily at 00:00 (Kubernetes cluster time) ``` The `cadence` field is required. GitLab supports the following types of CRON syntax for the cadence field: @@ -58,8 +57,8 @@ namespaces, you can use this configuration: ```yaml starboard: + cadence: '0 0 * * *' vulnerability_report: - cadence: '0 0 * * *' namespaces: - development - staging diff --git a/doc/user/clusters/create/index.md b/doc/user/clusters/create/index.md index bee622ac50a..b3d2b9f23fa 100644 --- a/doc/user/clusters/create/index.md +++ b/doc/user/clusters/create/index.md @@ -11,3 +11,4 @@ You connect the clusters to GitLab by using the agent for Kubernetes. - [Create a cluster on Google GKE](../../infrastructure/clusters/connect/new_gke_cluster.md) - [Create a cluster on Amazon EKS](../../infrastructure/clusters/connect/new_eks_cluster.md) +- [Create a cluster on Civo](../../infrastructure/clusters/connect/new_civo_cluster.md) diff --git a/doc/user/clusters/crossplane.md b/doc/user/clusters/crossplane.md index 3f38a473128..16615f88e25 100644 --- a/doc/user/clusters/crossplane.md +++ b/doc/user/clusters/crossplane.md @@ -10,4 +10,4 @@ redirect_to: '../../update/removals.md#managed-cluster-applicationsgitlab-ciyml' This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/333610) -in GitLab 15.0. Use [crossplane](http://crossplane.io/) directly instead. +in GitLab 15.0. Use [crossplane](https://crossplane.io/) directly instead. diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index 4ba0de3bf55..b7732a7abf8 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -49,7 +49,7 @@ In order to: After you have successful deployments to your group-level or instance-level cluster: 1. Navigate to your group's **Kubernetes** page. -1. Click on the **Environments** tab. +1. Select the **Environments** tab. Only successful deployments to the cluster are included in this page. Non-cluster environments aren't included. diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md index a6dbb5fe0d7..94fb443e0fb 100644 --- a/doc/user/clusters/integrations.md +++ b/doc/user/clusters/integrations.md @@ -98,7 +98,7 @@ To enable the Prometheus integration for your cluster: **Kubernetes** page. 1. Select the **Integrations** tab. 1. Check the **Enable Prometheus integration** checkbox. -1. Click **Save changes**. +1. Select **Save changes**. 1. Go to the **Health** tab to see your cluster's metrics. ## Elastic Stack cluster integration **(FREE SELF)** @@ -165,5 +165,5 @@ To enable the Elastic Stack integration for your cluster: **Kubernetes** page. 1. Select the **Integrations** tab. 1. Check the **Enable Elastic Stack integration** checkbox. -1. Click **Save changes**. +1. Select **Save changes**. 1. Go to the **Health** tab to see your cluster's metrics. diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index 8ca1bf5d57f..7ab77c67bcc 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -49,7 +49,7 @@ To create a project from the cluster management project template: 1. Select **Create project**. If you use self-managed GitLab, your instance might not include the latest version of the template. -In that case, select **Import project**, **Repo by URL** and for the **Git repository URL**, enter +In that case, select **Import project**, **Repository by URL** and for the **Git repository URL**, enter `https://gitlab.com/gitlab-org/project-templates/cluster-management.git`. ## Configure the project diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md index 77dbefa0755..0006ae02752 100644 --- a/doc/user/compliance/compliance_report/index.md +++ b/doc/user/compliance/compliance_report/index.md @@ -113,7 +113,7 @@ You can generate a commit-specific Chain of Custody report for a given commit SH 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Security & Compliance > Compliance report**. -1. At the top of the compliance report, to the right of **List of all merge commits**, select the down arrow (**{angle-down}**). +1. At the top of the compliance report, to the right of **List of all merge commits**, select the down arrow (**{chevron-lg-down}**). 1. Enter the merge commit SHA, and then select **Export commit custody report**. SHA and then select **Export commit custody report**. diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md index 7a400205e30..b5287816052 100644 --- a/doc/user/crm/index.md +++ b/doc/user/crm/index.md @@ -9,10 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2256) in GitLab 14.6 [with a flag](../../administration/feature_flags.md) named `customer_relations`. Disabled by default. > - In GitLab 14.8 and later, you can [create contacts and organizations only in root groups](https://gitlab.com/gitlab-org/gitlab/-/issues/350634). > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/346082) in GitLab 15.0. - -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 `customer_relations`. -On GitLab.com, this feature is available. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/346082) in GitLab 15.1. With customer relations management (CRM) you can create a record of contacts (individuals) and organizations (companies) and relate them to issues. @@ -33,9 +30,13 @@ To read more about what is planned for the future, see [issue 2256](https://gitl ## Enable customer relations management (CRM) -To enable customer relations management in a group: +Customer relations management features must be enabled at the group level. If your +group also contains subgroups, and you want to use CRM features in the subgroup, +you must enable CRM features for the subgroup. -1. On the top bar, select **Menu > Groups** and find your group. +To enable customer relations management in a group or subgroup: + +1. On the top bar, select **Menu > Groups** and find your group or subgroup. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Permissions and group features** section. 1. Select **Enable customer relations**. @@ -173,7 +174,6 @@ API. 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 `contacts_autocomplete`. On GitLab.com, this feature is available. -This feature is not ready for production use. When you use the `/add_contacts` or `/remove_contacts` quick actions, follow them with `[contact:` and an autocomplete list appears: diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 97c3d5f1058..a0649a61905 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -256,7 +256,7 @@ To create a thread by replying to a comment: The reply section is displayed. 1. Enter your reply. -1. Select **Comment** or **Add comment now** (depending on where in the UI you are replying). +1. Select **Reply** or **Add comment now** (depending on where in the UI you are replying). The top comment is converted to a thread. diff --git a/doc/user/free_user_limit.md b/doc/user/free_user_limit.md index 2340ef254f6..868e322cac9 100644 --- a/doc/user/free_user_limit.md +++ b/doc/user/free_user_limit.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Free user limit **(FREE SAAS)** -In GitLab 15.1 (June 22, 2022) and later, namespaces in GitLab.com on the Free tier +From September 15, 2022, namespaces in GitLab.com on the Free tier will be limited to five (5) members per [namespace](group/index.md#namespaces). This limit applies to top-level groups and personal namespaces. diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index e88777a7223..d515f9f4558 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -133,7 +133,7 @@ Below are the settings for [GitLab Pages](https://about.gitlab.com/stages-devops | IP address | `35.185.44.232` | - | | Custom domains support | **{check-circle}** Yes | **{dotted-circle}** No | | TLS certificates support | **{check-circle}** Yes | **{dotted-circle}** No | -| [Maximum size](../../administration/pages/index.md#set-global-maximum-pages-size-per-project) (compressed) | 1 GB | 100 MB | +| [Maximum size](../../administration/pages/index.md#set-global-maximum-size-of-each-gitlab-pages-site) (compressed) | 1 GB | 100 MB | The maximum size of your Pages site is also regulated by the artifacts maximum size, which is part of [GitLab CI/CD](#gitlab-cicd). @@ -156,10 +156,12 @@ the related documentation. | Maximum number of pipeline triggers in a project | `25000` for Free tier, Unlimited for all paid tiers | See [Limit the number of pipeline triggers](../../administration/instance_limits.md#limit-the-number-of-pipeline-triggers) | | Maximum pipeline schedules in projects | `10` for Free tier, `50` for all paid tiers | See [Number of pipeline schedules](../../administration/instance_limits.md#number-of-pipeline-schedules) | | Maximum pipelines per schedule | `24` for Free tier, `288` for all paid tiers | See [Limit the number of pipelines created by a pipeline schedule per day](../../administration/instance_limits.md#limit-the-number-of-pipelines-created-by-a-pipeline-schedule-per-day) | +| Maximum number of schedule rules defined for each security policy project | Unlimited for all paid tiers | See [Number of schedule rules defined for each security policy project](../../administration/instance_limits.md#limit-the-number-of-schedule-rules-defined-for-security-policy-project) | | Scheduled job archiving | 3 months (from June 22, 2020). Jobs created before that date were archived after September 22, 2020. | Never | -| Maximum test cases per [unit test report](../../ci/unit_test_reports.md) | `500000` | Unlimited | +| Maximum test cases per [unit test report](../../ci/testing/unit_test_reports.md) | `500000` | Unlimited | | Maximum registered runners | Free tier: `50` per-group / `50` per-project<br/>All paid tiers: `1000` per-group / `1000` per-project | See [Number of registered runners per scope](../../administration/instance_limits.md#number-of-registered-runners-per-scope) | | Limit of dotenv variables | Free tier: `50` / Premium tier: `100` / Ultimate tier: `150` | See [Limit dotenv variables](../../administration/instance_limits.md#limit-dotenv-variables) | +| Authorization token duration (minutes) | `15` | To set a custom value, in the Rails console, run `ApplicationSetting.last.update(container_registry_token_expire_delay: <integer>)`, where `<integer>` is the desired number of minutes. | ## Package registry limits @@ -186,7 +188,7 @@ the default value [is the same as for self-managed instances](../admin_area/sett | Setting | GitLab.com default | |-------------------------------|--------------------| | [Repository size including LFS](../admin_area/settings/account_and_limit_settings.md#repository-size-limit) | 10 GB | -| Maximum import size | 5 GB | +| [Maximum import size](../project/settings/import_export.md#maximum-import-file-size) | 5 GB | | Maximum attachment size | 10 MB | If you are near or over the repository size limit, you can either @@ -232,7 +234,7 @@ The following limits apply for [webhooks](../project/integrations/webhooks.md): | Setting | Default for GitLab.com | |----------------------|-------------------------| -| Webhook rate limit | `120` calls per minute for GitLab Free, unlimited for GitLab Premium and GitLab Ultimate | +| Webhook rate limit | `500` calls per minute for GitLab Free, unlimited for GitLab Premium and GitLab Ultimate. Webhook rate limits are applied per top-level namespace. | | Number of webhooks | `100` per project, `50` per group | | Maximum payload size | 25 MB | @@ -328,19 +330,20 @@ limiting responses](#rate-limiting-responses). The following table describes the rate limits for GitLab.com, both before and after the limits change in January, 2021: -| Rate limit | From 2021-02-12 | From 2022-02-03 | -|:--------------------------------------------------------------------------|:------------------------------|:----------------------------------------| -| **Protected paths** (for a given **IP address**) | **10** requests per minute | **10** requests per minute | -| **Raw endpoint** traffic (for a given **project, commit, and file path**) | **300** requests per minute | **300** requests per minute | -| **Unauthenticated** traffic (from a given **IP address**) | **500** requests per minute | **500** requests per minute | -| **Authenticated** API traffic (for a given **user**) | **2,000** requests per minute | **2,000** requests per minute | -| **Authenticated** non-API HTTP traffic (for a given **user**) | **1,000** requests per minute | **1,000** requests per minute | -| **All** traffic (from a given **IP address**) | **2,000** requests per minute | **2,000** requests per minute | -| **Issue creation** | **300** requests per minute | **200** requests per minute | -| **Note creation** (on issues and merge requests) | **60** requests per minute | **60** requests per minute | -| **Advanced, project, and group search** API (for a given **IP address**) | **10** requests per minute | **10** requests per minute | -| **GitLab Pages** requests (for a given **IP address**) | | **1000** requests per **50 seconds** | -| **GitLab Pages** requests (for a given **GitLab Pages domain**) | | **5000** requests per **10 seconds** | +| Rate limit | From 2021-02-12 | From 2022-02-03 | +|:---------------------------------------------------------------------------|:------------------------------|:----------------------------------------| +| **Protected paths** (for a given **IP address**) | **10** requests per minute | **10** requests per minute | +| **Raw endpoint** traffic (for a given **project, commit, and file path**) | **300** requests per minute | **300** requests per minute | +| **Unauthenticated** traffic (from a given **IP address**) | **500** requests per minute | **500** requests per minute | +| **Authenticated** API traffic (for a given **user**) | **2,000** requests per minute | **2,000** requests per minute | +| **Authenticated** non-API HTTP traffic (for a given **user**) | **1,000** requests per minute | **1,000** requests per minute | +| **All** traffic (from a given **IP address**) | **2,000** requests per minute | **2,000** requests per minute | +| **Issue creation** | **300** requests per minute | **200** requests per minute | +| **Note creation** (on issues and merge requests) | **60** requests per minute | **60** requests per minute | +| **Advanced, project, and group search** API (for a given **IP address**) | **10** requests per minute | **10** requests per minute | +| **GitLab Pages** requests (for a given **IP address**) | | **1000** requests per **50 seconds** | +| **GitLab Pages** requests (for a given **GitLab Pages domain**) | | **5000** requests per **10 seconds** | +| **Pipeline creation** requests (for a given **project, user, and commit**) | | **25** requests per minute | More details are available on the rate limits for [protected paths](#protected-paths-throttle) and [raw @@ -424,7 +427,7 @@ setting [disabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/1 ### SSH maximum number of connections GitLab.com defines the maximum number of concurrent, unauthenticated SSH -connections by using the [MaxStartups setting](http://man.openbsd.org/sshd_config.5#MaxStartups). +connections by using the [MaxStartups setting](https://man.openbsd.org/sshd_config.5#MaxStartups). If more than the maximum number of allowed connections occur concurrently, they are dropped and users get [an `ssh_exchange_identification` error](../../topics/git/troubleshooting_git.md#ssh_exchange_identification-error). diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index cd2d5c190a1..ba805d6e1bb 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -49,7 +49,7 @@ Select the desired period from the calendar dropdown. ## Sorting by different factors -Contributions per group member are also presented in tabular format. Click a column header to sort the table by that column: +Contributions per group member are also presented in tabular format. Select a column header to sort the table by that column: - Member name - Number of pushed events diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index 00e6bc671c1..6755bf9ffb9 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -41,7 +41,7 @@ Projects in nested subgroups are not included in the template list. ## Which projects are available as templates - Public and internal projects can be selected by any signed-in user as a template for a new project, - if all [project features](../project/settings/index.md#sharing-and-permissions) + if all [project features](../project/settings/index.md#configure-project-visibility-features-and-permissions) except for **GitLab Pages** and **Security & Compliance** are set to **Everyone With Access**. - Private projects can be selected only by users who are members of the projects. diff --git a/doc/user/group/epics/img/epics_search_v14_7.png b/doc/user/group/epics/img/epics_filter_v14_7.png Binary files differindex baed532c736..baed532c736 100644 --- a/doc/user/group/epics/img/epics_search_v14_7.png +++ b/doc/user/group/epics/img/epics_filter_v14_7.png diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index e8f720238ed..e0334eda875 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -87,6 +87,26 @@ To edit an epic's start date, due date, or labels: 1. Next to each section in the right sidebar, select **Edit**. 1. Select the dates or labels for your epic. +### Reorder list items in the epic description + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15260) in GitLab 15.1. + +When you view an epic that has a list in the description, you can also reorder the list items. + +Prerequisites: + +- You must have at least the Reporter role for the project, be the author of the epic, or be + assigned to the epic. +- The epic's description must have an [ordered, unordered](../../markdown.md#lists), or + [task](../../markdown.md#task-lists) list. + +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. Drag the row to the new position in the list. +1. Release the drag icon. + ## Bulk edit epics > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7250) in GitLab 12.2. @@ -187,17 +207,17 @@ To view epics in a group: The total count of open epics displayed in the sidebar is cached if higher than 1000. The cached value is rounded to thousands or millions and updated every 24 hours. -## Search for an epic from epics list page +## Filter the list of epics -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) from GitLab Ultimate to GitLab Premium in 12.8. -> - Searching by the user's reaction emoji [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325630) in GitLab 13.11. +> - Filtering by epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195704) in GitLab 12.9. +> - Filtering by child epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9029) in GitLab 13.0. +> - Filtering by the user's reaction emoji [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325630) in GitLab 13.11. > - Sorting by epic titles [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.1. -> - Searching 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. +> - 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. -You can search for an epic from the list of epics using filtered search bar based on following -parameters: +You can filter the list of epics by: - Title or description - Author name / username @@ -206,9 +226,9 @@ parameters: - Confidentiality - Reaction emoji - + -To search: +To filter: 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Epics**. @@ -216,7 +236,9 @@ To search: 1. From the dropdown menu, 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. -You can also sort epics list by: +## Sort the list of epics + +You can sort the epics list by: - Start date - Due date diff --git a/doc/user/group/img/restrict-by-email.gif b/doc/user/group/img/restrict-by-email.gif Binary files differdeleted file mode 100644 index d1ebeb07a0a..00000000000 --- a/doc/user/group/img/restrict-by-email.gif +++ /dev/null diff --git a/doc/user/group/img/restrict-by-ip.gif b/doc/user/group/img/restrict-by-ip.gif Binary files differdeleted file mode 100644 index 6292a58e748..00000000000 --- a/doc/user/group/img/restrict-by-ip.gif +++ /dev/null diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index 6967815bf22..ae1465d0b1b 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -1,37 +1,42 @@ --- -type: reference, howto stage: Manage group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Migrate groups from another instance of GitLab **(FREE)** +# Migrating groups **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/249160) in GitLab 13.7 [with a flag](../../feature_flags.md) named `bulk_import`. Disabled by default. -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/338985) in GitLab 14.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/249160) in GitLab 13.7 for group resources [with a flag](../../feature_flags.md) named `bulk_import`. Disabled by default. +> - Group resources [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/338985) in GitLab 14.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4 for project resources [with a flag](../../feature_flags.md) named `bulk_import_projects`. Disabled by default. 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 `bulk_import`. On GitLab.com, this feature is available. +On self-managed GitLab, by default [migrating group resources](#migrated-group-resources) is available. To hide the +feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `bulk_import`. +On self-managed GitLab, by default [migrating project resources](#migrated-project-resources) is not available. To show +this feature, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named +`bulk_import_projects`. On GitLab.com, migrating group resources is available but migrating project resources is not +available. -You can migrate your existing top-level groups to any of the following: +Users with the Owner role on a top-level group can migrate it to: -- Another GitLab instance, including GitLab.com. - Another top-level group. - The subgroup of any existing top-level group. +- Another GitLab instance, including GitLab.com. -Migrating groups is not the same as [group import/export](../settings/import_export.md). - -- Group import/export requires you to export a group to a file and then import that file in - another GitLab instance. -- Group migration automates this process. +Migrating groups using the method documented here is not the same as [migrating groups using file exports](../settings/import_export.md). +Importing and exporting groups using file exports requires you to export a group to a file and then import that file in +another GitLab instance. Migrating groups using the method documented here automates this step. ## Import your groups into GitLab When you migrate a group, you connect to your GitLab instance and then choose -groups to import. Not all the data is migrated. View the -[Migrated resources](#migrated-resources) list for details. +groups to import. Not all the data is migrated. See: + +- [Migrated group resources](#migrated-group-resources). +- [Migrated project resources](#migrated-project-resources). -Leave feedback about group migration in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/284495). +Leave feedback about group migration in [the relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/284495). NOTE: You might need to reconfigure your firewall to prevent blocking the connection on the self-managed @@ -74,66 +79,57 @@ Migration importer page. The remote groups you have the Owner role for are liste For information on automating user, group, and project import API calls, see [Automate group and project import](../../project/import/index.md#automate-group-and-project-import). -## Migrated resources +## Migrated group resources Only the following resources are migrated to the target instance. Any other items are **not** migrated: -- Groups ([Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4374) in 13.7) - - description - - attributes - - subgroups - - avatar ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322904) in 14.0) -- Group labels ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292429) in 13.9) - - title - - description - - color - - created_at ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300007) in 13.10) - - updated_at ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300007) in 13.10) +- Badges ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292431) in 13.11) +- Board Lists +- Boards +- Epics ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250281) in 13.7) +- Finisher +- Group Labels ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292429) in 13.9) +- Iterations ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292428) in 13.10) - 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 has a public email in the source GitLab instance that matches a confirmed email in the target GitLab instance -- Epics ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250281) in 13.7) - - title - - description - - state (open / closed) - - start date - - due date - - epic order on boards - - confidentiality - - labels ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/297460) in 13.9) - - author ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/298745) in 13.9) - - parent epic ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/297459) in 13.9) - - emoji award ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/297466) in 13.9) - - events ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/297465) in 13.10) - Milestones ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292427) in 13.10) - - title - - description - - state (active / closed) - - start date - - due date - - created at - - updated at - - iid ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326157) in 13.11) -- Iterations ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292428) in 13.10) - - iid - - title - - description - - state (upcoming / started / closed) - - start date - - due date - - created at - - updated at -- Badges ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292431) in 13.11) - - name - - link URL - - image URL -- Boards -- Board Lists +- Namespace Settings - Releases - Milestones ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339422) in GitLab 15.0). +- Sub-Groups +- Uploads + +## Migrated project resources + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4 [with a flag](../../feature_flags.md) named `bulk_import_projects`. Disabled by default. + +FLAG: +On self-managed GitLab, migrating project resources are not available by default. To make them available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `bulk_import_projects`. On GitLab.com, migrating project resources are not available. + +- 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) + - Branches (including protected branches) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339414) in GitLab 14.7) + - CI Pipelines ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339407) in GitLab 14.6) + - Designs ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339421) in GitLab 15.1) + - Issues ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267946) in GitLab 14.4) + - Labels ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339419) in GitLab 14.4) + - LFS Objects ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339405) in GitLab 14.8) + - Members ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/341886) in GitLab 14.8) + - Merge Requests ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339403) in GitLab 14.5) + - Migrate Push Rules ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339403) in GitLab 14.6) + - Pull Requests (including external pull requests) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339409) in GitLab 14.5) + - Pipeline History ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339412) in GitLab 14.6) + - Pipeline Schedules ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339408) in GitLab 14.8) + - Releases ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339422) in GitLab 15.1) + - Release Evidences ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/360567) in GitLab 15.1) + - Repositories ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4) + - Snippets ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343438) in GitLab 14.6) + - Uploads ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339401) in GitLab 14.5) + - Wikis ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345923) in GitLab 14.6) ## Troubleshooting Group Migration diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 87146329031..c0ae721e3b4 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -418,7 +418,7 @@ This action removes the group. It also adds a background job to delete all proje Specifically: -- In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [GitLab Premium](https://about.gitlab.com/pricing/premium/) or higher tiers, this action adds a background job to mark a group for deletion. By default, the job schedules the deletion 7 days in the future. You can modify this waiting period through the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). +- In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [GitLab Premium](https://about.gitlab.com/pricing/premium/) or higher tiers, this action adds a background job to mark a group for deletion. By default, the job schedules the deletion 7 days in the future. You can modify this waiting period through the [instance settings](../admin_area/settings/visibility_and_access_controls.md#deletion-protection). - In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/39504), if the user who sets up the deletion is removed from the group before the deletion happens, the job is cancelled, and the group is no longer scheduled for deletion. @@ -599,7 +599,7 @@ You can export a list of members in a group or subgroup as a CSV. 1. Select **Export as CSV**. 1. After the CSV file has been generated, it is emailed as an attachment to the user that requested it. -## Restrict group access by IP address **(PREMIUM)** +## Group access restriction by IP address **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in GitLab 12.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215410) from GitLab Ultimate to GitLab Premium in 13.1. @@ -611,24 +611,26 @@ applies to: - The GitLab UI, including subgroups, projects, and issues. - [In GitLab 12.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/12874), the API. -You should consider these security implications before configuring IP address restrictions: - -- **SSH requests, including `git` operations will fail from all IP addresses**: While you can restrict HTTP traffic on GitLab.com with IP address restrictions, - they cause SSH requests, including Git operations over SSH, to fail. For more information, - read [issue 271673](https://gitlab.com/gitlab-org/gitlab/-/issues/271673). -- **Administrators and group owners can access group settings from any IP address**: Users with these permission levels can always - access the group settings, regardless of IP restriction, but they cannot access projects - belonging to the group when accessing from a disallowed IP address. -- **Some GitLab API endpoints will remain accessible from any IP**: Only the [group](../../api/groups.md) (including all - [group resources](../../api/api_resources.md#group-resources)) APIs and [project](../../api/api_resources.md#project-resources) - (including all [project resources](../../api/api_resources.md#project-resources)) APIs are protected by IP address restrictions. -- **Activities performed by GitLab Runners are not bound by IP restrictions**: - When you register a runner, it is not bound by the IP restrictions. When the runner - requests a new job or an update to a job's state, it is also not bound by - the IP restrictions. But when the running CI/CD job sends Git requests from a +### Security implications + +You should consider some security implications before configuring IP address restrictions. + +- Restricting HTTP traffic on GitLab.com with IP address restrictions causes SSH requests (including Git operations over + SSH) to fail. For more information, see [the relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/271673). +- Administrators and group owners can access group settings from any IP address, regardless of IP restriction. However: + - Groups owners cannot access projects belonging to the group when accessing from a disallowed IP address. + - Administrators can access projects belonging to the group when accessing from a disallowed IP address. + Access to projects includes cloning code from them. + - Users can still see group and project names and hierarchies. Only the following are restricted: + - [Groups](../../api/groups.md), including all [group resources](../../api/api_resources.md#group-resources). + - [Project](../../api/projects.md), including all [project resources](../../api/api_resources.md#project-resources). +- When you register a runner, it is not bound by the IP restrictions. When the runner requests a new job or an update to + a job's state, it is also not bound by the IP restrictions. But when the running CI/CD job sends Git requests from a restricted IP address, the IP restriction prevents code from being cloned. -- **User dashboard activity**: Users may still see some events from the IP restricted groups and projects - on their dashboard. Activity may include push, merge, issue, or comment events. +- Users may still see some events from the IP restricted groups and projects on their dashboard. Activity may include + push, merge, issue, or comment events. + +### Restrict group access by IP address To restrict group access by IP address: @@ -637,7 +639,9 @@ To restrict group access by IP address: 1. In the **Allow access to the following IP addresses** field, enter IPv4 or IPv6 address ranges in CIDR notation. 1. Select **Save changes**. -  +In self-managed installations of GitLab 15.1 and later, you can also configure +[globally-allowed IP address ranges](../admin_area/settings/visibility_and_access_controls.md#configure-globally-allowed-ip-address-ranges) +at the group level. ## Restrict group access by domain **(PREMIUM)** @@ -654,8 +658,6 @@ To restrict group access by domain: 1. In the **Restrict membership by email** field, enter the domain names. 1. Select **Save changes**. - - Any time you attempt to add a new user, the user's [primary email](../profile/index.md#change-your-primary-email) is compared against this list. Only users with a [primary email](../profile/index.md#change-your-primary-email) that matches any of the configured email domain restrictions can be added to the group. @@ -734,14 +736,17 @@ To disable group mentions: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. > - [Inheritance and enforcement added](https://gitlab.com/gitlab-org/gitlab/-/issues/321724) in GitLab 13.11. > - [Instance setting to enable by default added](https://gitlab.com/gitlab-org/gitlab/-/issues/255449) in GitLab 14.2. +> - [Instance setting is inherited and enforced when disabled](https://gitlab.com/gitlab-org/gitlab/-/issues/352960) in GitLab 15.1. +> - [User interface changed](https://gitlab.com/gitlab-org/gitlab/-/issues/352961) in GitLab 15.1. -[Delayed project deletion](../project/settings/index.md#delayed-project-deletion) can be enabled for groups. When enabled, projects in -the group are deleted after a period of delay. During this period, projects are in a read-only state and can be restored. The default -period is seven days but [is configurable at the instance level](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). +[Delayed project deletion](../project/settings/index.md#delayed-project-deletion) is locked and disabled unless the instance-level settings for +[deletion protection](../admin_area/settings/visibility_and_access_controls.md#deletion-protection) is enabled for either groups only or groups and projects. +When enabled on groups, projects in the group are deleted after a period of delay. During this period, projects are in a read-only state and can be restored. +The default period is seven days but [is configurable at the instance level](../admin_area/settings/visibility_and_access_controls.md#retention-period). On self-managed GitLab, projects are deleted immediately by default. In GitLab 14.2 and later, an administrator can -[change the default setting](../admin_area/settings/visibility_and_access_controls.md#default-delayed-project-deletion) +[change the default setting](../admin_area/settings/visibility_and_access_controls.md#deletion-protection) for projects in newly-created groups. On GitLab.com, see the [GitLab.com settings page](../gitlab_com/index.md#delayed-project-deletion) for @@ -751,8 +756,12 @@ To enable delayed deletion of projects in a group: 1. Go to the group's **Settings > General** page. 1. Expand the **Permissions and group features** section. -1. Check **Enable delayed project deletion**. -1. Optional. To prevent subgroups from changing this setting, select **Enforce for all subgroups**. +1. Scroll to: + - (GitLab 15.1 and later) **Deletion protection** and select **Keep deleted projects**. + - (GitLab 15.0 and earlier) **Enable delayed project deletion** and tick the checkbox. +1. Optional. To prevent subgroups from changing this setting, select: + - (GitLab 15.1 and later), **Enforce deletion protection for all subgroups** + - (GitLab 15.0 and earlier), **Enforce for all subgroups**. 1. Select **Save changes**. NOTE: @@ -766,8 +775,6 @@ 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. -Previously, this setting was available only for groups enforcing a -[Group Managed Account](saml_sso/group_managed_accounts.md) in SAML. This setting will be 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. @@ -800,7 +807,7 @@ The group's new subgroups have push rules set for them based on either: - The closest parent group with push rules defined. - Push rules set at the instance level, if no parent groups have push rules defined. -## Group approval settings **(PREMIUM)** +## Group merge request approval settings **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285458) in GitLab 13.9. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../administration/feature_flags.md), disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.5. @@ -844,6 +851,7 @@ Support for group-level settings for merge request approval rules is tracked in - [Enforce two-factor authentication (2FA)](../../security/two_factor_authentication.md#enforce-2fa-for-all-users-in-a-group): Enforce 2FA for all group members. - Namespaces [API](../../api/namespaces.md) and [Rake tasks](../../raketasks/features.md). +- [Control access and visibility](../admin_area/settings/visibility_and_access_controls.md). ## Troubleshooting @@ -855,7 +863,7 @@ If a user sees a 404 when they would normally expect access, and the problem is - `json.allowed`: `false` In viewing the log entries, compare the `remote.ip` with the list of -[allowed IPs](#restrict-group-access-by-ip-address) for the group. +[allowed IPs](#group-access-restriction-by-ip-address) for the group. ### Validation errors on namespaces and groups diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md index 6771ff8739a..0a00d0c1c1c 100644 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ b/doc/user/group/saml_sso/group_managed_accounts.md @@ -3,121 +3,12 @@ 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/engineering/ux/technical-writing/#assignments +remove_date: '2022-06-13' +redirect_to: 'index.md' --- # Group Managed Accounts **(PREMIUM)** -WARNING: -This [Closed Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#sts=Closed%20Beta) feature is being re-evaluated in favor of a different -[approach](https://gitlab.com/groups/gitlab-org/-/epics/4786) that aligns more closely with our [Subscription Agreement](https://about.gitlab.com/handbook/legal/subscription-agreement/). -We recommend that group owners who haven't yet implemented this feature wait for the new solution. - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/709) in GitLab 12.1. -> - It's deployed behind a feature flag, disabled by default. - -When [SSO for Groups](index.md) is enforced, groups can enable an additional level of protection by enforcing the creation of dedicated user accounts to access the group. - -With group-managed accounts enabled, users are required to create a new, dedicated user linked to the group. -The notification email address associated with the user is locked to the email address received from the configured identity provider. -Without group-managed accounts, users can link their SAML identity with any existing user on the instance. - -When this option is enabled: - -- All users in the group are required to log in via the SSO URL associated with the group. -- After the group-managed account has been created, group activity requires the use of this user account. -- Users can't share a project in the group outside the top-level group (also applies to forked projects). - -Upon successful authentication, GitLab prompts the user with options, based on the email address received from the configured identity provider: - -- To create a unique account with the newly received email address. -- If the received email address matches one of the user's verified GitLab email addresses, the option to convert the existing account to a group-managed account. ([Introduced in GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/13481).) - -Since use of the group-managed account requires the use of SSO, users of group-managed accounts lose access to these accounts when they are no longer able to authenticate with the connected identity provider. In the case of an offboarded employee who has been removed from your identity provider: - -- The user is unable to access the group (their credentials no longer work on the identity provider when prompted to use SSO). -- Contributions in the group (for example, issues and merge requests) remains intact. - -Please refer to our [SAML SSO for Groups page](../index.md) for information on how to configure SAML. - -## Feature flag **(PREMIUM SELF)** - -The group-managed accounts feature is behind these feature flags: `group_managed_accounts`, `sign_up_on_sso` and `convert_user_to_group_managed_accounts`. The flags are disabled by default. -To activate the feature, ask a GitLab administrator with Rails console access to run: - -```ruby -Feature.enable(:group_managed_accounts) -Feature.enable(:sign_up_on_sso) -Feature.enable(:convert_user_to_group_managed_accounts) -``` - -## Project restrictions for Group-managed accounts - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12420) in GitLab 12.9. - -Projects within groups with enabled group-managed accounts are not to be shared with: - -- Groups outside of the parent group. -- Members who are not users managed by this group. - -This restriction also applies to projects forked from or to those groups. - -## Outer forks restriction for Group-managed accounts - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34648) in GitLab 12.9. - -Groups with group-managed accounts can prevent forking of projects to destinations outside the group. -To do so, enable the "Prohibit outer forks" option in **Settings > SAML SSO**. -When enabled **at the parent group level**, projects within the group can be forked -only to other destinations within the group (including its subgroups). - -## Credentials inventory for Group-managed accounts **(ULTIMATE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38133) in GitLab 12.8. - -Owners who manage user accounts in a group can view the following details of personal access tokens and SSH keys: - -- Owners -- Scopes -- Usage patterns - -To access the Credentials inventory of a group, navigate to **{shield}** **Security & Compliance > Credentials** in your group's sidebar. - -This feature is similar to the [Credentials inventory for self-managed instances](../../admin_area/credentials_inventory.md). - -### Revoke a group-managed account's personal access token - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214811) in GitLab 13.5. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/267184) in GitLab 13.10. - -Group owners can revoke the personal access tokens of accounts in their group. To do so, select -the Personal Access Tokens tab, and select Revoke. - -When a personal access token is revoked, the group-managed account user is notified by email. - -## Limiting lifetime of personal access tokens of users in Group-managed accounts **(ULTIMATE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118893) in GitLab 12.10. - -Users in a group managed account can optionally specify an expiration date for -[personal access tokens](../../profile/personal_access_tokens.md). -This expiration date is not a requirement, and can be set to any arbitrary date. - -Since personal access tokens are the only token needed for programmatic access to GitLab, organizations with security requirements may want to enforce more protection to require regular rotation of these tokens. - -### Set a limit - -Only a GitLab administrator or an owner of a group-managed account can set a limit. When this field -is left empty, the [instance-level restriction](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-access-tokens) -on the lifetime of personal access tokens apply. - -To set a limit on how long personal access tokens are valid for users in a group managed account: - -1. Navigate to the **Settings > General** page in your group's sidebar. -1. Expand the **Permissions and group features** section. -1. Fill in the **Maximum allowable lifetime for access tokens (days)** field. -1. Click **Save changes**. - -Once a lifetime for personal access tokens is set: - -- GitLab applies the lifetime for new personal access tokens and requires users managed by the group to set an expiration date that's no later than the allowed lifetime. -- After three hours, revoke old tokens with no expiration date or with a lifetime longer than the allowed lifetime. Three hours is given to allow administrators/group owner to change the allowed lifetime, or remove it, before revocation takes place. +This [closed beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#sts=Closed%20Beta) feature was never enabled globally. See +[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/296544) for progress on removing the feature. +Use [SAML SSO](index.md) instead. diff --git a/doc/user/group/saml_sso/group_sync.md b/doc/user/group/saml_sso/group_sync.md new file mode 100644 index 00000000000..2239562b831 --- /dev/null +++ b/doc/user/group/saml_sso/group_sync.md @@ -0,0 +1,161 @@ +--- +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/engineering/ux/technical-writing/#assignments +--- + +# SAML Group Sync **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363084) for self-managed instances in GitLab 15.1. + +WARNING: +Changing Group Sync configuration can remove users from the mapped GitLab group. +Removal happens if there is any mismatch between the group names and the list of `groups` in the SAML response. +If changes must be made, ensure either the SAML response includes the `groups` attribute +and the `AttributeValue` value matches the **SAML Group Name** in GitLab, +or that all groups are removed from GitLab to disable Group Sync. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a demo of Group Sync using Azure, see [Demo: SAML Group Sync](https://youtu.be/Iqvo2tJfXjg). + +## Configure SAML Group Sync + +To configure SAML Group Sync: + +1. Configure SAML authentication: + - For GitLab self-managed, see [SAML OmniAuth Provider](../../../integration/saml.md). + - For GitLab.com, see [SAML SSO for GitLab.com groups](index.md). +1. Ensure your SAML identity provider sends an attribute statement named `Groups` or `groups`. + +NOTE: +The value for `Groups` or `groups` in the SAML response can be either the group name or the group ID. + +```xml +<saml:AttributeStatement> + <saml:Attribute Name="Groups"> + <saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue> + <saml:AttributeValue xsi:type="xs:string">Product Managers</saml:AttributeValue> + </saml:Attribute> +</saml:AttributeStatement> +``` + +Other attribute names such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` +are not accepted as a source of groups. +See the [SAML troubleshooting page](../../../administration/troubleshooting/group_saml_scim.md) +for examples on configuring the required attribute name in the SAML identity provider's settings. + +## Configure SAML Group Links + +When SAML is enabled, users with the Maintainer or Owner role +see a new menu item in group **Settings > SAML Group Links**. You can configure one or more **SAML Group Links** to map +a SAML identity provider group name to a GitLab role. This can be done for a top-level group or any subgroup. + +To link the SAML groups: + +1. In **SAML Group Name**, enter the value of the relevant `saml:AttributeValue`. +1. Choose the role in **Access Level**. +1. Select **Save**. +1. Repeat to add additional group links if required. + + + +If a user is a member of multiple SAML groups mapped to the same GitLab group, +the user gets the highest role from the groups. For example, if one group +is linked as Guest and another Maintainer, a user in both groups gets the Maintainer +role. + +Users granted: + +- A higher role with Group Sync are displayed as having + [direct membership](../../project/members/#display-direct-members) of the group. +- A lower or the same role with Group Sync are displayed as having + [inherited membership](../../project/members/#display-inherited-members) of the group. + +### 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. + +FLAG: +In [GitLab 15.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/364144), on GitLab.com, users in the top-level +group are assigned the [default membership role](index.md#role) rather than removed. This setting is enabled with the +`saml_group_sync_retain_default_membership` feature flag and can be configured by GitLab.com administrators only. + +For example, in the following diagram: + +- Alex Garcia signs into GitLab and is removed from GitLab Group C because they don't belong + to SAML Group C. +- Sidney Jones belongs to SAML Group C, but is not added to GitLab Group C because they have + not yet signed in. + +```mermaid +graph TB + subgraph SAML users + SAMLUserA[Sidney Jones] + SAMLUserB[Zhang Wei] + SAMLUserC[Alex Garcia] + SAMLUserD[Charlie Smith] + end + + subgraph SAML groups + SAMLGroupA["Group A"] --> SAMLGroupB["Group B"] + SAMLGroupA --> SAMLGroupC["Group C"] + SAMLGroupA --> SAMLGroupD["Group D"] + end + + SAMLGroupB --> |Member|SAMLUserA + SAMLGroupB --> |Member|SAMLUserB + + SAMLGroupC --> |Member|SAMLUserA + SAMLGroupC --> |Member|SAMLUserB + + SAMLGroupD --> |Member|SAMLUserD + SAMLGroupD --> |Member|SAMLUserC +``` + +```mermaid +graph TB + subgraph GitLab users + GitLabUserA[Sidney Jones] + GitLabUserB[Zhang Wei] + GitLabUserC[Alex Garcia] + GitLabUserD[Charlie Smith] + end + + subgraph GitLab groups + GitLabGroupA["Group A (SAML configured)"] --> GitLabGroupB["Group B (SAML Group Link not configured)"] + GitLabGroupA --> GitLabGroupC["Group C (SAML Group Link configured)"] + GitLabGroupA --> GitLabGroupD["Group D (SAML Group Link configured)"] + end + + GitLabGroupB --> |Member|GitLabUserA + + GitLabGroupC --> |Member|GitLabUserB + GitLabGroupC --> |Member|GitLabUserC + + GitLabGroupD --> |Member|GitLabUserC + GitLabGroupD --> |Member|GitLabUserD +``` + +```mermaid +graph TB + subgraph GitLab users + GitLabUserA[Sidney Jones] + GitLabUserB[Zhang Wei] + GitLabUserC[Alex Garcia] + GitLabUserD[Charlie Smith] + end + + subgraph GitLab groups after Alex Garcia signs in + GitLabGroupA[Group A] + GitLabGroupA["Group A (SAML configured)"] --> GitLabGroupB["Group B (SAML Group Link not configured)"] + GitLabGroupA --> GitLabGroupC["Group C (SAML Group Link configured)"] + GitLabGroupA --> GitLabGroupD["Group D (SAML Group Link configured)"] + end + + GitLabGroupB --> |Member|GitLabUserA + GitLabGroupC --> |Member|GitLabUserB + GitLabGroupD --> |Member|GitLabUserC + GitLabGroupD --> |Member|GitLabUserD +``` diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 1b480a52920..c05e847e2c9 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -176,6 +176,36 @@ If using [Group Sync](#group-sync), customize the name of the group claim to mat See the [troubleshooting page](../../../administration/troubleshooting/group_saml_scim.md#azure-active-directory) for an example configuration. +### 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 | + +You must download the certificate to get the SHA1 certificate fingerprint. + +The recommended attributes and claims settings are: + +- **Primary email** set to `email`. +- **First name** set to `first_name`. +- **Last name** set to `last_name`. + +For NameID, the following settings are recommended: + +- **Name ID format** is set to `EMAIL`. +- **NameID** set to `Basic Information > Primary email`. + +When selecting **Verify SAML Configuration** on the GitLab SAML SSO page, disregard the warning recommending setting the NameID format to "persistent". + +See the [troubleshooting page](../../../administration/troubleshooting/group_saml_scim.md#google-workspace) for an example configuration. + ### Okta setup notes Please 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. @@ -342,7 +372,7 @@ To rescind a user's access to the group when only SAML SSO is configured, either - Remove (in order) the user from: 1. The user data store on the identity provider or the list of users on the specific app. 1. The GitLab.com group. -- Use Group Sync at the top-level of your group to [automatically remove the user](#automatic-member-removal). +- Use Group Sync at the top-level of your group to [automatically remove the user](group_sync.md#automatic-member-removal). To rescind a user's access to the group when also using SCIM, refer to [Blocking access](scim_setup.md#blocking-access). @@ -372,149 +402,7 @@ For example, to unlink the `MyOrg` account: ## Group Sync -WARNING: -Changing Group Sync configuration can remove users from the relevant GitLab group. -Removal happens if there is any mismatch between the group names and the list of `groups` in the SAML response. -If changes must be made, ensure either the SAML response includes the `groups` attribute -and the `AttributeValue` value matches the **SAML Group Name** in GitLab, -or that all groups are removed from GitLab to disable Group Sync. - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a demo of Group Sync using Azure, see [Demo: SAML Group Sync](https://youtu.be/Iqvo2tJfXjg). - -When the SAML response includes a user and their group memberships from the SAML identity provider, -GitLab uses that information to automatically manage that user's GitLab group memberships. - -Ensure your SAML identity provider sends an attribute statement named `Groups` or `groups` like the following: - -```xml -<saml:AttributeStatement> - <saml:Attribute Name="Groups"> - <saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue> - <saml:AttributeValue xsi:type="xs:string">Product Managers</saml:AttributeValue> - </saml:Attribute> -</saml:AttributeStatement> -``` - -Other attribute names such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` -are not accepted as a source of groups. -See the [SAML troubleshooting page](../../../administration/troubleshooting/group_saml_scim.md) -for examples on configuring the required attribute name in the SAML identity provider's settings. - -NOTE: -The value for `Groups` or `groups` in the SAML response can be either the group name or the group ID. -To inspect the SAML response, you can use one of these [SAML debugging tools](#saml-debugging-tools). - -When SAML SSO is enabled for the top-level group, `Maintainer` and `Owner` level users -see a new menu item in group **Settings > SAML Group Links**. You can configure one or more **SAML Group Links** to map -a SAML identity provider group name to a GitLab Access Level. This can be done for the parent group or the subgroups. - -To link the SAML groups from the `saml:AttributeStatement` example above: - -1. In the **SAML Group Name** box, enter the value of `saml:AttributeValue`. -1. Choose the desired **Access Level**. -1. **Save** the group link. -1. Repeat to add additional group links if desired. - - - -If a user is a member of multiple SAML groups mapped to the same GitLab group, -the user gets the highest access level from the groups. For example, if one group -is linked as `Guest` and another `Maintainer`, a user in both groups gets `Maintainer` -access. - -Users granted: - -- A higher role with Group Sync are displayed as having - [direct membership](../../project/members/#display-direct-members) of the group. -- A lower or the same role with Group Sync are displayed as having - [inherited membership](../../project/members/#display-inherited-members) of the group. - -### Automatic member removal - -After a group sync, users who are not members of a mapped SAML group are removed from -the GitLab group. Even if SSO authentication is successful, if an existing user is not a member of any of the configured groups: - -- They get an "unauthorized" message if they try to view the group. -- All of their permissions to subgroups and projects are also removed. - -For example, in the following diagram: - -- Alex Garcia signs into GitLab and is removed from GitLab Group C because they don't belong - to SAML Group C. -- Sidney Jones belongs to SAML Group C, but is not added to GitLab Group C because they have - not yet signed in. - -```mermaid -graph TB - subgraph SAML users - SAMLUserA[Sidney Jones] - SAMLUserB[Zhang Wei] - SAMLUserC[Alex Garcia] - SAMLUserD[Charlie Smith] - end - - subgraph SAML groups - SAMLGroupA["Group A"] --> SAMLGroupB["Group B"] - SAMLGroupA --> SAMLGroupC["Group C"] - SAMLGroupA --> SAMLGroupD["Group D"] - end - - SAMLGroupB --> |Member|SAMLUserA - SAMLGroupB --> |Member|SAMLUserB - - SAMLGroupC --> |Member|SAMLUserA - SAMLGroupC --> |Member|SAMLUserB - - SAMLGroupD --> |Member|SAMLUserD - SAMLGroupD --> |Member|SAMLUserC -``` - -```mermaid -graph TB - subgraph GitLab users - GitLabUserA[Sidney Jones] - GitLabUserB[Zhang Wei] - GitLabUserC[Alex Garcia] - GitLabUserD[Charlie Smith] - end - - subgraph GitLab groups - GitLabGroupA["Group A (SAML configured)"] --> GitLabGroupB["Group B (SAML Group Link not configured)"] - GitLabGroupA --> GitLabGroupC["Group C (SAML Group Link configured)"] - GitLabGroupA --> GitLabGroupD["Group D (SAML Group Link configured)"] - end - - GitLabGroupB --> |Member|GitLabUserA - - GitLabGroupC --> |Member|GitLabUserB - GitLabGroupC --> |Member|GitLabUserC - - GitLabGroupD --> |Member|GitLabUserC - GitLabGroupD --> |Member|GitLabUserD -``` - -```mermaid -graph TB - subgraph GitLab users - GitLabUserA[Sidney Jones] - GitLabUserB[Zhang Wei] - GitLabUserC[Alex Garcia] - GitLabUserD[Charlie Smith] - end - - subgraph GitLab groups after Alex Garcia signs in - GitLabGroupA[Group A] - GitLabGroupA["Group A (SAML configured)"] --> GitLabGroupB["Group B (SAML Group Link not configured)"] - GitLabGroupA --> GitLabGroupC["Group C (SAML Group Link configured)"] - GitLabGroupA --> GitLabGroupD["Group D (SAML Group Link configured)"] - end - - GitLabGroupB --> |Member|GitLabUserA - GitLabGroupC --> |Member|GitLabUserB - GitLabGroupD --> |Member|GitLabUserC - GitLabGroupD --> |Member|GitLabUserD -``` +For information on automatically managing GitLab group membership, see [SAML Group Sync](group_sync.md). ## Passwords for users created via SAML SSO for Groups @@ -528,8 +416,8 @@ This section contains possible solutions for problems you might encounter. SAML responses are base64 encoded, so we recommend the following browser plugins to decode them on the fly: -- [SAML tracer for Firefox](https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/) -- [Chrome SAML Panel](https://chrome.google.com/webstore/detail/saml-chrome-panel/paijfdbeoenhembfhkhllainmocckace?hl=en) +- [SAML-tracer](https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/) for Firefox. +- [SAML Message Decoder](https://chrome.google.com/webstore/detail/saml-message-decoder/mpabchoaimgbdbbjjieoaeiibojelbhm?hl=en) for Chrome. Specific attention should be paid to: @@ -548,7 +436,7 @@ To generate a SAML Response: - [SAML-tracer](https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/) for Firefox. 1. Open a new browser tab. 1. Open the SAML tracer console: - - Chrome: Right click on the page, select **Inspect**, then click on the SAML tab in the opened developer console. + - Chrome: Right-click on the page, select **Inspect**, then select the **SAML** tab in the opened developer console. - Firefox: Select the SAML-tracer icon located on the browser toolbar. 1. Go to the GitLab single sign-on URL for the group in the same browser tab with the SAML tracer open. 1. Select **Authorize** or attempt to log in. A SAML response is displayed in the tracer console that resembles this @@ -569,6 +457,10 @@ This can then be compared to the [NameID](#nameid) being sent by the identity pr ### Users receive a 404 +Because SAML SSO for groups is a paid feature, your subscription expiring can result in a `404` error when you're signing in using SAML SSO on GitLab.com. +If all users are receiving a `404` when attempting to log in using SAML, confirm +[there is an active subscription](../../../subscriptions/gitlab_com/index.md#view-your-gitlab-saas-subscription) being used in this SAML SSO namespace. + If you receive a `404` during setup when using "verify configuration", make sure you have used the correct [SHA-1 generated fingerprint](../../../integration/saml.md#notes-on-configuring-your-identity-provider). diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index bc1799c2e54..cc154b96ed0 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -82,7 +82,7 @@ table, use the Azure defaults. For a list of required attributes, refer to the [ For guidance, you can view [an example configuration in the troubleshooting reference](../../../administration/troubleshooting/group_saml_scim.md#azure-active-directory). -1. Below the mapping list click on **Show advanced options > Edit attribute list for AppName**. +1. Below the mapping list select **Show advanced options > Edit attribute list for AppName**. 1. Ensure the `id` is the primary and required field, and `externalId` is also required. NOTE: @@ -112,7 +112,7 @@ After the above steps are complete: 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. In the **Application** tab, select **Browse App Catalog**. -1. Search for **GitLab**, find and select on the 'GitLab' application. +1. Search for **GitLab**, find and select the 'GitLab' application. 1. On the GitLab application overview page, select **Add**. 1. Under **Application Visibility** select both checkboxes. Currently the GitLab application does not support SAML authentication so the icon should not be shown to users. 1. Select **Done** to finish adding the application. diff --git a/doc/user/group/settings/group_access_tokens.md b/doc/user/group/settings/group_access_tokens.md index 4b791d5a221..649e7f2c264 100644 --- a/doc/user/group/settings/group_access_tokens.md +++ b/doc/user/group/settings/group_access_tokens.md @@ -36,7 +36,7 @@ You can use group access tokens: - Consider [disabling group access tokens](#enable-or-disable-group-access-token-creation) to lower potential abuse. -You cannot use group access tokens to create other access tokens. +You cannot use group access tokens to create other group, project, or personal access tokens. Group access tokens inherit the [default prefix setting](../../admin_area/settings/account_and_limit_settings.md#personal-access-token-prefix) configured for personal access tokens. @@ -147,9 +147,12 @@ 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 projects](../../project/settings/project_access_tokens.md#bot-users-for-projects), -except they are added to groups instead of projects. -These bot users do not count as licensed seats. +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: + +- Do not count as licensed seats. +- Can have a maximum role of Owner for a group. For more information, see + [Create a group access token](../../../api/group_access_tokens.md#create-a-group-access-token). For more information, see [Bot users for projects](../../project/settings/project_access_tokens.md#bot-users-for-projects). diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index 23a638fb98c..eb94a181647 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -1,16 +1,24 @@ --- -type: reference stage: Manage group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Group import/export **(FREE)** +# Migrating groups using file exports (deprecated) **(FREE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2888) in GitLab 13.0 as an experimental feature. May change in future releases. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2888) in GitLab 13.0 as an experimental feature. May change in future releases. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/4619) in GitLab 14.6. -You can export groups, with all their related data, from one GitLab instance to another. -You can also [export projects](../../project/settings/import_export.md). +WARNING: +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/4619) in GitLab 14.6 and replaced by +[a different migration method](../import/index.md). To follow progress on a solution for +[offline environments](../../application_security/offline_deployments/index.md), see +[the relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/363406). + +You can export groups, with all their related data, from one GitLab instance to another. You can also: + +- [Migrate groups](../import/index.md) using the preferred method. +- [Migrate projects using file exports](../../project/settings/import_export.md). ## Enable export for a group @@ -63,10 +71,6 @@ For more details on the specific data persisted in a group export, see the ## Export a group -WARNING: -This feature will be [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/4619) -in GitLab 14.6 and replaced by [GitLab Migration](../import/). - Prerequisites: - You must have the Owner role for the group. @@ -96,16 +100,11 @@ You can export groups from the [Community Edition to the Enterprise Edition](htt The Enterprise Edition retains some group data that isn't part of the Community Edition. If you're 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). -## Importing the group - -WARNING: -This feature will be [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/4619) -in GitLab 14.8 and replaced by [GitLab Migration](../import/). +## Import the group 1. Create a new group: - On the top bar, select **New** (**{plus}**) and then **New group**. - On an existing group's page, select the **New subgroup** button. - 1. Select **Import group**. 1. Enter your group name. 1. Accept or modify the associated group URL. diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 4be97779603..72d42a8081f 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -50,9 +50,8 @@ To view value stream analytics for your group: - In the **To** field, select an end date. The charts and list show workflow items created during the date range. 1. Optional. Sort results by ascending or descending: - - To sort by most recent or oldest workflow item, select the **Merge requests** or **Issues** - header. The header name differs based on the stage you select. - - To sort by most or least amount of time spent in each stage, select the **Time** header. + - To sort by most recent or oldest workflow item, select the **Last event** header. + - To sort by most or least amount of time spent in each stage, select the **Duration** header. A badge next to the workflow items table header shows the number of workflow items that completed during the selected stage. @@ -366,7 +365,7 @@ The chart shows data for the last 500 workflow items. - In the **From** field, select a start date. - In the **To** field, select an end date. -## Type of work - Tasks by type chart +## Tasks by type chart > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32421) in GitLab 12.10. diff --git a/doc/user/infrastructure/clusters/connect/img/variables_civo.png b/doc/user/infrastructure/clusters/connect/img/variables_civo.png Binary files differnew file mode 100644 index 00000000000..5a20478b13c --- /dev/null +++ b/doc/user/infrastructure/clusters/connect/img/variables_civo.png diff --git a/doc/user/infrastructure/clusters/connect/index.md b/doc/user/infrastructure/clusters/connect/index.md index 004f4409919..37e1024a32c 100644 --- a/doc/user/infrastructure/clusters/connect/index.md +++ b/doc/user/infrastructure/clusters/connect/index.md @@ -10,11 +10,6 @@ The [certificate-based Kubernetes integration with GitLab](../index.md) was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. To connect your clusters, use the [GitLab agent](../../../clusters/agent/index.md). -<!-- TBA: (We need to resolve https://gitlab.com/gitlab-org/gitlab/-/issues/343660 before adding this line) -If you don't have a cluster yet, create one and connect it to GitLab through the agent. -You can also create a new cluster from GitLab using [Infrastructure as Code](../../iac/index.md#create-a-new-cluster-through-iac). ---> - ## Cluster levels (DEPRECATED) > [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/infrastructure/clusters/connect/new_civo_cluster.md b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md new file mode 100644 index 00000000000..d8401d5a286 --- /dev/null +++ b/doc/user/infrastructure/clusters/connect/new_civo_cluster.md @@ -0,0 +1,137 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Create a Civo Kubernetes cluster + +Every new Civo account receives [$250 in credit](https://civo.com/signup) to get started with the GitLab integration with Civo Kubernetes. You can also use a marketplace app to install GitLab on your Civo Kubernetes cluster. + +Learn how to create a new cluster on Civo Kubernetes through +[Infrastructure as Code (IaC)](../../index.md). This process uses the Civo +and Kubernetes Terraform providers to create Civo Kubernetes clusters. You connect the clusters to GitLab +by using the GitLab agent for Kubernetes. + +**Prerequisites:** + +- A [Civo account](https://civo.com/signup). +- [A runner](https://docs.gitlab.com/runner/install/) you can use to run the GitLab CI/CD pipeline. + +**Steps:** + +1. [Import the example project](#import-the-example-project). +1. [Register the agent for Kubernetes](#register-the-agent). +1. [Configure your project](#configure-your-project). +1. [Provision your cluster](#provision-your-cluster). + +## Import the example project + +To create a cluster from GitLab using Infrastructure as Code, you must +create a project to manage the cluster from. In this tutorial, you start with +a sample project and modify it according to your needs. + +Start by [importing the example project by URL](../../../project/import/repo_by_url.md). + +To import the project: + +1. On the top bar, select **Menu > Create new project**. +1. Select **Import project**. +1. Select **Repository by URL**. +1. For the **Git repository URL**, enter `https://gitlab.com/civocloud/gitlab-terraform-civo.git`. +1. Complete the fields and select **Create project**. + +This project provides you with: + +- A [cluster on Civo](https://gitlab.com/civocloud/gitlab-terraform-civo/-/blob/master/civo.tf) with defaults for name, region, node count, and Kubernetes version. +- The [GitLab agent for Kubernetes](https://gitlab.com/civocloud/gitlab-terraform-civo/-/blob/master/agent.tf) installed in the cluster. + +## Register the agent + +To create a GitLab agent for Kubernetes: + +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. Select **Connect a cluster (agent)**. +1. From the **Select an agent** dropdown list, select `civo-agent` and select **Register an agent**. +1. GitLab generates a registration token for the agent. Securely store this secret token, as you will need it later. +1. GitLab provides an address for the agent server (KAS), which you will also need later. + +## Configure your project + +Use CI/CD environment variables to configure your project. + +**Required configuration:** + +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Variables**. +1. Set the variable `BASE64_CIVO_CREDENTIALS` to the [token](https://www.civo.com/account/security) from your Civo account. +1. Set the variable `TF_VAR_agent_token` to the agent token you received in the previous task. +1. Set the variable `TF_VAR_kas_address` to the agent server address in the previous task. + + + +**Optional configuration:** + +The file [`variables.tf`](https://gitlab.com/civocloud/gitlab-terraform-civo/-/blob/master/variables.tf) +contains other variables that you can override according to your needs: + +- `TF_VAR_civo_region`: Set your cluster's region. +- `TF_VAR_cluster_name`: Set your cluster's name. +- `TF_VAR_cluster_description`: Set a description for the cluster. To create a reference to your GitLab project on your Civo cluster detail page, set this value to `$CI_PROJECT_URL`. This value helps you determine which project was responsible for provisioning the cluster you see on the Civo dashboard. +- `TF_VAR_machine_type`: Set the machine type for the Kubernetes nodes. +- `TF_VAR_node_count`: Set the number of Kubernetes nodes. +- `TF_VAR_agent_version`: Set the version of the GitLab agent. +- `TF_VAR_agent_namespace`: Set the Kubernetes namespace for the GitLab agent. + +Refer to the [Civo Terraform provider](https://registry.terraform.io/providers/civo/civo/latest/docs/resources/kubernetes_cluster) and the [Kubernetes Terraform provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs) documentation for further resource options. + +## Provision your cluster + +After configuring your project, manually trigger the provisioning of your cluster. In GitLab: + +1. On the left sidebar, go to **CI/CD > Pipelines**. +1. Next to **Play** (**{play}**), select the dropdown icon (**{angle-down}**). +1. Select **Deploy** to manually trigger the deployment job. + +When the pipeline finishes successfully, you can see your new cluster: + +- In Civo dashboard: on your [Kubernetes tab](https://www.civo.com/account/kubernetes). +- In GitLab: from your project's sidebar, select **Infrastructure > Kubernetes clusters**. + +## Use your cluster + +After you provision the cluster, it is connected to GitLab and is ready for deployments. To check the connection: + +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. In the list, view the **Connection status** column. + +For more information about the capabilities of the connection, see [the GitLab agent for Kubernetes documentation](../index.md). + +## Remove the cluster + +A cleanup job is not included in your pipeline by default. To remove all created resources, you +must modify your GitLab CI/CD template before running the cleanup job. + +To remove all resources: + +1. Add the following to your `.gitlab-ci.yml` file: + + ```yaml + stages: + - init + - validate + - build + - deploy + - cleanup + + destroy: + extends: .destroy + needs: [] + ``` + +1. On the left sidebar, select **CI/CD > Pipelines** and select the most recent pipeline. +1. For the `destroy` job, select **Play** (**{play}**). + +## Civo support + +This Civo integration is supported by Civo. Send your support requests to [Civo support](https://www.civo.com/contact). diff --git a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md index 50899053cad..798e02ab9b4 100644 --- a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md @@ -36,7 +36,7 @@ To import the project: 1. On the top bar, select **Menu > Create new project**. 1. Select **Import project**. -1. Select **Repo by URL**. +1. Select **Repository by URL**. 1. For the **Git repository URL**, enter `https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks.git`. 1. Complete the fields and select **Create project**. @@ -92,7 +92,7 @@ View the [AWS Terraform provider](https://registry.terraform.io/providers/hashic After configuring your project, manually trigger the provisioning of your cluster. In GitLab: 1. On the left sidebar, go to **CI/CD > Pipelines**. -1. Next to **Play** (**{play}**), select the dropdown icon (**{angle-down}**). +1. Next to **Play** (**{play}**), select the dropdown icon (**{chevron-lg-down}**). 1. Select **Deploy** to manually trigger the deployment job. When the pipeline finishes successfully, you can view the new cluster: diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md index be58b4565a1..07d0c722d8b 100644 --- a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md @@ -43,7 +43,7 @@ To import the project: 1. On the top bar, select **Menu > Create new project**. 1. Select **Import project**. -1. Select **Repo by URL**. +1. Select **Repository by URL**. 1. For the **Git repository URL**, enter `https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke.git`. 1. Complete the fields and select **Create project**. @@ -70,9 +70,6 @@ To create a GitLab agent for Kubernetes: To set up your project to communicate to GCP and the GitLab API: -1. Create a [GitLab personal access token](../../../profile/personal_access_tokens.md) with - `api` scope. The Terraform script uses it to connect the cluster to your GitLab group. Take note of the generated token. You will - need it when you [configure your project](#configure-your-project). 1. To authenticate GCP with GitLab, create a [GCP service account](https://cloud.google.com/docs/authentication/getting-started) with following roles: `Compute Network Viewer`, `Kubernetes Engine Admin`, `Service Account User`, and `Service Account Admin`. Both User and Admin service accounts are necessary. The User role impersonates the [default service account](https://cloud.google.com/compute/docs/access/service-accounts#default_service_account) @@ -98,7 +95,7 @@ Use CI/CD environment variables to configure your project. 1. Set the variable `BASE64_GOOGLE_CREDENTIALS` to the `base64` encoded JSON file you just created. 1. Set the variable `TF_VAR_gcp_project` to your GCP's `project` name. 1. Set the variable `TF_VAR_agent_token` to the agent token displayed in the previous task. -1. Set the variable `TF_VAR_kas_address` to the agent server address displayed in the previous task. +1. Set the variable `TF_VAR_kas_address` to the agent server address displayed in the previous task. **Optional configuration:** @@ -120,7 +117,7 @@ Refer to the [Google Terraform provider](https://registry.terraform.io/providers After configuring your project, manually trigger the provisioning of your cluster. In GitLab: 1. On the left sidebar, go to **CI/CD > Pipelines**. -1. Next to **Play** (**{play}**), select the dropdown icon (**{angle-down}**). +1. Next to **Play** (**{play}**), select the dropdown icon (**{chevron-lg-down}**). 1. Select **Deploy** to manually trigger the deployment job. When the pipeline finishes successfully, you can see your new cluster: @@ -151,11 +148,12 @@ To remove all resources: - init - validate - build + - test - deploy - cleanup destroy: - extends: .destroy + extends: .terraform:destroy needs: [] ``` diff --git a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md index 7b2b5b4afd4..aa07a23db18 100644 --- a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md +++ b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md @@ -57,7 +57,7 @@ In your Auto DevOps project, you can use the GitLab agent to connect with your K - Add a key called `KUBE_INGRESS_BASE_DOMAIN` with the application deployment domain as the value. - Add a key called `KUBE_CONTEXT` with a value like `path/to/agent/project:agent-name`. Select the environment scope of your choice. - If you are not sure what your agent’s context is, edit your `.gitlab-ci.yml` file and add a job to see the available contexts: + If you are not sure what your agent's context is, edit your `.gitlab-ci.yml` file and add a job to see the available contexts: ```yaml deploy: diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index 0f7965a3527..422552c5b71 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -32,8 +32,7 @@ To get started, choose the template that best suits your needs: All templates: -- Use the [GitLab-managed Terraform state](#gitlab-managed-terraform-state) as - the Terraform state storage backend. +- Use the [GitLab-managed Terraform state](terraform_state.md) as the Terraform state storage backend. - Trigger four pipeline stages: `test`, `validate`, `build`, and `deploy`. - Run Terraform commands: `test`, `validate`, `plan`, and `plan-json`. It also runs the `apply` only on the default branch. - Run the [Terraform SAST scanner](../../application_security/iac_scanning/index.md#configure-iac-scanning-manually). @@ -58,6 +57,9 @@ to use one of these templates: - [The stable template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) with an skeleton that you can built on top of. - [The advanced template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml) to fully customize your setup. +NOTE: +In each GitLab major release (for example, 15.0), the latest templates replace the older ones. This process can introduce breaking changes. You can [use an older version of the template](troubleshooting.md#use-an-older-version-of-the-template) if you need to. + ### Use a Terraform template To use a Terraform template: @@ -86,37 +88,19 @@ To use a Terraform template: # TF_ROOT: terraform/production ``` -1. (Optional) Override in your `.gitlab-ci.yml` file the attributes present +1. Optional. Override in your `.gitlab-ci.yml` file the attributes present in the template you fetched to customize your configuration. -## GitLab-managed Terraform state - -Use the [GitLab-managed Terraform state](terraform_state.md) to store state -files in local storage or in a remote store of your choice. - -## Terraform module registry - -Use GitLab as a [Terraform module registry](../../packages/terraform_module_registry/index.md) -to create and publish Terraform modules to a private registry. - -## Terraform integration in merge requests - -Use the [Terraform integration in merge requests](mr_integration.md) -to collaborate on Terraform code changes and Infrastructure-as-Code -workflows. - -## The GitLab Terraform provider - -The [GitLab Terraform provider](https://github.com/gitlabhq/terraform-provider-gitlab) is a Terraform plugin to facilitate -managing of GitLab resources such as users, groups, and projects. It is released separately from GitLab -and its documentation is available on [Terraform](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs). - -## Create a new cluster through IaC - -- Learn how to [create a new cluster on Amazon Elastic Kubernetes Service (EKS)](../clusters/connect/new_eks_cluster.md). -- Learn how to [create a new cluster on Google Kubernetes Engine (GKE)](../clusters/connect/new_gke_cluster.md). - ## Related topics -- [Terraform images](https://gitlab.com/gitlab-org/terraform-images). -- [Troubleshooting](troubleshooting.md) issues with GitLab and Terraform. +- View [the images that contain the `gitlab-terraform` shell script](https://gitlab.com/gitlab-org/terraform-images). +- Use GitLab as a [Terraform module registry](../../packages/terraform_module_registry/index.md). +- To store state files in local storage or in a remote store, use the [GitLab-managed Terraform state](terraform_state.md). +- To collaborate on Terraform code changes and Infrastructure-as-Code workflows, use the + [Terraform integration in merge requests](mr_integration.md). +- To manage GitLab resources like users, groups, and projects, use the + [GitLab Terraform provider](https://github.com/gitlabhq/terraform-provider-gitlab). It is released separately from GitLab + and its documentation is available on [the Terraform docs site](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs). +- [Create a new cluster on Amazon Elastic Kubernetes Service (EKS)](../clusters/connect/new_eks_cluster.md). +- [Create a new cluster on Google Kubernetes Engine (GKE)](../clusters/connect/new_gke_cluster.md). +- [Troubleshoot](troubleshooting.md) issues with GitLab and Terraform. diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index f56fe92ec01..e8637abce91 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -22,8 +22,13 @@ In GitLab, you can: - Lock and unlock states. - Remotely execute `terraform plan` and `terraform apply` commands. -For self-managed instances, before you can use GitLab for your Terraform state files, -an administrator must [set up Terraform state storage](../../../administration/terraform_state.md). +## Prerequisites + +For self-managed GitLab, before you can use GitLab for your Terraform state files: + +- An administrator must [set up Terraform state storage](../../../administration/terraform_state.md). +- You must enable the **Infrastructure** menu for your project. Go to **Settings > General**, + expand **Visibility, project features, permissions**, and under **Operations**, turn on the toggle. ## Initialize a Terraform state as a backend by using GitLab CI/CD @@ -56,7 +61,7 @@ To configure GitLab CI/CD as a backend: 1. In the root directory of your project repository, create a `.gitlab-ci.yml` file. Use [this file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) to populate it. - + 1. Push your project to GitLab. This action triggers a pipeline, which runs the `gitlab-terraform init`, `gitlab-terraform validate`, and `gitlab-terraform plan` commands. @@ -99,12 +104,31 @@ The following example demonstrates how to change the state name. The same workfl You can use a GitLab-managed Terraform state backend as a [Terraform data source](https://www.terraform.io/language/state/remote-state-data). -1. Create a file named `example.auto.tfvars` with the following contents: +1. In your `main.tf` or other relevant file, declare these variables. Leave the values empty. + + ```hcl + variable "example_remote_state_address" { + type = string + description = "Gitlab remote state file address" + } + + variable "example_username" { + type = string + description = "Gitlab username to query remote state" + } + + variable "example_access_token" { + type = string + description = "GitLab access token to query remote state" + } + ``` + +1. To override the values from the previous step, create a file named `example.auto.tfvars`. This file should **not** be versioned in your project repository. ```plaintext - example_remote_state_address=https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME> - example_username=<GitLab username> - example_access_token=<GitLab Personal Access Token> + example_remote_state_address = "https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME>" + example_username = "<GitLab username>" + example_access_token = "<GitLab Personal Access Token>" ``` 1. In a `.tf` file, define the data source by using [Terraform input variables](https://www.terraform.io/language/values/variables): diff --git a/doc/user/infrastructure/iac/troubleshooting.md b/doc/user/infrastructure/iac/troubleshooting.md index 9dfe58396e2..881bcb32aed 100644 --- a/doc/user/infrastructure/iac/troubleshooting.md +++ b/doc/user/infrastructure/iac/troubleshooting.md @@ -60,7 +60,7 @@ my-terraform-job: extends: .apply ``` -There are two different causes for the error: +There are three different causes for the error: - In the case of `.init`, the error occurs because the init stage and jobs [were removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71188) from the templates, since they are no longer required. To resolve the syntax error, you can safely remove any jobs extending `.init`. - For all other jobs, the reason for the failure is that the base jobs have been [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67719): A `.terraform:` prefix has been added to every job name. For example, `.apply` became `.terraform:apply`. To fix this error, you can update the base job names. For example: @@ -71,6 +71,21 @@ There are two different causes for the error: + extends: .terraform:apply ``` +- In GitLab 15.0, templates use [`rules`](../../../ci/yaml/index.md#rules) syntax + instead of [`only/except`](../../../ci/yaml/index.md#only--except). + Ensure the syntax in your `.gitlab-ci.yml` file does not include both. + +#### Use an older version of the template + +Breaking changes can occur during major releases. If you encounter a breaking change or want to use an older version of a template, you can update your `.gitlab-ci.yml` to refer to an older one. For example: + +```yaml +include: + remote: https://gitlab.com/gitlab-org/configure/template-archive/-/raw/main/14-10/Terraform.gitlab-ci.yml +``` + +View the [template-archive](https://gitlab.com/gitlab-org/configure/template-archive) to see which templates are available. + ## Troubleshooting Terraform state ### Unable to lock Terraform state files in CI jobs for `terraform apply` using a plan created in a previous job diff --git a/doc/user/markdown.md b/doc/user/markdown.md index bbcb0f62a5c..b1e6fcb2f4e 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -380,8 +380,8 @@ the [Asciidoctor user manual](https://asciidoctor.org/docs/user-manual/#activati You can add task lists anywhere Markdown is supported. -- In issues, merge requests, and comments, you can click to select the boxes. -- In all other places, you cannot click to select the boxes. You must edit the Markdown manually +- In issues, merge requests, and comments, you can select the boxes. +- In all other places, you cannot select the boxes. You must edit the Markdown manually by adding or removing an `x` in the brackets. To create a task list, follow the format of an ordered or unordered list: @@ -790,12 +790,16 @@ do_this_and_do_that_and_another_thing but_emphasis is_desired _here_ ``` +<!-- vale gitlab.Spelling = NO --> + perform_complicated_task do_this_and_do_that_and_another_thing but_emphasis is_desired _here_ +<!-- vale gitlab.Spelling = YES --> + --- If you wish to emphasize only a part of a word, it can still be done with asterisks: diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 20284328918..1b14582a3f0 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -20,12 +20,12 @@ have a [GitLab Premium](https://about.gitlab.com/pricing/) plan. To add a project to the dashboard: -1. Ensure your alerts - [populate the `gitlab_environment_name` field](../../operations/metrics/alerts.md#external-prometheus-instances). +1. Ensure your alerts populate the `gitlab_environment_name` label on the alerts you set up in Prometheus. + The value of this should match the name of your environment in GitLab. In GitLab 13.9, you can display alerts for the `production` environment only. -1. Click the **Add projects** button in the home screen of the dashboard. +1. Select **Add projects** in the home screen of the dashboard. 1. Search and add one or more projects using the **Search your projects** field. -1. Click the **Add projects** button. +1. Select **Add projects**. Once added, the dashboard displays the project's number of active alerts, last commit, pipeline status, and when it was last deployed. diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index fe7a41aa542..ae64c419632 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -57,7 +57,7 @@ To download and run a container image hosted in the GitLab Container Registry: 1. Copy the link to your container image: - Go to your project or group's **Packages & Registries > Container Registry** and find the image you want. - - Next to the image name, click the **Copy** button. + - Next to the image name, select **Copy**.  @@ -113,7 +113,7 @@ To authenticate, you can use: Both of these require the minimum scope to be: - For read (pull) access, `read_registry`. -- For write (push) access, `write_registry`. +- For write (push) access, `write_registry` & `read_registry`. To authenticate, run the `docker` command. For example: @@ -404,7 +404,7 @@ To delete images from within GitLab: by clicking the red **{remove}** **Trash** icon next to the tag you want to delete. -1. In the dialog box, click **Remove tag**. +1. In the dialog box, select **Remove tag**. ### Delete images using the API @@ -506,7 +506,7 @@ You can, however, remove the Container Registry for a project: 1. Go to your project's **Settings > General** page. 1. Expand the **Visibility, project features, permissions** section and disable **Container Registry**. -1. Click **Save changes**. +1. Select **Save changes**. The **Packages & Registries > Container Registry** entry is removed from the project's sidebar. @@ -707,3 +707,27 @@ GitLab is [migrating to the next generation of the Container Registry](https://g During the migration, you may encounter difficulty deleting tags. If you encounter an error, it's likely that your image repository is in the process of being migrated. Please wait a few minutes and try again. + +### `unauthorized: authentication required` when pushing large images + +When pushing large images, you might get an error like the following: + +```shell +docker push gitlab.example.com/myproject/docs:latest +The push refers to a repository [gitlab.example.com/myproject/docs] +630816f32edb: Preparing +530d5553aec8: Preparing +... +4b0bab9ff599: Waiting +d1c800db26c7: Waiting +42755cf4ee95: Waiting +unauthorized: authentication required +``` + +On self-managed GitLab instances, by default, tokens for the Container Registry expire every five minutes. +When pushing larger images, or images that take longer than five minutes to push, +you might encounter this error. On GitLab.com, the expiration time is 15 minutes. + +If you are using self-managed GitLab, you can ask an administrator to +[increase the token duration](../../../administration/packages/container_registry.md#increase-token-duration) +if necessary. 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 9dcb4d7127d..8f90f42ad08 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 @@ -114,8 +114,8 @@ up your builds and reduce the amount of data transferred. For more information, ## Check automation frequency -We often create automation scripts bundled into container images to perform regular tasks on specific intervals. -You can reduce the frequency of those intervals in cases where the automation is pulling container images from +We often create automation scripts bundled into container images to perform regular tasks on specific intervals. +You can reduce the frequency of those intervals in cases where the automation is pulling container images from the GitLab Registry to a service outside of GitLab.com. ## Move to GitLab Premium or Ultimate 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 7b52a6a8ce3..3e41a260854 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_storage.md +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -109,12 +109,12 @@ To create a cleanup policy in the UI: | **Remove tags older than** | Remove only tags older than X days. | | **Remove tags matching** | The regex pattern that determines which tags to remove. This value cannot be blank. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | -1. Click **Save**. +1. Select **Save**. Depending on the interval you chose, the policy is scheduled to run. NOTE: -If you edit the policy and click **Save** again, the interval is reset. +If you edit the policy and select **Save** again, the interval is reset. ### Regex pattern examples diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 37e1f0c3eb1..22b792e443f 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -32,6 +32,11 @@ Prerequisites: 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. +- You must call this API endpoint serially when attempting to upload multiple files under the + same package name and version. Attempts to concurrently upload multiple files into + a new package name and version may face partial failures with + `HTTP 500: Internal Server Error` responses due to the requests racing to + create the package. ```plaintext PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name?status=:status @@ -64,6 +69,14 @@ Example response without attribute `select`: } ``` +Example request with attribute `select = package_file`: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --upload-file path/to/file.txt \ + "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt?select=package_file" +``` + Example response with attribute `select = package_file`: ```json diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index d2edfcb94c5..733fd383a04 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -108,7 +108,7 @@ 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 +as a filename and ignore `~/.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/helm_repository/index.md b/doc/user/packages/helm_repository/index.md index 73298afc9cd..88ea5afad3c 100644 --- a/doc/user/packages/helm_repository/index.md +++ b/doc/user/packages/helm_repository/index.md @@ -78,10 +78,10 @@ For example: ```yaml image: curlimages/curl:latest - + stages: - upload - + upload: stage: upload script: diff --git a/doc/user/packages/infrastructure_registry/index.md b/doc/user/packages/infrastructure_registry/index.md index 47f563fd7e7..551289a575a 100644 --- a/doc/user/packages/infrastructure_registry/index.md +++ b/doc/user/packages/infrastructure_registry/index.md @@ -15,19 +15,13 @@ projects. ## View packages -To view packages within your project or group: +To view packages within your project: -1. Go to the project or group. +1. Go to the project. 1. Go to **Packages & Registries > Infrastructure Registry**. You can search, sort, and filter packages on this page. -When you view packages in a group: - -- All packages published to the group and its projects are displayed. -- Only the projects you can access are displayed. -- If a project is private, or you are not a member of the project, it is not displayed. - For information on how to create and upload a package, view the GitLab documentation for your package type: @@ -68,7 +62,7 @@ To delete a package, you must have suitable [permissions](../../permissions.md). You can delete packages by using [the API](../../../api/packages.md#delete-a-project-package) or the UI. -To delete a package in the UI, from your group or project: +To delete a package in the UI, from your project: 1. Go to **Packages & Registries > Infrastructure Registry**. 1. Find the name of the package you want to delete. diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 1e3b5bdc323..eaa04404a1f 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -701,7 +701,7 @@ dependencies { For your project, go to **Packages & Registries > Package Registry**. -To remove a package, click the red trash icon or, from the package details, the **Delete** button. +To remove a package, select the red trash icon or, from the package details, the **Delete** button. ## Create Maven packages with GitLab CI/CD diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 1f37e5639c6..bdcbea68568 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -397,7 +397,7 @@ If multiple packages have the same name and version, when you install a package, - Replace `@foo` with your scope. - Replace `gitlab.example.com` with your domain name. - + For [project-level endpoints](#use-the-gitlab-endpoint-for-npm-packages) run: ```shell diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 37b6404d487..2e182d20811 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -171,7 +171,7 @@ To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet en  -1. Click **Save**. +1. Select **Save**. The source is displayed in your list. @@ -200,7 +200,7 @@ To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endp  -1. Click **Save**. +1. Select **Save**. The source is displayed in your list. diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index 1f278bd1476..d68c7218ca5 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -65,7 +65,7 @@ For most package types, the following credential types are valid: [GitLab-#333444](https://gitlab.com/gitlab-org/gitlab/-/issues/333444), which prevents you from using a job token with internal projects. This bug only impacts self-managed GitLab instances. - + ## Use GitLab CI/CD to build packages You can use [GitLab CI/CD](../../../ci/index.md) to build packages. @@ -110,7 +110,7 @@ You can also remove the Package Registry for your project specifically: 1. In your project, go to **Settings > General**. 1. Expand the **Visibility, project features, permissions** section and disable the **Packages** feature. -1. Click **Save changes**. +1. Select **Save changes**. The **Packages & Registries > Package Registry** entry is removed from the sidebar. @@ -125,7 +125,7 @@ to **Only Project Members**, the Package Registry is then public. However, disab Registry disables all Package Registry operations. [GitLab-#329253](https://gitlab.com/gitlab-org/gitlab/-/issues/329253) -proposes adding the ability to control Package Registry visibility from the UI. +proposes adding the ability to control Package Registry visibility from the UI. | | | Anonymous<br/>(everyone on internet) | Guest | Reporter, Developer, Maintainer, Owner | | -------------------- | --------------------- | --------- | ----- | ------------------------------------------ | @@ -167,7 +167,7 @@ You can also use the [API](../../../api/packages.md) to administer the Package R ## Accepting contributions This table lists unsupported package manager formats that we are accepting contributions for. -Consider contributing to GitLab. This [development documentation](../../../development/packages.md) +Consider contributing to GitLab. This [development documentation](../../../development/packages/index.md) guides you through the process. <!-- vale gitlab.Spelling = NO --> diff --git a/doc/user/packages/package_registry/reduce_package_registry_storage.md b/doc/user/packages/package_registry/reduce_package_registry_storage.md index f8a1e63a228..ed4ef1665bc 100644 --- a/doc/user/packages/package_registry/reduce_package_registry_storage.md +++ b/doc/user/packages/package_registry/reduce_package_registry_storage.md @@ -31,7 +31,7 @@ To delete a package in the UI, from your group or project: 1. Go to **Packages & Registries > Package Registry**. 1. Find the name of the package you want to delete. -1. Click **Delete**. +1. Select **Delete**. The package is permanently deleted. diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index a107d06a63c..42c85ae9d41 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -22,11 +22,11 @@ To authenticate to the Terraform module registry, you need either: When you publish a Terraform Module, if it does not exist, it is created. -If a package with the same name and version already exists, it will not be created. It does not overwrite the existing package. - Prerequisites: -- You need to [authenticate with the API](../../../api/index.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope. +- A package with the same name and version must not already exist. +- 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. ```plaintext PUT /projects/:id/packages/terraform/modules/:module-name/:module-system/:module-version/file @@ -35,8 +35,8 @@ 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. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), or hyphens (`-`) and cannot exceed 64 characters. -| `module-system` | string | yes | The package system. It can contain only lowercase letters (`a-z`) and numbers (`0-9`), and cannot exceed 64 characters. More information can be found in the [Terraform Module Registry Protocol documentation](https://www.terraform.io/internals/module-registry-protocol). +| `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). | `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. @@ -111,17 +111,27 @@ To work with Terraform modules in [GitLab CI/CD](../../../ci/index.md), you can For example: ```yaml -image: curlimages/curl:latest - stages: - upload upload: stage: upload + 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} # The version of your Terraform module to be published to your project's registry script: - - 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file path/to/file.tgz "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/terraform/modules/my-module/my-system/0.0.1/file"' + - tar -cvzf ${TERRAFORM_MODULE_NAME}-${TERRAFORM_MODULE_SYSTEM}-${TERRAFORM_MODULE_VERSION}.tgz -C ${TERRAFORM_MODULE_DIR} --exclude=./.git . + - 'curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file ${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 ``` +To trigger this upload job, add a Git tag to your commit. The `rules:if: $CI_COMMIT_TAG` defines this so that not every commit to your repo triggers the upload. +For other ways to control jobs in your CI/CD pipeline, refer to the [`.gitlab-ci.yml`](../../../ci/yaml/index.md) keyword reference. + ## Example projects For examples of the Terraform module registry, check the projects below: diff --git a/doc/user/permissions.md b/doc/user/permissions.md index d28cf75d11f..801c107e371 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -150,6 +150,7 @@ The following table lists project permissions available for each role: | [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) | | | | ✓ (*21*) | ✓ | | [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 | | | ✓ | ✓ | ✓ | @@ -157,7 +158,7 @@ The following table lists project permissions available for each role: | [Projects](project/index.md):<br>Edit project badges | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Edit project settings | | | | ✓ | ✓ | | [Projects](project/index.md):<br>Export project | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Manage [project access tokens](project/settings/project_access_tokens.md) (*11*) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Manage [project access tokens](project/settings/project_access_tokens.md) (*11*) | | | | ✓ (*21*) | ✓ | | [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*) | @@ -212,7 +213,7 @@ The following table lists project permissions available for each role: public and internal projects (not on private projects). [External users](#external-users) must be given explicit access even if the project is internal. For GitLab.com, see the [GitLab.com visibility settings](gitlab_com/index.md#visibility-settings). -2. Guest users can only view the [confidential issues](project/issues/confidential_issues.md) they created themselves. +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 Developers and Maintainers are given. 5. Guest users can access GitLab [**Releases**](project/releases/index.md) for downloading assets but are not allowed to download the source code nor see [repository information like commits and release evidence](project/releases/index.md#view-a-release-and-download-assets). @@ -232,11 +233,12 @@ The following table lists project permissions available for each role: 15. Guest users can only set metadata (for example, labels, assignees, or milestones) when creating an issue. They cannot change the metadata on existing issues. 16. In GitLab 14.5 or later, Guests are not allowed to [create incidents](../operations/incident_management/incidents.md#incident-creation). - A guest who created an incident when they had the Reporter role or who is assigned to the incident can modify the title, description and metrics. They can also close and reopen the incident. + In GitLab 15.1 and later, a Guest who created an issue that was promoted to an incident cannot edit, close, or reopen their incident. 17. In projects that accept contributions from external members, users can create, edit, and close their own merge requests. 18. Authors and assignees of issues can modify the title and description even if they don't have the Reporter role. 19. Authors and assignees can close and reopen issues even if they don't have the Reporter role. 20. The ability to view the Container Registry and pull images is controlled by the [Container Registry's visibility permissions](packages/container_registry/index.md#container-registry-visibility-permissions). +21. Maintainers cannot create, demote, or remove Owners, and they cannot promote users to the Owner role. They also cannot approve Owner role access requests. <!-- markdownlint-enable MD029 --> @@ -250,8 +252,8 @@ More details about the permissions for some project-level features follow. - [Public pipelines](../ci/pipelines/settings.md#change-which-users-can-view-your-pipelines): When set to public, gives access to certain CI/CD features to *Guest* project members. -- [Pipeline visibility](../ci/enable_or_disable_ci.md#enable-cicd-in-a-project): When set to **Everyone with Access**, - gives access to certain CI/CD "view" features to *non-project* members. +- [Pipeline visibility](../ci/pipelines/settings.md#change-pipeline-visibility-for-non-project-members-in-public-projects): + When set to **Everyone with Access**, gives access to certain CI/CD "view" features to *non-project* members. | Action | Non-member | Guest | Reporter | Developer | Maintainer | Owner | |---------------------------------------------------------------------------------------------------------------------------|------------|---------|----------|-----------|------------|-------| @@ -268,6 +270,7 @@ More details about the permissions for some project-level features follow. | Cancel and retry jobs | | | | ✓ | ✓ | ✓ | | Create new [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | | Delete job logs or job artifacts | | | | ✓ (*4*) | ✓ | ✓ | +| Run CI/CD pipeline | | | | ✓ | ✓ | ✓ | | 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#debug-logging) | | | | ✓ | ✓ | ✓ | @@ -355,7 +358,7 @@ Read through the documentation on [permissions for File Locking](project/file_lo ### Confidential Issues permissions [Confidential issues](project/issues/confidential_issues.md) can be accessed by users with reporter and higher permission levels, -as well as by guest users that create a confidential issue. To learn more, +as well as by guest users that create a confidential issue or are assigned to it. To learn more, read through the documentation on [permissions and access to confidential issues](project/issues/confidential_issues.md#permissions-and-access-to-confidential-issues). ### Container Registry visibility permissions @@ -428,6 +431,7 @@ The following table lists group permissions available for each role: | View [Billing](../subscriptions/gitlab_com/index.md#view-your-gitlab-saas-subscription) | | | | | ✓ (4) | | View group [Usage Quotas](usage_quotas.md) page | | | | | ✓ (4) | | Manage group runners | | | | | ✓ | +| [Migrate groups](group/import/index.md) | | | | | ✓ | <!-- markdownlint-disable MD029 --> @@ -477,7 +481,7 @@ For example, if an external user is added as Guest, and your project is internal private, they do not have access to the code; you need to grant the external user access at the Reporter level or above if you want them to have access to the code. You should always take into account the -[project's visibility and permissions settings](project/settings/index.md#sharing-and-permissions) +[project's visibility and permissions settings](project/settings/index.md#configure-project-visibility-features-and-permissions) as well as the permission level of the user. NOTE: @@ -517,7 +521,7 @@ and the ignore case flag is set (`/regex pattern/i`). Here are some examples: - Use `\.internal@domain\.com$` to mark email addresses ending with `.internal@domain.com` as internal. - Use `^(?:(?!\.ext@domain\.com).)*$\r?` to mark users with email addresses - NOT including `.ext@domain.com` as internal. + not including `.ext@domain.com` as internal. WARNING: Be aware that this regex could lead to a diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index a820cf150e9..2dbeaae2267 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -22,7 +22,20 @@ 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). -You must use a [personal access token](../personal_access_tokens.md) instead. +You can use a [personal access token](../personal_access_tokens.md) instead. + +## Git Credential Manager + +For Git over HTTPS, [Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager) (GCM) offers an alternative to personal access tokens. By default, GCM +authenticates using OAuth, opening GitLab in your web browser. The first time you authenticate, GitLab asks you to authorize the app. If you remain signed in to GitLab, subsequent +authentication requires no interaction. + +So you don't need to reauthenticate on every push, GCM supports caching as well as a variety of platform-specific credential stores that persist between sessions. This feature is useful whether you use personal access tokens or OAuth. + +GCM supports GitLab.com out the box. To use with self-managed GitLab, see [GitLab support](https://github.com/GitCredentialManager/git-credential-manager/blob/main/docs/gitlab.md) +documentation. + +Git Credential Manager is developed primarily by GitHub, Inc. It is an open-source project and is supported by the community. ## Enable two-factor authentication @@ -206,7 +219,7 @@ To set up 2FA with a U2F device: 1. Select **Account**. 1. Select **Enable Two-Factor Authentication**. 1. Connect your U2F device. -1. Select on **Set up New U2F Device**. +1. Select **Set up New U2F Device**. 1. A light begins blinking on your device. Activate it by pressing its button. A message displays indicating that your device was successfully set up. Select **Register U2F Device** to complete the @@ -322,9 +335,6 @@ To disable 2FA: This clears all your 2FA registrations, including mobile applications and U2F or WebAuthn devices. -Support Team support for disabling 2FA is limited, depending on your subscription level. For more information, see the -[Account Recovery](https://about.gitlab.com/support/#account-recovery-and-2fa-resets) section of our website. - ## Recovery options If you don't have access to your code generation device, you can recover access to your account: diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index d7eb5040416..07f21da3099 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -324,8 +324,12 @@ git config --global user.email <your email address> ## User activity -GitLab tracks user contribution activity. -You can follow or unfollow other users from their [user profiles](#access-your-user-profile). +GitLab tracks user contribution activity. You can follow or unfollow other users from either: + +- Their [user profiles](#access-your-user-profile). +- The small popover that appears when you hover over a user's name ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/76050) + in GitLab 15.0). + To view a user's activity in a top-level Activity view: 1. From a user's profile, select **Follow**. @@ -395,7 +399,7 @@ You can add this URL to your feed reader. ### Reset the user activity feed token -Feed tokens are sensitive and can reveal information from confidential issues. +Feed tokens are sensitive and can reveal information from confidential issues. If you think your feed token has been exposed, you should reset it. To reset your feed token: @@ -404,7 +408,7 @@ To reset your feed token: 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. 1. Scroll down. In the **Feed token** section, select the - **reset this token** link. + **reset this token** link. 1. On the confirmation box, select **OK**. A new token is generated. @@ -415,8 +419,13 @@ A new token is generated. When you sign in to the main GitLab application, a `_gitlab_session` cookie is set. When you close your browser, the cookie is cleared client-side -and it expires after "Application settings > Session duration (minutes)"/`session_expire_delay` -(defaults to `10080` minutes = 7 days) of no activity. +and it expires after a set duration. GitLab administrators can determine the duration: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. +1. Expand **Account and limit**. The set duration is in **Session duration (minutes)**. + +The default is `10080`, which equals 7 days. When you sign in to the main GitLab application, you can also check the **Remember me** option. This sets the `remember_user_token` diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 09e71ce9133..af84b746280 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -194,3 +194,8 @@ questions that you know someone might ask. Each scenario can be a third-level heading, e.g. `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> + +## Alternatives to personal access tokens + +For Git over HTTPS, an alternative to personal access tokens is [Git Credential Manager](account/two_factor_authentication.md#git-credential-manager), +which securely authenticates using OAuth. diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index c654eb2b0e8..e99a2dad980 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -91,7 +91,7 @@ Introduced in GitLab 13.6, the themes [Solarized](https://gitlab.com/gitlab-org/ ## Diff colors -A diff compares the old/removed content with the new/added content (e.g. when +A diff compares the old/removed content with the new/added content (for example, when [reviewing a merge request](../project/merge_requests/reviews/index.md#review-a-merge-request) or in a [Markdown inline diff](../markdown.md#inline-diff)). Typically, the colors red and green are used for removed and added lines in diffs. diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 935bc01bae7..be73f2c9a01 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. WARNING: -This feature was deprecated in GitLab 14.5. Use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac) +This feature was deprecated in GitLab 14.5. Use [Infrastructure as Code](../../infrastructure/iac/index.md) to create new clusters. Through GitLab, you can create new clusters and add existing clusters hosted on Amazon Elastic @@ -23,7 +23,7 @@ use the [GitLab agent](../../clusters/agent/index.md). ## Create a new EKS cluster -To create a new cluster from GitLab, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac). +To create a new cluster from GitLab, use [Infrastructure as Code](../../infrastructure/iac/index.md). ### How to create a new cluster on EKS through cluster certificates (DEPRECATED) @@ -58,7 +58,7 @@ cluster certificates: - Group's **Kubernetes** page, for a group-level cluster. - **Menu > Admin > Kubernetes**, for an instance-level cluster. 1. Select **Integrate with a cluster certificate**. -1. Under the **Create new cluster** tab, click **Amazon EKS** to display an +1. Under the **Create new cluster** tab, select **Amazon EKS** to display an `Account ID` and `External ID` needed for later steps. 1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM policy: 1. From the left panel, select **Policies**. @@ -116,8 +116,8 @@ cluster certificates: If you get an error during this process, GitLab does not roll back the changes. You must remove resources manually. You can do this by deleting the relevant [CloudFormation stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-delete-stack.html). - 1. Click **Review policy**. - 1. Enter a suitable name for this policy, and click **Create Policy**. You can now close this window. + 1. Select **Review policy**. + 1. Enter a suitable name for this policy, and select **Create Policy**. You can now close this window. ### Prepare the cluster in Amazon @@ -140,16 +140,16 @@ In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create another IAM role (**role B**) for GitLab authentication with AWS: 1. On the AWS IAM console, select **Roles** from the left panel. -1. Click **Create role**. +1. Select **Create role**. 1. Under **Select type of trusted entity**, select **Another AWS account**. 1. Enter the Account ID from GitLab into the **Account ID** field. 1. Check **Require external ID**. 1. Enter the External ID from GitLab into the **External ID** field. -1. Click **Next: Permissions**, and select the policy you just created. -1. Click **Next: Tags**, and optionally enter any tags you wish to associate with this role. -1. Click **Next: Review**. +1. Select **Next: Permissions**, and select the policy you just created. +1. Select **Next: Tags**, and optionally enter any tags you wish to associate with this role. +1. Select **Next: Review**. 1. Enter a role name and optional description into the fields provided. -1. Click **Create role**. The new role name displays at the top. Click on its name and copy the +1. Select **Create role**. The new role name displays at the top. Select its name and copy the `Role ARN` from the newly created role. ### Configure your cluster's data in GitLab @@ -213,7 +213,7 @@ Otherwise, the deployed app isn't externally available outside of the cluster. GitLab creates a new pipeline, which begins to build, test, and deploy the app. After the pipeline has finished, your app runs in EKS, and is available -to users. Click on **CI/CD > Environments**. +to users. Select **CI/CD > Environments**.  @@ -252,7 +252,7 @@ IAM user in the Amazon AWS console, and follow these steps: 1. Check **Enable Amazon EKS integration**. 1. Enter your **Account ID**. 1. Enter your [access key and ID](#eks-access-key-and-id). -1. Click **Save changes**. +1. Select **Save changes**. #### EKS access key and ID diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index cb8d04e0e28..2e1c8766ae3 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -64,8 +64,8 @@ cluster certificates: cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - **Menu > Admin > Kubernetes** page, for an instance-level cluster. -1. Click **Integrate with a cluster certificate**. -1. Under the **Create new cluster** tab, click **Google GKE**. +1. Select **Integrate with a cluster certificate**. +1. Under the **Create new cluster** tab, select **Google GKE**. 1. Connect your Google account if you haven't done already by clicking the **Sign in with Google** button. 1. Choose your cluster's settings: @@ -83,7 +83,7 @@ cluster certificates: See the [Cloud Run for Anthos section](#cloud-run-for-anthos) for more information. - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. See the [Managed clusters section](gitlab_managed_clusters.md) for more information. -1. Finally, click the **Create Kubernetes cluster** button. +1. Finally, select the **Create Kubernetes cluster** button. After a couple of minutes, your cluster is ready. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 8cdd1792e7f..95d8064b380 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. -To create and manage a new cluster use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac). +To create and manage a new cluster use [Infrastructure as Code](../../infrastructure/iac/index.md). ## Disable a cluster @@ -22,7 +22,7 @@ When you successfully connect an existing cluster using cluster certificates, th - **Menu > Admin > Kubernetes** page, for an instance-level cluster. 1. Select the name of the cluster you want to disable. 1. Toggle **GitLab Integration** off (in gray). -1. Click **Save changes**. +1. Select **Save changes**. ## Remove a cluster diff --git a/doc/user/project/clusters/gitlab_managed_clusters.md b/doc/user/project/clusters/gitlab_managed_clusters.md index e295abf8d31..3b85d29fb4a 100644 --- a/doc/user/project/clusters/gitlab_managed_clusters.md +++ b/doc/user/project/clusters/gitlab_managed_clusters.md @@ -47,7 +47,7 @@ To clear the cache: 1. Navigate to your project's **Infrastructure > Kubernetes clusters** page, and select your cluster. 1. Expand the **Advanced settings** section. -1. Click **Clear cluster cache**. +1. Select **Clear cluster cache**. ## Base domain @@ -66,10 +66,10 @@ You can either: To determine the external Ingress IP address, or external Ingress hostname: - *If the cluster is on GKE*: - 1. Click the **Google Kubernetes Engine** link in the **Advanced settings**, + 1. Select the **Google Kubernetes Engine** link in the **Advanced settings**, or go directly to the [Google Kubernetes Engine dashboard](https://console.cloud.google.com/kubernetes/). 1. Select the proper project and cluster. - 1. Click **Connect** + 1. Select **Connect**. 1. Execute the `gcloud` command in a local terminal or using the **Cloud Shell**. - *If the cluster is not on GKE*: Follow the specific instructions for your diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index b1158be9fb6..58006c29057 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -52,7 +52,7 @@ is required to use Logs. ## Accessing the log explorer -To access the **Log explorer**, click the **More actions** **{ellipsis_v}** menu on +To access the **Log explorer**, select the **More actions** **{ellipsis_v}** menu on a [metrics dashboard](../../../operations/metrics/index.md) and select **View logs**, or: 1. Sign in as a user with the _View pod logs_ @@ -68,7 +68,7 @@ a [metrics dashboard](../../../operations/metrics/index.md) and select **View lo 1. When mousing over the list of pods, GitLab displays a tooltip with the exact pod name and status.  - 1. Click on the desired pod to display the **Log Explorer**. + 1. Select the desired pod to display the **Log Explorer**. ### Logs view @@ -97,7 +97,7 @@ Support for historical data is coming When you enable [Elastic Stack](../../clusters/integrations.md#elastic-stack-cluster-integration) on your cluster, you can filter logs displayed in the **Log Explorer** by date. -Click **Show last** in the **Log Explorer** to see the available options. +Select **Show last** in the **Log Explorer** to see the available options. ### Full text search diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 086e1fccf6c..94b5f6f52b9 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -55,7 +55,7 @@ Nurtch is the company behind the [Rubix library](https://github.com/Nurtch/rubix Rubix is an open-source Python library that makes it easy to perform common DevOps tasks inside Jupyter Notebooks. Tasks such as plotting Cloudwatch metrics and rolling your ECS/Kubernetes app are simplified down to a couple of lines of -code. See the [Nurtch Documentation](http://docs.nurtch.com/en/latest/) for more +code. See the [Nurtch Documentation](https://docs.nurtch.com/en/latest/) for more information. ## Configure an executable runbook with GitLab @@ -153,15 +153,15 @@ the components outlined above and the pre-loaded demo runbook. ``` 1. After JupyterHub has been installed successfully, open the **Jupyter Hostname** - in your browser. Click the **Sign in with GitLab** button to log in to + in your browser. Select **Sign in with GitLab** button to log in to JupyterHub and start the server. Authentication is enabled for any user of the GitLab instance with OAuth2. This button redirects you to a page at GitLab requesting authorization for JupyterHub to use your GitLab account.  -1. Click **Authorize**, and GitLab redirects you to the JupyterHub application. -1. Click **Start My Server** to start the server in a few seconds. +1. Select **Authorize**, and GitLab redirects you to the JupyterHub application. +1. Select **Start My Server** to start the server in a few seconds. 1. To configure the runbook's access to your GitLab project, you must enter your [GitLab Access Token](../../../profile/personal_access_tokens.md) and your Project ID in the **Setup** section of the demo runbook: @@ -208,13 +208,13 @@ the components outlined above and the pre-loaded demo runbook.  - 1. Click **Save variables**. + 1. Select **Save variables**. - 1. In Jupyter, click the **Run SQL queries in Notebook** heading, and then click + 1. In Jupyter, select the **Run SQL queries in Notebook** heading, and then select **Run**. The results are displayed inline as follows:  You can try other operations, such as running shell scripts or interacting with a Kubernetes cluster. Visit the -[Nurtch Documentation](http://docs.nurtch.com/) for more information. +[Nurtch Documentation](https://docs.nurtch.com/) for more information. diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index e37ff560080..197a995952a 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -255,7 +255,7 @@ README @group @group/with-nested/subgroup /docs/* @root-docs # Include `/**` to specify Code Owners for all subdirectories -# in a directory. This rule matches `docs/projects/index.md` or +# in a directory. This rule matches `docs/projects/index.md` or # `docs/development/index.md` /docs/**/*.md @root-docs diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 42c1b8b0a62..a90ffbe5796 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -69,7 +69,7 @@ specific environment, there are a lot of use cases. To name a few: - You want to promote what's running in staging, to production. You go to the environments list, verify that what's running in staging is what you think is - running, then click on the [manual job](../../ci/jobs/job_control.md#create-a-job-that-must-be-run-manually) to deploy to production. + running, then select the [manual job](../../ci/jobs/job_control.md#create-a-job-that-must-be-run-manually) to deploy to production. - You trigger a deploy, and you have many containers to upgrade so you know this takes a while (you've also throttled your deploy to only take down X containers at a time). But you need to tell someone when it's deployed, so you @@ -80,7 +80,7 @@ specific environment, there are a lot of use cases. To name a few: stuck or failed. - You've got an MR that looks good, but you want to run it on staging because staging is set up in some way closer to production. You go to the environment - list, find the [Review App](../../ci/review_apps/index.md) you're interested in, and click the + list, find the [Review App](../../ci/review_apps/index.md) you're interested in, and select the manual action to deploy it to staging. ## Enabling deploy boards @@ -129,7 +129,7 @@ To display the deploy boards for a specific [environment](../../ci/environments/ Once all of the above are set up and the pipeline has run at least once, navigate to the environments page under **Deployments > Environments**. -Deploy boards are visible by default. You can explicitly click +Deploy boards are visible by default. You can explicitly select the triangle next to their respective environment name in order to hide them. ### Example manifest file diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 64c18ab6f3b..595f5e541b7 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -190,6 +190,8 @@ To pull images from the Dependency Proxy, you must: ### GitLab deploy token +> Support for `gitlab-deploy-token` at the group level [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214014) in GitLab 15.1 [with a flag](../../../administration/feature_flags.md) named `ci_variable_for_group_gitlab_deploy_token`. Enabled by default. + There's a special case when it comes to deploy tokens. If a user creates one named `gitlab-deploy-token`, the username and token of the deploy token is automatically exposed to the CI/CD jobs as CI/CD variables: `CI_DEPLOY_USER` @@ -203,9 +205,10 @@ docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY ``` NOTE: -The special handling for the `gitlab-deploy-token` deploy token is not -implemented for group deploy tokens. To make the group-level deploy token available for -CI/CD jobs, the `CI_DEPLOY_USER` and `CI_DEPLOY_PASSWORD` variables should be set under **Settings** to the name and token of the group deploy token respectively. +In GitLab 15.0 and earlier, the special handling for the `gitlab-deploy-token` deploy token +does not work for group deploy tokens. To make the group-level deploy token available +for CI/CD jobs, the `CI_DEPLOY_USER` and `CI_DEPLOY_PASSWORD` CI/CD variables must be +set in **Settings > CI/CD > Variables** to the name and token of the group deploy token. ## Troubleshooting diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 4f8cfad1444..42287ff84ce 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -116,7 +116,7 @@ You might also be interested in templates for various ### Set a default template for merge requests and issues -> `Default.md` template [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78302) in GitLab 14.8. +> `Default.md` (case insensitive) template [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78302) in GitLab 14.8. In a project, you can choose a default description template for new issues and merge requests. As a result, every time a new merge request or issue is created, it's pre-filled with the text you @@ -129,9 +129,9 @@ Prerequisites: To set a default description template for merge requests, either: -- [Create a merge request template](#create-a-merge-request-template) named `Default.md` or `default.md` +- [In GitLab 14.8 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78302), [create a merge request template](#create-a-merge-request-template) named `Default.md` (case insensitive) and save it in `.gitlab/merge_request_templates/`. - This doesn't overwrite the default template if one has been set in the project settings. + This [doesn't overwrite](#priority-of-default-description-templates) the default template if one has been set in the project settings. - Users on GitLab Premium and higher: set the default template in project settings: 1. On the top bar, select **Menu > Projects** and find your project. @@ -142,9 +142,9 @@ To set a default description template for merge requests, either: To set a default description template for issues, either: -- [Create an issue template](#create-an-issue-template) named `Default.md` or `default.md` +- [In GitLab 14.8 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78302), [create an issue template](#create-an-issue-template) named `Default.md` (case insensitive) and save it in `.gitlab/issue_templates/`. - This doesn't overwrite the default template if one has been set in the project settings. + This [doesn't overwrite](#priority-of-default-description-templates) the default template if one has been set in the project settings. - Users on GitLab Premium and higher: set the default template in project settings: 1. On the top bar, select **Menu > Projects** and find your project. @@ -159,15 +159,15 @@ headings, lists, and so on. You can also provide `issues_template` and `merge_requests_template` attributes in the [Projects REST API](../../api/projects.md) to keep your default issue and merge request templates up to date. -#### Priority of description templates +#### Priority of default description templates When you set [merge request and issue description templates](#set-a-default-template-for-merge-requests-and-issues) in various places, they have the following priorities in a project. The ones higher up override the ones below: -1. Template selected in project settings. -1. `Default.md` from the parent group. -1. `Default.md` from the project repository. +1. Template set in project settings. +1. `Default.md` (case insensitive) from the parent group. +1. `Default.md` (case insensitive) from the project repository. ## Example description template diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index ef0c787b9d3..37ec7c8e8d3 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -42,7 +42,7 @@ To override syntax highlighting for a file type: After the changes merge into your [default branch](repository/branches/default.md), all `*.pl` files in your project are highlighted in your preferred language. -You can also extend the highlighting with common gateway interface (CGI) options, such as: +You can also extend the highlighting with Common Gateway Interface (CGI) options, such as: ``` conf # JSON file with .erb in it diff --git a/doc/user/project/img/time_tracking_report_v13_12.png b/doc/user/project/img/time_tracking_report_v13_12.png Binary files differdeleted file mode 100644 index 2132ca01cf4..00000000000 --- a/doc/user/project/img/time_tracking_report_v13_12.png +++ /dev/null diff --git a/doc/user/project/img/time_tracking_report_v15_1.png b/doc/user/project/img/time_tracking_report_v15_1.png Binary files differnew file mode 100644 index 00000000000..a9ddefebb2f --- /dev/null +++ b/doc/user/project/img/time_tracking_report_v15_1.png diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index 17d717bdc61..c150e124ac8 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -71,6 +71,6 @@ Here's a few links to get you started with the migration: - [Migrate using the `cvs-fast-export` tool](https://gitlab.com/esr/cvs-fast-export) - [Stack Overflow post on importing the CVS repository](https://stackoverflow.com/a/11490134/974710) -- [Convert a CVS repository to Git](http://www.techrepublic.com/article/convert-cvs-repositories-to-git/) +- [Convert a CVS repository to Git](https://www.techrepublic.com/article/convert-cvs-repositories-to-git/) - [Man page of the `git-cvsimport` tool](https://mirrors.edge.kernel.org/pub/software/scm/git/docs/git-cvsimport.html) - [Migrate using `reposurgeon`](http://www.catb.org/~esr/reposurgeon/repository-editing.html#conversion) diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index 6913cda0cd5..4103367accc 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -19,12 +19,12 @@ you'll need to follow the instructions for [exporting a project](../settings/imp  -Go to the **Import Projects** tab, then click on **GitLab.com**, and you are redirected to GitLab.com +Go to the **Import Projects** tab, then select **GitLab.com**, and you are redirected to GitLab.com for permission to access your projects. After accepting, you are automatically redirected to the importer.  -To import a project, click "Import". The importer imports your repository and issues. +To import a project, select **Import**. The importer imports your repository and issues. Once the importer is done, a new GitLab project is created with your imported data. ## Automate group and project import **(PREMIUM)** diff --git a/doc/user/project/import/img/import_projects_from_repo_url.png b/doc/user/project/import/img/import_projects_from_repo_url.png Binary files differdeleted file mode 100644 index fd3eae98ebf..00000000000 --- a/doc/user/project/import/img/import_projects_from_repo_url.png +++ /dev/null diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index a44669e738e..8fb495cd0db 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -71,19 +71,19 @@ To import Jira issues to a GitLab project:  -1. Click the **Import from** dropdown list and select the Jira project that you wish to import issues from. +1. Select the **Import from** dropdown list and select the Jira project that you wish to import issues from. In the **Jira-GitLab user mapping template** section, the table shows to which GitLab users your Jira users are mapped. When the form appears, the dropdown list defaults to the user conducting the import. -1. To change any of the mappings, click the dropdown list in the **GitLab username** column and +1. To change any of the mappings, select the dropdown list in the **GitLab username** column and select the user you want to map to each Jira user. The dropdown list may not show all the users, so use the search bar to find a specific user in this GitLab project. -1. Click **Continue**. You're presented with a confirmation that import has started. +1. Select **Continue**. You're presented with a confirmation that import has started. While the import is running in the background, you can navigate away from the import status page to the issues page, and you can see the new issues appearing in the issues list. diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index 131732d2bae..f04048980e7 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -53,13 +53,13 @@ As a result, the following projects are created: To start the import: -1. From your GitLab dashboard click **New project**. +1. From your GitLab dashboard select **New project**. 1. Switch to the **Import project** tab. -1. Click on the **Manifest file** button. +1. Select **Manifest file**. 1. Provide GitLab with a manifest XML file. 1. Select a group you want to import to (you need to create a group first if you don't have one). -1. Click **List available repositories**. At this point, you are redirected +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 click **Import all repositories** to start the import. +1. Check the list and select **Import all repositories** to start the import.  diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 0b96238006e..5163f957171 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -9,20 +9,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can import your existing repositories by providing the Git URL: -<!-- vale gitlab.Spelling = NO --> -<!-- vale gitlab.SubstitutionWarning = NO --> - -1. From your GitLab dashboard click **New project**. -1. Switch to the **Import project** tab. -1. Click on the **Repo by URL** button. -1. Fill in the "Git repository URL" and the remaining project fields. -1. Click **Create project** to begin the import process. -1. Once complete, you will be redirected to your newly created project. - -<!-- vale gitlab.Spelling = YES --> -<!-- vale gitlab.SubstitutionWarning = YES --> - - +1. On the top bar, select **Menu > Create new project**. +1. Select the **Import project** tab. +1. Select **Repository by URL**. +1. Enter a **Git repository URL**. +1. Complete the remaining fields. +1. Select **Create project**. + +Your newly created project is displayed. ## Automate group and project import **(PREMIUM)** diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 0f7ce182e1a..ac4b9d0769b 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -38,7 +38,7 @@ 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#sharing-and-permissions). +[Sharing 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 b7e25b815fc..3780ea37c0b 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -32,6 +32,6 @@ With the webhook URL created in the Discord channel, you can set up the Discord 1. Ensure that the **Active** toggle is enabled. 1. Check the checkboxes corresponding to the GitLab events for which you want to send notifications to Discord. 1. Paste the webhook URL that you copied from the create Discord webhook step. -1. Configure the remaining options and click the **Save changes** button. +1. Configure the remaining options and select the **Save changes** button. The Discord channel you created the webhook for now receives notification of the GitLab events that were configured. diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index 2a1b12057aa..1319c9e74cd 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -31,7 +31,7 @@ GitLab supports integrating Harbor projects at the group or project level. Compl 1. Turn on the **Active** toggle under **Enable Integration**. 1. Provide the Harbor configuration information: - **Harbor URL**: The base URL of Harbor instance which is being linked to this GitLab project. For example, `https://harbor.example.net`. - - **Harbor project name**: The project name in the Harbor instance. For example, `testproject`. + - **Harbor project name**: The project name in the Harbor instance. For example, `testproject`. - **Username**: Your username in the Harbor instance, which should meet the requirements in [prerequisites](#prerequisites). - **Password**: Password of your username. @@ -39,7 +39,7 @@ GitLab supports integrating Harbor projects at the group or project level. Compl After the Harbor integration is activated: -- The global variables `$HARBOR_USER`, `$HARBOR_PASSWORD`, `$HARBOR_URL`, and `$HARBOR_PROJECT` are created for CI/CD use. +- The global variables `$HARBOR_USERNAME`, `$HARBOR_PASSWORD`, `$HARBOR_URL`, and `$HARBOR_PROJECT` are created for CI/CD use. - The project-level integration settings override the group-level integration settings. ## Secure your requests to the Harbor APIs diff --git a/doc/user/project/integrations/pipeline_status_emails.md b/doc/user/project/integrations/pipeline_status_emails.md index 742ab977090..c58f5a13613 100644 --- a/doc/user/project/integrations/pipeline_status_emails.md +++ b/doc/user/project/integrations/pipeline_status_emails.md @@ -21,3 +21,6 @@ To enable pipeline status emails: **Notify only broken pipelines**. 1. Select the branches to send notifications for. 1. Select **Save changes**. + +In [GitLab 15.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89546) +and later, pipeline notifications triggered by blocked users are not delivered. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index 6e751b907eb..4c8e648537c 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -38,7 +38,7 @@ Next, the Ingress needs to be annotated for Prometheus monitoring. Two new annot - `prometheus.io/scrape: "true"` - `prometheus.io/port: "10254"` -Managing these settings depends on how NGINX Ingress has been deployed. If you have deployed via the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress), metrics can be enabled with `controller.stats.enabled` along with the required annotations. Alternatively it is possible to edit the NGINX Ingress YML directly in the [Kubernetes dashboard](https://github.com/kubernetes/dashboard). +Managing these settings depends on how NGINX Ingress has been deployed. If you have deployed via the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress), metrics can be enabled with `controller.stats.enabled` along with the required annotations. Alternatively it is possible to edit the NGINX Ingress YAML directly in the [Kubernetes dashboard](https://github.com/kubernetes/dashboard). ## Specifying the Environment label diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index bcab8d05f69..a989b418199 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -38,7 +38,7 @@ For example, this is a configuration for a project named `gitlab-ci`: You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. Learn more about the steps and consequences of disabling GitLab issues in -[Sharing and permissions](../settings/index.md#sharing-and-permissions). +[Sharing and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). ## Reference Redmine issues in GitLab diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 870554100b7..bd93fbcbcbc 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -91,7 +91,7 @@ the error message and keep troubleshooting from there. You might see an entry like the following in your Sidekiq log: ```plaintext -2019-01-10_13:22:08.42572 2019-01-10T13:22:08.425Z 6877 TID-abcdefg ProjectServiceWorker JID-3bade5fb3dd47a85db6d78c5 ERROR: {:class=>"ProjectServiceWorker", :service_class=>"SlackService", :message=>"SSL_connect returned=1 errno=0 state=error: certificate verify failed"} +2019-01-10_13:22:08.42572 2019-01-10T13:22:08.425Z 6877 TID-abcdefg Integrations::ExecuteWorker JID-3bade5fb3dd47a85db6d78c5 ERROR: {:class=>"Integrations::ExecuteWorker :service_class=>"SlackService", :message=>"SSL_connect returned=1 errno=0 state=error: certificate verify failed"} ``` This issue occurs when there is a problem with GitLab communicating with Slack, diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index dd4cdb632e6..e8b2470cf13 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -33,6 +33,6 @@ notifications: 1. Ensure that the **Active** toggle is enabled. 1. Select the checkboxes corresponding to the GitLab events you want to receive in Webex Teams. 1. Paste the **Webhook** URL for the Webex Teams space. -1. Configure the remaining options and then click **Test settings and save changes**. +1. Configure the remaining options and then select **Test settings and save changes**. The Webex Teams space begins to receive all applicable GitLab events. diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 2bf6b4bbe01..ed62a34f6a3 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -1050,6 +1050,9 @@ Pipeline events are triggered when the status of a pipeline changes. In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53159) and later, the pipeline webhook returns only the latest jobs. +In [GitLab 15.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89546) +and later, pipeline webhooks triggered by blocked users are not processed. + Request header: ```plaintext @@ -1126,6 +1129,15 @@ Payload example: "email": "user@gitlab.com" } }, + "source_pipeline":{ + "project":{ + "id": 41, + "web_url": "https://gitlab.example.com/gitlab-org/upstream-project", + "path_with_namespace": "gitlab-org/upstream-project", + }, + "pipeline_id": 30, + "job_id": 3401 + }, "builds":[ { "id": 380, @@ -1301,6 +1313,9 @@ Job events are triggered when the status of a job changes. The `commit.id` in the payload is the ID of the pipeline, not the ID of the commit. +In [GitLab 15.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89546) +and later, job events triggered by blocked users are not processed. + Request header: ```plaintext @@ -1662,7 +1677,7 @@ Payload example: { "id": 1, "created_at": "2020-11-02 12:55:12 UTC", - "description": "v1.0 has been released", + "description": "v1.1 has been released", "name": "v1.1", "released_at": "2020-11-02 12:55:12 UTC", "tag": "v1.1", diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index ac7d447961c..e4ce736684b 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -40,7 +40,9 @@ including: ## Group webhooks **(PREMIUM)** You can configure a group webhook, which is triggered by events -that occur across all projects in the group. +that occur across all projects in the group. If you configure identical webhooks +in a group and a project, they are both triggered by an event in the +project. Group webhooks can also be configured to listen for events that are specific to a group, including: @@ -171,7 +173,8 @@ work you must have Ruby installed. ruby print_http_body.rb 8000 ``` -1. In GitLab, add your webhook receiver as `http://my.host:8000/`. +1. In GitLab, [configure the webhook](#configure-a-webhook-in-gitlab) and add your + receiver's URL, for example, `http://receiver.example.com:8000/`. 1. Select **Test**. You should see something like this in the console: diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index 6c70a5e679b..25fc9c4e1c3 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -29,7 +29,7 @@ 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#sharing-and-permissions). +[Sharing 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 67125c3ebbf..0256c52e4a3 100644 --- a/doc/user/project/integrations/zentao.md +++ b/doc/user/project/integrations/zentao.md @@ -10,11 +10,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w [ZenTao](https://www.zentao.net/) is a web-based project management platform. +The following versions of ZenTao are supported: + +- ZenTao 15.4 +- ZenTao Pro 10.2 +- ZenTao Biz 5.2 +- ZenTao Max 2.2 + ## Configure ZenTao -This integration requires a ZenTao API secret key. +This integration requires a ZenTao API secret key. -Complete these steps in ZenTao: +Complete these steps in ZenTao: 1. Go to your **Admin** page and select **Develop > Application**. 1. Select **Add Application**. @@ -32,7 +39,7 @@ Complete these steps in GitLab: 1. Turn on the **Active** toggle under **Enable Integration**. 1. Provide the ZenTao configuration information: - **ZenTao Web URL**: The base URL of the ZenTao instance web interface you're linking to this GitLab project (for example, `example.zentao.net`). - - **ZenTao API URL** (optional): The base URL to the ZenTao instance API. Defaults to the Web URL value if not set. + - **ZenTao API URL** (optional): The base URL to the ZenTao instance API. Defaults to the Web URL value if not set. - **ZenTao API token**: Use the key you generated when you [configured ZenTao](#configure-zentao). - **ZenTao Product ID**: To display issues from a single ZenTao product in a given GitLab project. The Product ID can be found in the ZenTao product page under **Settings > Overview**. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index d731ceb5aca..c8ecb2fd2e6 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -70,17 +70,17 @@ GitLab automatically loads the last board you visited. To create a new issue board: -1. Click the dropdown with the current board name in the upper left corner of the issue boards page. -1. Click **Create new board**. +1. Select the dropdown with the current board name in the upper left corner of the issue boards page. +1. Select **Create new board**. 1. Enter the new board's name and select its scope: milestone, labels, assignee, or weight. ### Delete an issue board To delete the currently active issue board: -1. Click the dropdown with the current board name in the upper left corner of the issue boards page. -1. Click **Delete board**. -1. Click **Delete** to confirm. +1. Select the dropdown with the current board name in the upper left corner of the issue boards page. +1. Select **Delete board**. +1. Select **Delete** to confirm. ## Issue boards use cases @@ -289,7 +289,7 @@ assignee list: Now that the assignee list is added, you can assign or unassign issues to that user by [moving issues](#move-issues-and-lists) to and from an assignee list. -To remove an assignee list, just as with a label list, click the trash icon. +To remove an assignee list, just as with a label list, select the trash icon.  @@ -307,7 +307,7 @@ milestone, giving you more freedom and visibility on the issue board. To add a m Like the assignee lists, you're able to [drag issues](#move-issues-and-lists) to and from a milestone list to manipulate the milestone of the dragged issues. -As in other list types, click the trash icon to remove a list. +As in other list types, select the trash icon to remove a list.  @@ -392,8 +392,8 @@ Examples: To set a WIP limit for a list: 1. Navigate to a Project or Group board of which you're a member. -1. Click the settings icon in a list's header. -1. Next to **Work In Progress Limit**, click **Edit**. +1. Select the settings icon in a list's header. +1. Next to **Work In Progress Limit**, select **Edit**. 1. Enter the maximum number of issues. 1. Press <kbd>Enter</kbd> to save. diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 9d23a63b940..402ce4bebec 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -31,12 +31,12 @@ There are two ways to change an issue's confidentiality. The first way is to edit the issue and toggle the confidentiality checkbox. After you save the issue, the confidentiality of the issue is updated. -The second way is to locate the Confidentiality section in the sidebar and click +The second way is to locate the **Confidentiality** section in the sidebar and select **Edit**. A popup should appear and give you the option to turn on or turn off confidentiality. | Turn off confidentiality | Turn on confidentiality | | :-----------: | :----------: | -|  |  | +|  |  | Every change from regular to confidential and vice versa, is indicated by a system note in the issue's comments. @@ -84,6 +84,9 @@ There are two kinds of level access for confidential issues. The general rule is that confidential issues are visible only to members of a project with at least the Reporter role. However, a guest user can also create confidential issues, but can only view the ones that they created themselves. +Users with the Guest role or non-members can also read the confidential issue if they are assigned to the issue. +When a Guest user or non-member is unassigned from a confidential issue, +they can no longer view it. Confidential issues are also hidden in search results for unprivileged users. For example, here's what a user with the Maintainer role and the Guest role diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index a3f6ee5e61e..2fe3d78194c 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -25,7 +25,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 at the top 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**. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index e5dde0ed451..d1b27f6eab0 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -29,7 +29,7 @@ For a video overview, see [Design Management (GitLab 12.2)](https://www.youtube. - On self-managed instances, a GitLab administrator must [enable LFS globally](../../../administration/lfs/index.md). - On both GitLab.com and self-managed instances, LFS must be - [enabled for the project itself](../settings/index.md#sharing-and-permissions). + [enabled for the project itself](../settings/index.md#configure-project-visibility-features-and-permissions). If enabled globally, LFS is enabled by default for all projects. If you have disabled it for your project, you must enable it again. @@ -92,7 +92,7 @@ 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** (**{angle-left}**) or **Go to next design** (**{angle-right}**). +- In the top-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: diff --git a/doc/user/search/img/issue_search_by_id_v15_0.png b/doc/user/project/issues/img/issue_search_by_id_v15_0.png Binary files differindex 411cebc0ccb..411cebc0ccb 100644 --- a/doc/user/search/img/issue_search_by_id_v15_0.png +++ b/doc/user/project/issues/img/issue_search_by_id_v15_0.png diff --git a/doc/user/project/issues/img/turn_off_confidentiality_v15_1.png b/doc/user/project/issues/img/turn_off_confidentiality_v15_1.png Binary files differnew file mode 100644 index 00000000000..e6050aec0de --- /dev/null +++ b/doc/user/project/issues/img/turn_off_confidentiality_v15_1.png diff --git a/doc/user/project/issues/img/turn_on_confidentiality_v15_1.png b/doc/user/project/issues/img/turn_on_confidentiality_v15_1.png Binary files differnew file mode 100644 index 00000000000..24a7ad554f8 --- /dev/null +++ b/doc/user/project/issues/img/turn_on_confidentiality_v15_1.png diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index bd0cf92e320..a2dbc8581d9 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -45,7 +45,7 @@ To learn how the GitLab Strategic Marketing department uses GitLab issues with [ - [Health status](managing_issues.md#health-status) - [Cross-link issues](crosslinking_issues.md) - [Sort issue lists](sorting_issue_lists.md) -- [Search for issues](../../search/index.md#filter-issue-and-merge-request-lists) +- [Search for issues](managing_issues.md#filter-the-list-of-issues) - [Epics](../../group/epics/index.md) - [Issue boards](../issue_board.md) - [Issues API](../../../api/issues.md) diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 7db66dd013b..fbdce211295 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -225,8 +225,6 @@ When you're creating a new issue, you can complete the following fields: ## Edit an issue -> Reordering list items [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15260) in GitLab 15.0. - You can edit an issue's title and description. Prerequisites: @@ -239,11 +237,23 @@ To edit an issue: 1. Edit the available fields. 1. Select **Save changes**. -You can also reorder list items, which include bullet, numerical, and task list items. -To reorder list items: +### Reorder list items in the issue description + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15260) in GitLab 15.0. + +When you view an issue that has a list in the description, you can also reorder the list items. + +Prerequisites: + +- You must have at least the Reporter role for the project, be the author of the issue, or be + assigned to the issue. +- The issue's description must have an [ordered, unordered](../../markdown.md#lists), or + [task](../../markdown.md#task-lists) list. -1. Hover over the list item row to make the drag icon visible. -1. Click and hold the drag icon. +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. Drag the row to the new position in the list. 1. Release the drag icon. @@ -471,7 +481,7 @@ Referenced issues are still displayed, but are not closed automatically. The automatic issue closing is disabled by default in a project if the project has the issue tracker disabled. If you want to enable automatic issue closing, make sure to -[enable GitLab Issues](../settings/index.md#sharing-and-permissions). +[enable GitLab Issues](../settings/index.md#configure-project-visibility-features-and-permissions). Changing this setting applies only to new merge requests or commits. Already closed issues remain as they are. @@ -554,6 +564,52 @@ To add an issue to an [iteration](../../group/iterations/index.md): Alternatively, you can use the `/iteration` [quick action](../quick_actions.md#issues-merge-requests-and-epics). +## View all issues assigned to you + +To view all issues assigned to you: + +1. On the top bar, put your cursor in the **Search** box. +1. From the dropdown list, select **Issues assigned to me**. + +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**. + +## Filter the list of issues + +> - Filtering by iterations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6. +> - Filtering by iterations was moved from GitLab Ultimate to GitLab Premium in 13.9. +> - Filtering by type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322755) in GitLab 13.10 [with a flag](../../../administration/feature_flags.md) named `vue_issues_list`. Disabled by default. +> - Filtering by type was [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/322755) in GitLab 14.10. +> - Filtering by type is generally available in GitLab 15.1. [Feature flag `vue_issues_list`](https://gitlab.com/gitlab-org/gitlab/-/issues/359966) removed. + +To filter the list of issues: + +1. Above the list of issues, select **Search or filter results...**. +1. In the dropdown list that appears, select the attribute you want to filter by. +1. Select or type the operator to use for filtering the attribute. The following operators are + available: + - `=`: Is + - `!=`: Is not ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18059) in GitLab 12.7) +1. Enter the text to filter the attribute by. + You can filter some attributes by **None** or **Any**. +1. Repeat this process to filter by multiple attributes. Multiple attributes are joined by a logical + `AND`. + +GitLab displays the results on-screen, but you can also +[retrieve them as an RSS feed](../../search/index.md#retrieve-search-results-as-feed). + +### Filter issues by ID + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39908) in GitLab 12.1. + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Issues > List**. +1. In the **Search** box, type the issue ID. For example, enter filter `#10` to return only issue 10. + + + ## Copy issue reference To refer to an issue elsewhere in GitLab, you can use its full URL or a short reference, which looks like diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index 279f297d016..105dcd529c8 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -34,7 +34,7 @@ it clear that their role is complete. ## How it works From an opened issue, expand the right sidebar, locate the assignees entry, -and click on **Edit**. From the dropdown menu, select as many users as you want +and select **Edit**. From the dropdown menu, select as many users as you want to assign the issue to.  diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index b8151ac873a..028dd2ea473 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -61,7 +61,7 @@ You can also add a linked issue from a commit message or the description in anot ## Remove a linked issue -In the **Linked issues** section of an issue, click the remove button (**{close}**) on the +In the **Linked issues** section of an issue, select the remove button (**{close}**) on the right-side of each issue token to remove. Due to the bi-directional relationship, the relationship no longer appears in either issue. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 2cc23b14857..160dade87bb 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -16,8 +16,7 @@ Labels are a key part of [issue boards](issue_board.md). With labels you can: - Categorize [epics](../group/epics/index.md), issues, and merge requests using colors and descriptive titles like `bug`, `feature request`, or `docs`. - Dynamically filter and manage [epics](../group/epics/index.md), issues, and merge requests. -- [Search lists of issues, merge requests, and epics](../search/index.md#search-issues-and-merge-requests), - as well as [issue boards](../search/index.md#issue-boards). +- Search lists of issues, merge requests, and epics, as well as issue boards. ## Types of labels @@ -125,8 +124,7 @@ To do so: 1. Select **Create project label**. 1. Fill in the name field. You can't specify a description if creating a label this way. You can add a description later by [editing the label](#edit-a-label). -1. Optional. Select a color by selecting from the available colors, or enter a hex color value for - a specific color. +1. Select a color by selecting from the available colors, or enter a hex color value for a specific color. 1. Select **Create**. ### Create a group label @@ -160,8 +158,7 @@ To do so: 1. Select **Create group label**. 1. Fill in the name field. You can't specify a description if creating a label this way. You can add a description later by [editing the label](#edit-a-label). -1. Optional. Select a color by selecting from the available colors,enter input a hex color value - for a specific color. +1. Select a color by selecting from the available colors,enter input a hex color value for a specific color. 1. Select **Create**. ## Edit a label @@ -336,7 +333,7 @@ For example, filtering by the `platform::*` label returns issues that have `plat `platform::Android`, or `platform::Linux` labels. NOTE: -Filtering by scoped labels not available on the [issues or merge requests dashboard pages](../search/index.md#search-issues-and-merge-requests). +Filtering by scoped labels not available on the issues or merge requests dashboard pages. ### Scoped labels examples diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 28bd353d8cc..7bea57d180b 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -225,9 +225,10 @@ GitLab users can request to become a member of a project. An email is sent to the most recently active project maintainers. Up to ten project maintainers are notified. -Any project maintainer can approve or decline the request. +Any project owner or maintainer can approve or decline the request. +Project maintainers cannot approve Owner role access requests. -If a project does not have any maintainers, the notification is sent to the +If a project does not have any direct owners or maintainers, the notification is sent to the most recently active owners of the project's group. If you change your mind before your request is approved, select diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index 612f499bb65..b8907532066 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -46,10 +46,10 @@ To define the `a11y` job for GitLab 12.9 and later: ```yaml stages: - accessibility - + variables: a11y_urls: "https://about.gitlab.com https://gitlab.com/users/sign_in" - + include: - template: "Verify/Accessibility.gitlab-ci.yml" ``` diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index f0ab4d606ad..014936208c6 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -22,7 +22,8 @@ flexibility: - Specify a list of users who act as [code owners](../../code_owners.md) for specific files, and require their approval before work can merge. -You can configure merge request approvals on a per-project basis. Administrators of +You can configure merge request approvals on a per-project basis, and +[on the group level](../../../group/index.md#group-merge-request-approval-settings). Administrators of [GitLab Premium](https://about.gitlab.com/pricing/) and [GitLab Ultimate](https://about.gitlab.com/pricing/) self-managed GitLab instances can also configure approvals @@ -103,7 +104,18 @@ Without the approvals, the work cannot merge. Required approvals enable multiple to determine who should review the work. - Require an [approval before merging code that causes test coverage to decline](../../../../ci/pipelines/settings.md#coverage-check-approval-rule) - Users on GitLab Ultimate can also [require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests) - before merging code that could introduce a vulnerability. + before merging code that could introduce a vulnerability. + +## Invalid rules + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334698) in GitLab 15.1. + +Whenever an approval rule cannot be satisfied, the rule will be displayed as `Invalid`. This applies to the following conditions: + +- The only eligible approver is the author of the merge request. +- No eligible approvers (either groups or users) have been assigned to the approval rule. + +These rules will be automatically approved to unblock their respective merge requests. ## Related topics diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 17a42e1b540..21cf5cca4d1 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -250,6 +250,10 @@ For more information about this validation error, read You can use [scan result policies](../../../application_security/policies/scan-result-policies.md#scan-result-policy-editor) to define security approvals based on the status of vulnerabilities in the merge request and the default branch. Details for each security policy is shown in the Security Approvals section of your Merge Request configuration. +The security approval rules are applied to all merge requests until the pipeline is complete. The application of the +security approval rules prevents users from merging in code before the security scans run. Once the pipeline is +complete, the security approval rules are checked to determine if the security approvals are still required. +  These policies are both created and edited in the [security policy editor](../../../application_security/policies/index.md#policy-editor). diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 9c2b54888fb..9295ea4c310 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -139,7 +139,7 @@ You can also enforce merge request approval settings: - At the [instance level](../../../admin_area/merge_requests_approvals.md), which apply to all groups on an instance and, therefore, all projects. -- On a [top-level group](../../../group/index.md#group-approval-settings), which apply to all subgroups +- On a [top-level group](../../../group/index.md#group-merge-request-approval-settings), which apply to all subgroups and projects. If the settings are inherited by a group or project, they cannot be changed in the group or project diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index fb41ec3eff6..14f3979cf34 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -18,7 +18,7 @@ to cherry-pick the changes introduced by that merge request.  -After you click that button, a modal displays a +After you select that button, a modal displays a [branch filter search box](../repository/branches/index.md#branch-filter-search-box) where you can choose to either: @@ -69,12 +69,12 @@ git cherry-pick -m 2 7a39eb0 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, click **Commits** to display the commit details page. -1. Click on the **Options** dropdown and select **Cherry-pick** to show the cherry-pick modal. +1. In the merge request's secondary menu, select **Commits** to display the commit details page. +1. Select the **Options** dropdown and select **Cherry-pick** to show the cherry-pick modal. 1. In **Pick into project** and **Pick into branch**, select the destination project and branch:  1. Optional. Select **Start a new merge request** if you're ready to create a merge request. -1. Click **Cherry-pick**. +1. Select **Cherry-pick**. ## Related topics diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 7e8ef9272d4..623af914692 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -28,6 +28,20 @@ Code Quality: - Is available by using [Auto Code Quality](../../../topics/autodevops/stages.md#auto-code-quality), provided by [Auto DevOps](../../../topics/autodevops/index.md). - Can be extended through [Analysis Plugins](https://docs.codeclimate.com/docs/list-of-engines) or a [custom tool](#implementing-a-custom-tool). +## Summary of features per tier + +Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), +as shown in the following table: + +| Capability | In Free | In Premium | In Ultimate | +|:----------------------------------------------------------------------|:--------------------|:--------------------|:-------------------| +| [Configure scanners](#configuring-jobs-using-variables) | **{check-circle}** | **{check-circle}** | **{check-circle}** | +| [Integrate custom scanners](#implementing-a-custom-tool) | **{check-circle}** | **{check-circle}** | **{check-circle}** | +| [Generate JSON or HTML report artifacts](#generate-an-html-report) | **{check-circle}** | **{check-circle}** | **{check-circle}** | +| [See findings in merge request widget](#code-quality-widget) | **{check-circle}** | **{check-circle}** | **{check-circle}** | +| [See reports in CI pipelines](#code-quality-reports) | **{dotted-circle}** | **{check-circle}** | **{check-circle}** | +| [See findings in merge request diff view](#code-quality-in-diff-view) | **{dotted-circle}** | **{dotted-circle}** | **{check-circle}** | + ## Code Quality Widget > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) to GitLab Free in 13.2. @@ -242,7 +256,7 @@ This can be done: - For a single pipeline run: 1. Go to **CI/CD > Pipelines** - 1. Click **Run pipeline** + 1. Select **Run pipeline** 1. Add `CODE_QUALITY_DISABLED` as the variable key, with any value. ### Using with merge request pipelines @@ -402,32 +416,40 @@ CI/CD variable to `html`. This is useful if you just want to view the report in human-readable format or to publish this artifact on GitLab Pages for even easier reviewing. +To generate both JSON and HTML report files, add another job to your template by using `extends: code_quality`: + ```yaml include: - template: Code-Quality.gitlab-ci.yml -code_quality: +code_quality_html: + extends: code_quality variables: REPORT_FORMAT: html artifacts: paths: [gl-code-quality-report.html] ``` -It's also possible to generate both JSON and HTML report files by defining -another job and using `extends: code_quality`: +NOTE: +Adding a job means your code is scanned twice: once to generate a JSON report and once to generate an HTML report. + +You can also generate _only_ an HTML report instead of the standard JSON report. To do so, set `REPORT_FORMAT` to `html` in the existing job: ```yaml include: - template: Code-Quality.gitlab-ci.yml -code_quality_html: - extends: code_quality +code_quality: variables: REPORT_FORMAT: html artifacts: paths: [gl-code-quality-report.html] ``` +WARNING: +If you only generate an HTML report, you can't see your results in the [merge request widget](#code-quality-widget), [pipeline report](#code-quality-reports), or [diff view](#code-quality-in-diff-view). +These features require a JSON report. + ## Extending functionality ### Using Analysis Plugins @@ -557,9 +579,9 @@ GitLab only uses the Code Quality artifact from the latest created job (with the If multiple jobs in a pipeline generate a code quality artifact, those of earlier jobs are ignored. To avoid confusion, configure only one job to generate a `gl-code-quality-report.json`. -### Rubocop errors +### RuboCop errors -When using Code Quality jobs on a Ruby project, you can encounter problems running Rubocop. +When using Code Quality jobs on a Ruby project, you can encounter problems running RuboCop. For example, the following error can appear when using either a very recent or very old version of Ruby: @@ -569,15 +591,15 @@ Unknown Ruby version 2.7 found in `.ruby-version`. (RuboCop::ValidationError) Supported versions: 2.1, 2.2, 2.3, 2.4, 2.5 ``` -This is caused by the default version of Rubocop used by the check engine not covering +This is caused by the default version of RuboCop used by the check engine not covering support for the Ruby version in use. -To use a custom version of Rubocop that +To use a custom version of RuboCop that [supports the version of Ruby used by the project](https://docs.rubocop.org/rubocop/compatibility.html#support-matrix), you can [override the configuration through a `.codeclimate.yml` file](https://docs.codeclimate.com/docs/rubocop#using-rubocops-newer-versions) created in the project repository. -For example, to specify using Rubocop release **0.67**: +For example, to specify using RuboCop release **0.67**: ```yaml version: "2" diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index b9b65d759dc..6f9bc452b96 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -92,8 +92,8 @@ Commit message templates support these variables: 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. -After you edit a commit message on an open merge request, GitLab will -not automatically update the commit message again. +After you edit a commit message on an open merge request, GitLab +automatically updates the commit message again. To restore the commit message to the project template, reload the page. ## Related topics diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index df527ec6ebf..aaa9bec945f 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Exporting merge requests CSV enables you and your team to export all the data collected from merge requests into a comma-separated values (CSV) file, which stores tabular data in plain text. -To export merge requests to CSV, navigate to your **Merge requests** from the sidebar of a project and click **Export to CSV**. +To export merge requests to CSV, navigate to your **Merge requests** from the sidebar of a project and select **Export to CSV**. ## CSV Output diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index 637b682d603..13cc68f02dd 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -23,14 +23,14 @@ the **Merge** button until you remove the **Draft** flag: 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, click **Mark as draft**. +- **Viewing a merge request**: In the top 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 click **Start the title with Draft:** + the beginning of the merge request's title, or select **Start the title with Draft:** below the **Title** field. - **Commenting in an existing merge request**: Add the `/draft` [quick action](../quick_actions.md#issues-merge-requests-and-epics) in a comment. This quick action is a toggle, and can be repeated to change the status - again. This quick action discards any other text in the comment. + back to Ready. - **Creating a commit**: Add `draft:`, `Draft:`, `fixup!`, or `Fixup!` to the beginning of a commit message targeting the merge request's source branch. This is not a toggle, and adding this text again in a later commit doesn't mark the @@ -40,19 +40,18 @@ 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, click **Mark as ready**. +- **Viewing a merge request**: In the top 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 click **Mark as ready**: + 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 click **Remove the Draft: prefix from the title** + from the beginning of the title, or select **Remove the Draft: prefix from the title** below the **Title** field. -- **Commenting in an existing merge request**: Add the `/draft` +- **Commenting in an existing merge request**: Add the `/ready` [quick action](../quick_actions.md#issues-merge-requests-and-epics) - in a comment in the merge request. This quick action is a toggle, and can be repeated - to change the status back. This quick action discards any other text in the comment. + in a comment in the merge request. In [GitLab 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/15332), when you mark a merge request as ready, notifications are triggered to @@ -64,9 +63,9 @@ When viewing or searching in your project's merge requests list, you can include draft merge requests: 1. Go to your project and select **Merge requests**. -1. In the navigation bar, click **Open**, **Merged**, **Closed**, or **All** to +1. In the navigation bar, select **Open**, **Merged**, **Closed**, or **All** to filter by merge request status. -1. Click the search box to display a list of filters and select **Draft**, or +1. Select the search box to display a list of filters and select **Draft**, or enter the word `draft`. 1. Select `=`. 1. Select **Yes** to include drafts, or **No** to exclude, and press **Return** diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index c1986a80ca0..09ee828ffd3 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -126,7 +126,7 @@ 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#merge-request-settings). +[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. @@ -140,35 +140,6 @@ is set for deletion, the merge request widget displays the  -### Branch retargeting on merge **(FREE SELF)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. -> - [Disabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. -> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/320895) GitLab 13.10. - -In specific circumstances, GitLab can retarget the destination branch of -open merge request, if the destination branch merges while the merge request is -open. Merge requests are often chained in this manner, with one merge request -depending on another: - -- **Merge request 1**: merge `feature-alpha` into `main`. -- **Merge request 2**: merge `feature-beta` into `feature-alpha`. - -These merge requests are usually handled in one of these ways: - -- Merge request 1 is merged into `main` first. Merge request 2 is then - retargeted to `main`. -- Merge request 2 is merged into `feature-alpha`. The updated merge request 1, which - now contains the contents of `feature-alpha` and `feature-beta`, is merged into `main`. - -GitLab retargets up to four merge requests when their target branch is merged into -`main`, so you don't need to perform this operation manually. Merge requests from -forks are not retargeted. - -The feature today works only on merge. Clicking the **Remove source branch** button -after the merge request was merged will not automatically retarget a merge request. -This improvement is [tracked as a follow-up](https://gitlab.com/gitlab-org/gitlab/-/issues/321559). - ## Recommendations and best practices for merge requests - When working locally in your branch, add multiple commits and only push when diff --git a/doc/user/project/merge_requests/img/ff_merge_rebase_v14_9.png b/doc/user/project/merge_requests/img/ff_merge_rebase_v14_9.png Binary files differdeleted file mode 100644 index 17ce42e7a69..00000000000 --- a/doc/user/project/merge_requests/img/ff_merge_rebase_v14_9.png +++ /dev/null diff --git a/doc/user/search/img/filter_approved_by_merge_requests_v14_6.png b/doc/user/project/merge_requests/img/filter_approved_by_merge_requests_v14_6.png Binary files differindex 8d47fdc2652..8d47fdc2652 100644 --- a/doc/user/search/img/filter_approved_by_merge_requests_v14_6.png +++ b/doc/user/project/merge_requests/img/filter_approved_by_merge_requests_v14_6.png diff --git a/doc/user/search/img/filter_approver_merge_requests_v14_6.png b/doc/user/project/merge_requests/img/filter_approver_merge_requests_v14_6.png Binary files differindex 58950031378..58950031378 100644 --- a/doc/user/search/img/filter_approver_merge_requests_v14_6.png +++ b/doc/user/project/merge_requests/img/filter_approver_merge_requests_v14_6.png diff --git a/doc/user/search/img/filtering_merge_requests_by_date_v14_6.png b/doc/user/project/merge_requests/img/filtering_merge_requests_by_date_v14_6.png Binary files differindex 398820f7864..398820f7864 100644 --- a/doc/user/search/img/filtering_merge_requests_by_date_v14_6.png +++ b/doc/user/project/merge_requests/img/filtering_merge_requests_by_date_v14_6.png diff --git a/doc/user/search/img/filtering_merge_requests_by_environment_v14_6.png b/doc/user/project/merge_requests/img/filtering_merge_requests_by_environment_v14_6.png Binary files differindex c35f2c8a58b..c35f2c8a58b 100644 --- a/doc/user/search/img/filtering_merge_requests_by_environment_v14_6.png +++ b/doc/user/project/merge_requests/img/filtering_merge_requests_by_environment_v14_6.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 510dcd82907..30b69c2fff5 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -45,13 +45,100 @@ If your group contains subgroups, this view also displays merge requests from th To view all merge requests assigned to you: +<!-- vale gitlab.FirstPerson = NO --> + 1. On the top bar, put your cursor in the **Search** box. 1. From the dropdown list, select **Merge requests assigned to me**. -Or, to use a [keyboard shortcut](../../shortcuts.md), press <kbd>Shift</kbd> + <kbd>m</kbd>. +<!-- vale gitlab.FirstPerson = YES --> + +Or: + +- To use a [keyboard shortcut](../../shortcuts.md), press <kbd>Shift</kbd> + <kbd>m</kbd>. +- On the top bar, on the top right, select **{merge-request-open}** **Merge requests**. + Then select one of the following: + - [Review requests](reviews/index.md). + - Merge requests assigned. + +## Filter the list of merge requests + +To filter the list of merge requests: + +1. Above the list of merge requests, select **Search or filter results...**. +1. In the dropdown list that appears, select the attribute you wish to filter by. +1. Select or type the operator to use for filtering the attribute. The following operators are + available: + - `=`: Is + - `!=`: Is not ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18059) in GitLab 12.7) +1. Enter the text to filter the attribute by. + You can filter some attributes by **None** or **Any**. +1. Repeat this process to filter by multiple attributes. Multiple attributes are joined by a logical + `AND`. + +GitLab displays the results on-screen, but you can also +[retrieve them as an RSS feed](../../search/index.md#retrieve-search-results-as-feed). + +### Filter merge requests by ID + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39908) in GitLab 12.1. + +You can filter the **Merge Request** list to find merge requests by their ID. + +For example, enter filter `#30` to return only merge request 30. + +### Filter merge requests by approvers **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. + +To filter merge requests by an individual eligible approver ([Code owner](../code_owners.md)), you can type (or select from +the dropdown list) **Approver** and select the user. + + + +### Filter merge requests by "approved by" **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30335) in GitLab 13.0. +> - Moved to GitLab Premium in 13.9. + +To filter merge requests already approved by a specific individual, you can type (or select from +the dropdown list) **Approved-By** and select the user. + + -You can [search and filter](../../search/index.md#filter-issue-and-merge-request-lists), -the results, or select a merge request to begin a review. +### Filter merge requests by reviewer + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47605) in GitLab 13.7. + +To filter review requested merge requests for a specific individual, you can type (or select from +the dropdown list) **Reviewer** and select the user. + +### Filter merge requests by environment or deployment date + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44041) in GitLab 13.6. + +To filter merge requests by deployment data, such as the environment or a date, +you can type (or select from the dropdown list) the following: + +- Environment +- Deployed-before +- Deployed-after + +NOTE: +Projects using a [fast-forward merge method](methods/index.md#fast-forward-merge) +do not return results, as this method does not create a merge commit. + +When filtering by an environment, a dropdown list presents all environments that +you can choose from: + + + +When filtering by `Deployed-before` or `Deployed-after`, the date refers to when +the deployment to an environment (triggered by the merge commit) completed successfully. +You must enter the deploy date manually. Deploy dates +use the format `YYYY-MM-DD`, and must be quoted if you wish to specify +both a date and time (`"YYYY-MM-DD HH:MM"`): + + ## Add changes to a merge request @@ -84,8 +171,7 @@ a merge request, or: 1. Select **Edit**. 1. Search for the user you want to assign, and select the user. -The merge request is added to the user's -[assigned merge request list](../../search/index.md#search-issues-and-merge-requests). +The merge request is added to the user's assigned merge request list. ### Assign multiple users **(PREMIUM)** @@ -136,6 +222,35 @@ 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**. +### Update merge requests when target branch merges **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. +> - [Disabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/320895) GitLab 13.10. + +Merge requests are often chained together, with one merge request depending on +the code added or changed in another merge request. To support keeping individual +merge requests small, GitLab can update up to four open merge requests when their +target branch merges into `main`. For example: + +- **Merge request 1**: merge `feature-alpha` into `main`. +- **Merge request 2**: merge `feature-beta` into `feature-alpha`. + +If these merge requests are open at the same time, and merge request 1 (`feature-alpha`) +merges into `main`, GitLab updates the destination of merge request 2 from `feature-alpha` +to `main`. + +Merge requests with interconnected content updates are usually handled in one of these ways: + +- Merge request 1 is merged into `main` first. Merge request 2 is then + retargeted to `main`. +- Merge request 2 is merged into `feature-alpha`. The updated merge request 1, which + now contains the contents of `feature-alpha` and `feature-beta`, is merged into `main`. + +This feature works only when a merge request is merged. Selecting **Remove source branch** +after merging does not retarget open merge requests. This improvement is +[proposed as a follow-up](https://gitlab.com/gitlab-org/gitlab/-/issues/321559). + ## Request attention to a merge request > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343528) in GitLab 14.10 [with a flag](../../../administration/feature_flags.md) named `mr_attention_requests`. Disabled by default. @@ -190,7 +305,7 @@ For a software developer working in a team: 1. You checkout a new branch, and submit your changes through a merge request. 1. You gather feedback from your team. 1. You work on the implementation optimizing code with [Code Quality reports](code_quality.md). -1. You verify your changes with [Unit test reports](../../../ci/unit_test_reports.md) in GitLab CI/CD. +1. You verify your changes with [Unit test reports](../../../ci/testing/unit_test_reports.md) in GitLab CI/CD. 1. You avoid using dependencies whose license is not compatible with your project with [License Compliance reports](../../compliance/license_compliance/index.md). 1. You request the [approval](approvals/index.md) from your manager. 1. Your manager: @@ -215,7 +330,7 @@ For a web developer writing a webpage for your company's website: - [Create a merge request](creating_merge_requests.md) - [Review a merge request](reviews/index.md) - [Authorization for merge requests](authorization_for_merge_requests.md) -- [Testing and reports](testing_and_reports_in_merge_requests.md) +- [Testing and reports](../../../ci/testing/index.md) - [GitLab keyboard shortcuts](../../shortcuts.md) - [Comments and threads](../../discussions/index.md) - [Suggest code changes](reviews/suggestions.md) diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index ac1c61f2e72..9182cf11566 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -16,7 +16,7 @@ finish and remember to merge the request manually. ## How it works -When you click "Merge When Pipeline Succeeds", the status of the merge +When you select "Merge When Pipeline Succeeds", the status of the merge request is updated to show the impending merge. If you can't wait for the pipeline to succeed, you can choose **Merge immediately** in the dropdown menu on the right of the main button. @@ -56,10 +56,11 @@ As a result, [disabling GitLab CI/CD pipelines](../../../ci/enable_or_disable_ci does not disable this feature, as it is possible to use pipelines from external CI providers with this feature. To enable it, you must: -1. Navigate to your project's **Settings > General** page. -1. Expand the **Merge requests** section. -1. In the **Merge checks** subsection, select the **Pipelines must succeed** checkbox. -1. Press **Save** for the changes to take effect. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Merge requests**. +1. Under **Merge checks**, select the **Pipelines must succeed** checkbox. +1. Select **Save**. This setting also prevents merge requests from being merged if there is no pipeline. You should be careful to configure CI/CD so that pipelines run for every merge request. @@ -104,11 +105,13 @@ for details on avoiding two pipelines for a single merge request. When the **Pipelines must succeed** checkbox is checked, [skipped pipelines](../../../ci/pipelines/index.md#skip-a-pipeline) prevent merge requests from being merged. To change this behavior: -1. Navigate to your project's **Settings > General** page. -1. Expand the **Merge requests** section. -1. In the **Merge checks** subsection, ensure **Pipelines must succeed** is checked. -1. In the **Merge checks** subsection, select the **Skipped pipelines are considered successful** checkbox. -1. Press **Save** for the changes to take effect. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Merge requests**. +1. Under **Merge checks**: + - Ensure **Pipelines must succeed** is selected. + - Select the **Skipped pipelines are considered successful** checkbox. +1. Select **Save**. ## From the command line diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md index adfa5288f81..d3221162cfd 100644 --- a/doc/user/project/merge_requests/methods/index.md +++ b/doc/user/project/merge_requests/methods/index.md @@ -77,7 +77,7 @@ When a fast-forward merge is not possible, the user is given the option to rebas NOTE: Projects using the fast-forward merge strategy can't filter merge requests -[by deployment date](../../../search/index.md#filtering-merge-requests-by-environment-or-deployment-date), +[by deployment date](../index.md#filter-merge-requests-by-environment-or-deployment-date), because no merge commit is created. When you visit the merge request page with `Fast-forward merge` @@ -87,8 +87,6 @@ method selected, you can accept it **only if a fast-forward merge is possible**. ## Rebasing in (semi-)linear merge methods -> Rebasing without running a CI/CD pipeline [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118825) in GitLab 14.7. - In these merge methods, you can merge only when your source branch is up-to-date with the target branch: - Merge commit with semi-linear history. @@ -96,11 +94,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 offers you the [`/rebase` quick action](../../../../topics/git/git_rebase.md#rebase-from-the-gitlab-ui), -and the ability to **Rebase** from the user interface: - - - -In [GitLab 14.7](https://gitlab.com/gitlab-org/gitlab/-/issues/118825) and later, you can also rebase without running a CI/CD pipeline. +and the ability to select **Rebase** from the user interface. If the target branch is ahead of the source branch and a conflict-free rebase is not possible, you must rebase the source branch locally before you can do a fast-forward merge. @@ -110,6 +104,23 @@ not possible, you must rebase the source branch locally before you can do a fast Rebasing may be required before squashing, even though squashing can itself be considered equivalent to rebasing. +### Rebase without CI/CD pipeline + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118825) in GitLab 14.7 [with a flag](../../../../administration/feature_flags.md) named `rebase_without_ci_ui`. Disabled by default. + +FLAG: +On GitLab.com and 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 `rebase_without_ci_ui`. +The feature is not ready for production use. + +To rebase a merge request's branch without triggering a CI/CD pipeline, select +**Rebase without pipeline** from the merge request reports section. +This option is available when fast-forward merge is not possible but a conflict-free +rebase is possible. + +Rebasing without a CI/CD pipeline saves resources in projects with a semi-linear +workflow that requires frequent rebases. + ## Related topics - [Commits history](../commits.md) diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 7b4a41f9339..8f433c13887 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -22,7 +22,7 @@ to revert the changes introduced by that merge request.  -After you click that button, a modal appears where you can choose to +After you select that button, a modal appears where you can choose to revert the changes directly into the selected branch or you can opt to create a new merge request with the revert changes. diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index eb5a54e6119..8f77ce90436 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -89,7 +89,7 @@ comment itself. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8225) in GitLab 13.10. -If you have a review in progress, you will be presented with the option to **Add to review**: +If you have a review in progress, you are presented with the option to **Add to review**:  @@ -123,9 +123,9 @@ Use [attention requests](../index.md#request-attention-to-a-merge-request) inste After a reviewer completes their [merge request reviews](../../../discussions/index.md), the author of the merge request can request a new review from the reviewer: -1. If the right sidebar in the merge request is collapsed, click the +1. If the right sidebar in the merge request is collapsed, select the **{chevron-double-lg-left}** **Expand Sidebar** icon to expand it. -1. In the **Reviewers** section, click the **Re-request a review** icon (**{redo}**) +1. In the **Reviewers** section, select the **Re-request a review** icon (**{redo}**) next to the reviewer's name. GitLab creates a new [to-do item](../../../todos.md) for the reviewer, and sends @@ -168,11 +168,11 @@ When bulk-editing merge requests in a project, you can edit the following attrib To update multiple project merge requests at the same time: 1. In a project, go to **Merge requests**. -1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with +1. Select **Edit merge requests**. A sidebar on the right-hand side of your screen appears with editable fields. 1. Select the checkboxes next to each merge request you want to edit. 1. Select the appropriate fields and their values from the sidebar. -1. Click **Update all**. +1. Select **Update all**. ## Bulk edit merge requests at the group level **(PREMIUM)** @@ -188,11 +188,11 @@ When bulk editing merge requests in a group, you can edit the following attribut To update multiple group merge requests at the same time: 1. In a group, go to **Merge requests**. -1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with +1. Select **Edit merge requests**. A sidebar on the right-hand side of your screen appears with editable fields. 1. Select the checkboxes next to each merge request you want to edit. 1. Select the appropriate fields and their values from the sidebar. -1. Click **Update all**. +1. Select **Update all**. ## Associated features diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 8e6794bcfa7..7360b57103b 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -82,9 +82,13 @@ in four backticks instead of three: GitLab uses a default commit message when applying suggestions: `Apply %{suggestions_count} suggestion(s) to %{files_count} file(s)` +<!-- vale gitlab.BadPlurals = NO --> + For example, consider that a user applied 3 suggestions to 2 different files, the default commit message is: **Apply 3 suggestion(s) to 2 file(s)** +<!-- vale gitlab.BadPlurals = YES --> + These commit messages can be customized to follow any guidelines you might have. To do so, expand the **Merge requests** tab within your project's **General** settings and change the **Merge suggestions** text: diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 85b5bbea284..fcbd732f8ee 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -68,11 +68,37 @@ A single Cobertura XML file can be no more than 10MiB. For large projects, split smaller files. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/328772) for more details. When submitting many files, it can take a few minutes for coverage to show on a merge request. +The visualization only displays after the pipeline is complete. If the pipeline has +a [blocking manual job](../../../ci/jobs/job_control.md#types-of-manual-jobs), the +pipeline waits for the manual job before continuing and is not considered complete. +The visualization cannot be displayed if the blocking manual job did not run. + ### Artifact expiration By default, the [pipeline artifact](../../../ci/pipelines/pipeline_artifacts.md#storage) used to draw the visualization on the merge request expires **one week** after creation. +### Coverage report from child pipeline + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363301) in GitLab 15.1 [with a flag](../../../administration/feature_flags.md). 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 `ci_child_pipeline_coverage_reports`. +On GitLab.com, this feature is not available. +The feature is not ready for production use. + +If the test coverage is created in jobs that are in a child pipeline, the parent pipeline must use +`strategy: depend`. + +```yaml +child_test_pipeline: + trigger: + include: + - local: path/to/child_pipeline.yml + - template: Security/SAST.gitlab-ci.yml + strategy: depend +``` + ### Automatic class path correction > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217664) in GitLab 13.8. @@ -255,7 +281,7 @@ run tests: - coverage run -m pytest - coverage report - coverage xml - coverage: '/TOTAL.*\s([.\d]+)%/' + coverage: '/(?i)total.*? (100(?:\.0+)?\%|[1-9]?\d(?:\.\d+)?\%)$/' artifacts: reports: coverage_report: @@ -389,3 +415,27 @@ run tests: coverage_format: cobertura path: coverage/coverage.xml ``` + +## Troubleshooting + +### Test coverage visualization not displayed + +If the test coverage visualization is not displayed in the diff view, you can check +the coverage report itself and verify that: + +- The file you are viewing in the diff view is mentioned in the coverage report. +- The `source` and `filename` nodes in the report follows the [expected structure](#automatic-class-path-correction) + to match the files in your repository. + +Report artifacts are not downloadable by default. If you want the report to be downloadable +from the job details page, add your coverage report to the artifact `paths`: + +```yaml +artifacts: + paths: + - coverage/cobertura-coverage.xml + reports: + coverage_report: + coverage_format: cobertura + path: coverage/cobertura-coverage.xml +``` diff --git a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md index 741ac325cca..6c0086bc429 100644 --- a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md +++ b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md @@ -1,39 +1,11 @@ --- -stage: Verify -group: Pipeline Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -description: "Test your code and display reports in merge requests" +redirect_to: '../../../ci/testing/index.md' +remove_date: '2022-08-31' --- -# Tests and reports in merge requests **(FREE)** +This document was moved to [another location](../../../ci/testing/index.md). -GitLab has the ability to test the changes included in a feature branch and display reports -or link to useful information directly from merge requests: - -| Feature | Description | -|----------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [Accessibility Testing](accessibility_testing.md) | Automatically report A11y violations for changed pages in merge requests. | -| [Browser Performance Testing](browser_performance_testing.md) | Quickly determine the browser performance impact of pending code changes. | -| [Load Performance Testing](load_performance_testing.md) | Quickly determine the server performance impact of pending code changes. | -| [Code Quality](code_quality.md) | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. | -| [Display arbitrary job artifacts](../../../ci/yaml/index.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../../../ci/pipelines/job_artifacts.md) in merge requests. | -| [GitLab CI/CD](../../../ci/index.md) | Build, test, and deploy your code in a per-branch basis with built-in CI/CD. | -| [Unit test reports](../../../ci/unit_test_reports.md) | Configure your CI jobs to use Unit test reports, and let GitLab display a report on the merge request so that it's easier and faster to identify the failure without having to check the entire job log. | -| [License Compliance](../../compliance/license_compliance/index.md) | Manage the licenses of your dependencies. | -| [Metrics Reports](../../../ci/metrics_reports.md) | Display the Metrics Report on the merge request so that it's fast and easy to identify changes to important metrics. | -| [Multi-Project pipelines](../../../ci/pipelines/multi_project_pipelines.md) | When you set up GitLab CI/CD across multiple projects, you can visualize the entire pipeline, including all cross-project interdependencies. | -| [Merge request pipelines](../../../ci/pipelines/merge_request_pipelines.md) | Customize a specific pipeline structure for merge requests in order to speed the cycle up by running only important jobs. | -| [Pipeline Graphs](../../../ci/pipelines/index.md#visualize-pipelines) | View the status of pipelines within the merge request, including the deployment process. | -| [Test Coverage visualization](test_coverage_visualization.md) | See test coverage results for merge requests, within the file diff. | - -## Security Reports **(ULTIMATE)** - -In addition to the reports listed above, GitLab can do many types of [Security reports](../../application_security/index.md), -generated by scanning and reporting any vulnerabilities found in your project: - -| Feature | Description | -|-----------------------------------------------------------------------------------------|------------------------------------------------------------------| -| [Container Scanning](../../application_security/container_scanning/index.md) | Analyze your Docker images for known vulnerabilities. | -| [Dynamic Application Security Testing (DAST)](../../application_security/dast/index.md) | Analyze your running web applications for known vulnerabilities. | -| [Dependency Scanning](../../application_security/dependency_scanning/index.md) | Analyze your dependencies for known vulnerabilities. | -| [Static Application Security Testing (SAST)](../../application_security/sast/index.md) | Analyze your source code for known vulnerabilities. | +<!-- This redirect file can be deleted after <2022-08-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/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index 05cc424e5ee..d6fcd9fbb16 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w [Burndown](#burndown-charts) and [burnup](#burnup-charts) charts show the progress of completing a milestone. - + ## Burndown charts @@ -19,7 +19,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Burndown charts show the number of issues over the course of a milestone. - + At a glance, you see the current state for the completion a given milestone. Without them, you would have to organize the data from the milestone and plot it @@ -106,7 +106,7 @@ Reopened issues are considered as having been opened on the day after they were Burnup charts show the assigned and completed work for a milestone. - + To view a project's burnup chart: diff --git a/doc/user/project/milestones/img/burndown_and_burnup_charts_v13_6.png b/doc/user/project/milestones/img/burndown_and_burnup_charts_v13_6.png Binary files differdeleted file mode 100644 index 8d6ba1d4fa7..00000000000 --- a/doc/user/project/milestones/img/burndown_and_burnup_charts_v13_6.png +++ /dev/null diff --git a/doc/user/project/milestones/img/burndown_and_burnup_charts_v15_1.png b/doc/user/project/milestones/img/burndown_and_burnup_charts_v15_1.png Binary files differnew file mode 100644 index 00000000000..58c0ddf892f --- /dev/null +++ b/doc/user/project/milestones/img/burndown_and_burnup_charts_v15_1.png diff --git a/doc/user/project/milestones/img/burndown_chart_v13_6.png b/doc/user/project/milestones/img/burndown_chart_v13_6.png Binary files differdeleted file mode 100644 index e06b24f9907..00000000000 --- a/doc/user/project/milestones/img/burndown_chart_v13_6.png +++ /dev/null diff --git a/doc/user/project/milestones/img/burndown_chart_v15_1.png b/doc/user/project/milestones/img/burndown_chart_v15_1.png Binary files differnew file mode 100644 index 00000000000..2953380292d --- /dev/null +++ b/doc/user/project/milestones/img/burndown_chart_v15_1.png diff --git a/doc/user/project/milestones/img/burnup_chart_v13_6.png b/doc/user/project/milestones/img/burnup_chart_v13_6.png Binary files differdeleted file mode 100644 index a850caba348..00000000000 --- a/doc/user/project/milestones/img/burnup_chart_v13_6.png +++ /dev/null diff --git a/doc/user/project/milestones/img/burnup_chart_v15_1.png b/doc/user/project/milestones/img/burnup_chart_v15_1.png Binary files differnew file mode 100644 index 00000000000..e89b76344ed --- /dev/null +++ b/doc/user/project/milestones/img/burnup_chart_v15_1.png diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index c2b85a2183c..b0f3179961d 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -11,17 +11,9 @@ Milestones in GitLab are a way to track issues and merge requests created to ach Milestones allow you to organize issues and merge requests into a cohesive group, with an optional start date and an optional due date. -## Milestones as Agile sprints - -Milestones can be used as Agile sprints so that you can track all issues and merge requests related to a particular sprint. To do so: - -1. Set the milestone start date and due date to represent the start and end of your Agile sprint. -1. Set the milestone title to the name of your Agile sprint, such as `November 2018 sprint`. -1. Add an issue to your Agile sprint by associating the desired milestone from the issue's right-hand sidebar. - ## Milestones as releases -Similarly, milestones can be used as releases. To do so: +Milestones can be used to track releases. To do so: 1. Set the milestone due date to represent the release date of your release and leave the milestone start date blank. 1. Set the milestone title to the version of your release, such as `Version 9.4`. @@ -117,19 +109,19 @@ Every issue and merge request can be assigned a milestone. The milestones are vi ### Filtering in list pages -From the project and group issue/merge request list pages, you can [filter](../../search/index.md#search-issues-and-merge-requests) by both group and project milestones. +From the project and group issue/merge request list pages, you can filter by both group and project milestones. ### Filtering in issue boards From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in: -- [Search and filter bar](../../search/index.md#issue-boards) +- [Search and filter bar](../issue_board.md#filter-issues) - [Issue board configuration](../issue_board.md#configurable-issue-boards) From [group issue boards](../issue_board.md#group-issue-boards), you can filter by only group milestones in: -- [Search and filter bar](../../search/index.md#issue-boards) +- [Search and filter bar](../issue_board.md#filter-issues) - [Issue board configuration](../issue_board.md#configurable-issue-boards) ### Special milestone filters @@ -164,7 +156,7 @@ There are also tabs below these that show the following: The milestone view contains a [burndown and burnup chart](burndown_and_burnup_charts.md), showing the progress of completing a milestone. - + ### Milestone sidebar 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 5433e02b210..6daf671a751 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 @@ -53,7 +53,7 @@ search the web for `how to add dns record on <my hosting service>`. ## `A` record -A DNS A record maps a host to an IPv4 IP address. +A DNS `A` record maps a host to an IPv4 IP address. It points a root domain as `example.com` to the host's IP address as `192.192.192.192`. @@ -61,10 +61,10 @@ Example: - `example.com` => `A` => `192.192.192.192` -## CNAME record +## `CNAME` record -CNAME records define an alias for canonical name for your server (one defined -by an A record). It points a subdomain to another domain. +`CNAME` records define an alias for canonical name for your server (one defined +by an `A` record). It points a subdomain to another domain. Example: @@ -84,14 +84,14 @@ Example: Then you can register emails for `users@mail.example.com`. -## TXT record +## `TXT` record A `TXT` record can associate arbitrary text with a host or other name. A common use is for site verification. Example: -- `example.com`=> TXT => `"google-site-verification=6P08Ow5E-8Q0m6vQ7FMAqAYIDprkVV8fUf_7hZ4Qvc8"` +- `example.com`=> `TXT` => `"google-site-verification=6P08Ow5E-8Q0m6vQ7FMAqAYIDprkVV8fUf_7hZ4Qvc8"` This way, you can verify the ownership for that domain name. @@ -102,4 +102,4 @@ You can have one DNS record or more than one combined: - `example.com` => `A` => `192.192.192.192` - `www` => `CNAME` => `example.com` - `MX` => `mail.example.com` -- `example.com`=> TXT => `"google-site-verification=6P08Ow5E-8Q0m6vQ7FMAqAYIDprkVV8fUf_7hZ4Qvc8"` +- `example.com`=> `TXT` => `"google-site-verification=6P08Ow5E-8Q0m6vQ7FMAqAYIDprkVV8fUf_7hZ4Qvc8"` 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 d970c0f9ef4..2c668e2c409 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 @@ -47,13 +47,13 @@ this document for an [overview on DNS records](dns_concepts.md). #### 1. Add a custom domain to Pages -Navigate to your project's **Setting > Pages** and click **+ New domain** +Navigate to your project's **Setting > Pages** and select **+ New domain** to add your custom domain to GitLab Pages. You can choose whether to: - Add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). - Leave it blank (it can be added later). -Click **Create New Domain**. +Select **Create New Domain**.  @@ -82,20 +82,20 @@ Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/214718) for de Root domains (`example.com`) require: -- A [DNS A record](dns_concepts.md#a-record) pointing your domain to the Pages server. -- A [TXT record](dns_concepts.md#txt-record) to verify your domain's ownership. +- A [DNS `A` record](dns_concepts.md#a-record) pointing your domain to the Pages server. +- A [`TXT` record](dns_concepts.md#txt-record) to verify your domain's ownership. | From | DNS Record | To | | --------------------------------------------- | ---------- | --------------- | -| `example.com` | A | `35.185.44.232` | -| `_gitlab-pages-verification-code.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `example.com` | `A` | `35.185.44.232` | +| `_gitlab-pages-verification-code.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | For projects on GitLab.com, this IP is `35.185.44.232`. For projects living in other GitLab instances (CE or EE), please contact your sysadmin asking for this information (which IP address is Pages server running on your instance). - + WARNING: Note that if you use your root domain for your GitLab Pages website @@ -111,7 +111,7 @@ as it most likely doesn't work if you set an [`MX` record](dns_concepts.md#mx-re Subdomains (`subdomain.example.com`) require: - A DNS [`ALIAS` or `CNAME` record](dns_concepts.md#cname-record) pointing your subdomain to the Pages server. -- A DNS [TXT record](dns_concepts.md#txt-record) to verify your domain's ownership. +- A DNS [`TXT` record](dns_concepts.md#txt-record) to verify your domain's ownership. | From | DNS Record | To | |:--------------------------------------------------------|:----------------|:----------------------| @@ -122,7 +122,7 @@ Note that, 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`. - + ##### For both root and subdomains @@ -137,11 +137,11 @@ They require: | From | DNS Record | To | | ------------------------------------------------- | ---------- | ---------------------- | -| `example.com` | A | `35.185.44.232` | -| `_gitlab-pages-verification-code.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `example.com` | `A` | `35.185.44.232` | +| `_gitlab-pages-verification-code.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | |---------------------------------------------------+------------+------------------------| -| `www.example.com` | CNAME | `namespace.gitlab.io` | -| `_gitlab-pages-verification-code.www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `www.example.com` | `CNAME` | `namespace.gitlab.io` | +| `_gitlab-pages-verification-code.www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | If you're using Cloudflare, check [Redirecting `www.domain.com` to `domain.com` with Cloudflare](#redirecting-wwwdomaincom-to-domaincom-with-cloudflare). @@ -162,8 +162,8 @@ If you're using Cloudflare, check Once you have added all the DNS records: 1. Go back at your project's **Settings > Pages**. -1. Locate your domain name and click **Details**. -1. Click the **Retry verification** button to activate your new domain. +1. Locate your domain name and select **Details**. +1. Select the **Retry verification** button to activate your new domain.  @@ -208,15 +208,15 @@ For a root domain: | From | DNS Record | To | | ------------------------------------------------- | ---------- | ---------------------- | -| `example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | -| `_gitlab-pages-verification-code.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `_gitlab-pages-verification-code.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | For a subdomain: | From | DNS Record | To | | ------------------------------------------------- | ---------- | ---------------------- | -| `www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | -| `_gitlab-pages-verification-code.www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `_gitlab-pages-verification-code.www.example.com` | `TXT` | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | ### Adding more domain aliases @@ -241,10 +241,10 @@ can use the following setup: 1. In GitLab, verify your domain. 1. In Cloudflare, create a DNS `CNAME` record pointing `www` to `domain.com`. 1. In Cloudflare, add a Page Rule pointing `www.domain.com` to `domain.com`: - - Navigate to your domain's dashboard and click **Page Rules** + - Navigate to your domain's dashboard and select **Page Rules** on the top nav. - - Click **Create Page Rule**. - - Enter the domain `www.domain.com` and click **+ Add a Setting**. + - Select **Create Page Rule**. + - Enter the domain `www.domain.com` and select **+ Add a Setting**. - From the dropdown menu, choose **Forwarding URL**, then select the status code **301 - Permanent Redirect**. - Enter the destination URL `https://domain.com`. @@ -285,7 +285,7 @@ meet these requirements. - To add the certificate at the time you add a new domain, go to your project's **Settings > Pages > New Domain**, 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, click **Details** and **Edit** to add the certificate. + project's **Settings > Pages**, locate your domain name, select **Details** and **Edit** to add the certificate.  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 cb22a200514..184e4f345c1 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 @@ -43,13 +43,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**. -1. Find your domain and click **Details**. -1. Click **Edit** in the top-right corner. +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. Click **Save changes**. +1. Select **Save changes**. Once enabled, GitLab obtains a LE certificate and add it to the associated Pages domain. GitLab also renews it automatically. @@ -70,8 +70,8 @@ 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**. -1. Click **Edit** on your domain. -1. Click **Retry**. +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. @@ -86,7 +86,7 @@ Another possible cause of this error is the `_redirects` file because the curren 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**. -1. Click **Remove** on your domain. +1. Select **Remove** on your domain. 1. [Add the domain again and verify it](index.md#1-add-a-custom-domain-to-pages). 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: 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 0c848a24dec..b080bee85aa 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 @@ -23,7 +23,7 @@ highly recommendable. Let's start with an introduction to the importance of HTTPS. -## Why should I care about HTTPS? +## Why should you care about HTTPS? 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 @@ -42,7 +42,7 @@ Now we have a different picture. [According to Josh Aas](https://letsencrypt.org > _We've since come to realize that HTTPS is important for almost all websites. It's important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn't want its content altered](https://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We've also learned that any site not secured by HTTPS [can be used to attack other sites](https://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._ Therefore, the reason why certificates are so important is that they encrypt -the connection between the **client** (you, me, your visitors) +the connection between the **client** (you, your visitors) and the **server** (where you site lives), through a keychain of authentications and validations. 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 b32d71a4887..92baba6b9c6 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 @@ -12,15 +12,15 @@ You can create a new project from a template and run the CI/CD pipeline to gener Use a template when you want to test GitLab Pages or start a new project that's already configured to generate a Pages site. -1. From the top navigation, click the **+** button and select **New project**. +1. From the top navigation, select the **+** button and select **New project**. 1. Select **Create from Template**. -1. Next to one of the templates starting with **Pages**, click **Use template**. +1. Next to one of the templates starting with **Pages**, select **Use template**.  -1. Complete the form and click **Create project**. +1. Complete the form and select **Create project**. 1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** - and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your + and select **Run pipeline** to trigger GitLab CI/CD to build and deploy your site. When the pipeline is finished, go to **Settings > Pages** to find the link to diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 5846ceeb1b6..1ea7500273e 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -71,7 +71,7 @@ To restrict access to your website, enable [GitLab Pages Access Control](pages_a If you ever feel the need to purge your Pages content, you can do so by going to your project's settings through the gear icon in the top right, and then -navigating to **Pages**. Click the **Remove pages** button to delete your Pages +navigating to **Pages**. Select the **Remove pages** button to delete your Pages website.  @@ -259,20 +259,20 @@ for both the `/data` and `/data/` URL paths. ## Frequently Asked Questions -### Can I download my generated pages? +### Can you download your generated pages? Sure. All you need to do is download the artifacts archive from the job page. -### Can I use GitLab Pages if my project is private? +### Can you use GitLab Pages if your project is private? Yes. GitLab Pages doesn't care whether you set your project's visibility level to private, internal or public. -### Can I create a personal or a group website +### Can you create a personal or a group website? Yes. See the documentation about [GitLab Pages domain names, URLs, and base URLs](getting_started_part_one.md). -### Do I need to create a user/group website before creating a project website? +### Do you need to create a user/group website before creating a project website? No, you don't. You can create your project first and access it under `http(s)://namespace.example.io/projectname`. diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 9b747e04973..eb897c176fa 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -10,9 +10,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can enable Pages access control on your project if your administrator has [enabled the access control feature](../../../administration/pages/index.md#access-control) -on your GitLab instance. When enabled, only +on your GitLab instance. When enabled, only authenticated [members of your project](../../permissions.md#project-members-permissions) -(at least Guest) can access your website: +(at least Guest) can access your website, by default: <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a demonstration, see [Pages access controls](https://www.youtube.com/watch?v=tSPAr5mQYc8). @@ -36,7 +36,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. Click **Save changes**. Note that your changes may not take effect immediately. GitLab Pages uses +1. Select **Save changes**. Note that 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/redirects.md b/doc/user/project/pages/redirects.md index 1db404f4888..791b6a1550a 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -164,7 +164,7 @@ Splats also match empty strings, so the previous rule redirects ### Rewrite all requests to a root `index.html` NOTE: -If you are using [GitLab Pages integration with Let’s Encrypt](custom_domains_ssl_tls_certification/lets_encrypt_integration.md), +If you are using [GitLab Pages integration with Let's Encrypt](custom_domains_ssl_tls_certification/lets_encrypt_integration.md), you must enable it before adding this rule. Otherwise, the redirection breaks the Let's Encrypt integration. For more details, see [GitLab Pages issue 649](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/649). diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 56f5a2d24ff..3e40a7962ae 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -21,10 +21,12 @@ When a branch is protected, the default behavior enforces these restrictions on | Protect a branch | At least the Maintainer role. | | Push to the branch | GitLab administrators and anyone with **Allowed** permission. (1) | | Force push to the branch | No one. | -| Delete the branch | No one. | +| Delete the branch | No one. (2) | 1. Users with the Developer role can create a project in a group, but might not be allowed to initially push to the [default branch](repository/branches/default.md). +1. No one can delete a protected branch using Git commands, however, users with at least Maintainer + role can [delete a protected branch from the UI or API](#delete-a-protected-branch). ### Set the default branch protection level diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 5df34fcdcc4..870c544cf4c 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -31,7 +31,7 @@ To protect a tag, you must have at least the Maintainer role. 1. Go to the project's **Settings > Repository**. -1. From the **Tag** dropdown list, select the tag you want to protect or type and click **Create wildcard**. In the screenshot below, we chose to protect all tags matching `v*`: +1. From the **Tag** dropdown list, select the tag you want to protect or type and select **Create wildcard**. In the screenshot below, we chose to protect all tags matching `v*`:  @@ -86,6 +86,26 @@ To prevent this problem: Users can still create branches, but not tags, with the protected names. +## Delete a protected tag + +You can manually delete protected tags with the GitLab API, or the +GitLab user interface. + +Prerequisite: + +- You must have at least the Maintainer role in your project. + +To do this: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Tags**. +1. Next to the tag you want to delete, select **Delete** (**{remove}**). +1. On the confirmation dialog, enter the tag name and select **Yes, delete protected tag**. + +Protected tags can only be deleted by using GitLab either from the UI or API. +These protections prevent you from accidentally deleting a tag through local +Git commands or third-party Git clients. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index b73b381ffcd..d5a7058d3d2 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -67,7 +67,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/copy_metadata <#issue>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another issue in the project. | | `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. | | `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to do as done. | -| `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Toggle the draft status. | +| `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Toggle the [draft status](merge_requests/drafts.md). | | `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | | `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue and mark as a duplicate of another issue. Also, mark both as related. | | `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | @@ -85,6 +85,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296787) in GitLab 14.5). | | `/page <policy name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Start escalations for the incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79977) in GitLab 14.9). | | `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in GitLab 13.0) | +| `/ready` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set the [ready status](merge_requests/drafts.md#mark-merge-requests-as-ready) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/90361) in GitLab 15.1). | | `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. | | `/reassign_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Replace current reviewers with those specified. | | `/rebase` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index c0a6fa9c301..d5ddc0468e1 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -63,7 +63,7 @@ switch between ascending or descending order, select **Sort order**. You can create a release: -- [Using a job in your CI/CD pipeline](#create-a-release-by-using-a-cicd-job). +- [Using a job in your CI/CD pipeline](#creating-a-release-by-using-a-cicd-job). - [In the Releases page](#create-a-release-in-the-releases-page). - [In the Tags page](#create-a-release-in-the-tags-page). - Using the [Releases API](../../../api/releases/index.md#create-a-release). @@ -118,100 +118,71 @@ To edit release notes of an existing Git tag: You can use Markdown and drag and drop files to this text box. 1. Select **Save changes**. -### Create a release by using a CI/CD job +### Creating a release by using a CI/CD job -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19298) in GitLab 12.7. - -You can create a release directly as part of the GitLab CI/CD pipeline -by using the [`release` keyword](../../../ci/yaml/index.md#release) in the job definition. +You can create a release directly as part of the GitLab CI/CD pipeline by using the +[`release` keyword](../../../ci/yaml/index.md#release) in the job definition. The release is created only if the job processes without error. If the API returns an error during release creation, the release job fails. -#### CI/CD example of the `release` keyword +Methods for creating a release using a CI/CD job include: + +- Create a release when a Git tag is created. +- Create a release when a commit is merged to the default branch. + +#### Create a release when a Git tag is created -To create a release when you push a Git tag, or when you add a Git tag -in the UI by going to **Repository > Tags**: +In this CI/CD example, pushing a Git tag to the repository, or creating a Git tag in the UI triggers +the release. You can use this method if you prefer to create the Git tag manually, and create a +release as a result. NOTE: -Do not provide **Release notes** when you create the Git tag in the UI. -Providing release notes creates a release, resulting in the pipeline failing. +Do not provide Release notes when you create the Git tag in the UI. Providing release notes +creates a release, resulting in the pipeline failing. + +Key points in the following _extract_ of an example `.gitlab-ci.yml` file: + +- The `rules` stanza defines when the job is added to the pipeline. +- The Git tag is used in the release's name and description. ```yaml release_job: stage: release image: registry.gitlab.com/gitlab-org/release-cli:latest rules: - - if: $CI_COMMIT_TAG # Run this job when a tag is created manually + - if: $CI_COMMIT_TAG # Run this job when a tag is created script: - echo "running release_job" - release: - name: 'Release $CI_COMMIT_TAG' - description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION must be defined - tag_name: '$CI_COMMIT_TAG' # elsewhere in the pipeline. - ref: '$CI_COMMIT_TAG' - milestones: - - 'm1' - - 'm2' - - 'm3' - released_at: '2020-07-15T08:00:00Z' # Optional, is auto generated if not defined, or can use a variable. - assets: # Optional, multiple asset links - links: - - name: 'asset1' - url: 'https://example.com/assets/1' - - name: 'asset2' - url: 'https://example.com/assets/2' - filepath: '/pretty/url/1' # optional - link_type: 'other' # optional + release: # See https://docs.gitlab.com/ee/ci/yaml/#release for available properties + tag_name: '$CI_COMMIT_TAG' + description: '$CI_COMMIT_TAG' ``` -To create a release automatically when commits are pushed or merged to the default branch, -using a new Git tag that is defined with variables: +#### Create a release when a commit is merged to the default branch -```yaml -prepare_job: - stage: prepare # This stage must run before the release stage - rules: - - if: $CI_COMMIT_TAG - when: never # Do not run this job when a tag is created manually - - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch - script: - - echo "EXTRA_DESCRIPTION=some message" >> variables.env # Generate the EXTRA_DESCRIPTION and TAG environment variables - - echo "TAG=v$(cat VERSION)" >> variables.env # and append to the variables.env file - artifacts: - reports: - dotenv: variables.env # Use artifacts:reports:dotenv to expose the variables to other jobs +In this CI/CD example, merging a commit to the default branch triggers the pipeline. You can use +this method if your release workflow does not create a tag manually. +Key points in the following _extract_ of an example `.gitlab-ci.yml` file: + +- The Git tag, description, and reference are created automatically in the pipeline. +- If you manually create a tag, the `release_job` job does not run. + +```yaml release_job: stage: release image: registry.gitlab.com/gitlab-org/release-cli:latest - needs: - - job: prepare_job - artifacts: true rules: - if: $CI_COMMIT_TAG when: never # Do not run this job when a tag is created manually - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch script: - echo "running release_job for $TAG" - release: - name: 'Release $TAG' - description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION and the $TAG - tag_name: '$TAG' # variables must be defined elsewhere - ref: '$CI_COMMIT_SHA' # in the pipeline. For example, in the - milestones: # prepare_job - - 'm1' - - 'm2' - - 'm3' - released_at: '2020-07-15T08:00:00Z' # Optional, is auto generated if not defined, or can use a variable. - assets: - links: - - name: 'asset1' - url: 'https://example.com/assets/1' - - name: 'asset2' - url: 'https://example.com/assets/2' - filepath: '/pretty/url/1' # optional - link_type: 'other' # optional + release: # See https://docs.gitlab.com/ee/ci/yaml/#release for available properties + tag_name: 'v0.$CI_PIPELINE_IID' # The version is incremented per pipeline. + description: 'v0.$CI_PIPELINE_IID' + ref: '$CI_COMMIT_SHA' # The tag is created from the pipeline SHA. ``` NOTE: @@ -219,6 +190,36 @@ Environment variables set in `before_script` or `script` are not available for e in the same job. Read more about [potentially making variables available for expanding](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6400). +#### Skip multiple pipelines when creating a release + +Creating a release using a CI/CD job could potentially trigger multiple pipelines if the associated tag does not exist already. To understand how this might happen, consider the following workflows: + +- Tag first, release second: + 1. A tag is created via UI or pushed. + 1. A tag pipeline is triggered, and runs `release` job. + 1. A release is created. + +- Release first, tag second: + 1. A pipeline is triggered when commits are pushed or merged to default branch. The pipeline runs `release` job. + 1. A release is created. + 1. A tag is created. + 1. A tag pipeline is triggered. The pipeline also runs `release` job. + +In the second workflow, the `release` job runs in multiple pipelines. To prevent this, you can use the [`workflow:rules` keyword](../../../ci/yaml/index.md#workflowrules) to determine if a release job should run in a tag pipeline: + +```yaml +release_job: + rules: + - if: $CI_COMMIT_TAG + when: never # Do not run this job in a tag pipeline + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when commits are pushed or merged to the default branch + script: + - echo "Create release" + release: + name: 'My awesome release' + tag_name: '$CI_COMMIT_TAG' +``` + ### Use a custom SSL CA certificate authority You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority, diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index f9fd1a48b9a..e087ed6c439 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -252,7 +252,7 @@ We are tracking this problem in [issue 20474](https://gitlab.com/gitlab-org/gitl This issue often occurs when a branch named `HEAD` is present in the repository. To fix the problem: -1. In your local repository, create a new, temporary branch and push it: +1. In your local repository, create a new temporary branch and push it: ```shell git checkout -b tmp_default && git push -u origin tmp_default diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 351daaaca3b..6da2e5fc7ee 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -50,7 +50,7 @@ To compare branches in a repository: 1. Select **Repository > Compare** in the sidebar. 1. Select the target repository to compare with the [repository filter search box](#repository-filter-search-box). 1. Select branches to compare using the [branch filter search box](#branch-filter-search-box). -1. Click **Compare** to view the changes inline: +1. Select **Compare** to view the changes inline:  @@ -98,7 +98,7 @@ Sometimes when you have hundreds of branches you may want a more flexible matchi  -The Swap revisions feature allows you to swap the Source and Target revisions. When the Swap revisions button is clicked, the selected revisions for Source and Target will be swapped. +The Swap revisions feature allows you to swap the Source and Target revisions. When the Swap revisions button is clicked, the selected revisions for Source and Target is swapped.  diff --git a/doc/user/project/repository/csv.md b/doc/user/project/repository/csv.md index 4bf6c7451d5..27424268d2b 100644 --- a/doc/user/project/repository/csv.md +++ b/doc/user/project/repository/csv.md @@ -13,7 +13,7 @@ A comma-separated values (CSV) file is a delimited text file that uses a comma t Each line of the file is a data record. Each record consists of one or more fields, separated by commas. The use of the comma as a field separator is the source of the name for this file format. A CSV file typically stores tabular data (numbers and text) in plain text, in which case each line -will have the same number of fields. +has the same number of fields. The CSV file format is not fully standardized. Other characters can be used as column delimiters. Fields may or may not be surrounded to escape special characters. diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 198993e21f3..0026834ae83 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -27,7 +27,7 @@ are shown. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19299) in GitLab 12.7. -To see earlier revisions of a specific line, click **View blame prior to this change** +To see earlier revisions of a specific line, select **View blame prior to this change** until you've found the changes you're interested in viewing:  diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index d013d2802bf..1ed6dbd3348 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -28,15 +28,11 @@ GitLab. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6589) in GitLab 14.5 as an [Alpha](../../../../policy/alpha-beta-support.md#alpha-features) release [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75500) in GitLab 14.9. Feature flag `jupyter_clean_diffs` removed. > - [Reintroduced toggle](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85079) in GitLab 15.0 [with a flag](../../../../administration/feature_flags.md) named `ipynb_semantic_diff`. Enabled by default. -> - Selecting between raw and cleaner diffs [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85203) in GitLab 15.0 [with a flag](../../../../administration/feature_flags.md) named `rendered_diffs_viewer`. Enabled by default. FLAG: On self-managed GitLab, by default semantic diffs are available. To hide the feature, ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) named `ipynb_semantic_diff`. On GitLab.com, this feature is available. -FLAG: -On self-managed GitLab, by default the ability to switch between raw and rendered diffs is available. To hide the feature, ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md)named `rendered_diffs_viewer`. On GitLab.com, this feature is available. - When commits include changes to Jupyter Notebook files, GitLab: - Transforms the machine-readable `.ipynb` file into a human-readable Markdown file. diff --git a/doc/user/project/repository/managing_large_repositories.md b/doc/user/project/repository/managing_large_repositories.md index d6f88697c54..76f66f41297 100644 --- a/doc/user/project/repository/managing_large_repositories.md +++ b/doc/user/project/repository/managing_large_repositories.md @@ -1,5 +1,5 @@ --- -stage: Enablement +stage: Systems group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments description: "Documentation on large repositories." @@ -16,13 +16,13 @@ On this page we detail several best practices to improve performance with these It's *strongly* recommended in any Git system that binary or blob files (for example, packages, audio, video, graphics, etc.) are stored as Large File Storage (LFS) objects. In such setup, the Objects are stored elsewhere, such as in Object Storage, and this can reduce the repository size significantly, thus improving performance. -Refer to the [Git LFS docs for more info](../../../topics/git/lfs/index.md). +Refer to the [Git LFS docs for more information](../../../topics/git/lfs/index.md). ## Gitaly Pack Objects Cache Gitaly, the service that provides storage for Git repositories, can be configured to cache a short rolling window of Git fetch responses. This is recommended for large repositories as it can notably reduce server load when your server receives lots of fetch traffic. -Refer to the [Gitaly Pack Objects Cache for more info](../../../administration/gitaly/configure_gitaly.md#pack-objects-cache). +Refer to the [Gitaly Pack Objects Cache for more information](../../../administration/gitaly/configure_gitaly.md#pack-objects-cache). ## Reference Architectures @@ -34,7 +34,7 @@ In these types of setups it's recommended that the GitLab environment used match Gitaly Cluster can notably improve large repository performance as it holds multiple replicas of the repository across several nodes. As a result, Gitaly Cluster can load balance read requests against those repositories and is also fault tolerant. -It's recommended for large repositories, however, Gitaly Cluster is a large solution with additional complexity of setup and management. Refer to the [Gitaly Cluster docs for more info](../../../administration/gitaly/index.md), specifically the [Before deploying Gitaly Cluster](../../../administration/gitaly/index.md#before-deploying-gitaly-cluster) section. +It's recommended for large repositories, however, Gitaly Cluster is a large solution with additional complexity of setup and management. Refer to the [Gitaly Cluster docs for more information](../../../administration/gitaly/index.md), specifically the [Before deploying Gitaly Cluster](../../../administration/gitaly/index.md#before-deploying-gitaly-cluster) section. ## Keep GitLab up to date @@ -48,4 +48,4 @@ CI/CD loads tend to be concurrent as pipelines are scheduled during set times. A When designing CI/CD pipelines, it's advisable to reduce their concurrency by staggering them to run at different times, for example, a set running at one time and then another set running several minutes later. -There's several other actions that can be explored to improve CI/CD performance with large repositories. Refer to the [Runner docs for more info](../../../ci/large_repositories/index.md). +There's several other actions that can be explored to improve CI/CD performance with large repositories. Refer to the [Runner docs for more information](../../../ci/large_repositories/index.md). diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 1645cf7244e..fe1c9653cfe 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -167,7 +167,7 @@ for you to check: - [GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints) - [GitLab.com](../../../gitlab_com/index.md#ssh-host-keys-fingerprints) - [Launchpad](https://help.launchpad.net/SSHFingerprints) -- [Savannah](http://savannah.gnu.org/maintenance/SshAccess/) +- [Savannah](https://savannah.gnu.org/maintenance/SshAccess/) - [SourceForge](https://sourceforge.net/p/forge/documentation/SSH%20Key%20Fingerprints/) Other providers vary. You can securely gather key fingerprints with the following diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index 73103a9af3d..3599faf4de6 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -96,9 +96,9 @@ assigned when you set up pull mirroring. > Moved to GitLab Premium in 13.9. Pull mirroring uses polling to detect new branches and commits added upstream, -often minutes afterwards. If you notify GitLab by -[API](../../../../api/projects.md#start-the-pull-mirroring-process-for-a-project), -updates are pulled immediately. +often minutes afterwards. You can notify GitLab using an +[API call](../../../../api/projects.md#start-the-pull-mirroring-process-for-a-project), +but the [minimum interval for pull mirroring limits](index.md#force-an-update) is still enforced. For more information, read [Start the pull mirroring process for a project](../../../../api/projects.md#start-the-pull-mirroring-process-for-a-project). diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md index 994cf78d98a..592aff85434 100644 --- a/doc/user/project/repository/push_rules.md +++ b/doc/user/project/repository/push_rules.md @@ -26,6 +26,9 @@ For custom push rules use [server hooks](../../../administration/server_hooks.md You can create push rules for all new projects to inherit, but they can be overridden at the project level or the [group level](../../group/index.md#group-push-rules). +All projects created after you configure global push rules inherit this +configuration. However, each existing project must be updated manually, using the +process described in [Override global push rules per project](#override-global-push-rules-per-project). Prerequisite: @@ -42,7 +45,8 @@ To create global push rules: ## Override global push rules per project The push rule of an individual project overrides the global push rule. -To override global push rules for a specific project: +To override global push rules for a specific project, or to update the rules +for an existing project to match new global push rules: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. @@ -77,10 +81,12 @@ Use these rules for your commit messages. ## Validate branch names To validate your branch names, enter a regular expression for **Branch name**. -To allow any branch name, leave empty. Your -[default branch](branches/default.md) is always allowed. +To allow any branch name, leave empty. Your [default branch](branches/default.md) +is always allowed. Certain formats of branch names are restricted by default for +security purposes. Names with 40 hexadecimal characters, similar to Git commit hashes, +are prohibited. -Examples: +Some validation examples: - Branches must start with `JIRA-`. @@ -101,11 +107,6 @@ Examples: `^[a-z0-9\\-]{4,15}$` ``` -NOTE: -In GitLab 12.10 and later, certain formats of branch names are restricted by -default for security purposes. 40-character hexadecimal names, similar to Git -commit hashes, are prohibited. - ## Prevent unintended consequences Use these rules to prevent unintended consequences. @@ -134,6 +135,8 @@ Never commit secrets, such as credential files and SSH private keys, to a versio system. In GitLab, you can use a predefined list of files to block those files from a repository. Merge requests that contain a file that matches the list are blocked. This push rule does not restrict files already committed to the repository. +You must update the configuration of existing projects to use the rule, using the +process described in [Override global push rules per project](#override-global-push-rules-per-project). Files blocked by this rule are listed below. For a complete list of criteria, refer to [`files_denylist.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml). diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 747bd690911..370a349b982 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -14,7 +14,7 @@ dropdown menu. ## Create a file -From a project's files page, click the '+' button to the right of the branch selector. +From a project's files page, select the '+' button to the right of the branch selector. Choose **New file** from the dropdown.  @@ -24,7 +24,7 @@ defaults to the branch you were viewing in the file browser. If you enter a new branch name, a checkbox displays, allowing you to start a new merge request after you commit the changes. -When you are satisfied with your new file, click **Commit Changes** at the bottom. +When you are satisfied with your new file, select **Commit Changes** at the bottom.  @@ -72,7 +72,7 @@ You don't need to construct these lines manually. Instead, you can: 1. Hover over the number of a line you want to be highlighted when sharing. 1. Right-click the number with your mouse. -1. Click **Copy Link Address** in the context menu. +1. Select **Copy Link Address** in the context menu.  @@ -82,7 +82,7 @@ The ability to create a file is great when the content is text. However, this doesn't work well for binary data such as images, PDFs, or other binary file types. In this case, you need to upload a file. -From a project's files page, click the '+' button to the right of the branch +From a project's files page, select the '+' button to the right of the branch selector. Choose **Upload file** from the dropdown:  @@ -91,7 +91,7 @@ After the upload dialog pops up, there are two ways to upload your file. Either drag and drop a file on the popup or use the **click to upload** link. After you select a file to upload, a file preview displays. -Enter a commit message, choose a branch, and click **Upload file** when you are +Enter a commit message, choose a branch, and select **Upload file** when you are ready.  @@ -101,13 +101,13 @@ ready. To keep files in the repository organized it is often helpful to create a new directory. -From a project's files page, click the plus button (`+`) to the right of the branch selector. +From a project's files page, select the plus button (`+`) to the right of the branch selector. Choose **New directory** from the dropdown.  In the new directory dialog, enter a directory name, a commit message, and choose -the target branch. Click **Create directory** to finish. +the target branch. Select **Create directory** to finish.  @@ -153,7 +153,7 @@ 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`. -When you click the **Create branch** button in an empty +When you select the **Create branch** button in an empty repository project, GitLab performs these actions: - Creates a default branch. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 19c3218137f..17e55b7aac2 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -146,7 +146,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: diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 9b37e147a52..4eeb7c5ba83 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -4,10 +4,13 @@ group: Import info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" --- -# Project import/export **(FREE)** +# Migrating projects using file exports **(FREE)** Existing projects on any self-managed GitLab instance or GitLab.com can be exported to a file and -then imported into a new GitLab instance. +then imported into a new GitLab instance. You can also: + +- [Migrate groups](../../group/import/index.md) using the preferred method. +- [Migrate groups using file exports](../../group/settings/import_export.md). ## Set up project import/export @@ -34,8 +37,8 @@ Before you can import a project, you must export it. Prerequisites: -- Review the list of [data that will be exported](#items-that-are-exported). - Not all data is exported. +- Review the list of [items that are exported](#items-that-are-exported). + Not all items are exported. - You must have at least the Maintainer role for the project. To export a project and its data, follow these steps: @@ -74,7 +77,7 @@ The following items are **not** exported: - [Child pipeline history](https://gitlab.com/gitlab-org/gitlab/-/issues/221088) - Build traces and artifacts -- Container registry images +- Package and container registry images - CI/CD variables - Pipeline triggers - Webhooks @@ -152,6 +155,9 @@ Administrators can set the maximum import file size one of two ways: The default is `0` (unlimited). +For the GitLab.com setting, see the [Account and limit settings](../../gitlab_com/index.md#account-and-limit-settings) +section of the GitLab.com settings page. + ## Map users for import Imported users can be mapped by their public email addresses on self-managed instances, if an administrator (not an owner) does the import. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 1e63472763d..46a6c1a049e 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -7,32 +7,29 @@ type: reference, index, howto # Project settings **(FREE)** -The **Settings** page in GitLab provides a centralized home for your -[project](../index.md) configuration options. To access it, go to your project's homepage -and, in the left navigation menu, select **Settings**. To reduce complexity, settings are -grouped by topic into sections. To display all settings in a section, select **Expand**. +Use the **Settings** page to manage the configuration options in your [project](../index.md). -In GitLab versions [13.10 and later](https://gitlab.com/groups/gitlab-org/-/epics/4842), -GitLab displays a search box to help you find the settings you want to view. +## View project settings -NOTE: -Only users who have the Maintainer role for the project and administrators can -access project settings. - -## General settings +You must have at least the Maintainer role to view project settings. -Under a project's general settings, you can find everything concerning the -functionality of a project. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. To display all settings in a section, select **Expand**. +1. Optional. Use the search box to find a setting. -### General project settings +## Edit project name and description -Adjust your project's name, description, avatar, [default branch](../repository/branches/default.md), and topics: +Use the project general settings to edit your project details. -The project description also partially supports [standard Markdown](../../markdown.md#features-extended-from-standard-markdown). -You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and -[line-breaks](../../markdown.md#line-breaks) to add more context to the project description. +1. Sign in to GitLab with at least the Maintainer role. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. In the **Project name** text box, enter your project name. +1. In the **Project description** text box, enter your project description. +1. Under **Project avatar**, to change your project avatar, select **Choose file**. -#### Topics +## Assign topics to a project Use topics to categorize projects and find similar new projects. @@ -40,21 +37,10 @@ To assign topics to a project: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings** > **General**. -1. Under **Topics**, enter the project topics. Existing popular topics are suggested as you type. +1. In the **Topics** text box, enter the project topics. Popular topics are suggested as you type. 1. Select **Save changes**. -For GitLab.com, explore popular topics on the [Explore topics page](../working_with_projects.md#explore-topics). -When you select a topic, you can see relevant projects. - -NOTE: -The assigned topics are visible only to everyone with access to the project, -but everyone can see which topics exist at all on the GitLab instance. -Do not include sensitive information in the name of a topic. - -If you're an instance administrator, see also -[Administering topics](../../admin_area/index.md#administering-topics). - -#### Compliance frameworks **(PREMIUM)** +## Compliance frameworks **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) in GitLab 13.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/287779) in GitLab 13.12. @@ -80,7 +66,7 @@ Creating compliance frameworks on subgroups with GraphQL causes the framework to created on the root ancestor if the user has the correct permissions. The GitLab UI presents a read-only view to discourage this behavior. -#### Compliance pipeline configuration **(ULTIMATE)** +### Compliance pipeline configuration **(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. @@ -186,7 +172,7 @@ as we have not [unified the user experience for these two features](https://gitl For details on the similarities and differences between these features, see [Enforce scan execution](../../application_security/#enforce-scan-execution). -##### Ensure compliance jobs are always run +### Ensure compliance jobs are always run Compliance pipelines use GitLab CI/CD to give you an incredible amount of flexibility for defining any sort of compliance jobs you like. Depending on your goals, these jobs @@ -218,7 +204,7 @@ cannot change them: This ensures that your job uses the settings you intend and that they are not overridden by project-level pipelines. -##### Avoid parent and child pipelines in GitLab 14.7 and earlier +### Avoid parent and child pipelines in GitLab 14.7 and earlier NOTE: This advice does not apply to GitLab 14.8 and later because [a fix](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78878) added @@ -236,25 +222,27 @@ Therefore, in projects with compliance frameworks, we recommend replacing This alternative ensures the compliance pipeline does not re-start the parent pipeline. -### Sharing and permissions +## Configure project visibility, features, and permissions -For your repository, you can set up features such as public access, repository features, -documentation, access permissions, and more. To do so from your project, -go to **Settings** > **General**, and expand the **Visibility, project features, permissions** -section. +To configure visibility, features, and permissions for a project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand the **Visibility, project features, permissions** section. +1. To change the project visibility, select the dropdown list. If you select to **Public**, you limit access to some features to **Only Project Members**. +1. To allow users to request access to the project, select the **Users can request access** checkbox. +1. Use the [toggles](#project-feature-settings) to enable or disable features in the project. +1. Select **Save changes**. -You can now change the [Project visibility](../../public_access.md). -If you set **Project Visibility** to public, you can limit access to some features -to **Only Project Members**. In addition, you can select the option to -[Allow users to request access](../members/index.md#request-access-to-a-project). +### Project feature settings -Use the switches to enable or disable the following features: +Use the toggles to enable or disable features in the project. | Option | More access limit options | Description | |:---------------------------------|:--------------------------|:--------------| | **Issues** | ✓ | Activates the GitLab issues tracker. | | **Repository** | ✓ | Enables [repository](../repository/) functionality | -| **Merge requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#merge-request-settings). | +| **Merge requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#configure-merge-request-settings-for-a-project). | | **Forks** | ✓ | Enables [forking](../repository/forking_workflow.md) functionality. | | **Git Large File Storage (LFS)** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs). | | **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality. | @@ -269,33 +257,28 @@ Use the switches to enable or disable the following features: | **Operations** | ✓ | Control access to Operations-related features, including [Operations Dashboard](../../../operations/index.md), [Environments and Deployments](../../../ci/environments/index.md), [Feature Flags](../../../operations/feature_flags.md). | | **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md). | -Some features depend on others: +When you disable a feature, the following additional features are also disabled: -- If you disable the **Issues** option, GitLab also removes the following - features: +- If you disable the **Issues** feature, project users cannot use: - **Issue Boards** - - [**Service Desk**](#service-desk) + - **Service Desk** + - Project users can still access **Milestones** from merge requests. - NOTE: - When the **Issues** option is disabled, you can still access **Milestones** - from merge requests. - -- Additionally, if you disable both **Issues** and **Merge Requests**, you cannot access: +- If you disable **Issues** and **Merge Requests**, project users cannot use: - **Labels** - **Milestones** -- If you disable **Repository** functionality, GitLab also disables the following - features for your project: +- If you disable **Repository**, project users cannot access: - **Merge requests** - **CI/CD** - **Container Registry** - **Git Large File Storage** - **Packages** -- Metrics dashboard access requires reading both project environments and deployments. +- Metrics dashboard access requires reading project environments and deployments. Users with access to the metrics dashboard can also access environments and deployments. -#### Disabling the CVE ID request button **(FREE SAAS)** +## Disabling the CVE ID request button **(FREE SAAS)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. @@ -305,12 +288,12 @@ setting **Enable CVE ID requests in the issue sidebar**.  -#### Disabling email notifications +## Disabling email notifications Project owners can disable all [email notifications](../../profile/notifications.md) related to the project by selecting the **Disable email notifications** checkbox. -### Merge request settings +## Configure merge request settings for a project Set up your project's merge request settings: @@ -326,20 +309,20 @@ Set up your project's merge request settings: - 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. -### Service Desk +## Service Desk Enable [Service Desk](../service_desk.md) for your project to offer customer support. -### Export project +## Export project Learn how to [export a project](import_export.md#import-a-project-and-its-data) in GitLab. -### Advanced settings +## Advanced settings Here you can run housekeeping, archive, rename, transfer, [remove a fork relationship](#removing-a-fork-relationship), or delete a project. -#### Archiving a project +## Archiving a project Archiving a project makes it read-only for all users and indicates that it's no longer actively maintained. Projects that have been archived can also be @@ -353,11 +336,11 @@ in project listings. To archive a project: 1. Navigate to your project's **Settings > General**. -1. Under **Advanced**, click **Expand**. -1. In the **Archive project** section, click the **Archive project** button. +1. Under **Advanced**, select **Expand**. +1. In the **Archive project** section, select **Archive project**. 1. Confirm the action when asked to. -#### Unarchiving a project +## Unarchiving a project Unarchiving a project removes the read-only restriction on a project, and makes it available in project listings. Only project owners and administrators have the @@ -373,21 +356,21 @@ To find an archived project: 1. Select **Explore projects**. 1. In the **Sort projects** dropdown box, select **Show archived projects**. 1. In the **Filter by name** field, provide the project's name. - 1. Click the link to the project to open its **Details** page. + 1. Select the link to the project to open its **Details** page. Next, to unarchive the project: 1. Navigate to your project's **Settings > General**. -1. Under **Advanced**, click **Expand**. -1. In the **Unarchive project** section, click the **Unarchive project** button. +1. Under **Advanced**, select **Expand**. +1. In the **Unarchive project** section, select **Unarchive project**. 1. Confirm the action when asked to. -#### Renaming a repository +## Renaming a repository NOTE: Only project maintainers and administrators have the [permissions](../../permissions.md#project-members-permissions) to rename a repository. Not to be confused with a project's name where it can also be -changed from the [general project settings](#general-project-settings). +changed from the [general project settings](#edit-project-name-and-description). A project's repository name defines its URL (the one you use to access the project via a browser) and its place on the file disk where GitLab is installed. @@ -395,15 +378,15 @@ project via a browser) and its place on the file disk where GitLab is installed. To rename a repository: 1. Navigate to your project's **Settings > General**. -1. Under **Advanced**, click **Expand**. +1. Under **Advanced**, select **Expand**. 1. Under **Change path**, update the repository's path. -1. Click **Change path**. +1. Select **Change path**. Remember that this can have unintended side effects since everyone with the old URL can't push or pull. Read more about what happens with the [redirects when renaming repositories](../repository/index.md#what-happens-when-a-repository-path-changes). -#### Transferring an existing project into another namespace +## Transferring an existing project into another namespace NOTE: Only project owners and administrators have the [permissions](../../permissions.md#project-members-permissions) @@ -440,7 +423,7 @@ NOTE: GitLab administrators can use the [administration interface](../../admin_area/index.md#administering-projects) to move any project to any namespace if needed. -##### Transferring a GitLab.com project to a different subscription tier +## Transferring a GitLab.com project to a different subscription tier When you transfer a project from a namespace that's licensed for GitLab SaaS Premium or Ultimate to Free, some data related to the paid features is deleted. @@ -448,7 +431,7 @@ For example, [project access tokens](../../../user/project/settings/project_acce [pipeline subscriptions](../../../ci/pipelines/multi_project_pipelines.md#trigger-a-pipeline-when-an-upstream-project-is-rebuilt) and [test cases](../../../ci/test_cases/index.md) are deleted. -#### Delete a project +## Delete a project You can mark a project to be deleted. @@ -470,18 +453,20 @@ WARNING: The default deletion behavior for projects was changed to [delayed project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6, and then to [immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. -#### Delayed project deletion **(PREMIUM)** +### Delayed project deletion **(PREMIUM)** + +> [Enabled for projects in personal namespaces](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89466) in GitLab 15.1. -Projects in a group (not a personal namespace) can be deleted after a delay period. Multiple settings can affect whether +Projects can be deleted after a delay period. Multiple settings can affect whether delayed project deletion is enabled for a particular project: -- Self-managed instance [settings](../../admin_area/settings/visibility_and_access_controls.md#default-delayed-project-deletion). +- Self-managed instance [settings](../../admin_area/settings/visibility_and_access_controls.md#deletion-protection). You can enable delayed project deletion as the default setting for new groups, and configure the number of days for the delay. For GitLab.com, see the [GitLab.com settings](../../gitlab_com/index.md#delayed-project-deletion). - Group [settings](../../group/index.md#enable-delayed-project-deletion) to enabled delayed project deletion for all projects in the group. -##### Delete a project immediately +### Delete a project immediately > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191367) in GitLab 14.1. @@ -505,16 +490,16 @@ The following are deleted: - Your project and its repository. - All related resources including issues and merge requests. -#### Restore a project **(PREMIUM)** +## Restore a project **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. To restore a project marked for deletion: 1. Navigate to your project, and select **Settings > General > Advanced**. -1. In the Restore project section, click the **Restore project** button. +1. In the Restore project section, select **Restore project**. -#### Removing a fork relationship +## Removing a fork relationship Forking is a great way to [contribute to a project](../repository/forking_workflow.md) of which you're not a member. @@ -529,7 +514,7 @@ To restore the fork relationship, [use the API](../../../api/projects.md#create- To do so: 1. Navigate to your project's **Settings > General > Advanced**. -1. Under **Remove fork relationship**, click the likewise-labeled button. +1. Under **Remove fork relationship**, select the likewise-labeled button. 1. Confirm the action by typing the project's path as instructed. NOTE: diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index e332b74f908..77a53874777 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -36,13 +36,15 @@ You can use project access tokens: - Consider [disabling project access tokens](#enable-or-disable-project-access-token-creation) to lower potential abuse. -You cannot use project access tokens to create other access tokens. +You cannot use project access tokens to create other group, project, or personal access tokens. Project access tokens inherit the [default prefix setting](../../admin_area/settings/account_and_limit_settings.md#personal-access-token-prefix) configured for personal access tokens. ## Create a project access token +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/89114) in GitLab 15.1, Owners can select Owner role for project access tokens. + To create a project access token: 1. On the top bar, select **Menu > Projects** and find your project. @@ -116,6 +118,8 @@ Bot users for projects: - Are included in a project's member list but cannot be modified. - Cannot be added to any other project. +- Can have a maximum role of Owner for a project. For more information, see + [Create a project access token](../../../api/project_access_tokens.md#create-a-project-access-token). When the project access token is [revoked](#revoke-a-project-access-token): diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 0891e02f3f7..971ecf66a3c 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -102,7 +102,7 @@ type `/spend 1h 2021-01-31`. If you type a future date, no time is logged. -### Remove time spent +### Subtract time spent Prerequisites: @@ -112,11 +112,10 @@ To subtract time, enter a negative value. For example, `/spend -3d` removes thre days from the total time spent. You can't go below 0 minutes of time spent, so if you remove more time than already entered, GitLab ignores the subtraction. -To remove all the time spent at once, use the `/remove_time_spent` [quick action](quick_actions.md). - ### Delete time spent -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356796) in GitLab 15.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356796) in GitLab 14.10. +> - Delete button [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356796) in GitLab 15.1. A timelog is a single entry of time spent, either positive or negative. @@ -124,7 +123,18 @@ Prerequisites: - You must be the author of the timelog or have at least the Maintainer role for the project. -You can [delete timelogs](../../api/graphql/reference/index.md#mutationtimelogdelete) using the GraphQL API. +To delete a timelog, either: + +- In the time tracking report, on the right of a timelog entry, select **Delete time spent** (**{remove}**). +- Use the [GraphQL API](../../api/graphql/reference/index.md#mutationtimelogdelete). + +### Delete all the time spent + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To delete all the time spent at once, use the `/remove_time_spent` [quick action](quick_actions.md). ## View a time tracking report @@ -137,7 +147,7 @@ To view a time tracking report: 1. Go to an issue or a merge request. 1. In the right sidebar, select **Time tracking report**. - + The breakdown of spent time is limited to a maximum of 100 entries. diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 9db30ee2ab6..facaba45aec 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -19,7 +19,7 @@ and from merge requests: - *When viewing a file, or the repository file list* - 1. In the upper right corner of the page, select **Open in Web IDE** if it is visible. 1. If **Open in Web IDE** is not visible: - 1. Select the **(angle-down)** next to **Edit** or **Gitpod**, depending on your configuration. + 1. Select the (**{chevron-lg-down}**) next to **Edit** or **Gitpod**, depending on your configuration. 1. Select **Open in Web IDE** from the list to display it as the editing option. 1. Select **Open in Web IDE** to open the editor. - *When viewing a merge request* - @@ -198,13 +198,13 @@ left. ## Switching merge requests -To switch between your authored and assigned merge requests, click the +To switch between your authored and assigned merge requests, select the dropdown in the top of the sidebar to open a list of merge requests. You must commit or discard all your changes before switching to a different merge request. ## Switching branches -To switch between branches of the current project repository, click the dropdown +To switch between branches of the current project repository, select the dropdown in the top of the sidebar to open a list of branches. You must commit or discard all your changes before switching to a different branch. @@ -320,7 +320,7 @@ The [File Sync](#file-syncing-to-web-terminal) feature is supported on Kubernete To enable the Web IDE terminals you must create the file `.gitlab/.gitlab-webide.yml` inside the repository's root. This -file is fairly similar to the [CI configuration file](../../../ci/yaml/index.md) +file is fairly similar to the [`.gitlab-ci.yml` file](../../../ci/yaml/index.md) syntax but with some restrictions: - No global blocks (such as `before_script` or `after_script`) can be defined. @@ -334,7 +334,7 @@ syntax but with some restrictions: that, if you override the default `script` value, you have to add a command which would keep the job running, like `sleep`. -In the code below there is an example of this configuration file: +For example, with this configuration file: ```yaml terminal: @@ -348,20 +348,20 @@ terminal: NODE_ENV: "test" ``` -After the terminal has started, the console is displayed and we could access +After the terminal starts, the console is displayed and you can access the project repository files. -When you use the image keyword, a container with the specified image is created. If you specify an image, it has no effect. This is the case when you use the [shell executor](https://docs.gitlab.com/runner/executors/shell.html). +When you use the `image` keyword, a container with the specified image is created. +If you use the [shell executor](https://docs.gitlab.com/runner/executors/shell.html) +or the [SSH executor](https://docs.gitlab.com/runner/executors/ssh.html), `image` has no effect. -**Important**. The terminal job is branch dependent. This means that the -configuration file used to trigger and configure the terminal is the one in -the selected branch of the Web IDE. - -If there is no configuration file in a branch, an error message is shown. +The terminal job is branch dependent. The configuration file used to trigger +and configure the terminal is the one in the selected branch of the Web IDE. +If no configuration file exists in a branch, an error message is displayed. ### Running interactive terminals in the Web IDE -If Interactive Terminals are available for the current user, the **Terminal** button is visible in the right sidebar of the Web IDE. Click this button to open +If Interactive Terminals are available for the current user, the **Terminal** button is visible in the right sidebar of the Web IDE. Select this button to open or close the terminal tab. After opening, the tab shows the **Start Web Terminal** button. This button may @@ -383,7 +383,7 @@ to running commands in a local terminal or through SSH. While the terminal is running, it can be stopped by clicking **Stop Terminal**. This disconnects the terminal and stops the runner's terminal job. From here, -click **Restart Terminal** to start a new terminal session. +select **Restart Terminal** to start a new terminal session. ### File syncing to web terminal diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index fe6c7ae62b8..5ae0cf46d9b 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -270,7 +270,7 @@ Support for displaying a generated table of contents with a custom side navigati Wikis are enabled by default in GitLab. Project [administrators](../../permissions.md) can enable or disable a project wiki by following the instructions in -[Sharing and permissions](../settings/index.md#sharing-and-permissions). +[Sharing and permissions](../settings/index.md#configure-project-visibility-features-and-permissions). Administrators for self-managed GitLab installs can [configure additional wiki settings](../../../administration/wikis/index.md). diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index bfc83aa22f5..83cab819f54 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -59,7 +59,7 @@ To explore project topics: The **Projects** page shows list of topics sorted by the number of associated projects. To view projects associated with a topic, select a topic from the list. -You can assign topics to a project on the [Project Settings page](settings/index.md#topics). +You can assign topics to a project on the [Project Settings page](settings/index.md#assign-topics-to-a-project). If you're an instance administrator, you can administer all project topics from the [Admin Area's Topics page](../admin_area/index.md#administering-topics). @@ -73,7 +73,7 @@ To create a project in GitLab: - Create a [blank project](#create-a-blank-project). - Create a project from a: - [built-in template](#create-a-project-from-a-built-in-template). - - [custom template](#create-a-project-from-a-custom-template). + - [custom template](#create-a-project-from-a-custom-template). - [HIPAA audit protocol template](#create-a-project-from-the-hipaa-audit-protocol-template). - [Import a project](../../user/project/import/index.md) from a different repository. Contact your GitLab administrator if this option is not available. @@ -115,7 +115,7 @@ Built-in templates are sourced from the following groups: - [`project-templates`](https://gitlab.com/gitlab-org/project-templates) - [`pages`](https://gitlab.com/pages) -Anyone can contribute a built-in template by following [these steps](https://about.gitlab.com/community/contribute/project-templates/). +Anyone can [contribute a built-in template](../../development/project_templates.md). To create a project from a built-in template: @@ -336,6 +336,29 @@ To view the activity of a project: 1. On the left sidebar, select **Project information > Activity**. 1. Select a tab to view the type of project activity. +## Search in projects + +You can search through your projects. + +1. On the top bar, select **Menu**. +1. In **Search your projects**, type the project name. + +GitLab filters as you type. + +You can also look for the projects you [starred](#star-a-project) (**Starred projects**). + +You can **Explore** all public and internal projects available in GitLab.com, from which you can filter by visibility, +through **Trending**, best rated with **Most stars**, or **All** of them. + +You can sort projects by: + +- Name +- Created date +- Updated date +- Owner + +You can also choose to hide or show archived projects. + ## Leave a project If you leave a project, you are no longer a project @@ -484,5 +507,5 @@ download starts, the `insteadOf` configuration sends the traffic to the secondar - [Import a project](../../user/project/import/index.md). - [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md). - [Fork a project](repository/forking_workflow.md#creating-a-fork). -- [Adjust project visibility and access levels](settings/index.md#sharing-and-permissions). +- [Adjust project visibility and access levels](settings/index.md#configure-project-visibility-features-and-permissions). - [Limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names) diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index 5435a9d027c..075c9b6154b 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -1,5 +1,5 @@ --- -stage: Enablement +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/engineering/ux/technical-writing/#assignments" type: reference @@ -9,27 +9,23 @@ type: reference > Moved to GitLab Premium in 13.9. -NOTE: -This is the user documentation. To configure the Advanced Search, -visit the [administrator documentation](../../integration/elasticsearch.md). -Advanced Search is enabled in GitLab.com. +Advanced Search uses Elasticsearch for faster, more advanced search across the entire +GitLab instance. -GitLab Advanced Search expands on the Basic Search with an additional set of -features for faster, more advanced searches across the entire GitLab instance -when searching in: +Use Advanced Search when searching in: - Projects - Issues - Merge requests - Milestones -- Epics -- Comments +- Users +- Epics (when searching in a group only) - Code +- Comments - Commits -- Users - Wiki (except [group wikis](../project/wiki/group.md)) -The Advanced Search can be useful in various scenarios: +Advanced Search can be useful in various scenarios: - **Faster searches:** Advanced Search is based on Elasticsearch, which is a purpose-built full @@ -46,6 +42,13 @@ The Advanced Search can be useful in various scenarios: may be connected to each other, so your developers need to instantly search throughout the GitLab instance and find the code they search for. +## Configuring Advanced Search + +For self-managed GitLab instances, an administrator must +[configure Advanced Search](../../integration/advanced_search/elasticsearch.md). + +On GitLab.com, Advanced Search is enabled. + ## Advanced Search syntax See the documentation on [Advanced Search syntax](global_search/advanced_search_syntax.md). @@ -93,7 +96,7 @@ doesn't return any results for searches considered abusive according to the foll - Searches with less than 2 characters. - Searches with any term greater than 100 characters. URL search terms have a maximum of 200 characters. -- Searches with a stop word as the only term (ie: "the", "and", "if", etc.). +- Searches with a stop word as the only term (for example, "the", "and", "if", etc.). - Searches with a `group_id` or `project_id` parameter that is not completely numeric. - Searches with a `repository_ref` or `project_ref` parameter that has special characters not allowed by [Git refname](https://git-scm.com/docs/git-check-ref-format). - Searches with a `scope` that is unknown. diff --git a/doc/user/search/global_search/advanced_search_syntax.md b/doc/user/search/global_search/advanced_search_syntax.md index 3aa016f0bff..9daa7afd6de 100644 --- a/doc/user/search/global_search/advanced_search_syntax.md +++ b/doc/user/search/global_search/advanced_search_syntax.md @@ -1,5 +1,5 @@ --- -stage: Enablement +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/engineering/ux/technical-writing/#assignments --- @@ -18,7 +18,7 @@ Advanced Search searches default project branches only. ## General search -<!-- markdownlint-disable --> +<!-- markdownlint-disable --> | Use | Description | Example | |-----|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------| @@ -33,7 +33,7 @@ Advanced Search searches default project branches only. | Use | Description | Example | |--------------|---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| -| `filename:` | File name | [`filename:*spec.rb`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=filename%3A*spec.rb&group_id=9970&project_id=278964) | +| `filename:` | Filename | [`filename:*spec.rb`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=filename%3A*spec.rb&group_id=9970&project_id=278964) | | `path:` | Repository location | [`path:spec/workers/`](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=path%3Aspec%2Fworkers&snippets=) | | `extension:` | File extension, without the `.` | [`extension:js`](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=extension%3Ajs&snippets=) | | `blob:` | Git object ID | [`blob:998707*`](https://gitlab.com/search?snippets=false&scope=blobs&repository_ref=&search=blob%3A998707*&group_id=9970) | diff --git a/doc/user/search/img/basic_search_results.png b/doc/user/search/img/basic_search_results.png Binary files differdeleted file mode 100644 index 52aa2e3fe6c..00000000000 --- a/doc/user/search/img/basic_search_results.png +++ /dev/null diff --git a/doc/user/search/img/basic_search_results_v15_1.png b/doc/user/search/img/basic_search_results_v15_1.png Binary files differnew file mode 100644 index 00000000000..b85627c9b95 --- /dev/null +++ b/doc/user/search/img/basic_search_results_v15_1.png diff --git a/doc/user/search/img/basic_search_v14_4.png b/doc/user/search/img/basic_search_v14_4.png Binary files differdeleted file mode 100644 index 86aab68f1f0..00000000000 --- a/doc/user/search/img/basic_search_v14_4.png +++ /dev/null diff --git a/doc/user/search/img/basic_search_v15_1.png b/doc/user/search/img/basic_search_v15_1.png Binary files differnew file mode 100644 index 00000000000..069d62ca80c --- /dev/null +++ b/doc/user/search/img/basic_search_v15_1.png diff --git a/doc/user/search/img/code_search_git_blame_v14_9.png b/doc/user/search/img/code_search_git_blame_v14_9.png Binary files differdeleted file mode 100644 index eb8d14de4a4..00000000000 --- a/doc/user/search/img/code_search_git_blame_v14_9.png +++ /dev/null diff --git a/doc/user/search/img/code_search_git_blame_v15_1.png b/doc/user/search/img/code_search_git_blame_v15_1.png Binary files differnew file mode 100644 index 00000000000..e61ee5993c2 --- /dev/null +++ b/doc/user/search/img/code_search_git_blame_v15_1.png diff --git a/doc/user/search/img/dashboard_links_v14_6.png b/doc/user/search/img/dashboard_links_v14_6.png Binary files differdeleted file mode 100644 index 52ae39d9d1a..00000000000 --- a/doc/user/search/img/dashboard_links_v14_6.png +++ /dev/null diff --git a/doc/user/search/img/issues_mrs_shortcut_v14_6.png b/doc/user/search/img/issues_mrs_shortcut_v14_6.png Binary files differdeleted file mode 100644 index 52753eb8fc7..00000000000 --- a/doc/user/search/img/issues_mrs_shortcut_v14_6.png +++ /dev/null diff --git a/doc/user/search/img/multiple_assignees.png b/doc/user/search/img/multiple_assignees.png Binary files differdeleted file mode 100644 index 5c46f3dda46..00000000000 --- a/doc/user/search/img/multiple_assignees.png +++ /dev/null diff --git a/doc/user/search/img/search_issues_board.png b/doc/user/search/img/search_issues_board.png Binary files differdeleted file mode 100644 index 84048ae6a02..00000000000 --- a/doc/user/search/img/search_issues_board.png +++ /dev/null diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 171d8a63d2d..76a85b55585 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -1,80 +1,82 @@ --- -stage: Create -group: Editor +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/engineering/ux/technical-writing/#assignments --- # Searching in GitLab **(FREE)** -## Search issues and merge requests +GitLab has two types of searches available: _basic_ and _advanced_. -To search through issues and merge requests in multiple projects, on the top bar, select the **Issues** or **Merge requests** links. +Both types of search are the same, except when you are searching through code. -The numbers indicate how many issues, merge requests, and to-do items are assigned to you: +- When you use basic search to search code, your search includes one project at a time. +- When you use [advanced search](advanced_search.md) to search code, your search includes all projects at once. - +## Basic search + +Use basic search to find: + +- Projects +- Issues +- Merge requests +- Milestones +- Users +- Epics (when searching in a group only) +- Code +- Comments +- Commits +- Wiki + +## Perform a search + +To start a search, type your search query in the search bar on the top-right of the screen. +You must type at least two characters. + + + +After the results are displayed, you can modify the search, select a different type of data to +search, or choose a specific group or project. + + + +## Search in code + +To search through code or other documents in a project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, in the search field, type the string you want to search for. +1. Press **Enter**. + +Code search shows only the first result in the file. -- **{issues}** **Issues**: Issues assigned to you. -- **{merge-request-open}** **Merge requests**: Open [merge requests](../project/merge_requests/index.md). - Select the icon to show a dropdown list of merge request filters: - - [Attention requests](../project/merge_requests/index.md#request-attention-to-a-merge-request) (**{attention-solid}**) for you. - - [Review requests](../project/merge_requests/reviews/index.md) for you. - - Merge requests assigned to you. -- **{todo-done}** **To-do items**: The [to-do items](../todos.md) assigned to you. +To search across all of GitLab, ask your administrator to enable [advanced search](advanced_search.md). -You can search through **Open**, **Closed**, or **All** issues. +### View Git blame from code search -You can also filter the results using the search and filter field, as described in -[Filter issue and merge request lists](#filter-issue-and-merge-request-lists). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327052) in GitLab 14.7. -### Issues and MRs assigned to you or created by you +After you find search results, you can view who made the last change to the line +where the results were found. -GitLab shows shortcuts to issues and merge requests created by you or assigned to you -in the search field in the upper right corner: +1. From the code search result, hover over the line number. +1. On the left, select **View blame**. - +  -### Filter issue and merge request lists +## Search for a SHA -> - Filtering by epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195704) in GitLab 12.9. -> - Filtering by child epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9029) in GitLab 13.0. -> - Filtering by iterations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6. -> - Filtering by iterations was moved from GitLab Ultimate to GitLab Premium in 13.9. -> - Filtering by type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322755) in GitLab 13.10 [with a flag](../../administration/feature_flags.md) named `vue_issues_list`. Disabled by default. -> - Filtering by type was [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/322755) in GitLab 14.10. -> - Filtering by attention request was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343528) in GitLab 14.10 [with a flag](../../administration/feature_flags.md) named `mr_attention_requests`. Disabled by default. +You can search for a commit SHA. -Follow these steps to filter the **Issues** and **Merge requests** list pages in projects and -groups: +1. On the top bar, select **Menu > Projects** and find your project. +1. On the top bar, in the search field, type the SHA. -1. Select **Search or filter results...**. -1. In the dropdown list that appears, select the attribute you wish to filter by: - - Assignee - - [Attention requests](../project/merge_requests/index.md#request-attention-to-a-merge-request) - - Author - - Confidential - - [Epic and child Epic](../group/epics/index.md) (available only for the group the Epic was created, not for [higher group levels](https://gitlab.com/gitlab-org/gitlab/-/issues/233729)). - - [Iteration](../group/iterations/index.md) - - [Label](../project/labels.md) - - [Milestone](../project/milestones/index.md) - - My-reaction - - Release - - Type - - Weight - - Search for this text -1. Select or type the operator to use for filtering the attribute. The following operators are - available: - - `=`: Is - - `!=`: Is not ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18059) in GitLab 12.7) -1. Enter the text to [filter the attribute by](#filters-autocomplete). - You can filter some attributes by **None** or **Any**. -1. Repeat this process to filter by multiple attributes. Multiple attributes are joined by a logical - `AND`. +If a single result is returned, GitLab redirects to the commit result +and gives you the option to return to the search results page. -GitLab displays the results on-screen, but you can also -[retrieve them as an RSS feed](#retrieve-search-results-as-feed). + -### Searching for specific terms +## Searching for specific terms You can filter issues and merge requests by specific terms included in titles or descriptions. @@ -87,7 +89,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. -### Retrieve search results as feed +## Retrieve search results as feed > Feeds for merge requests were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66336) in GitLab 14.3. @@ -96,92 +98,19 @@ RSS feed of search results: 1. Go to your project's page. 1. On the left sidebar, select **Issues** or **Merge requests**. -1. Build your search query as described in [Filter issue and merge request lists](#filter-issue-and-merge-request-lists). +1. Perform a search. 1. Select the feed symbol **{rss}** to display the results as an RSS feed in Atom format. The URL of the result contains both a feed token, and your search query. You can add this URL to your feed reader. -### Filtering by ID - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39908) in GitLab 12.1. - -You can filter the **Issues** list to individual instances by their ID. For example, enter filter `#10` to return only issue 10. The same applies to the **Merge requests** list. Enter filter `#30` to return only merge request 30. - - - -### Filtering merge requests by approvers **(PREMIUM)** - -> Moved to GitLab Premium in 13.9. - -To filter merge requests by an individual eligible approver ([Codeowner](../project/code_owners.md)), you can type (or select from -the dropdown list) **Approver** and select the user. - - - -### Filtering merge requests by "approved by" **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30335) in GitLab 13.0. -> - Moved to GitLab Premium in 13.9. - -To filter merge requests already approved by a specific individual, you can type (or select from -the dropdown list) **Approved-By** and select the user. - - - -### Filtering merge requests by reviewer - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47605) in GitLab 13.7. - -To filter review requested merge requests for a specific individual, you can type (or select from -the dropdown list) **Reviewer** and select the user. - -### Filtering merge requests by environment or deployment date - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44041) in GitLab 13.6. - -To filter merge requests by deployment data, such as the environment or a date, -you can type (or select from the dropdown list) the following: - -- Environment -- Deployed-before -- Deployed-after - -NOTE: -Projects using a [fast-forward merge method](../project/merge_requests/fast_forward_merge.md) -do not return results, as this method does not create a merge commit. - -When filtering by an environment, a dropdown list presents all environments that -you can choose from: - - - -When filtering by `Deployed-before` or `Deployed-after`, the date refers to when -the deployment to an environment (triggered by the merge commit) completed successfully. -You must enter the deploy date manually. Deploy dates -use the format `YYYY-MM-DD`, and must be quoted if you wish to specify -both a date and time (`"YYYY-MM-DD HH:MM"`): - - - -## Filters autocomplete - -GitLab provides many filters across many pages (issues, merge requests, epics, -and pipelines among others) which you can use to narrow down your search. When -using the filter functionality, you can start typing characters to bring up -relevant users or other attributes. - -For performance optimization, there is a requirement of a minimum of three -characters to begin your search. To search for issues with the assignee `Simone Presley`, -you must type at least `Sim` before autocomplete displays results. - ## Search history Search history is available for issues and merge requests, and is stored locally in your browser. To run a search from history: 1. In the top menu, select **Issues** or **Merge requests**. -1. To the left of the search bar, click **Recent searches**, and select a search from the list. +1. To the left of the search bar, select **Recent searches**, and select a search from the list. ## Removing search filters @@ -189,61 +118,6 @@ Individual filters can be removed by clicking on the filter's (x) button or back To delete filter tokens one at a time, the <kbd>⌥</kbd> (Mac) / <kbd>Control</kbd> + <kbd>⌫</kbd> keyboard combination can be used. -## Filtering with multiple filters of the same type - -Some filters can be added multiple times. These include but are not limited to assignees and labels. When you filter with these multiple filters of the same type, the `AND` logic is applied. For example, if you were filtering `assignee:@sam assignee:@sarah`, your results include only entries whereby the assignees are assigned to both Sam and Sarah are returned. - - - -## To-Do List - -You can search your [To-Do List](../todos.md) by "to do" and "done". -You can filter to-do items per project, author, type, and action. -Also, you can sort them by [**Label priority**](../../user/project/labels.md#set-label-priority), -**Last created**, and **Oldest created**. - -## Projects - -You can search through your projects from the top bar, by selecting **Menu > Projects**. -On the field **Filter by name**, type the project or group name you want to find, and GitLab -filters them for you as you type. - -You can also look for the projects you [starred](../project/working_with_projects.md#star-a-project) (**Starred projects**). -You can **Explore** all public and internal projects available in GitLab.com, from which you can filter by visibility, -through **Trending**, best rated with **Most stars**, or **All** of them. - -You can also sort them by: - -- Name -- Created date -- Updated date -- Owner - -You can also choose to hide or show archived projects. - -## Groups - -Similarly to [projects search](#projects), you can search through your groups from -the left menu, by clicking the menu bar, then **Groups**. - -On the field **Filter by name**, type the group name you want to find, and GitLab -filters them for you as you type. - -You can also **Explore** all public and internal groups available in GitLab.com, -and sort them by **Name**, **Last created**, **Oldest created**, or **Updated date**. - -## Issue boards - -From an [issue board](../../user/project/issue_board.md), you can filter issues by **Author**, **Assignee**, **Milestone**, and **Labels**. -You can also filter them by name (issue title), from the field **Filter by name**, which is loaded as you type. - -To search for issues to add to lists present in your issue board, select -the button **Add issues** on the top-right of your screen, opening a modal window from which -you can, besides filtering them by **Name**, **Author**, **Assignee**, **Milestone**, -and **Labels**, select multiple issues to add to a list of your choice: - - - ## Autocomplete suggestions In the search bar, you can view autocomplete suggestions for: @@ -257,63 +131,6 @@ In the search bar, you can view autocomplete suggestions for: - Recently viewed epics (try and type some word from the title of a recently viewed epic) - [GitLab Flavored Markdown](../markdown.md#gitlab-specific-references) (GLFM) for issues in a project (try and type a GLFM reference for an issue) -## Basic search - -The Basic search in GitLab enables you to search -across the entire GitLab instance, in a group, or in a single project. Basic search is -backed by the database and allows searching in: - -- Projects -- Issues -- Merge requests -- Milestones -- Users -- Epics (Group only) -- Code (Project only) -- Comments (Project only) -- Commits (Project only) -- Wiki (Project only) - -To start a search, type into the search bar on the top-right of the screen. You can always search -in all GitLab and may also see the options to search in a group or project if you are in the -group or project dashboard. - - - -After the results are returned, you can modify the search, select a different type of data to -search, or choose a specific group or project. - - - -### Code search - -To search through code or other documents in a single project, you can use -the search field on the top-right of your screen while the project page is open. -Code search shows only the first result in the file. - -#### Git blame from code search **(FREE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327052) in GitLab 14.7. - -You can access Git blame from any line that returned a result from the code search: - - - -### SHA search - -You can quickly access a commit from the project dashboard by entering the SHA -into the search field on the top right of the screen. If a single result is found, you are -redirected to the commit result and given the option to return to the search results page. - - - -## Advanced Search **(PREMIUM)** - -Leverage Elasticsearch for faster, more advanced code search across your entire -GitLab instance. - -[Learn how to use the Advanced Search.](advanced_search.md) - ## Search settings > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292941) in GitLab 13.8 [with a flag](../../administration/feature_flags.md) named `search_settings_in_page`. Disabled by default. diff --git a/doc/user/tasks.md b/doc/user/tasks.md index 8be7fbca213..fc49661c61c 100644 --- a/doc/user/tasks.md +++ b/doc/user/tasks.md @@ -8,10 +8,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334812) in GitLab 14.5 [with a flag](../administration/feature_flags.md) named `work_items`. Disabled by default. -WARNING: -Tasks are in [**Alpha**](../policy/alpha-beta-support.md#alpha-features). Current implementation does not have any API requests and works with mocked data. -For the latest updates, check the [Tasks Roadmap](https://gitlab.com/groups/gitlab-org/-/epics/7103). - 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`. @@ -31,7 +27,26 @@ to work items and adding custom work item types, visit [epic 6033](https://gitlab.com/groups/gitlab-org/-/epics/6033) or [Plan direction page](https://about.gitlab.com/direction/plan/). -## View a task +## Create a task + +To create a task: + +1. In an issue description, create a [task list](markdown.md#task-lists). +1. Hover over a task item and select **Convert to work item** (**{doc-new}**). +1. Confirm or edit the title, and select **Create work item**. + +## Edit a task + +To edit a task: + +1. In the issue description, view the task links. +1. Select a link. The task is displayed. + - To edit the description, select **Edit**, then select **Save**. + - To edit the title or state, make your changes, then click outside the field. The changes are saved automatically. + +## Delete a task + +To delete a task: -The only way to view a task is to open it with a deep link, -for example: `/<group_name>/<project_name>/-/work_item/1`. +1. In the issue description, select the task. +1. From the options menu (**{ellipsis_v}**), select **Delete work item**. diff --git a/doc/user/todos.md b/doc/user/todos.md index c261d719da0..0a120100c57 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -23,6 +23,14 @@ To access your To-Do List: On the top bar, in the top right, select To-Do List (**{task-done}**). +## Search the To-Do List + +You can search your To-Do List by `to do` and `done`. + +You can filter to-do items per project, author, type, and action. +Also, you can sort them by [**Label priority**](project/labels.md#set-label-priority), +**Last created**, and **Oldest created**. + ## Actions that create to-do items Many to-do items are created automatically. diff --git a/doc/user/upgrade_email_bypass.md b/doc/user/upgrade_email_bypass.md index 8cd9a47f3e6..6401828270d 100644 --- a/doc/user/upgrade_email_bypass.md +++ b/doc/user/upgrade_email_bypass.md @@ -27,7 +27,7 @@ sent within five minutes, with a link for users to re-confirm the subject email ## Do the confirmation emails expire? -The links in these re-confirmation emails expire after one day by default. Users who click an expired link are asked to request a new re-confirmation email. Any user can request a new re-confirmation email from `http://gitlab.example.com/users/confirmation/new`. +The links in these re-confirmation emails expire after one day by default. Users who select an expired link are asked to request a new re-confirmation email. Any user can request a new re-confirmation email from `http://gitlab.example.com/users/confirmation/new`. ## Generate a list of affected users diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index 21aa93d3f8b..84c98a60917 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -32,7 +32,7 @@ You can view storage usage for your project or [namespace](../user/group/#namesp The statistics are displayed. Select any title to view details. The information on this page is updated every 90 minutes. -If your namespace shows `N/A`, push a commit to any project in the +If your namespace shows `'Not applicable.'`, push a commit to any project in the namespace to recalculate the storage. ## Storage usage statistics @@ -50,7 +50,7 @@ The following storage usage statistics are available to a maintainer: ## Manage your storage usage -You can use several methods to manage and reduce your usage for some storage types. +You can use several methods to manage and reduce your usage for some storage types. For more information, see the following pages: |
