diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-06-16 18:25:58 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-06-16 18:25:58 +0000 |
| commit | a5f4bba440d7f9ea47046a0a561d49adf0a1e6d4 (patch) | |
| tree | fb69158581673816a8cd895f9d352dcb3c678b1e /doc/user | |
| parent | d16b2e8639e99961de6ddc93909f3bb5c1445ba1 (diff) | |
| download | gitlab-ce-14.0.0-rc42.tar.gz | |
Add latest changes from gitlab-org/gitlab@14-0-stable-eev14.0.0-rc42
Diffstat (limited to 'doc/user')
317 files changed, 4543 insertions, 4828 deletions
diff --git a/doc/user/abuse_reports.md b/doc/user/abuse_reports.md index 66b7c3c6ac7..c84c3541366 100644 --- a/doc/user/abuse_reports.md +++ b/doc/user/abuse_reports.md @@ -1,5 +1,6 @@ --- redirect_to: 'report_abuse.md' +remove_date: '2021-07-21' --- This file was moved to [another location](report_abuse.md). diff --git a/doc/user/admin_area/abuse_reports.md b/doc/user/admin_area/abuse_reports.md index 5424d4d2cb4..4bfa277fc9f 100644 --- a/doc/user/admin_area/abuse_reports.md +++ b/doc/user/admin_area/abuse_reports.md @@ -1,5 +1,6 @@ --- redirect_to: 'review_abuse_reports.md' +remove_date: '2021-07-21' --- This file was moved to [another location](review_abuse_reports.md). diff --git a/doc/user/admin_area/activating_deactivating_users.md b/doc/user/admin_area/activating_deactivating_users.md index cafc7caf981..e89c42b34ba 100644 --- a/doc/user/admin_area/activating_deactivating_users.md +++ b/doc/user/admin_area/activating_deactivating_users.md @@ -1,5 +1,6 @@ --- redirect_to: 'moderate_users.md' +remove_date: '2021-08-12' --- This document was moved to [another location](moderate_users.md). diff --git a/doc/user/admin_area/analytics/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index b13faf2bb3e..6ca5e5034bf 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -1,21 +1,23 @@ --- -stage: none -group: unassigned +stage: Manage +group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# DevOps Report +# DevOps Report **(FREE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30469) in GitLab 9.3. -> - [Renamed from Conversational Development Index](https://gitlab.com/gitlab-org/gitlab/-/issues/20976) in GitLab 12.6. +> [Renamed from Conversational Development Index](https://gitlab.com/gitlab-org/gitlab/-/issues/20976) in GitLab 12.6. The DevOps Report gives you an overview of your entire instance's adoption of [Concurrent DevOps](https://about.gitlab.com/topics/concurrent-devops/) from planning to monitoring. -To see DevOps Report, go to **Admin Area > Analytics > DevOps Report**. +To see DevOps Report: -## DevOps Score **(FREE)** +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Analytics > DevOps Report**. + +## DevOps Score NOTE: Your GitLab instance's [usage ping](../settings/usage_statistics.md#usage-ping) must be activated in order to use this feature. @@ -34,21 +36,30 @@ Usage ping data is aggregated on GitLab servers for analysis. Your usage information is **not sent** to any other GitLab instances. If you have just started using GitLab, it may take a few weeks for data to be collected before this feature is available. -## DevOps Adoption **(ULTIMATE)** +## DevOps Adoption **(ULTIMATE SELF)** -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247112) in GitLab 13.7 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247112) in GitLab 13.7 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) +> - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59267) in GitLab 14.0. +> - Enabled on GitLab.com. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-or-enable-devops-adoption). **(ULTIMATE SELF)** The DevOps Adoption tab shows you which groups within your organization are using the most essential features of GitLab: -- Issues -- Merge Requests -- Approvals -- Runners -- Pipelines -- Deploys -- Scanning - -Buttons to manage your groups appear in the DevOps Adoption section of the page. +- Dev + - Issues + - Merge Requests + - Approvals + - Code owners +- Sec + - Scans +- Ops + - Runners + - Pipelines + - Deployments + +When managing groups in the UI, you can add your groups with the **Add group to table** +button, in the top right hand section the page. DevOps Adoption allows you to: @@ -56,20 +67,22 @@ DevOps Adoption allows you to: - Identify specific groups that are lagging in their adoption of GitLab so you can help them along in their DevOps journey. - Find the groups that have adopted certain features and can provide guidance to other groups on how to use those features. + + ### Disable or enable DevOps Adoption -DevOps Adoption is deployed behind a feature flag that is **disabled by default**. +DevOps Adoption is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to enable it. +can opt to disable it. -To enable it: +To disable it: ```ruby -Feature.enable(:devops_adoption_feature) +Feature.disable(:devops_adoption_feature) ``` -To disable it: +To reenable it: ```ruby -Feature.disable(:devops_adoption_feature) +Feature.enable(:devops_adoption_feature) ``` diff --git a/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_0.png b/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_0.png Binary files differnew file mode 100644 index 00000000000..f4170b2938c --- /dev/null +++ b/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_0.png diff --git a/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6_a.png b/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6_a.png Binary files differindex 210c5c2609a..bd02065556c 100644 --- a/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6_a.png +++ b/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6_a.png diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md index bea22745e7b..465b26d516c 100644 --- a/doc/user/admin_area/analytics/index.md +++ b/doc/user/admin_area/analytics/index.md @@ -1,16 +1,19 @@ --- -stage: none -group: unassigned +stage: Manage +group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Instance-level analytics +# Instance-level analytics **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41416) in GitLab 11.2. -Administrators have access to instance-wide analytics, as shown in **Admin Area > Analytics**. +Administrators have access to instance-wide analytics: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Analytics**. There are several kinds of statistics: -- [DevOps Report](dev_ops_report.md): Provides an overview of your entire instance's feature usage. **(FREE)** -- [Usage Trends](usage_trends.md): Shows how much data your instance contains, and how that is changing. **(FREE)** +- [DevOps Report](dev_ops_report.md): Provides an overview of your entire instance's feature usage. +- [Usage Trends](usage_trends.md): Shows how much data your instance contains, and how that is changing. diff --git a/doc/user/admin_area/analytics/usage_trends.md b/doc/user/admin_area/analytics/usage_trends.md index 7fb23f702a4..49c81b1a965 100644 --- a/doc/user/admin_area/analytics/usage_trends.md +++ b/doc/user/admin_area/analytics/usage_trends.md @@ -4,7 +4,7 @@ group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Usage Trends **(FREE)** +# Usage Trends **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235754) in GitLab 13.5 behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46962) in GitLab 13.6. diff --git a/doc/user/admin_area/analytics/user_cohorts.md b/doc/user/admin_area/analytics/user_cohorts.md index ca5dff85757..b906f9b8fa6 100644 --- a/doc/user/admin_area/analytics/user_cohorts.md +++ b/doc/user/admin_area/analytics/user_cohorts.md @@ -1,5 +1,6 @@ --- redirect_to: '../user_cohorts.md' +remove_date: '2021-06-01' --- This document was moved to [another location](../user_cohorts.md). diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index 0d72f09dfd9..d7f0b7e3854 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -9,8 +9,10 @@ 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 -of GitLab. These settings are accessed from the **Admin Area** in the **Appearance** -section. +of GitLab. To access these settings: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > Appearance**. ## Navigation bar diff --git a/doc/user/admin_area/approving_users.md b/doc/user/admin_area/approving_users.md index 2b3b90cb1a4..3d9722035d5 100644 --- a/doc/user/admin_area/approving_users.md +++ b/doc/user/admin_area/approving_users.md @@ -34,7 +34,8 @@ sign in. To view user sign ups pending approval: -1. Go to **Admin Area > Overview > Users**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Overview > Users**. 1. Select the **Pending approval** tab. ## Approve or reject a user sign up @@ -43,9 +44,10 @@ A user sign up pending approval can be approved or rejected from the Admin Area. To approve or reject a user sign up: -1. Go to **Admin Area > Overview > Users**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Overview > Users**. 1. Select the **Pending approval** tab. -1. In the user's row select settings (**{settings}**). +1. In the user's row, select settings (**{settings}**). 1. Select **Approve** or **Reject**. Approving a user: diff --git a/doc/user/admin_area/blocking_unblocking_users.md b/doc/user/admin_area/blocking_unblocking_users.md index cafc7caf981..e89c42b34ba 100644 --- a/doc/user/admin_area/blocking_unblocking_users.md +++ b/doc/user/admin_area/blocking_unblocking_users.md @@ -1,5 +1,6 @@ --- redirect_to: 'moderate_users.md' +remove_date: '2021-08-12' --- This document was moved to [another location](moderate_users.md). diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index 67a89f896ff..93e6aa9bb16 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -5,21 +5,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Broadcast Messages **(FREE SELF)** +# Broadcast messages **(FREE SELF)** GitLab can display broadcast messages to all users of a GitLab instance. There are two types of broadcast messages: -- banners -- notifications +- Banners +- Notifications -You can style a message's content using the `a` and `br` HTML tags. The `br` tag inserts a line break. The `a` HTML tag accepts `class` and `style` attributes with the following CSS properties: - -- `color` -- `border` -- `background` -- `padding` -- `margin` -- `text-decoration` +Broadcast messages can be managed using the [broadcast messages API](../../api/broadcast_messages.md). ## Banners @@ -36,6 +29,8 @@ remote: ... ``` +If more than one banner is active at one time, they are displayed in a stack in order of creation. + ## Notifications Notifications are shown on the bottom right of a page and can contain placeholders. A placeholder is replaced with an attribute of the active user. Placeholders must be surrounded by curly braces, for example `{{name}}`. @@ -51,65 +46,63 @@ If the user is not signed in, user related values are empty.  -Broadcast messages can be managed using the [broadcast messages API](../../api/broadcast_messages.md). - -NOTE: -If more than one banner message is active at one time, they are displayed in a stack in order of creation. -If more than one notification message is active at one time, only the newest is shown. +If more than one notification is active at one time, only the newest is shown. -## Adding a broadcast message +## Add a broadcast message -To display messages to users on your GitLab instance, add broadcast message. +To display messages to users on your GitLab instance, add a broadcast message. To add a broadcast message: -1. Navigate to the **Admin Area > Messages** page. -1. Add the text for the message to the **Message** field. Markdown and emoji are supported. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Messages**. +1. Add the text for the message to the **Message** field. You can style a message's content using Markdown, emoji, and the `a` and `br` HTML tags. + The `br` tag inserts a line break. The `a` HTML tag accepts `class` and `style` attributes with the following CSS properties: + - `color` + - `border` + - `background` + - `padding` + - `margin` + - `text-decoration` 1. Select one of the suggested background colors, or add the hex code of a different color. The default color is orange. +1. Select the **Dismissable** checkbox to enable users to dismiss the broadcast message. 1. If required, add a **Target Path** to only show the broadcast message on URLs matching that path. You can use the wildcard character `*` to match multiple URLs, for example `mygroup/myproject*`. 1. Select a date for the message to start and end. -1. Click the **Add broadcast message** button. - -NOTE: -When scoping messages, you can't use preceding or trailing slashes. For example, -instead of `/mygroup/myproject/`, you must use `mygroup/myproject`. A fix is -[planned for GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59482). +1. Select **Add broadcast message**. NOTE: The **Background color** field expects the value to be a hexadecimal code because the form uses the [color_field](https://api.rubyonrails.org/v6.0.3.4/classes/ActionView/Helpers/FormHelper.html#method-i-color_field) helper method, which generates the proper HTML to render. -NOTE: -Once a broadcast message has expired, it is no longer displayed in the UI but is still listed in the -list of broadcast messages. User can also dismiss a broadcast message if the option **Dismissable** is set. +When a broadcast message expires, it no longer displays in the user interface but is still listed in the +list of broadcast messages. -## Editing a broadcast message +## Edit a broadcast message -If changes are required to a broadcast message, they can be edited. +If you need to make changes to a broadcast message, you can edit it. To edit a broadcast message: -1. Navigate to the **Admin Area > Messages** page. -1. From the list of broadcast messages, click the appropriate button to edit the message. -1. After making the required changes, click the **Update broadcast message** button. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Messages**. +1. From the list of broadcast messages, select the edit button for the message. +1. After making the required changes, select **Update broadcast message**. -NOTE: Expired messages can be made active again by changing their end date. -## Deleting a broadcast message +## Delete a broadcast message -Broadcast messages that are no longer required can be deleted. +If you no longer require a broadcast message, you can delete it. +You can delete a broadcast message while it's active. To delete a broadcast message: -1. Navigate to the **Admin Area > Messages** page. -1. From the list of broadcast messages, click the appropriate button to delete the message. - -Once deleted, the broadcast message is removed from the list of broadcast messages. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Messages**. +1. From the list of broadcast messages, select the delete button for the message. -NOTE: -Broadcast messages can be deleted while active. +When a broadcast message is deleted, it's removed from the list of broadcast messages. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index c47dc7d70f5..dfb37cb8646 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -9,7 +9,9 @@ type: howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20912) in GitLab 12.6. -GitLab administrators are responsible for the overall security of their instance. To assist, GitLab provides a Credentials inventory to keep track of all the credentials that can be used to access their self-managed instance. +GitLab administrators are responsible for the overall security of their instance. To assist, GitLab +provides a Credentials inventory to keep track of all the credentials that can be used to access +their self-managed instance. Using Credentials inventory, you can see all the personal access tokens (PAT), SSH keys, and GPG keys that exist in your GitLab instance. In addition, you can [revoke](#revoke-a-users-personal-access-token) @@ -21,7 +23,10 @@ and [delete](#delete-a-users-ssh-key) and see: - When they expire. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214809) in GitLab 13.2. - When they were revoked. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214809) in GitLab 13.2. -To access the Credentials inventory, navigate to **Admin Area > Credentials**. +To access the Credentials inventory: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Credentials**. The following is an example of the Credentials inventory page: diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index b4b33df37bf..6cf3c5bbd7d 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -30,12 +30,12 @@ see [Custom group-level project templates](../group/custom_project_templates.md) ## Configuring GitLab administrators can configure a GitLab group that serves as template -source for an entire GitLab instance by: +source for an entire GitLab instance: -1. Navigating to **Admin Area > Settings > Templates**. -1. Expanding **Custom project templates**. -1. Selecting a group to use. -1. Pressing **Save changes**. +1. On the top bar, navigate to **Menu > Admin > Settings > Templates**. +1. Expand **Custom project templates**. +1. Select a group to use. +1. Select **Save changes**. NOTE: Projects below subgroups of the template group are **not** supported. diff --git a/doc/user/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md index 32756ab4780..37fdb3ae195 100644 --- a/doc/user/admin_area/diff_limits.md +++ b/doc/user/admin_area/diff_limits.md @@ -10,28 +10,34 @@ type: reference You can set a maximum size for display of diff files (patches). For details about diff files, [view changes between files](../project/merge_requests/changes.md). +Read more about the [built-in limits for merge requests and diffs](../../administration/instance_limits.md#merge-requests). -## Maximum diff patch size +## Configure diff limits -Diff files which exceed this value are presented as 'too large' and cannot -be expandable. Instead of an expandable view, a link to the blob view is -shown. +WARNING: +These settings are experimental. An increased maximum increases resource +consumption of your instance. Keep this in mind when adjusting the maximum. + +To speed the loading time of merge request views and branch comparison views +on your instance, you can configure three instance-level maximum values for diffs: + +- **Maximum diff patch size**: The total size, in bytes, of the entire diff. +- **Maximum diff files**: The total number of files changed in a diff. +- **Maximum diff files**: The total number of files changed in a diff. The default value is 1000. +- **Maximum diff lines**: The total number of lines changed in a diff. The default value is 50,000. -Patches greater than 10% of this size are automatically collapsed, and a -link to expand the diff is presented. -This affects merge requests and branch comparison views. +When a diff reaches 10% of any of these values, the files are shown in a +collapsed view, with a link to expand the diff. Diffs that exceed any of the +set values are presented as **Too large** are cannot be expanded in the UI. -To set the maximum diff patch size: +To configure these values: -1. Go to the Admin Area (**{admin}**) and select **Settings > General**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. 1. Expand **Diff limits**. 1. Enter a value for **Maximum diff patch size**, measured in bytes. 1. Select **Save changes**. -WARNING: -This setting is experimental. An increased maximum increases resource -consumption of your instance. Keep this in mind when adjusting the maximum. - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/admin_area/geo_nodes.md b/doc/user/admin_area/geo_nodes.md index e5132ef4e96..32b1555c33d 100644 --- a/doc/user/admin_area/geo_nodes.md +++ b/doc/user/admin_area/geo_nodes.md @@ -82,7 +82,7 @@ In GitLab 11.11, **secondary** nodes can use identical external URLs as long as a unique `name` is set for each Geo node. The `gitlab.rb` setting `gitlab_rails['geo_node_name']` must: -- Be set for each GitLab instance that runs `unicorn`, `sidekiq`, or `geo_logcursor`. +- Be set for each GitLab instance that runs `puma`, `sidekiq`, or `geo_logcursor`. - Match a Geo node name. The load balancer must use sticky sessions in order to avoid authentication diff --git a/doc/user/admin_area/img/cohorts_v13_9_a.png b/doc/user/admin_area/img/cohorts_v13_9_a.png Binary files differindex a891b5b12c2..1a4590290b9 100644 --- a/doc/user/admin_area/img/cohorts_v13_9_a.png +++ b/doc/user/admin_area/img/cohorts_v13_9_a.png diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 5d1fde1c767..2e4a8261c63 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -7,12 +7,13 @@ type: reference # GitLab Admin Area **(FREE SELF)** -The Admin Area provides a web UI for administering some features of GitLab self-managed instances. +The Admin Area provides a web UI to manage and configure some features of GitLab +self-managed instances. If you are an Admin user, you can access the Admin Area +by visiting `/admin` on your self-managed instance. You can also access it through +the UI: -To access the Admin Area, either: - -- Click the Admin Area icon (**{admin}**). -- Visit `/admin` on your self-managed instance. +- GitLab versions 14.0 and later: on the top bar, select **Menu >** **{admin}** **Admin**. +- GitLab versions 13.12 and earlier: on the top bar, select the Admin Area icon (**{admin}**). NOTE: Only admin users can access the Admin Area. @@ -35,7 +36,7 @@ The Admin Area is made up of the following sections: | **{location-dot}** Geo | Configure and maintain [Geo nodes](geo_nodes.md). | | **{key}** Deploy keys | Create instance-wide [SSH deploy keys](../project/deploy_keys/index.md). | | **{lock}** Credentials | View [credentials](credentials_inventory.md) that can be used to access your instance. | -| **{template}** Service Templates | Create [service templates](../project/integrations/services_templates.md) for projects. | +| **{template}** Integrations | Manage [instance-level default settings](settings/project_integration_management.md) for a project integration. | | **{labels}** Labels | Create and maintain [labels](labels.md) for your GitLab instance. | | **{appearance}** Appearance | Customize [GitLab appearance](appearance.md). | | **{settings}** Settings | Modify the [settings](settings/index.md) for your GitLab instance. | @@ -46,7 +47,7 @@ The Dashboard provides statistics and system information about the GitLab instan To access the Dashboard, either: -- Click the Admin Area icon (**{admin}**). +- On the top bar, select **Menu >** **{admin}** **Admin**. - Visit `/admin` on your self-managed instance. The Dashboard is the default view of the Admin Area, and is made up of the following sections: @@ -68,10 +69,12 @@ The following topics document the **Overview** section of the Admin Area. You can administer all projects in the GitLab instance from the Admin Area's Projects page. -To access the Projects page, go to **Admin Area > Overview > Projects**. +To access the Projects page: -Click the **All**, **Private**, **Internal**, or **Public** tab to list only projects of that -criteria. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Overview > Projects**. +1. Select the **All**, **Private**, **Internal**, or **Public** tab to list only + projects of that criteria. By default, all projects are listed, in reverse order of when they were last updated. For each project, the following information is listed: @@ -106,9 +109,10 @@ You can combine the filter options. For example, to list only public projects wi ### Administering Users -You can administer all users in the GitLab instance from the Admin Area's Users page. +You can administer all users in the GitLab instance from the Admin Area's Users page: -To access the Users page, go to **Admin Area > Overview > Users**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Overview > Users**. To list users matching a specific criteria, click on one of the following tabs on the **Users** page: @@ -151,7 +155,11 @@ An administrator can "impersonate" any other user, including other administrator This allows the administrator to "see what the user sees," and take actions on behalf of the user. You can impersonate a user in the following ways: -- Through the UI, by selecting **Admin Area > Overview > Users > Select a user > Impersonate**. +- Through the UI: + 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. In the left sidebar, select **Overview > Users**. + 1. From the list of users, select a user. + 1. Select **Impersonate**. - With the API, using [impersonation tokens](../../api/README.md#impersonation-tokens). All impersonation activities are [captured with audit events](../../administration/audit_events.md#impersonation-data). @@ -197,7 +205,10 @@ The [Cohorts](user_cohorts.md) tab displays the monthly cohorts of new users and You can administer all groups in the GitLab instance from the Admin Area's Groups page. -To access the Groups page, go to **Admin Area > Overview > Groups**. +To access the Groups page: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In 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 @@ -216,11 +227,12 @@ To [Create a new group](../group/index.md#create-a-group) click **New group**. You can administer all jobs in the GitLab instance from the Admin Area's Jobs page. -To access the Jobs page, go to **Admin Area > Overview > Jobs**. +To access the Jobs page: -All jobs are listed, in descending order of job ID. - -Click the **All** tab to list all jobs. Click the **Pending**, **Running**, or **Finished** tab to list only jobs of that status. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Overview > Jobs**. All jobs are listed, in descending order of job ID. +1. Click the **All** tab to list all jobs. Click the **Pending**, **Running**, or **Finished** + tab to list only jobs of that status. For each job, the following details are listed: @@ -241,7 +253,10 @@ For each job, the following details are listed: You can administer all runners in the GitLab instance from the Admin Area's **Runners** page. See [GitLab Runner](https://docs.gitlab.com/runner/) for more information. -To access the **Runners** page, go to **Admin Area > Overview > Runners**. +To access the **Runners** page: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Overview > Runners**. The **Runners** page features: @@ -287,7 +302,10 @@ You can also edit, pause, or remove each runner. You can list all Gitaly servers in the GitLab instance from the Admin Area's **Gitaly Servers** page. For more details, see [Gitaly](../../administration/gitaly/index.md). -To access the **Gitaly Servers** page, go to **Admin Area > Overview > Gitaly Servers**. +To access the **Gitaly Servers** page: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Overview > Gitaly Servers**. For each Gitaly server, the following details are listed: @@ -344,7 +362,7 @@ For multi-node systems we recommend ingesting the logs into services like Elasti |:------------------------|:---------| | `application.log` | GitLab user activity | | `git_json.log` | Failed GitLab interaction with Git repositories | -| `production.log` | Requests received from Unicorn, and the actions taken to serve those requests | +| `production.log` | Requests received from Puma, and the actions taken to serve those requests | | `sidekiq.log` | Background jobs | | `repocheck.log` | Repository activity | | `integrations_json.log` | Activity between GitLab and integrated systems | diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index 73472fcf67a..58876b87576 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -34,13 +34,13 @@ is locked. The first time you visit your GitLab EE installation signed in as an administrator, you should see a note urging you to upload a license with a link that takes you -to **Admin Area > License**. +to the **License** area. -Otherwise, you can: +Otherwise, to manually go to the **License** area: -1. Navigate manually to the **Admin Area** by selecting the wrench (**{admin}**) icon in the top menu. +1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. Navigate to the **License** tab, and select **Upload New License**. +1. On the left sidebar, select **License**, and select **Upload New License**. - *If you've received a `.gitlab-license` file:* 1. Download the license file to your local machine. @@ -113,9 +113,9 @@ before this occurs. To remove a license from a self-managed instance: -1. In the top navigation bar, click the **{admin}** wrench icon to navigate to the [Admin Area](index.md). -1. Click **License** in the left sidebar. -1. Click **Remove License**. +1. On the top bar, select **Menu >** **{admin}** **Admin** to go to the [Admin Area](index.md). +1. On the left sidebar, select **License**. +1. Select **Remove license**. ## License history diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index fadccadaf2c..b221b1d51a7 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -15,8 +15,8 @@ project level. To enable merge request approval rules for an instance: -1. Navigate to **Admin Area >** **{push-rules}** **Push Rules** and expand **Merge -requests approvals**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **{push-rules}** **Push Rules**, and expand **Merge request (MR) approvals**. 1. Set the required rule. 1. Click **Save changes**. diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index c04003dd75f..71e72cc630c 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -21,9 +21,10 @@ administrators can choose to block the user. Users can be blocked [via an abuse report](review_abuse_reports.md#blocking-users), or directly from the Admin Area. To do this: -1. Navigate to **Admin Area > Overview > Users**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Overview > Users**. 1. Select a user. -1. Under the **Account** tab, click **Block user**. +1. Under the **Account** tab, select **Block user**. A blocked user: @@ -43,10 +44,11 @@ A blocked user does not consume a [seat](../../subscriptions/self_managed/index. A blocked user can be unblocked from the Admin Area. To do this: -1. Navigate to **Admin Area > Overview > Users**. -1. Click on the **Blocked** tab. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Overview > Users**. +1. Select on the **Blocked** tab. 1. Select a user. -1. Under the **Account** tab, click **Unblock user**. +1. Under the **Account** tab, select **Unblock user**. Users can also be unblocked using the [GitLab API](../../api/users.md#unblock-user). @@ -74,16 +76,17 @@ with the following differences: A deactivated user: - Cannot access Git repositories or the API. -- Will not receive any notifications from GitLab. -- Will not be able to use [slash commands](../../integration/slash_commands.md). +- Does not receive any notifications from GitLab. +- Does not be able to use [slash commands](../../integration/slash_commands.md). Personal projects, and group and user history of the deactivated user are left intact. A user can be deactivated from the Admin Area. To do this: -1. Navigate to **Admin Area > Overview > Users**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Overview > Users**. 1. Select a user. -1. Under the **Account** tab, click **Deactivate user**. +1. Under the **Account** tab, select **Deactivate user**. Please note that for the deactivation option to be visible to an admin, the user: @@ -95,6 +98,23 @@ Users can also be deactivated using the [GitLab API](../../api/users.md#deactiva NOTE: A deactivated user does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). +### Automatically deactivate dormant users + +> [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: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > General**. +1. Expand the **Account and limit** section. +1. Under **Dormant users**, check **Deactivate dormant users after 90 days of inactivity**. +1. Select **Save changes**. + +When this feature is enabled, GitLab runs a job once a day to deactivate the dormant users. + +A maximum of 100,000 users can be deactivated per day. + ### Activating a user > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4. @@ -103,10 +123,11 @@ A deactivated user can be activated from the Admin Area. To do this: -1. Navigate to **Admin Area > Overview > Users**. -1. Click on the **Deactivated** tab. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Overview > Users**. +1. Select the **Deactivated** tab. 1. Select a user. -1. Under the **Account** tab, click **Activate user**. +1. Under the **Account** tab, select **Activate user**. Users can also be activated using the [GitLab API](../../api/users.md#activate-user). @@ -134,23 +155,25 @@ To completely block a user, administrators can choose to ban the user. Users can be banned using the Admin Area. To do this: -1. Navigate to **Admin Area > Overview > Users**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Overview > Users**. 1. Select a user. -1. Under the **Account** tab, click **Ban user**. +1. Under the **Account** tab, select **Ban user**. NOTE: This feature is a work in progress. Currently, banning a user only blocks them and does not hide their comments or issues. -This functionality will be implemented in follow up issues. +This functionality is planned to be implemented in follow up issues. ### Unban a user A banned user can be unbanned using the Admin Area. To do this: -1. Navigate to **Admin Area > Overview > Users**. -1. Click on the **Banned** tab. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Overview > Users**. +1. Select the **Banned** tab. 1. Select a user. -1. Under the **Account** tab, click **Unban user**. +1. Under the **Account** tab, select **Unban user**. NOTE: Unbanning a user changes the user's state to active and consumes a diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 2d4683911fb..a3e46ea6225 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -143,9 +143,11 @@ This check is being exempt from Rack Attack. NOTE: Access token has been deprecated in GitLab 9.4 in favor of [IP whitelist](#ip-whitelist). -An access token needs to be provided while accessing the probe endpoints. The current -accepted token can be found under the **Admin Area > Monitoring > Health check** -(`admin/health_check`) page of your GitLab instance. +An access token needs to be provided while accessing the probe endpoints. You can +find the current accepted token in the user interface: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Monitoring > Health Check**. (`admin/health_check`)  diff --git a/doc/user/admin_area/review_abuse_reports.md b/doc/user/admin_area/review_abuse_reports.md index 12a3111c6f3..a179eb70453 100644 --- a/doc/user/admin_area/review_abuse_reports.md +++ b/doc/user/admin_area/review_abuse_reports.md @@ -16,7 +16,8 @@ reports in the Admin Area. To receive notifications of new abuse reports by e-mail, follow these steps: -1. Select **Admin Area > Settings > Reporting**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > Reporting**. 1. Expand the **Abuse reports** section. 1. Provide an email address. @@ -30,7 +31,10 @@ documentation](../report_abuse.md). ## Resolving abuse reports -To access abuse reports, go to **Admin Area > Abuse Reports**. +To access abuse reports: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Abuse Reports**. There are 3 ways to resolve an abuse report, with a button for each method: diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md index 8bc5a035e2a..f2a849e1894 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -9,18 +9,22 @@ type: reference ## Default projects limit -You can change the default maximum number of projects that users can create in their personal namespace. -Navigate to **Admin Area > Settings > General**, then expand **Account and Limit**. -You can increase or decrease that `Default projects limit` value. +You can change the default maximum number of projects that users can create in their personal namespace: -- If you set `Default projects limit` to 0, users are not allowed to create projects - in their users personal namespace. However, projects can still be created in a group. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. Increase or decrease that **Default projects limit** value. + +If you set **Default projects limit** to 0, users are not allowed to create projects +in their users personal namespace. However, projects can still be created in a group. ## Max attachment size -You can change the maximum file size for attachments in comments and replies in GitLab. -Navigate to **Admin Area > Settings > General**, then expand **Account and Limit**. -From here, you can increase or decrease by changing the value in `Maximum attachment size (MB)`. +You can change the maximum file size for attachments in comments and replies in GitLab: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. Increase or decrease by changing the value in **Maximum attachment size (MB)**. NOTE: If you choose a size larger than the configured value for the web server, @@ -29,15 +33,26 @@ details. ## Max push size -You can change the maximum push size for your repository. -Navigate to **Admin Area > Settings > General**, then expand **Account and Limit**. -From here, you can increase or decrease by changing the value in `Maximum push size (MB)`. +You can change the maximum push size for your repository: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. Increase or decrease by changing the value in **Maximum push size (MB)**. + +NOTE: +When you [add files to a repository](../../project/repository/web_editor.md#create-a-file) +through the web UI, the maximum **attachment** size is the limiting factor, +because the [web server](../../../development/architecture.md#components) +must receive the file before GitLab can generate the commit. +Use [Git LFS](../../../topics/git/lfs/index.md) to add large files to a repository. ## Max import size -You can change the maximum file size for imports in GitLab. -Navigate to **Admin Area > Settings > General**, then expand **Account and Limit**. -From here, you can increase or decrease by changing the value in `Maximum import size (MB)`. +You can change the maximum file size for imports in GitLab: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. Increase or decrease by changing the value in **Maximum import size (MB)**. NOTE: If you choose a size larger than the configured value for the web server, @@ -55,7 +70,8 @@ A prefix can help you identify PATs visually, as well as with automation tools. Only a GitLab administrator can set the prefix, which is a global setting applied to any PAT generated in the system by any user: -1. Navigate to **Admin Area > Settings > General**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In 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**. @@ -97,7 +113,8 @@ These settings can be found in: 1. Fill in the **Repository size limit (MB)** field in the **Naming, visibility** section. 1. Click **Save changes**. - GitLab global settings: - 1. From the Dashboard, navigate to **Admin Area > Settings > General**. + 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. In 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**. @@ -143,7 +160,8 @@ GitLab administrators can choose to customize the session duration (in minutes) To set a limit on how long these sessions are valid: -1. Navigate to **Admin Area > Settings > General**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In 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**. @@ -167,7 +185,8 @@ there are no restrictions. To set a lifetime on how long personal access tokens are valid: -1. Navigate to **Admin Area > Settings > General**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Maximum allowable lifetime for personal access tokens (days)** field. 1. Click **Save changes**. @@ -182,22 +201,19 @@ Once a lifetime for personal access tokens is set, GitLab: ## Enforce SSH key expiration **(ULTIMATE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250480) in GitLab 13.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250480) in GitLab 13.9. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/320970) in GitLab 14.0. -By default, expired SSH keys **can still be used**. +By default, expired SSH keys **are not usable**. -WARNING: -Allowing use of expired SSH keys by default is deprecated and scheduled to change in GitLab 14.0. +To allow the use of expired SSH keys: -To prevent the use of expired SSH keys: - -1. Navigate to **Admin Area > Settings > General**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. -1. Select the **Enforce SSH key expiration** checkbox. - -Enforcing SSH key expiration immediately disables all expired SSH keys. +1. Uncheck the **Enforce SSH key expiration** checkbox. -For more information, see the following issue on [SSH key expiration](https://gitlab.com/gitlab-org/gitlab/-/issues/320970). +Disabling SSH key expiration immediately enables all expired SSH keys. ## Do not enforce Personal Access Token expiration **(ULTIMATE SELF)** @@ -209,7 +225,8 @@ You can allow the use of expired PATs with the following steps: To do this: -1. Navigate to **Admin Area > Settings > General**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. 1. Expand the **Account and limit** section. 1. Uncheck the **Enforce personal access token expiration** checkbox. @@ -221,8 +238,9 @@ To maintain integrity of user details in [Audit Events](../../../administration/ To do this: -1. Navigate to **Admin Area > Settings > General**, then expand **Account and Limit**. -1. Check the **Prevent users from changing their profile name** checkbox. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**, then expand **Account and limit**. +1. Select the **Prevent users from changing their profile name** checkbox. NOTE: When this ability is disabled, GitLab administrators can still use the diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index decd204dbe5..ffe969a6799 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -1,22 +1,22 @@ --- stage: Verify -group: Continuous Integration +group: Pipeline Execution 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 --- -# Continuous Integration and Deployment Admin settings **(FREE SELF)** +# Continuous Integration and Deployment Admin Area settings **(FREE SELF)** -In this area, you will find settings for Auto DevOps, runners, and job artifacts. -You can find it in the [Admin Area](index.md) by navigating to -**Admin Area > Settings > CI/CD**. +The [Admin Area](index.md) has the instance settings for Auto DevOps, runners, and +job artifacts. -## Auto DevOps **(FREE SELF)** +## Auto DevOps To enable (or disable) [Auto DevOps](../../../topics/autodevops/index.md) for all projects: -1. Go to **Admin Area > Settings > CI/CD**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > CI/CD**. 1. Check (or uncheck to disable) the box that says **Default to Auto DevOps pipeline for all projects**. 1. Optionally, set up the [Auto DevOps base domain](../../../topics/autodevops/index.md#auto-devops-base-domain) which is used for Auto Deploy and Auto Review Apps. @@ -28,6 +28,25 @@ From now on, every existing project and newly created ones that don't have a If you want to disable it for a specific project, you can do so in [its settings](../../../topics/autodevops/index.md#enable-or-disable-auto-devops). +## Shared runner details + +To display details about the instance's shared runners in all projects' +runner settings: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Continuous Integration and Deployment**. +1. Enter your shared runner details in the **Shared runner details** field. + +You can use [Markdown](../../markdown.md) for improved formatting. To see the rendered +details: + +1. On the top bar, select **Menu > Project** and select any group or project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Runners**. + + + ## Maximum artifacts size **(FREE SELF)** The maximum size of the [job artifacts](../../../administration/job_artifacts.md) @@ -45,9 +64,10 @@ To change it at the: - Instance level: - 1. Go to **Admin Area > Settings > CI/CD**. - 1. Change the value of maximum artifacts size (in MB). - 1. Click **Save changes** for the changes to take effect. + 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the left sidebar, select **Settings > CI/CD**. + 1. Change the value of maximum artifacts size (in MB). + 1. Click **Save changes** for the changes to take effect. - Group level (this overrides the instance setting): @@ -64,14 +84,15 @@ To change it at the: NOTE: The setting at all levels is only available to GitLab administrators. -## Default artifacts expiration **(FREE SELF)** +## Default artifacts expiration The default expiration time of the [job artifacts](../../../administration/job_artifacts.md) can be set in the Admin Area of your GitLab instance. The syntax of duration is described in [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) and the default value is `30 days`. -1. Go to **Admin Area > Settings > CI/CD**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > CI/CD**. 1. Change the value of default expiration time. 1. Click **Save changes** for the changes to take effect. @@ -85,12 +106,13 @@ be updated for artifacts created before this setting was changed. The administrator may need to manually search for and expire previously-created artifacts, as described in the [troubleshooting documentation](../../../administration/troubleshooting/gitlab_rails_cheat_sheet.md#remove-artifacts-more-than-a-week-old). -## Keep the latest artifacts for all jobs in the latest successful pipelines **(CORE ONLY)** +## Keep the latest artifacts for all jobs in the latest successful pipelines -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50889) in GitLab Core 13.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50889) in GitLab 13.9. -When enabled (default), the artifacts for the most recent pipeline for a ref are -locked against deletion and kept regardless of the expiry time. +When enabled (default), the artifacts of the most recent pipeline for each Git ref +([branches and tags](https://git-scm.com/book/en/v2/Git-Internals-Git-References)) +are locked against deletion and kept regardless of the expiry time. When disabled, the latest artifacts for any **new** successful or fixed pipelines are allowed to expire. @@ -100,7 +122,8 @@ If disabled at the instance level, you cannot enable this per-project. To disable the setting: -1. Go to **Admin Area > Settings > CI/CD**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. Clear the **Keep the latest artifacts for all jobs in the latest successful pipelines** checkbox. 1. Click **Save changes** @@ -121,18 +144,17 @@ shared runners per month. Setting this to `0` (default value) grants unlimited pipeline minutes. While build limits are stored as minutes, the counting is done in seconds. Usage resets on the first day of each month. On GitLab.com, the quota is calculated based on your -[subscription plan](https://about.gitlab.com/pricing/#gitlab-com). +[subscription plan](../../../subscriptions/gitlab_com/index.md#ci-pipeline-minutes). To change the pipelines minutes quota: -1. Go to **Admin Area > Settings > CI/CD**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. In the **Pipeline minutes quota** box, enter the maximum number of minutes. 1. Click **Save changes** for the changes to take effect. ---- - -While the setting in the Admin Area has a global effect, as an admin you can +While the setting in the Admin Area has a global effect, as an administrator you can also change each group's pipeline minutes quota to override the global value. 1. Navigate to the **Admin Area > Overview > Groups** and hit the **Edit** @@ -140,8 +162,8 @@ also change each group's pipeline minutes quota to override the global value. 1. In the **Pipeline Minutes Quota** box, enter the maximum number of minutes. 1. Click **Save changes** for the changes to take effect. -Once saved, you can see the build quota in the group admin view. -The quota can also be viewed in the project admin view if shared runners +Once saved, you can see the build quota in the group settings. +The quota can also be viewed in the project settings if shared runners are enabled.  @@ -151,7 +173,7 @@ a group in the **Usage Quotas** page available to the group page settings list.  -## Archive jobs **(FREE SELF)** +## Archive jobs Archiving jobs is useful for reducing the CI/CD footprint on the system by removing some of the capabilities of the jobs (metadata needed to run the job), @@ -159,29 +181,40 @@ but persisting the traces and artifacts for auditing purposes. To set the duration for which the jobs are considered as old and expired: -1. Go to **Admin Area > Settings > CI/CD**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > CI/CD**. 1. Expand the **Continuous Integration and Deployment** section. 1. Set the value of **Archive jobs**. 1. Hit **Save changes** for the changes to take effect. -Once that time passes, the jobs are archived and no longer able to be +After that time passes, the jobs are archived and no longer able to be retried. Make it empty to never expire jobs. It has to be no less than 1 day, for example: <code>15 days</code>, <code>1 month</code>, <code>2 years</code>. As of June 22, 2020 the [value is set](../../gitlab_com/index.md#gitlab-cicd) to 3 months on GitLab.com. Jobs created before that date were archived after September 22, 2020. -## Default CI configuration path +## Protect CI/CD variables by default + +To set all new [CI/CD variables](../../../ci/variables/README.md) as +[protected](../../../ci/variables/README.md#protect-a-cicd-variable) by default: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > CI/CD**. +1. Select **Protect CI/CD variables by default**. + +## Default CI/CD configuration file > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18073) in GitLab 12.5. -The default CI configuration file path for new projects can be set in the Admin -Area of your GitLab instance (`.gitlab-ci.yml` if not set): +The default CI/CD configuration file and path for new projects can be set in the Admin Area +of your GitLab instance (`.gitlab-ci.yml` if not set): -1. Go to **Admin Area > Settings > CI/CD**. -1. Input the new path in the **Default CI configuration path** field. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > CI/CD**. +1. Input the new file and path in the **Default CI/CD configuration file** field. 1. Hit **Save changes** for the changes to take effect. -It is also possible to specify a [custom CI/CD configuration path for a specific project](../../../ci/pipelines/settings.md#custom-cicd-configuration-path). +It is also possible to specify a [custom CI/CD configuration file for a specific project](../../../ci/pipelines/settings.md#custom-cicd-configuration-file). ## Required pipeline configuration **(PREMIUM SELF)** @@ -191,30 +224,33 @@ This feature is being re-evaluated in favor of a different We recommend that users who haven't yet implemented this feature wait for the new solution. -GitLab administrators can force a pipeline configuration to run on every -pipeline. +You can set a [CI/CD template](../../../ci/examples/README.md#cicd-templates) +as a required pipeline configuration for all projects on a GitLab instance. You can +use a template from: -The configuration applies to all pipelines for a GitLab instance and is -sourced from: +- The default CI/CD templates. +- A custom template stored in an [instance template repository](instance_template_repository.md). -- The [instance template repository](instance_template_repository.md). -- GitLab-supplied configuration. + NOTE: + When you use a configuration defined in an instance template repository, + nested [`include:`](../../../ci/yaml/README.md#include) keywords + (including `include:file`, `include:local`, `include:remote`, and `include:template`) + [do not work](https://gitlab.com/gitlab-org/gitlab/-/issues/35345). -NOTE: -When you use a configuration defined in an instance template repository, -nested [`include:`](../../../ci/yaml/README.md#include) keywords -(including `include:file`, `include:local`, `include:remote`, and `include:template`) -[do not work](https://gitlab.com/gitlab-org/gitlab/-/issues/35345). +The project CI/CD configuration merges into the required pipeline configuration when +a pipeline runs. The merged configuration is the same as if the required pipeline configuration +added the project configuration with the [`include` keyword](../../../ci/yaml/README.md#include). +To view a project's full merged configuration, [View the merged YAML](../../../ci/pipeline_editor/index.md#view-expanded-configuration) +in the pipeline editor. -To set required pipeline configuration: +To select a CI/CD template for the required pipeline configuration: -1. Go to **Admin Area > Settings > CI/CD**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > CI/CD**. 1. Expand the **Required pipeline configuration** section. -1. Select the required configuration from the provided dropdown. +1. Select a CI/CD template from the dropdown. 1. Click **Save changes**. - - ## Package Registry configuration ### npm Forwarding **(PREMIUM SELF)** @@ -223,7 +259,8 @@ GitLab administrators can disable the forwarding of npm requests to [npmjs.com]( To disable it: -1. Go to **Admin Area > Settings > CI/CD**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Uncheck **Enable forwarding of npm package requests to npmjs.org**. 1. Click **Save changes**. @@ -236,7 +273,8 @@ GitLab administrators can adjust the maximum allowed file size for each package To set the maximum file size: -1. Go to **Admin Area > Settings > CI/CD**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > CI/CD**. 1. Expand the **Package Registry** section. 1. Find the package type you would like to adjust. 1. Enter the maximum file size, in bytes. diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 0975b93f98f..205dd77c1bf 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -39,10 +39,11 @@ the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/logs ## Configuration -The external authorization service can be enabled by an administrator on the GitLab -**Admin Area > Settings > General** page: +The external authorization service can be enabled by an administrator: - +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**: +  The available required properties are: diff --git a/doc/user/admin_area/settings/floc.md b/doc/user/admin_area/settings/floc.md index e1d10727341..31a626478ed 100644 --- a/doc/user/admin_area/settings/floc.md +++ b/doc/user/admin_area/settings/floc.md @@ -22,7 +22,8 @@ Permissions-Policy: interest-cohort=() To enable it: -1. Go to the Admin Area (**{admin}**) and select **Settings > General**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. 1. Expand **Federated Learning of Cohorts**. 1. Check the box. 1. Click **Save changes**. diff --git a/doc/user/admin_area/settings/gitaly_timeouts.md b/doc/user/admin_area/settings/gitaly_timeouts.md index 3570634b9ba..6f488efee11 100644 --- a/doc/user/admin_area/settings/gitaly_timeouts.md +++ b/doc/user/admin_area/settings/gitaly_timeouts.md @@ -12,7 +12,8 @@ configured to make sure that long running Gitaly calls don't needlessly take up To access Gitaly timeout settings: -1. Go to **Admin Area > Settings > Preferences**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > Preferences**. 1. Expand the **Gitaly** section. ## Available timeouts @@ -20,9 +21,8 @@ To access Gitaly timeout settings: The following timeouts can be modified: - **Default Timeout Period**. This timeout is the default for most Gitaly calls. It should be shorter than the - worker timeout that can be configured for [Puma](https://docs.gitlab.com/omnibus/settings/puma.html#puma-settings) - or [Unicorn](https://docs.gitlab.com/omnibus/settings/unicorn.html). Used to make sure that Gitaly - calls made within a web request cannot exceed the entire request timeout. + worker timeout that can be configured for [Puma](https://docs.gitlab.com/omnibus/settings/puma.html#puma-settings). + Used to make sure that Gitaly calls made within a web request cannot exceed the entire request timeout. Defaults to 55 seconds. - **Fast Timeout Period**. This is the timeout for very short Gitaly calls. Defaults to 10 seconds. diff --git a/doc/user/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md index 5739c3e4f10..d7c96c295f6 100644 --- a/doc/user/admin_area/settings/help_page.md +++ b/doc/user/admin_area/settings/help_page.md @@ -16,7 +16,8 @@ to go for help. You can customize and display this information on the GitLab ser You can add a help message, which is shown on the GitLab `/help` page (e.g., <https://gitlab.com/help>) in a new section at the top of the `/help` page: -1. Navigate to **Admin Area > Settings > Preferences**, then expand **Help page**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > Preferences**, then expand **Help page**. 1. Under **Help page text**, fill in the information you wish to display on `/help`. 1. Save your changes. You can now see the message on `/help`. @@ -25,7 +26,8 @@ You can add a help message, which is shown on the GitLab `/help` page (e.g., You can add a help message, which is shown on the GitLab login page in a new section titled `Need Help?`, located below the login page message: -1. Navigate to **Admin Area > Settings > Preferences**, then expand **Help page**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > Preferences**, then expand **Help page**. 1. Under **Help text**, fill in the information you wish to display on the login page.  diff --git a/doc/user/admin_area/settings/img/admin_required_pipeline.png b/doc/user/admin_area/settings/img/admin_required_pipeline.png Binary files differdeleted file mode 100644 index 501b1e3ba0a..00000000000 --- a/doc/user/admin_area/settings/img/admin_required_pipeline.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/continuous_integration_shared_runner_details_v14_0.png b/doc/user/admin_area/settings/img/continuous_integration_shared_runner_details_v14_0.png Binary files differnew file mode 100644 index 00000000000..d8bc3deccd4 --- /dev/null +++ b/doc/user/admin_area/settings/img/continuous_integration_shared_runner_details_v14_0.png diff --git a/doc/user/admin_area/settings/img/custom_sign_in_page_v13_6.png b/doc/user/admin_area/settings/img/custom_sign_in_page_v13_6.png Binary files differdeleted file mode 100644 index 5eb2134187a..00000000000 --- a/doc/user/admin_area/settings/img/custom_sign_in_page_v13_6.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/enforce_terms.png b/doc/user/admin_area/settings/img/enforce_terms.png Binary files differindex 3d93e1cc891..699e0e63ceb 100644 --- a/doc/user/admin_area/settings/img/enforce_terms.png +++ b/doc/user/admin_area/settings/img/enforce_terms.png diff --git a/doc/user/admin_area/settings/import_export_rate_limits.md b/doc/user/admin_area/settings/import_export_rate_limits.md index c6b965c18d3..12235bdb5ef 100644 --- a/doc/user/admin_area/settings/import_export_rate_limits.md +++ b/doc/user/admin_area/settings/import_export_rate_limits.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Project/Group Import/Export rate limits +# Project/group import/export rate limits **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35728) in GitLab 13.2. @@ -23,7 +23,7 @@ per minute per user basis: All rate limits are: -- Configurable at **(admin)** **Admin Area > Settings > Network > Import/Export Rate Limits** +- Configurable through the top bar at **Menu > Admin > Settings > Network > Import/Export Rate Limits** - Applied per minute per user - Not applied per IP address - Active by default. To disable, set the option to `0` diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index a66502d9466..6a5af09358d 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -9,25 +9,28 @@ type: index As an administrator of a GitLab self-managed instance, you can manage the behavior of your deployment. To do so, select **Admin Area > Settings**. -The admin area is not accessible on GitLab.com, and settings can only be changed by the +The Admin Area is not accessible on GitLab.com, and settings can only be changed by the GitLab.com administrators. See the [GitLab.com settings](../../gitlab_com/index.md) documentation for all current settings and limits on the GitLab.com instance. ## General -Access the default page for admin area settings by navigating to **Admin Area > Settings > General**: +To access the default page for Admin Area settings: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. | Option | Description | | ------ | ----------- | | [Visibility and access controls](visibility_and_access_controls.md) | Set default and restrict visibility levels. Configure import sources and Git access protocol. | -| [Account and limit](account_and_limit_settings.md) **(STARTER)** | Set projects and maximum size limits, session duration, user options, and check feature availability for namespace plan. | +| [Account and limit](account_and_limit_settings.md) | Set projects and maximum size limits, session duration, user options, and check feature availability for namespace plan. | | [Diff limits](../diff_limits.md) | Diff content limits. | | [Sign-up restrictions](sign_up_restrictions.md) | Configure the way a user creates a new account. | | [Sign in restrictions](sign_in_restrictions.md) | Set requirements for a user to sign in. Enable mandatory two-factor authentication. | | [Terms of Service and Privacy Policy](terms.md) | Include a Terms of Service agreement and Privacy Policy that all users must accept. | | [External Authentication](external_authorization.md#configuration) | External Classification Policy Authorization | | [Web terminal](../../../administration/integration/terminal.md#limiting-websocket-connection-time) | Set max session time for web terminal. | -| [Web IDE](../../project/web_ide/index.md#enabling-live-preview) | Manage Web IDE Features. | +| [Web IDE](../../project/web_ide/index.md#enable-live-preview) | Manage Web IDE features. | | [FLoC](floc.md) | Enable or disable [Federated Learning of Cohorts (FLoC)](https://en.wikipedia.org/wiki/Federated_Learning_of_Cohorts) tracking. | ## Integrations @@ -116,6 +119,11 @@ Access the default page for admin area settings by navigating to **Admin Area > | [Gitaly timeouts](gitaly_timeouts.md) | Configure Gitaly timeouts. | | Localization | [Default first day of the week](../../profile/preferences.md) and [Time tracking](../../project/time_tracking.md#limit-displayed-units-to-hours). | -NOTE: -You can change the [Default first day of the week](../../profile/preferences.md) for the entire GitLab instance -in the **Localization** section of **Admin Area > Settings > Preferences**. +### Default first day of the week + +You can change the [Default first day of the week](../../profile/preferences.md) +for the entire GitLab instance: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > Preferences**. +1. Scroll to the **Localization** section, and select your desired first day of the week. diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index 600d99934aa..c8a4c2866ca 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -17,12 +17,17 @@ while the project remains secure. ## Configuration -As an administrator, navigate to **Admin Area > Settings > Templates** and -select the project to serve as the custom template repository. +To select a project to serve as the custom template repository: - +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > Templates**. +1. Select the project: -After that, you can add custom templates to the selected repository and use them for the entire instance. +  + +1. Add custom templates to the selected repository. + +After you add templates, you can use them for the entire instance. They are available in the [Web Editor's dropdown](../../project/repository/web_editor.md#template-dropdowns) and through the [API settings](../../../api/settings.md). diff --git a/doc/user/admin_area/settings/package_registry_rate_limits.md b/doc/user/admin_area/settings/package_registry_rate_limits.md index 578b7cd1236..6e7b9b0da30 100644 --- a/doc/user/admin_area/settings/package_registry_rate_limits.md +++ b/doc/user/admin_area/settings/package_registry_rate_limits.md @@ -9,7 +9,8 @@ type: reference Rate limiting is a common technique used to improve the security and durability of a web application. For more details, see [Rate limits](../../../security/rate_limits.md). General user and -IP rate limits can be enforced in **Admin Area > Settings > Network > User and IP rate limits**. +IP rate limits can be enforced from the top bar at +**Menu > Admin > Settings > Network > User and IP rate limits**. For more details, see [User and IP rate limits](user_and_ip_rate_limits.md). With the [GitLab Package Registry](../../packages/package_registry/index.md), @@ -20,7 +21,7 @@ the [Packages API](../../../api/packages.md). When downloading such dependencies in downstream projects, many requests are made through the Packages API. You may therefore reach enforced user and IP rate limits. To address this issue, you can define specific rate limits for the Packages API in -**Admin Area > Settings > Network > Package Registry Rate Limits**: +**Menu > Admin > Settings > Network > Package Registry Rate Limits**: - Unauthenticated Packages API requests - Authenticated Packages API requests diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index b152787b23f..3140eecfa53 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -22,7 +22,8 @@ Only the complete settings for an integration can be inherited. Per-field inheri > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2137) in GitLab 13.3 for project-level integrations. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2543) in GitLab 13.6 for group-level integrations. -1. Navigate to **Admin Area > Settings > Integrations**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > Integrations**. 1. Select an integration. 1. Enter configuration details and click **Save changes**. @@ -53,7 +54,8 @@ integration on all non-configured groups and projects by default. ### Remove an instance-level default setting -1. Navigate to **Admin Area > Settings > Integrations**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > Integrations**. 1. Select an integration. 1. Click **Reset** and confirm. diff --git a/doc/user/admin_area/settings/push_event_activities_limit.md b/doc/user/admin_area/settings/push_event_activities_limit.md index 7032c1031a9..21e4f32ff8d 100644 --- a/doc/user/admin_area/settings/push_event_activities_limit.md +++ b/doc/user/admin_area/settings/push_event_activities_limit.md @@ -23,9 +23,14 @@ branches), only 1 bulk push event is created instead of 1,000 push events. This helps in maintaining good system performance and preventing spam on the activity feed. -This setting can be modified in **Admin Area > Settings > Network > Performance Optimization**. -This can also be configured via the [Application settings API](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls) -as `push_event_activities_limit`. The default value is 3, but it can be greater -than or equal 0. +To modify this setting: + +- In the Admin Area: + 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. In the left sidebar, select **Settings > Network**, then expand **Performance optimization**. +- Through the [Application settings API](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls) + as `push_event_activities_limit`. + +The default value is 3, but it can be greater than or equal 0.  diff --git a/doc/user/admin_area/settings/rate_limit_on_notes_creation.md b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md index 1997e6b5149..67a97d26b34 100644 --- a/doc/user/admin_area/settings/rate_limit_on_notes_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md @@ -28,5 +28,5 @@ The default value is `300`. Requests over the rate limit are logged into the `auth.log` file. For example, if you set a limit of 300, requests using the -[Projects::NotesController#create](https://gitlab.com/gitlab-org/gitlab/blob/master/app/controllers/projects/notes_controller.rb) +[Projects::NotesController#create](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/projects/notes_controller.rb) action exceeding a rate of 300 per minute are blocked. Access to the endpoint is allowed after one minute. diff --git a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md index a9b23b3dc50..24b69ba74c7 100644 --- a/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md +++ b/doc/user/admin_area/settings/rate_limits_on_raw_endpoints.md @@ -9,8 +9,11 @@ type: reference > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30829) in GitLab 12.2. -This setting allows you to rate limit the requests to raw endpoints, defaults to `300` requests per minute. -It can be modified in **Admin Area > Settings > Network > Performance Optimization**. +This setting defaults to `300` requests per minute, and allows you to rate limit the requests to raw endpoints: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > Network**. +1. Expand **Performance optimization**. For example, requests over `300` per minute to `https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/controllers/application_controller.rb` are blocked. Access to the raw file is released after 1 minute. diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 647f9332119..ecd259a345c 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -13,7 +13,8 @@ You can use **Sign-in restrictions** to customize authentication restrictions fo To access sign-in restriction settings: -1. Navigate to the **Admin Area > Settings > General**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. 1. Expand the **Sign-in restrictions** section. ## Password authentication enabled @@ -76,9 +77,9 @@ If necessary, you can disable **Admin Mode** as an administrator by using one of - [**Rails console**](../../../administration/operations/rails_console.md#starting-a-rails-console-session): ```ruby - ::Gitlab::CurrentSettings.update_attributes!(admin_mode: false) + ::Gitlab::CurrentSettings.update!(admin_mode: false) ``` - + ## Two-factor authentication When this feature is enabled, all users must use the [two-factor authentication](../../profile/account/two_factor_authentication.md). @@ -114,13 +115,14 @@ For example, if you include the following information in the noted text box: ```markdown # Custom sign-in text -To access this text box, navigate to Admin Area > Settings > General, and expand the "Sign-in restrictions" section. +To access this text box: + +1. On the top bar, select **Menu > Admin**. +1. In the left sidebar, select **Settings > General**, and expand the **Sign-in restrictions** section. ``` Your users see the **Custom sign-in text** when they navigate to the sign-in screen for your -GitLab instance: - - +GitLab instance. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index 0078db286a8..1098c7060f8 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -22,7 +22,8 @@ you do not expect public users to sign up for an account. To disable sign ups: -1. Go to **Admin Area > Settings > General** and expand **Sign-up restrictions**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. 1. Clear the **Sign-up enabled** checkbox, then select **Save changes**. ## Require administrator approval for new sign ups @@ -34,7 +35,8 @@ When this setting is enabled, any user visiting your GitLab domain and signing u To require administrator approval for new sign ups: -1. Go to **Admin Area > Settings > General** and expand **Sign-up restrictions**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. 1. Select the **Require admin approval for new sign-ups** checkbox, then select **Save changes**. In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/273258), if an administrator disables this setting, the users in pending approval state are @@ -47,7 +49,8 @@ their email address before they are allowed to sign in. To enforce confirmation of the email address used for new sign ups: -1. Go to **Admin Area > Settings > General** and expand **Sign-up restrictions**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. 1. Select the **Enable email restrictions for sign ups** checkbox, then select **Save changes**. ## User cap **(FREE SELF)** @@ -64,7 +67,8 @@ user cap, the users in pending approval state are automatically approved in a ba ### Set the user cap number -1. Go to **Admin Area > Settings > General**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Enter a number in **User cap**. 1. Select **Save changes**. @@ -73,7 +77,8 @@ New user sign ups are subject to the user cap restriction. ## Remove the user cap -1. Go to **Admin Area > Settings > General**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. 1. Expand **Sign-up restrictions**. 1. Remove the number from **User cap**. 1. Select **Save changes**. @@ -130,7 +135,8 @@ reduce the risk of malicious users creating spam accounts with disposable email To create an email domain allowlist or denylist: -1. Go to **Admin Area > Settings > General** and expand **Sign-up restrictions**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**, and expand **Sign-up restrictions**. 1. For the allowlist, you must enter the list manually. For the denylist, you can enter the list manually or upload a `.txt` file that contains list entries. diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index 3e0636ef7ac..46e85ffc9c0 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -7,7 +7,7 @@ type: reference # Enforce accepting Terms of Service **(FREE SELF)** -An admin can enforce acceptance of a terms of service and privacy policy. When this option is enabled, new and existing users must accept the terms. +An administrator can enforce acceptance of a terms of service and privacy policy. When this option is enabled, new and existing users must accept the terms. If configured, the Terms of Service page can be viewed via `https://your-instance.com/-/users/terms` at anytime. @@ -16,7 +16,8 @@ If configured, the Terms of Service page can be viewed via `https://your-instanc To enforce acceptance of a Terms of Service and Privacy Policy: 1. Log in to the GitLab instance as an admin user. -1. Go to **Admin Area > Settings > General**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. 1. Expand the **Terms of Service and Privacy Policy** section. 1. Check the **Require all users to accept Terms of Service and Privacy Policy when they access GitLab.** checkbox. diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index 59845a8d0d8..e7fa8b1dc40 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.md @@ -13,7 +13,11 @@ Within GitLab, we inform users of available third-party offers they might find v to enhance the development of their projects. An example is the Google Cloud Platform free credit for using [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/). -The display of third-party offers can be toggled in the **Admin Area > Settings** page. +To toggle the display of third-party offers: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings**, and expand **Third party offers**. +1. Select **Do not display offers from third parties within GitLab**. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index ada44115cec..b5a7ce318ff 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -10,8 +10,12 @@ type: reference GitLab Inc. periodically collects information about your instance in order to perform various actions. -All statistics are opt-out. You can enable/disable them in the -**Admin Area > Settings > Metrics and profiling** section **Usage statistics**. +All statistics are opt-out. To enable or disable them: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > Metrics and profiling**, and expand **Usage statistics**. +1. Enable or disable **Version check** and **Usage ping**. +1. Select **Save changes**. ## Network configuration @@ -40,8 +44,12 @@ This information is used, among other things, to identify to which versions patches must be backported, making sure active GitLab instances remain secure. -If you disable version check, this information isn't collected. Enable or -disable the version check in **Admin Area > Settings > Metrics and profiling > Usage statistics**. +If you disable version check, this information isn't collected. To enable or disable it: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > Metrics and profiling**, and expand **Usage statistics**. +1. Enable or disable **Version check**. +1. Select **Save changes**. ### Request flow example diff --git a/doc/user/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md index 9e64dd59a74..fdeda0cf451 100644 --- a/doc/user/admin_area/settings/user_and_ip_rate_limits.md +++ b/doc/user/admin_area/settings/user_and_ip_rate_limits.md @@ -11,20 +11,21 @@ Rate limiting is a common technique used to improve the security and durability of a web application. For more details, see [Rate limits](../../../security/rate_limits.md). -The following limits can be enforced in **Admin Area > Settings > Network > User and -IP rate limits**: +The following limits are disabled by default: - Unauthenticated requests - Authenticated API requests - Authenticated web requests -These limits are disabled by default. +To enforce any or all of them: -NOTE: -By default, all Git operations are first tried unauthenticated. Because of this, HTTP Git operations -may trigger the rate limits configured for unauthenticated requests. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > Network**, and expand **User and IP rate limits**: +  - + NOTE: + By default, all Git operations are first tried unauthenticated. Because of this, HTTP Git operations + may trigger the rate limits configured for unauthenticated requests. ## Response text 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 e335a9031d5..752856371bf 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -11,14 +11,18 @@ GitLab allows administrators to enforce specific controls. To access the visibility and access control options: -1. Sign in to GitLab as a user with Administrator [permissions](../../permissions.md). -1. Go to **Admin Area > Settings > General**. +1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. ## Default branch protection -This global option defines the branch protection that applies to every repository's default branch. [Branch protection](../../project/protected_branches.md) specifies which roles can push to branches and which roles can delete -branches. In this case _Default_ refers to a repository's default branch, which in most cases is `master`. +This global option defines the branch protection that applies to every repository's +[default branch](../../project/repository/branches/default.md). +[Branch protection](../../project/protected_branches.md) specifies which roles can push +to branches and which roles can delete branches. In this case _Default_ refers to a +repository's [default branch](../../project/repository/branches/default.md). This setting applies only to each repositories' default branch. To protect other branches, you must configure branch protection in repository. For details, see [protected branches](../../project/protected_branches.md). diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md index b01a299178d..e96ce969b3a 100644 --- a/doc/user/admin_area/user_cohorts.md +++ b/doc/user/admin_area/user_cohorts.md @@ -8,7 +8,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can analyze your users' GitLab activities over time. -To see user cohorts, go to **Admin Area > Overview > Users**. +To view user cohorts: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Overview > Users**. +1. Select the **Cohorts** tab. ## Overview diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index 284e87e9b35..1fce741cbef 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -4,12 +4,11 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# CI/CD Analytics +# CI/CD Analytics **(FREE)** -## Pipeline success and duration charts **(FREE)** +## Pipeline success and duration charts -> - Introduced in GitLab 3.1.1 as Commit Stats, and later renamed to Pipeline Charts. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/38318) to CI/CD Analytics in GitLab 12.8. +> [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/38318) to CI/CD Analytics in GitLab 12.8. GitLab tracks the history of your pipeline successes and failures, as well as how long each pipeline ran. To view this information, go to **Analytics > CI/CD Analytics**. @@ -48,14 +47,14 @@ performance indicators for software development teams: The following table shows the supported metrics, at which level they are supported, and which GitLab version (API and UI) they were introduced: -| Metric | Level | API version | Chart (UI) version | Comments | -| --------------- | ----------- | --------------- | ---------- | ------- | -| `deployment_frequency` | Project-level | [13.7+](../../api/dora/metrics.md) | [13.8+](#deployment-frequency-charts) | The [old API endpoint](../../api/dora4_project_analytics.md) was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/323713) in 13.10. | -| `deployment_frequency` | Group-level | [13.10+](../../api/dora/metrics.md) | To be supported | | -| `lead_time_for_changes` | Project-level | [13.10+](../../api/dora/metrics.md) | [13.11+](#lead-time-charts) | Unit in seconds. Aggregation method is median. | -| `lead_time_for_changes` | Group-level | [13.10+](../../api/dora/metrics.md) | To be supported | Unit in seconds. Aggregation method is median. | -| `change_failure_rate` | Project/Group-level | To be supported | To be supported | | -| `time_to_restore_service` | Project/Group-level | To be supported | To be supported | | +| Metric | Level | API version | Chart (UI) version | Comments | +|---------------------------|---------------------|--------------------------------------|---------------------------------------|-----------| +| `deployment_frequency` | Project-level | [13.7+](../../api/dora/metrics.md) | [13.8+](#deployment-frequency-charts) | The [old API endpoint](../../api/dora4_project_analytics.md) was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/323713) in 13.10. | +| `deployment_frequency` | Group-level | [13.10+](../../api/dora/metrics.md) | To be supported | | +| `lead_time_for_changes` | Project-level | [13.10+](../../api/dora/metrics.md) | [13.11+](#lead-time-charts) | Unit in seconds. Aggregation method is median. | +| `lead_time_for_changes` | Group-level | [13.10+](../../api/dora/metrics.md) | To be supported | Unit in seconds. Aggregation method is median. | +| `change_failure_rate` | Project/Group-level | To be supported | To be supported | | +| `time_to_restore_service` | Project/Group-level | To be supported | To be supported | | ### Deployment frequency charts **(ULTIMATE)** @@ -85,4 +84,4 @@ processes. For time periods in which no merge requests were deployed, the charts render a red, dashed line. -These charts are only available for projects. +These charts are available for both groups and projects. diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index d50a183aa54..8c67163c4b0 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -4,7 +4,7 @@ group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Analytics **(FREE)** +# Analyze GitLab usage **(FREE)** ## Definitions diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index 2af98492ee7..c3b3fcba52e 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Value Stream Analytics **(FREE)** > - Introduced as Cycle Analytics prior to GitLab 12.3 at the project level. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12077) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3 at the group level. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12077) in GitLab Premium 12.3 at the group level. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23427) from Cycle Analytics to Value Stream Analytics in GitLab 12.8. Value Stream Analytics measures the time spent to go from an @@ -15,20 +15,20 @@ Value Stream Analytics measures the time spent to go from an (also known as cycle time) for each of your projects or groups. Value Stream Analytics displays the median time spent in each stage defined in the process. -Value Stream Analytics is useful in order to quickly determine the velocity of a given +You can use Value Stream Analytics to determine the velocity of a given project. It points to bottlenecks in the development process, enabling management to uncover, triage, and identify the root cause of slowdowns in the software development life cycle. -For information on how to contribute to the development of Value Stream Analytics, see our [contributor documentation](../../development/value_stream_analytics.md). +For information about how to contribute to the development of Value Stream Analytics, see our [contributor documentation](../../development/value_stream_analytics.md). -Project-level Value Stream Analytics is available via **Project > Analytics > Value Stream**. +Project-level Value Stream Analytics is available by using **Project > Analytics > Value Stream**. NOTE: [Group-level Value Stream Analytics](../group/value_stream_analytics) is also available. ## Default stages -The stages tracked by Value Stream Analytics by default represent the [GitLab flow](../../topics/gitlab_flow.md). These stages can be customized in Group Level Value Stream Analytics. +The stages tracked by Value Stream Analytics by default represent the [GitLab flow](../../topics/gitlab_flow.md). You can customize these stages in group-level Value Stream Analytics. - **Issue** (Tracker) - Time to schedule an issue (by milestone or by adding it to an issue board) @@ -38,55 +38,49 @@ The stages tracked by Value Stream Analytics by default represent the [GitLab fl - Time to create a merge request - **Test** (CI) - Time it takes GitLab CI/CD to test your code -- **Review** (Merge Request/MR) +- **Review** (Merge request) - Time spent on code review - **Staging** (Continuous Deployment) - Time between merging and deploying to production ### Date ranges -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36300) in GitLab 10.0. - -GitLab provides the ability to filter analytics based on a date range. To filter results, select one of these options: - -1. Last 7 days -1. Last 30 days (default) -1. Last 90 days +To filter analytics results based on a date range, +select different **From** and **To** days +from the date picker (default: last 30 days). ## How Time metrics are measured -The "Time" metrics near the top of the page are measured as follows: +The **Time** metrics near the top of the page are measured as follows: -- **Lead time**: median time from issue created to issue closed. -- **Cycle time**: median time from first commit to issue closed. (You can associate a commit with an issue by [crosslinking in the commit message](../project/issues/crosslinking_issues.md#from-commit-messages).) +- **Lead time**: Median time from issue created to issue closed. +- **Cycle time**: Median time from first commit to issue closed. (You can associate a commit with an issue by [crosslinking in the commit message](../project/issues/crosslinking_issues.md#from-commit-messages).) ## How the stages are measured -Value Stream Analytics uses start events and stop events to measure the time that an Issue or MR spends in each stage. -For example, a stage might start when one label is added to an issue, and end when another label is added. -Items are not included in the stage time calculation if they have not reached the stop event. - -Each stage of Value Stream Analytics is further described in the table below. +Value Stream Analytics uses start events and stop events to measure the time that an issue or merge request spends in each stage. +For example, a stage might start when one label is added to an issue and end when another label is added. +Items aren't included in the stage time calculation if they have not reached the stop event. -| **Stage** | **Description** | -| --------- | --------------- | -| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whichever comes first. The label is tracked only if it already includes an [Issue Board list](../project/issue_board.md) created for it. | -| Plan | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. That first branch commit triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch must include the related issue number (such as `#42`). If the issue number is *not* included in a commit, that data is not included in the measurement time of the stage. | -| Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR). The process is tracked with the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) in the description of the merge request. For example, if the issue is closed with `Closes #xxx`, it's assumed that `xxx` is issue number for the merge request). If there is no closing pattern, the start time is set to the create time of the first commit. | -| Test | Essentially the start to finish time for all pipelines. Measures the median time to run the entire pipeline for that project. Related to the time required by GitLab CI/CD to run every job for the commits pushed to that merge request, as defined in the previous stage. | -| Review | Measures the median time taken to review merge requests with a closing issue pattern, from creation to merge. | -| Staging | Measures the median time between merging the merge request (with a closing issue pattern) to the first deployment to a [production environment](#how-the-production-environment-is-identified). Data not collected without a production environment. | +| Stage | Description | +|---------|---------------| +| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whichever comes first. The label is tracked only if it already includes an [Issue Board list](../project/issue_board.md) created for it. | +| Plan | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. That first branch commit triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch must include the related issue number (such as `#42`). If the issue number is *not* included in a commit, that data is not included in the measurement time of the stage. | +| Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR). The process is tracked with the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) in the description of the merge request. For example, if the issue is closed with `Closes #xxx`, it's assumed that `xxx` is issue number for the merge request). If there is no closing pattern, the start time is set to the create time of the first commit. | +| Test | Essentially the start to finish time for all pipelines. Measures the median time to run the entire pipeline for that project. Related to the time required by GitLab CI/CD to run every job for the commits pushed to that merge request, as defined in the previous stage. | +| Review | Measures the median time taken to review merge requests with a closing issue pattern, from creation to merge. | +| Staging | Measures the median time between merging the merge request (with a closing issue pattern) to the first deployment to a [production environment](#how-the-production-environment-is-identified). Data not collected without a production environment. | -How this works, behind the scenes: +How this works: 1. Issues and merge requests are grouped in pairs, where the merge request has the [closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) - for the corresponding issue. Issue/merge request pairs without closing patterns are - **not** included. -1. Issue/merge request pairs are filtered by the last XX days, specified through the UI - (default = 90 days). Pairs outside the filtered range are not included. + for the corresponding issue. Issue and merge request pairs without closing patterns are + not included. +1. Issue and merge request pairs are filtered by the last XX days, specified through the UI + (default is `90` days). Pairs outside the filtered range are not included. 1. For the remaining pairs, review information needed for stages, including - issue creation date, merge request merge time, and so on. + issue creation date and merge request merge time. In short, the Value Stream Analytics dashboard tracks data related to [GitLab flow](../../topics/gitlab_flow.md). It does not include data for: @@ -97,67 +91,69 @@ In short, the Value Stream Analytics dashboard tracks data related to [GitLab fl ## How the production environment is identified -Value Stream Analytics identifies production environments based on -[the deployment tier of environments](../../ci/environments/index.md#deployment-tier-of-environments). +Value Stream Analytics identifies production environments based on the +[deployment tier of environments](../../ci/environments/index.md#deployment-tier-of-environments). ## Example workflow -Below is a simple fictional workflow of a single cycle that happens in a -single day passing through all seven stages. Note that if a stage does not have -a start and a stop mark, it is not measured and hence not calculated in the median -time. It is assumed that milestones are created and CI for testing and setting +Here's a fictional workflow of a single cycle that happens in a +single day, passing through all seven stages. If a stage doesn't have +a start and a stop mark, it isn't measured and hence isn't calculated in the median +time. It's assumed that milestones are created, and CI for testing and setting environments is configured. 1. Issue is created at 09:00 (start of **Issue** stage). -1. Issue is added to a milestone at 11:00 (stop of **Issue** stage / start of +1. Issue is added to a milestone at 11:00 (stop of **Issue** stage and start of **Plan** stage). -1. Start working on the issue, create a branch locally and make one commit at +1. Start working on the issue, create a branch locally, and make one commit at 12:00. -1. Make a second commit to the branch which mentions the issue number at 12.30 - (stop of **Plan** stage / start of **Code** stage). -1. Push branch and create a merge request that contains the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) - in its description at 14:00 (stop of **Code** stage / start of **Test** and +1. Make a second commit to the branch that mentions the issue number at 12:30 + (stop of **Plan** stage and start of **Code** stage). +1. Push branch, and create a merge request that contains the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) + in its description at 14:00 (stop of **Code** stage and start of **Test** and **Review** stages). 1. The CI starts running your scripts defined in [`.gitlab-ci.yml`](../../ci/yaml/README.md) and - takes 5min (stop of **Test** stage). -1. Review merge request, ensure that everything is OK and merge the merge - request at 19:00. (stop of **Review** stage / start of **Staging** stage). -1. Now that the merge request is merged, a deployment to the `production` + takes 5 minutes (stop of **Test** stage). +1. Review merge request, ensure that everything is okay, and then merge the merge + request at 19:00 (stop of **Review** stage and start of **Staging** stage). +1. The merge request is merged, and a deployment to the `production` environment starts and finishes at 19:30 (stop of **Staging** stage). -From the above example we see the time used for each stage: +From the previous example we see the time used for each stage: -- **Issue**: 2h (11:00 - 09:00) -- **Plan**: 1h (12:00 - 11:00) -- **Code**: 2h (14:00 - 12:00) -- **Test**: 5min -- **Review**: 5h (19:00 - 14:00) -- **Staging**: 30min (19:30 - 19:00) +- **Issue**: 2 hrs (09:00 to 11:00) +- **Plan**: 1 hr (11:00 to 12:00) +- **Code**: 2 hrs (12:00 to 14:00) +- **Test**: 5 mins +- **Review**: 5 hrs (14:00 to 19:00) +- **Staging**: 30 mins (19:00 to 19:30) More information: -- The above example specifies the issue number in a latter commit. The process - still collects analytics data for that issue. -- The time required in the **Test** stage is not included in the overall time of - the cycle. It is included in the **Review** process, as every MR should be +- Although the previous example specifies the issue number in a later commit, the process + still collects analytics data for the issue. +- The time required in the **Test** stage isn't included in the overall time of + the cycle. The time is included in the **Review** process, as every merge request should be tested. -- The example above illustrates only **one cycle** of the multiple stages. Value +- The previous example illustrates only one cycle of the multiple stages. Value Stream Analytics, on its dashboard, shows the calculated median elapsed time for these issues. ## Permissions -The current permissions on the Project-level Value Stream Analytics dashboard are: +The permissions for the project-level Value Stream Analytics dashboard include: -- Public projects - anyone can access. -- Internal projects - any authenticated user can access. -- Private projects - any member Guest and above can access. +| Project type | Permissions | +|--------------|---------------------------------------| +| Public | Anyone can access | +| Internal | Any authenticated user can access | +| Private | Any member Guest and above can access | You can [read more about permissions](../../user/permissions.md) in general. ## More resources -Learn more about Value Stream Analytics in the following resources: +Learn more about Value Stream Analytics with the following resources: - [Value Stream Analytics feature page](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). - [Value Stream Analytics feature preview](https://about.gitlab.com/blog/2016/09/16/feature-preview-introducing-cycle-analytics/). 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 220d00adc7b..1162984a02d 100644 --- a/doc/user/application_security/api_fuzzing/create_har_files.md +++ b/doc/user/application_security/api_fuzzing/create_har_files.md @@ -1,11 +1,11 @@ --- stage: Secure -group: Fuzz Testing +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/#designated-technical-writers type: howto --- -# HTTP Archive format +# HTTP Archive format **(ULTIMATE)** HTTP Archive (HAR) format files are an industry standard for exchanging information about HTTP requests and HTTP responses. A HAR file's content is JSON formatted, containing browser interactions @@ -15,7 +15,7 @@ The HAR files can be used to perform [web API Fuzz Testing](index.md#http-archiv your [GitLab CI/CD](../../../ci/README.md) pipelines. WARNING: -**DANGER** A HAR file stores information exchanged between web client and web server. It could also +A HAR file stores information exchanged between web client and web server. It could also store sensitive information such as authentication tokens, API keys, and session cookies. We recommend that you review the HAR file contents before adding them to a repository. @@ -36,7 +36,7 @@ automatically record your network activity and generate the HAR file: 1. [Firefox web browser](#firefox-web-browser). WARNING: -**DANGER** HAR files may contain sensitive information such as authentication tokens, API keys, and +HAR files may contain sensitive information such as authentication tokens, API keys, and session cookies. We recommend that you review the HAR file contents before adding them to a repository. diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 8511c919c14..2b2ac76a7af 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -1,6 +1,6 @@ --- stage: Secure -group: Fuzz Testing +group: Dynamic Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -48,6 +48,7 @@ Example projects using these methods are available: - [Example HTTP Archive (HAR) project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/har) - [Example Postman Collection project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing/postman-api-fuzzing-example) - [Example GraphQL project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing/graphql-api-fuzzing-example) +- [Example SOAP project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing/soap-api-fuzzing-example) ## Enable Web API fuzzing @@ -116,8 +117,8 @@ To generate an API Fuzzing configuration snippet: > Support for OpenAPI Specification v3.0 was > [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228652) in GitLab 13.9. -The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an API description format for REST APIs. -This section shows you how to configure API fuzzing using an OpenAPI Specification to provide information about the target API to test. +The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an API description format for REST APIs. +This section shows you how to configure API fuzzing using an OpenAPI Specification to provide information about the target API to test. OpenAPI Specifications are provided as a file system resource or URL. Both JSON and YAML OpenAPI formats are supported. API fuzzing uses an OpenAPI document to generate the request body. When a request body is required, @@ -134,7 +135,7 @@ To configure API fuzzing in GitLab with an OpenAPI Specification: 1. Add the `fuzz` stage to your `.gitlab-ci.yml` file. 1. [Include](../../../ci/yaml/README.md#includetemplate) - the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml) + the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml) in your `.gitlab-ci.yml` file. 1. Provide the profile by adding the `FUZZAPI_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file. @@ -155,7 +156,7 @@ To configure API fuzzing in GitLab with an OpenAPI Specification: dynamic environments. To run API fuzzing against an application dynamically created during a GitLab CI/CD pipeline, have the application persist its URL in an `environment_url.txt` file. API fuzzing automatically parses that file to find its scan target. You can see an - example of this in the [Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). + example of this in the [Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). Example `.gitlab-ci.yml` file using an OpenAPI Specification: @@ -200,7 +201,7 @@ To configure API fuzzing to use a HAR file: 1. Add the `fuzz` stage to your `.gitlab-ci.yml` file. 1. [Include](../../../ci/yaml/README.md#includetemplate) - the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml) + the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml) in your `.gitlab-ci.yml` file. 1. Provide the profile by adding the `FUZZAPI_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file. @@ -222,7 +223,7 @@ To configure API fuzzing to use a HAR file: dynamic environments. To run API fuzzing against an app dynamically created during a GitLab CI/CD pipeline, have the app persist its domain in an `environment_url.txt` file. API fuzzing automatically parses that file to find its scan target. You can see an - [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). + [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). Example `.gitlab-ci.yml` file using a HAR file: @@ -271,7 +272,7 @@ To configure API fuzzing to use a Postman Collection file: 1. Add the `fuzz` stage to your `.gitlab-ci.yml` file. 1. [Include](../../../ci/yaml/README.md#includetemplate) - the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml) + the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml) in your `.gitlab-ci.yml` file. 1. Provide the profile by adding the `FUZZAPI_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file. @@ -294,7 +295,7 @@ To configure API fuzzing to use a Postman Collection file: dynamic environments. To run API fuzzing against an app dynamically created during a GitLab CI/CD pipeline, have the app persist its domain in an `environment_url.txt` file. API fuzzing automatically parses that file to find its scan target. You can see an - [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). + [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). Example `.gitlab-ci.yml` file using a Postman Collection file: @@ -567,6 +568,7 @@ profile increases as the number of tests increases. | `FUZZAPI_TARGET_URL` | Base URL of API testing target. | | `FUZZAPI_CONFIG` | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/276395) in GitLab 13.12, replaced with default `.gitlab/gitlab-api-fuzzing-config.yml`. API Fuzzing configuration file. | |[`FUZZAPI_PROFILE`](#api-fuzzing-profiles) | Configuration profile to use during testing. Defaults to `Quick-10`. | +|[`FUZZAPI_EXCLUDE_PATHS`](#exclude-paths) | Exclude API URL paths from testing. | |[`FUZZAPI_OPENAPI`](#openapi-specification) | OpenAPI Specification file or URL. | |[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | |[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | @@ -778,7 +780,7 @@ variables: ``` In this example `.gitlab-ci.yml`, the `SECRET_OVERRIDES` variable provides the JSON. This is a -[group or instance level CI/CD variable defined in the UI](../../../ci/variables/README.md#instance-cicd-variables): +[group or instance level CI/CD variable defined in the UI](../../../ci/variables/README.md#add-a-cicd-variable-to-an-instance): ```yaml stages: @@ -824,6 +826,47 @@ variables: FUZZAPI_OVERRIDES_INTERVAL: 300 ``` +### Exclude Paths + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211892) in GitLab 14.0. + +When testing an API it can be useful to exclude certain paths. For example, you might exclude testing of an authentication service or an older version of the API. To exclude paths, use the `FUZZAPI_EXCLUDE_PATHS` CI/CD variable . This variable is specified in your `.gitlab-ci.yml` file. To exclude multiple paths, separate entries using the `;` character. In the provided paths you can use a single character wildcard `?` and `*` for a multiple character wildcard. + +To verify the paths are excluded, review the `Tested Operations` and `Excluded Operations` portion of the job output. You should not see any excluded paths listed under `Tested Operations`. + +```plaintext +2021-05-27 21:51:08 [INF] API Security: --[ Tested Operations ]------------------------- +2021-05-27 21:51:08 [INF] API Security: 201 POST http://target:7777/api/users CREATED +2021-05-27 21:51:08 [INF] API Security: ------------------------------------------------ +2021-05-27 21:51:08 [INF] API Security: --[ Excluded Operations ]----------------------- +2021-05-27 21:51:08 [INF] API Security: GET http://target:7777/api/messages +2021-05-27 21:51:08 [INF] API Security: POST http://target:7777/api/messages +2021-05-27 21:51:08 [INF] API Security: ------------------------------------------------ +``` + +#### Examples of excluding paths + +This example excludes the `/auth` resource. This does not exclude child resources (`/auth/child`). + +```yaml +variables: + FUZZAPI_EXCLUDE_PATHS=/auth +``` + +To exclude `/auth`, and child resources (`/auth/child`), we use a wildcard. + +```yaml +variables: + FUZZAPI_EXCLUDE_PATHS=/auth* +``` + +To exclude multiple paths we can use the `;` character. In this example we exclude `/auth*` and `/v1/*`. + +```yaml +variables: + FUZZAPI_EXCLUDE_PATHS=/auth*;/v1/* +``` + ### Header Fuzzing Header fuzzing is disabled by default due to the high number of false positives that occur with many @@ -1159,7 +1202,7 @@ The API Fuzzing engine outputs an error message when it cannot establish a conne **Solution** - Remove the `FUZZAPI_API` variable from the `.gitlab-ci.yml` file. The value will be inherited from the API Fuzzing CI/CD template. We recommend this method instead of manually setting a value. -- If removing the variable is not possible, check to see if this value has changed in the latest version of the [API Fuzzing CI/CD template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml). If so, update the value in the `.gitlab-ci.yml` file. +- If removing the variable is not possible, check to see if this value has changed in the latest version of the [API Fuzzing CI/CD template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml). If so, update the value in the `.gitlab-ci.yml` file. ### Application cannot determine the base URL for the target API @@ -1171,7 +1214,7 @@ The best-suited solution will depend on whether or not your target API changes f #### Static environment solution -This solution is for pipelines in which the target API URL doesn't change (is static). +This solution is for pipelines in which the target API URL doesn't change (is static). **Add environmental variable** @@ -1188,7 +1231,7 @@ include: #### Dynamic environment solutions -In a dynamic environment your target API changes for each different deployment. In this case, there is more than one possible solution, we recommend to use the `environment_url.txt` file when dealing with dynamic environments. +In a dynamic environment your target API changes for each different deployment. In this case, there is more than one possible solution, we recommend to use the `environment_url.txt` file when dealing with dynamic environments. **Use environment_url.txt** diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 5ab56634d29..8e83ade5608 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -10,21 +10,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3672) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. WARNING: -GitLab 14.0 will replace its container scanning engine with Trivy. Currently, GitLab uses the open -source Clair engine for container scanning. GitLab 13.9 deprecates Clair. Until GitLab 14.0, this is -not a hard breaking change. Beginning in GitLab 14.0, GitLab will no longer update or maintain -Clair. To ensure that you get regular updates and the latest features, you must use the Trivy -container scanning engine beginning in GitLab 14.0. See the following sections for instructions on -moving from Clair to Trivy. +Versions of GitLab prior to 14.0 used Clair as the default container scanning engine. GitLab 14.0 +replaces Clair with Trivy and removes Clair from the product. If you run container scanning with the +default settings, GitLab switches you seamlessly and automatically to Trivy in GitLab 14.0. However, +if you customized the variables in your container scanning job, you should review the +[migration guide](#migrating-from-clair-to-trivy) and make any necessary updates. Your application's Docker image may itself be based on Docker images that contain known vulnerabilities. By including an extra job in your pipeline that scans for those vulnerabilities and displays them in a merge request, you can use GitLab to audit your Docker-based apps. -GitLab provides integration with two different open-source tools for vulnerability static analysis -in containers: +GitLab provides integration with open-source tools for vulnerability static analysis in containers: -- [Clair](https://github.com/quay/claircore) - [Trivy](https://github.com/aquasecurity/trivy) To integrate GitLab with security scanners other than those listed here, see @@ -41,10 +38,6 @@ information directly in the merge request.  -<!-- NOTE: The container scanning tool references the following heading in the code, so if you - make a change to this heading, make sure to update the documentation URLs used in the - container scanning tool (https://gitlab.com/gitlab-org/security-products/analyzers/klar) --> - ## Requirements To enable container scanning in your pipeline, you need the following: @@ -53,46 +46,25 @@ To enable container scanning in your pipeline, you need the following: or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. - Docker `18.09.03` or higher installed on the same computer as the runner. If you're using the shared runners on GitLab.com, then this is already the case. -- An image matching the following supported distributions (depending on the analyzer being used): - - | Scanning Engine | Supported distributions | - | --- | --- | - | [Clair](https://github.com/quay/claircore) | [Supported operating systems and languages](https://quay.github.io/claircore/) | - | [Trivy](https://github.com/aquasecurity/trivy) | Supported [operating systems](https://aquasecurity.github.io/trivy/latest/vuln-detection/os/) and [languages](https://aquasecurity.github.io/trivy/latest/vuln-detection/library/) | - +- An image matching the [supported distributions](#supported-distributions). - [Build and push](../../packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd) - your Docker image to your project's container registry. The name of the Docker image should use - the following [predefined CI/CD variables](../../../ci/variables/predefined_variables.md): - - ```plaintext - $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA - ``` - - You can use these directly in your `.gitlab-ci.yml` file: - - ```yaml - build: - image: docker:19.03.12 - stage: build - services: - - docker:19.03.12-dind - variables: - IMAGE_TAG: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA - script: - - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY - - docker build -t $IMAGE_TAG . - - docker push $IMAGE_TAG - ``` + the Docker image to your project's container registry. If using a third-party container + registry, you might need to provide authentication credentials using the `DOCKER_USER` and + `DOCKER_PASSWORD` [configuration variables](#available-cicd-variables). +- The name of the Docker image to scan, in the `DOCKER_IMAGE` [configuration variable](#available-cicd-variables). ## Configuration How you enable container scanning depends on your GitLab version: - GitLab 11.9 and later: [Include](../../../ci/yaml/README.md#includetemplate) the - [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) + [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) that comes with your GitLab installation. - GitLab versions earlier than 11.9: Copy and use the job from the - [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml). + [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml). + +Other changes: + - GitLab 13.6 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263482) better support for [FIPS](https://csrc.nist.gov/publications/detail/fips/140/2/final) by upgrading the `CS_MAJOR_VERSION` from `2` to `3`. Version `3` of the `container_scanning` Docker image uses @@ -102,17 +74,20 @@ How you enable container scanning depends on your GitLab version: `container_scanning` job's [`before_script`](../../../ci/yaml/README.md#before_script) and [`after_script`](../../../ci/yaml/README.md#after_script) blocks may not work with the new version. To roll back to the previous [`alpine:3.11.3`](https://hub.docker.com/_/alpine)-based - Docker image, you can specify the major version through the [`CS_MAJOR_VERSION`](#available-variables) + Docker image, you can specify the major version through the [`CS_MAJOR_VERSION`](#available-cicd-variables) variable. - GitLab 13.9 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322656) integration with [Trivy](https://github.com/aquasecurity/trivy) by upgrading `CS_MAJOR_VERSION` from `3` to `4`. +- GitLab 14.0 [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61850) + integration with [Trivy](https://github.com/aquasecurity/trivy) + as the default for container scanning. To include the `Container-Scanning.gitlab-ci.yml` template (GitLab 11.9 and later), add the following to your `.gitlab-ci.yml` file: ```yaml include: - - template: Container-Scanning.gitlab-ci.yml + - template: Security/Container-Scanning.gitlab-ci.yml ``` The included template: @@ -127,21 +102,14 @@ that you can download and analyze later. When downloading, you always receive th artifact. The following is a sample `.gitlab-ci.yml` that builds your Docker image, pushes it to the container -registry, and scans the containers: +registry, and scans the image: ```yaml -variables: - DOCKER_DRIVER: overlay2 - -stages: - - build - - test - build: - image: docker:stable + image: docker:latest stage: build services: - - docker:19.03.12-dind + - docker:dind variables: IMAGE: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA script: @@ -151,7 +119,7 @@ build: - docker push $IMAGE include: - - template: Container-Scanning.gitlab-ci.yml + - template: Security/Container-Scanning.gitlab-ci.yml ``` ### Customizing the container scanning settings @@ -159,76 +127,45 @@ include: There may be cases where you want to customize how GitLab scans your containers. For example, you may want to enable more verbose output, access a Docker registry that requires authentication, and more. To change such settings, use the [`variables`](../../../ci/yaml/README.md#variables) -parameter in your `.gitlab-ci.yml` to set [CI/CD variables](#available-variables). +parameter in your `.gitlab-ci.yml` to set [CI/CD variables](#available-cicd-variables). The variables you set in your `.gitlab-ci.yml` overwrite those in `Container-Scanning.gitlab-ci.yml`. This example [includes](../../../ci/yaml/README.md#include) the container scanning template and -enables verbose output for both analyzers: - -Clair: +enables verbose output for the analyzer: ```yaml include: - - template: Container-Scanning.gitlab-ci.yml + - template: Security/Container-Scanning.gitlab-ci.yml variables: - CLAIR_TRACE: true + SECURE_LOG_LEVEL: 'debug' ``` -Trivy: +#### Available CI/CD variables -```yaml -include: - - template: Container-Scanning.gitlab-ci.yml - -variables: - TRIVY_DEBUG: true -``` - -This example [includes](../../../ci/yaml/README.md#include) the container scanning template and -enables version `2` of the analyzer: - -```yaml -include: - - template: Container-Scanning.gitlab-ci.yml - -variables: - CS_MAJOR_VERSION: '2' -``` +You can [configure](#customizing-the-container-scanning-settings) analyzers by using the following CI/CD variables: -<!-- NOTE: The container scanning tool references the following heading in the code, so if you" - make a change to this heading, make sure to update the documentation URLs used in the" - container scanning tool (https://gitlab.com/gitlab-org/security-products/analyzers/klar)" --> +| CI/CD Variable | Default | Description | Scanner | +| ------------------------------ | ------------- | ----------- | ------------ | +| `ADDITIONAL_CA_CERT_BUNDLE` | `""` | Bundle of CA certs that you want to trust. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. | All | +| `CI_APPLICATION_REPOSITORY` | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | Docker repository URL for the image to be scanned. | All | +| `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | All | +| `CS_ANALYZER_IMAGE` | `$SECURE_ANALYZERS_PREFIX/$CS_PROJECT:$CS_MAJOR_VERSION` | Docker image of the analyzer. | All | +| `CS_DOCKER_INSECURE` | `"false"` | Allow access to secure Docker registries using HTTPS without validating the certificates. | All | +| `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | Trivy. The registry must listen on port `80/tcp`. | +| `CS_SEVERITY_THRESHOLD` | `UNKNOWN` | Severity level threshold. The scanner outputs vulnerabilities with severity level higher than or equal to this threshold. Supported levels are Unknown, Low, Medium, High, and Critical. | Trivy | +| `DOCKER_IMAGE` | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | The Docker image to be scanned. If set, this variable overrides the `$CI_APPLICATION_REPOSITORY` and `$CI_APPLICATION_TAG` variables. | All | +| `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. | All | +| `DOCKER_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. | All | +| `DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to use for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project. You should configure this variable only if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | All | +| `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. | All | -#### Available variables +### Supported distributions -You can [configure](#customizing-the-container-scanning-settings) both analyzers by using the following CI/CD variables: +Support depends on the scanner: -| CI/CD Variable | Default | Description | Supported by| -| ------------------------------ | ------------- | ----------- | ------------ | -| `ADDITIONAL_CA_CERT_BUNDLE` | `""` | Bundle of CA certs that you want to trust. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. | Both | -| `CLAIR_DB_CONNECTION_STRING` | `postgresql://postgres:password@clair-vulnerabilities-db:5432/postgres?sslmode=disable&statement_timeout=60000` | This variable represents the [connection string](https://www.postgresql.org/docs/9.3/libpq-connect.html#AEN39692) to the [PostgreSQL server hosting the vulnerability definitions](https://hub.docker.com/r/arminc/clair-db) database. **Do not change this** unless you're running the image locally as described in [Running the standalone container scanning tool](#running-the-standalone-container-scanning-tool). The host value for the connection string must match the [alias](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) value of the `Container-Scanning.gitlab-ci.yml` template file, which defaults to `clair-vulnerabilities-db`. | Clair | -| `CLAIR_DB_IMAGE` | `arminc/clair-db:latest` | The Docker image name and tag for the [PostgreSQL server hosting the vulnerability definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version (for example, to provide a consistent set of vulnerabilities for integration testing purposes, or to refer to a locally hosted vulnerability database for an on-premise offline installation). | Clair | -| `CLAIR_DB_IMAGE_TAG` | `latest` | (**DEPRECATED - use `CLAIR_DB_IMAGE` instead**) The Docker image tag for the [PostgreSQL server hosting the vulnerability definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version (for example, to provide a consistent set of vulnerabilities for integration testing purposes). | Clair | -| `CLAIR_OUTPUT` | `Unknown` | Severity level threshold. Vulnerabilities with severity level higher than or equal to this threshold are output. Supported levels are `Unknown`, `Negligible`, `Low`, `Medium`, `High`, `Critical`, and `Defcon1`. | Clair | -| `CLAIR_TRACE` | `"false"` | Set to true to enable more verbose output from the Clair server process. | Clair | -| `CLAIR_VULNERABILITIES_DB_URL` | `clair-vulnerabilities-db` | (**DEPRECATED - use `CLAIR_DB_CONNECTION_STRING` instead**) This variable is explicitly set in the [services section](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) of the `Container-Scanning.gitlab-ci.yml` file and defaults to `clair-vulnerabilities-db`. This value represents the address that the [PostgreSQL server hosting the vulnerability definitions](https://hub.docker.com/r/arminc/clair-db) is running on. **Do not change this** unless you're running the image locally as described in [Running the standalone container scanning tool](#running-the-standalone-container-scanning-tool). | Clair | -| `CI_APPLICATION_REPOSITORY` | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | Docker repository URL for the image to be scanned. | Both | -| `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | Both | -| `CS_ANALYZER_IMAGE` | `$SECURE_ANALYZERS_PREFIX/$CS_PROJECT:$CS_MAJOR_VERSION` | Docker image of the analyzer. | Both | -| `CS_MAJOR_VERSION` | `3` | The major version of the Docker image tag. | Both | -| `CS_PROJECT` | Depends on `$CS_MAJOR_VERSION`. `klar` if `$CS_MAJOR_VERSION` is set to `1`, `2` or `3`, and `container-scanning` otherwise. | Analyzer project to be used. | Both | -| `DOCKER_IMAGE` | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | The Docker image to be scanned. If set, this variable overrides the `$CI_APPLICATION_REPOSITORY` and `$CI_APPLICATION_TAG` variables. | Both | -| `DOCKER_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access secure Docker registries using HTTPS with bad (or self-signed) SSL certificates. | Clair | -| `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. | Clair | -| `DOCKER_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. | Clair | -| `DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to use for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project. You should configure this variable only if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | Both | -| `KLAR_TRACE` | `"false"` | Set to true to enable more verbose output from Klar. | Clair | -| `REGISTRY_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | Clair | -| `SECURE_ANALYZERS_PREFIX` | `"registry.gitlab.com/gitlab-org/security-products/analyzers"` | Set the Docker registry base address from which to download the analyzer. | Both | -| `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. | Both | -| `TRIVY_DEBUG` | `"false"` | Set to true to enable more verbose output from the Trivy process. | Trivy | +- [Trivy](https://aquasecurity.github.io/trivy/latest/vuln-detection/os/) (Default). ### Overriding the container scanning template @@ -236,37 +173,15 @@ If you want to override the job definition (for example, to change properties li must declare and override a job after the template inclusion, and then specify any additional keys. -This example sets `GIT_STRATEGY` to `fetch` to be considered by both Clair and Trivy: - -```yaml -include: - - template: Container-Scanning.gitlab-ci.yml - -.cs_common: - variables: - GIT_STRATEGY: fetch -``` - -This example sets `KLAR_TRACE` to `true`, which is specific to Clair: +This example sets `GIT_STRATEGY` to `fetch`: ```yaml include: - - template: Container-Scanning.gitlab-ci.yml + - template: Security/Container-Scanning.gitlab-ci.yml container_scanning: variables: - CLAIR_TRACE: true -``` - -This example sets `TRIVY_DEBUG` to `true`, which is specific to Trivy: - -```yaml -include: - - template: Container-Scanning.gitlab-ci.yml - -container_scanning_new: - variables: - TRIVY_DEBUG: true + GIT_STRATEGY: fetch ``` WARNING: @@ -276,36 +191,47 @@ instead. ### Migrating from Clair to Trivy -If you are currently using Clair and want to migrate to Trivy before GitLab 14.0, you can do so by -taking the following steps: +If you're migrating from a GitLab 13.x release to a GitLab 14.x release and have customized the +`container_scanning` job or its CI variables, you might need to perform these migration steps in +your CI file: + +1. Remove these variables: + + - `CS_MAJOR_VERSION` + - `CS_PROJECT` + - `SECURE_ANALYZERS_PREFIX` -1. Take the following actions in your CI file: +1. Review the `CS_ANALYZER_IMAGE` variable. It no longer depends on the variables above and its new + default value is `registry.gitlab.com/security-products/container-scanning:4`. If you have an + offline environment, see + [Running container scanning in an offline environment](#running-container-scanning-in-an-offline-environment). - - Set the variable `CS_MAJOR_VERSION` to `4`. The job scope is global variables, or under `.cs_common`. - - Remove the variable `CS_PROJECT` from your CI file. The job scope is `container_scanning_new`. - Setting this variable to `container-scanning` under the correct scope has the same effect as - removing it from your CI file. - - Remove the `CS_ANALYZER_IMAGE` variable from your CI file. The job scope is `.cs_common`. Note - that instead of overriding this variable, you can use `CS_MAJOR_VERSION`. +1. If present, remove the `.cs_common` and `container_scanning_new` configuration sections. -1. Remove any variables that are only applicable to Clair. For a complete list of these variables, - see the [available variables](#available-variables). -1. Make any [necessary customizations](#customizing-the-container-scanning-settings) to the - `Trivy` scanner. We strongly recommended that you minimize customizations, as they - might require changes in future GitLab major releases. +1. If the `container_scanning` section is present, it's safer to create one from scratch based on + the new version of the [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml). + Once finished, it should not have any variables that are only applicable to Klar or Clair. For a + complete list of supported variables, see [available variables](#available-cicd-variables). + +1. Make any [necessary customizations](#customizing-the-container-scanning-settings) + to the `Trivy` scanner. We recommend that you minimize such customizations, as they might require + changes in future GitLab major releases. + +1. Trigger a new run of a pipeline that includes the `container_scanning` job. Inspect the job + output and ensure that the log messages do not mention Clair. **Troubleshooting** Prior to the GitLab 14.0 release, any variable defined under the scope `container_scanning` is not considered for the Trivy scanner. Verify that all variables for Trivy are -either defined as a global variable, or under `.cs_common` and `container_scanning_new`. +either defined as a global variable, or under `container_scanning`. ### Using a custom SSL CA certificate authority You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority, which is used to verify the peer when fetching Docker images from a registry which uses HTTPS. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following: ```yaml -.cs_common: +container_scanning: variables: ADDITIONAL_CA_CERT_BUNDLE: | -----BEGIN CERTIFICATE----- @@ -379,7 +305,7 @@ at the logs that are produced by the container scanning analyzer in `container_s The log contains a list of found vulnerabilities as a table, for example: -```plainttext +```plaintext +------------+-------------------------+------------------------+-----------------------+------------------------------------------------------------------------+ | STATUS | CVE SEVERITY | PACKAGE NAME | PACKAGE VERSION | CVE DESCRIPTION | +------------+-------------------------+------------------------+-----------------------+------------------------------------------------------------------------+ @@ -420,8 +346,7 @@ To use container scanning in an offline environment, you need: | GitLab Analyzer | Container Registry | | --- | --- | -| [Klar](https://gitlab.com/gitlab-org/security-products/analyzers/klar/) (used to run Clair) | [Klar container registry](https://gitlab.com/gitlab-org/security-products/analyzers/klar/container_registry) | -| [Container-Scanning](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning) (used to run Trivy) | [Container-Scanning container registry](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/container_registry/1741162) | +| [Container-Scanning](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning) | [Container-Scanning container registry](https://gitlab.com/security-products/container-scanning/container_registry/) | Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), meaning the runner tries to pull Docker images from the GitLab container registry even if a local @@ -436,7 +361,6 @@ Support for custom certificate authorities was introduced in the following versi | Scanner | Version | | -------- | ------- | -| `Clair` | [v2.3.0](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/releases/v2.3.0) | | `Trivy` | [4.0.0](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/-/releases/4.0.0) | #### Make GitLab container scanning analyzer images available inside your Docker registry @@ -444,17 +368,8 @@ Support for custom certificate authorities was introduced in the following versi For container scanning, import the following default images from `registry.gitlab.com` into your [local Docker container registry](../../packages/container_registry/index.md): -Clair: - ```plaintext -registry.gitlab.com/gitlab-org/security-products/analyzers/klar -https://hub.docker.com/r/arminc/clair-db -``` - -Trivy: - -```plaintext -registry.gitlab.com/gitlab-org/security-products/analyzers/container-scanning +registry.gitlab.com/security-products/container-scanning ``` The process for importing Docker images into a local offline Docker registry depends on @@ -473,54 +388,33 @@ For details on saving and transporting Docker images as a file, see Docker's doc 1. [Override the container scanning template](#overriding-the-container-scanning-template) in your `.gitlab-ci.yml` file to refer to the Docker images hosted on your local Docker container registry: - Clair: - ```yaml include: - - template: Container-Scanning.gitlab-ci.yml + - template: Security/Container-Scanning.gitlab-ci.yml - .cs_common: - image: $CI_REGISTRY/namespace/gitlab-klar-analyzer - variables: - CLAIR_DB_IMAGE: $CI_REGISTRY/namespace/clair-vulnerabilities-db - ``` - - Trivy: - - ```yaml - include: - - template: Container-Scanning.gitlab-ci.yml - - .cs_common: + container_scanning: image: $CI_REGISTRY/namespace/gitlab-container-scanning ``` 1. If your local Docker container registry is running securely over `HTTPS`, but you're using a - self-signed certificate, then you must set `DOCKER_INSECURE: "true"` in the above - `container_scanning` section of your `.gitlab-ci.yml`. This only applies to Clair. + self-signed certificate, then you must set `CS_DOCKER_INSECURE: "true"` in the above + `container_scanning` section of your `.gitlab-ci.yml`. #### Automating container scanning vulnerability database updates with a pipeline We recommend that you set up a [scheduled pipeline](../../../ci/pipelines/schedules.md) -to fetch the latest vulnerabilities database on a preset schedule. Because the Clair scanner is -deprecated, the latest vulnerabilities are currently only available for the Trivy scanner. +to fetch the latest vulnerabilities database on a preset schedule. Automating this with a pipeline means you do not have to do it manually each time. You can use the following `.gitlab-yml.ci` example as a template. ```yaml variables: - # If using Clair, uncomment the following 2 lines and comment the Trivy lines below - # SOURCE_IMAGE: arminc/clair-db:latest - # TARGET_IMAGE: $CI_REGISTRY/$CI_PROJECT_PATH/clair-vulnerabilities-db - - # If using Trivy, uncomment the following 3 lines and comment the Clair lines above - CS_MAJOR_VERSION: 4 # ensure that this value matches the one you use in your scanning jobs - SOURCE_IMAGE: registry.gitlab.com/gitlab-org/security-products/analyzers/container-scanning:$CS_MAJOR_VERSION + SOURCE_IMAGE: registry.gitlab.com/security-products/container-scanning:4 TARGET_IMAGE: $CI_REGISTRY/$CI_PROJECT_PATH/gitlab-container-scanning image: docker:stable -update-vulnerabilities-db: +update-scanner-image: services: - docker:19-dind script: @@ -536,42 +430,6 @@ you're using a non-GitLab Docker registry, you must change the `$CI_REGISTRY` va ## Running the standalone container scanning tool -### Clair - -It's possible to run [Klar](https://gitlab.com/gitlab-org/security-products/analyzers/klar) -against a Docker container without needing to run it within the context of a CI job. To scan an -image directly, follow these steps: - -1. Run [Docker Desktop](https://www.docker.com/products/docker-desktop) or [Docker Machine](https://github.com/docker/machine). -1. Run the latest [prefilled vulnerabilities database](https://hub.docker.com/repository/docker/arminc/clair-db) Docker image: - - ```shell - docker run -p 5432:5432 -d --name clair-db arminc/clair-db:latest - ``` - -1. Configure a CI/CD variable to point to your local machine's IP address (or insert your IP address instead of the `LOCAL_MACHINE_IP_ADDRESS` variable in the `CLAIR_DB_CONNECTION_STRING` in the next step): - - ```shell - export LOCAL_MACHINE_IP_ADDRESS=your.local.ip.address - ``` - -1. Run the analyzer's Docker image, passing the image and tag you want to analyze in the `CI_APPLICATION_REPOSITORY` and `CI_APPLICATION_TAG` variables: - - ```shell - docker run \ - --interactive --rm \ - --volume "$PWD":/tmp/app \ - -e CI_PROJECT_DIR=/tmp/app \ - -e CLAIR_DB_CONNECTION_STRING="postgresql://postgres:password@${LOCAL_MACHINE_IP_ADDRESS}:5432/postgres?sslmode=disable&statement_timeout=60000" \ - -e CI_APPLICATION_REPOSITORY=registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256 \ - -e CI_APPLICATION_TAG=bc09fe2e0721dfaeee79364115aeedf2174cce0947b9ae5fe7c33312ee019a4e \ - registry.gitlab.com/gitlab-org/security-products/analyzers/klar - ``` - -The results are stored in `gl-container-scanning-report.json`. - -### Trivy - It's possible to run the [GitLab container scanning tool](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning) against a Docker container without needing to run it within the context of a CI job. To scan an image directly, follow these steps: @@ -589,7 +447,7 @@ image directly, follow these steps: -e CI_PROJECT_DIR=/tmp/app \ -e CI_APPLICATION_REPOSITORY=registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256 \ -e CI_APPLICATION_TAG=bc09fe2e0721dfaeee79364115aeedf2174cce0947b9ae5fe7c33312ee019a4e \ - registry.gitlab.com/gitlab-org/security-products/analyzers/container-scanning + registry.gitlab.com/security-products/container-scanning ``` The results are stored in `gl-container-scanning-report.json`. @@ -698,8 +556,8 @@ the security vulnerabilities in your groups, projects and pipelines. ## Vulnerabilities database update -If you're using Klar and want more information about the vulnerabilities database update, see the -[maintenance table](../vulnerabilities/index.md#vulnerability-scanner-maintenance). +If you use container scanning and want more information about the vulnerabilities database update, +see the [maintenance table](../vulnerabilities/index.md#vulnerability-scanner-maintenance). ## Interacting with the vulnerabilities @@ -711,13 +569,13 @@ Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. To enable remediation support, the scanning tool _must_ have access to the `Dockerfile` specified by -the [`DOCKERFILE_PATH`](#available-variables) CI/CD variable. To ensure that the scanning tool +the [`DOCKERFILE_PATH`](#available-cicd-variables) CI/CD variable. To ensure that the scanning tool has access to this -file, it's necessary to set [`GIT_STRATEGY: fetch`](../../../ci/runners/README.md#git-strategy) in +file, it's necessary to set [`GIT_STRATEGY: fetch`](../../../ci/runners/configure_runners.md#git-strategy) in your `.gitlab-ci.yml` file by following the instructions described in this document's [overriding the container scanning template](#overriding-the-container-scanning-template) section. -Read more about the [solutions for vulnerabilities](../vulnerabilities/index.md#remediate-a-vulnerability-automatically). +Read more about the [solutions for vulnerabilities](../vulnerabilities/index.md#resolve-a-vulnerability). ## Troubleshooting diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 8b0a84eae4b..b46547b6828 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -1,6 +1,6 @@ --- stage: Secure -group: Fuzz Testing +group: Dynamic Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -39,7 +39,7 @@ Docker image with the fuzz engine to run your app. To enable fuzzing, you must [include](../../../ci/yaml/README.md#includetemplate) -the [`Coverage-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Coverage-Fuzzing.gitlab-ci.yml) +the [`Coverage-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Coverage-Fuzzing.gitlab-ci.yml) provided as part of your GitLab installation. To do so, add the following to your `.gitlab-ci.yml` file: diff --git a/doc/user/application_security/cve_id_request.md b/doc/user/application_security/cve_id_request.md index bc0c1e52626..aaf701c91dc 100644 --- a/doc/user/application_security/cve_id_request.md +++ b/doc/user/application_security/cve_id_request.md @@ -5,7 +5,7 @@ group: Vulnerability Research 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 --- -# CVE ID Requests +# CVE ID Requests **(ULTIMATE SAAS)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index b8c3529225c..072f6fba4ba 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -27,62 +27,44 @@ Scanning a web application with both the browser-based crawler and GitLab DAST s The browser-based crawler is an extension to the GitLab DAST product. DAST should be included in the CI/CD configuration and the browser-based crawler enabled using CI/CD variables: -1. Install the DAST [prerequisites](index.md#prerequisite). +1. Ensure the DAST [prerequisites](index.md#prerequisites) are met. 1. Include the [DAST CI template](index.md#include-the-dast-template). 1. Set the target website using the `DAST_WEBSITE` CI/CD variable. 1. Set the CI/CD variable `DAST_BROWSER_SCAN` to `true`. - + An example configuration might look like the following: ```yaml include: - template: DAST.gitlab-ci.yml -variables: - DAST_WEBSITE: "https://example.com" - DAST_BROWSER_SCAN: "true" +dast: + variables: + DAST_WEBSITE: "https://example.com" + DAST_BROWSER_SCAN: "true" ``` -### Available variables +### Available CI/CD variables The browser-based crawler can be configured using CI/CD variables. -| CI/CD variable | Type | Example | Description | +| CI/CD variable | Type | Example | Description | |--------------------------------------| ----------------| --------------------------------- | ------------| | `DAST_WEBSITE` | URL | `http://www.site.com` | The URL of the website to scan. | -| `DAST_BROWSER_SCAN` | boolean | `true` | Configures DAST to use the browser-based crawler engine. | -| `DAST_BROWSER_ALLOWED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered in scope when crawled. By default the `DAST_WEBSITE` hostname is included in the allowed hosts list. | -| `DAST_BROWSER_EXCLUDED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered excluded and connections are forcibly dropped. | -| `DAST_BROWSER_IGNORED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are accessed but not reported against. | -| `DAST_BROWSER_MAX_ACTIONS` | number | `10000` | The maximum number of actions that the crawler performs. For example, clicking a link, or filling a form. | -| `DAST_BROWSER_MAX_DEPTH` | number | `10` | The maximum number of chained actions that the crawler takes. For example, `Click -> Form Fill -> Click` is a depth of three. | -| `DAST_BROWSER_NUMBER_OF_BROWSERS` | number | `3` | The maximum number of concurrent browser instances to use. For shared runners on GitLab.com we recommended a maximum of three. Private runners with more resources may benefit from a higher number, but will likely produce little benefit after five to seven instances. | -| `DAST_BROWSER_COOKIES` | dictionary | `abtesting_group:3,region:locked` | A cookie name and value to be added to every request. | -| `DAST_BROWSER_LOG` | List of strings | `brows:debug,auth:debug` | A list of modules and their intended log level. | -| `DAST_AUTH_URL` | string | `https://example.com/sign-in` | The URL of page that hosts the sign-in form. | -| `DAST_USERNAME` | string | `user123` | The username to enter into the username field on the sign-in HTML form. | -| `DAST_PASSWORD` | string | `p@55w0rd` | The password to enter into the password field on the sign-in HTML form. | -| `DAST_USERNAME_FIELD` | selector | `id:user` | A selector describing the username field on the sign-in HTML form. | -| `DAST_PASSWORD_FIELD` | selector | `css:.password-field` | A selector describing the password field on the sign-in HTML form. | -| `DAST_SUBMIT_FIELD` | selector | `xpath://input[@value='Login']` | A selector describing the element that when clicked submits the login form or the password form of a multi-page login process. | -| `DAST_FIRST_SUBMIT_FIELD` | selector | `.submit` | A selector describing the element that when clicked submits the username form of a multi-page login process. | - -The [DAST variables](index.md#available-variables) `SECURE_ANALYZERS_PREFIX`, `DAST_FULL_SCAN_ENABLED`, `DAST_AUTO_UPDATE_ADDONS`, `DAST_EXCLUDE_RULES`, `DAST_REQUEST_HEADERS`, `DAST_HTML_REPORT`, `DAST_MARKDOWN_REPORT`, `DAST_XML_REPORT`, +| `DAST_BROWSER_SCAN` | boolean | `true` | Configures DAST to use the browser-based crawler engine. | +| `DAST_BROWSER_ALLOWED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered in scope when crawled. By default the `DAST_WEBSITE` hostname is included in the allowed hosts list. | +| `DAST_BROWSER_EXCLUDED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered excluded and connections are forcibly dropped. | +| `DAST_BROWSER_IGNORED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are accessed but not reported against. | +| `DAST_BROWSER_MAX_ACTIONS` | number | `10000` | The maximum number of actions that the crawler performs. For example, clicking a link, or filling a form. | +| `DAST_BROWSER_MAX_DEPTH` | number | `10` | The maximum number of chained actions that the crawler takes. For example, `Click -> Form Fill -> Click` is a depth of three. | +| `DAST_BROWSER_NUMBER_OF_BROWSERS` | number | `3` | The maximum number of concurrent browser instances to use. For shared runners on GitLab.com we recommended a maximum of three. Private runners with more resources may benefit from a higher number, but will likely produce little benefit after five to seven instances. | +| `DAST_BROWSER_COOKIES` | dictionary | `abtesting_group:3,region:locked` | A cookie name and value to be added to every request. | +| `DAST_BROWSER_LOG` | List of strings | `brows:debug,auth:debug` | A list of modules and their intended log level. | + +The [DAST variables](index.md#available-cicd-variables) `SECURE_ANALYZERS_PREFIX`, `DAST_FULL_SCAN_ENABLED`, `DAST_AUTO_UPDATE_ADDONS`, `DAST_EXCLUDE_RULES`, `DAST_REQUEST_HEADERS`, `DAST_HTML_REPORT`, `DAST_MARKDOWN_REPORT`, `DAST_XML_REPORT`, +`DAST_AUTH_URL`, `DAST_USERNAME`, `DAST_PASSWORD`, `DAST_USERNAME_FIELD`, `DAST_PASSWORD_FIELD`, `DAST_FIRST_SUBMIT_FIELD`, `DAST_SUBMIT_FIELD`, `DAST_EXCLUDE_URLS`, `DAST_AUTH_VERIFICATION_URL`, `DAST_BROWSER_AUTH_VERIFICATION_SELECTOR`, `DAST_BROWSER_AUTH_VERIFICATION_LOGIN_FORM`, `DAST_BROWSER_AUTH_REPORT`, `DAST_INCLUDE_ALPHA_VULNERABILITIES`, `DAST_PATHS_FILE`, `DAST_PATHS`, `DAST_ZAP_CLI_OPTIONS`, and `DAST_ZAP_LOG_CONFIGURATION` are also compatible with browser-based crawler scans. - -#### Selectors - -Selectors are used by CI/CD variables to specify the location of an element displayed on a page in a browser. -Selectors have the format `type`:`search string`. The crawler will search for the selector using the search string based on the type. - -| Selector type | Example | Description | -| ------------- | ------------------------------ | ----------- | -| `css` | `css:.password-field` | Searches for a HTML element having the supplied CSS selector. Selectors should be as specific as possible for performance reasons. | -| `id` | `id:element` | Searches for an HTML element with the provided element ID. | -| `name` | `name:element` | Searches for an HTML element with the provided element name. | -| `xpath` | `xpath://*[@id="my-button"]/a` | Searches for a HTML element with the provided XPath. Note that XPath searches are expected to be less performant than other searches. | -| None provided | `a.click-me` | Defaults to searching using a CSS selector. | - + ## Vulnerability detection While the browser-based crawler crawls modern web applications efficiently, vulnerability detection is still managed by the standard DAST/Zed Attack Proxy (ZAP) solution. @@ -100,9 +82,9 @@ This can come at a cost of increased scan time. You can manage the trade-off between coverage and scan time with the following measures: -- Limit the number of actions executed by the browser with the [variable](#available-variables) `DAST_BROWSER_MAX_ACTIONS`. The default is `10,000`. -- Limit the page depth that the browser-based crawler will check coverage on with the [variable](#available-variables) `DAST_BROWSER_MAX_DEPTH`. The crawler uses a breadth-first search strategy, so pages with smaller depth are crawled first. The default is `10`. -- Vertically scaling the runner and using a higher number of browsers with [variable](#available-variables) `DAST_BROWSER_NUMBER_OF_BROWSERS`. The default is `3`. +- Limit the number of actions executed by the browser with the [variable](#available-cicd-variables) `DAST_BROWSER_MAX_ACTIONS`. The default is `10,000`. +- Limit the page depth that the browser-based crawler will check coverage on with the [variable](#available-cicd-variables) `DAST_BROWSER_MAX_DEPTH`. The crawler uses a breadth-first search strategy, so pages with smaller depth are crawled first. The default is `10`. +- Vertically scaling the runner and using a higher number of browsers with [variable](#available-cicd-variables) `DAST_BROWSER_NUMBER_OF_BROWSERS`. The default is `3`. ## Debugging scans using logging @@ -116,10 +98,11 @@ For example, the following job definition enables the browsing module and the au include: - template: DAST.gitlab-ci.yml -variables: - DAST_WEBSITE: "https://my.site.com" - DAST_BROWSER_SCAN: "true" - DAST_BROWSER_LOG: "brows:debug,auth:debug" +dast: + variables: + DAST_WEBSITE: "https://my.site.com" + DAST_BROWSER_SCAN: "true" + DAST_BROWSER_LOG: "brows:debug,auth:debug" ``` ### Log message format diff --git a/doc/user/application_security/dast/img/dast_auth_browser_scan_highlight.png b/doc/user/application_security/dast/img/dast_auth_browser_scan_highlight.png Binary files differnew file mode 100644 index 00000000000..132c9f9c991 --- /dev/null +++ b/doc/user/application_security/dast/img/dast_auth_browser_scan_highlight.png diff --git a/doc/user/application_security/dast/img/dast_auth_browser_scan_search_elements.png b/doc/user/application_security/dast/img/dast_auth_browser_scan_search_elements.png Binary files differnew file mode 100644 index 00000000000..4e1dca626bc --- /dev/null +++ b/doc/user/application_security/dast/img/dast_auth_browser_scan_search_elements.png diff --git a/doc/user/application_security/dast/img/dast_auth_report.jpg b/doc/user/application_security/dast/img/dast_auth_report.jpg Binary files differnew file mode 100644 index 00000000000..5d9d98045ef --- /dev/null +++ b/doc/user/application_security/dast/img/dast_auth_report.jpg diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 1093e7cfabd..675d01373d4 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -16,40 +16,161 @@ Dynamic Application Security Testing (DAST) examines applications for vulnerabilities like these in deployed environments. DAST uses the open source tool [OWASP Zed Attack Proxy](https://www.zaproxy.org/) for analysis. +After DAST creates its report, GitLab evaluates it for discovered +vulnerabilities between the source and target branches. Relevant +findings are noted in the merge request. + +The comparison logic uses only the latest pipeline executed for the target +branch's base commit. Running the pipeline on other commits has no effect on +the merge request. + NOTE: To learn how four of the top six attacks were application-based and how to protect your organization, download our ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) whitepaper. -You can use DAST to examine your web applications: +## DAST application analysis -- When initiated by a merge request, running as CI/CD pipeline job. -- On demand, outside the CI/CD pipeline. +DAST can analyze applications in two ways: -After DAST creates its report, GitLab evaluates it for discovered -vulnerabilities between the source and target branches. Relevant -findings are noted in the merge request. +- Passive scan only (DAST default). DAST executes + [ZAP's Baseline Scan](https://www.zaproxy.org/docs/docker/baseline-scan/) and doesn't + actively attack your application. +- Passive and active scan. DAST can be [configured](#full-scan) to also perform an active scan + to attack your application and produce a more extensive security report. It can be very + useful when combined with [Review Apps](../../../ci/review_apps/index.md). -The comparison logic uses only the latest pipeline executed for the target -branch's base commit. Running the pipeline on other commits has no effect on -the merge request. +NOTE: +A pipeline may consist of multiple jobs, including SAST and DAST scanning. If any job +fails to finish for any reason, the security dashboard doesn't show DAST scanner output. For +example, if the DAST job finishes but the SAST job fails, the security dashboard doesn't show DAST +results. On failure, the analyzer outputs an +[exit code](../../../development/integrations/secure.md#exit-code). -## Prerequisite +## Prerequisites -To use DAST, ensure you're using GitLab Runner with the +- [GitLab Runner](../../../ci/runners/README.md) available, with the [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). +- Target application deployed. For more details, read [Deployment options](#deployment-options). + +### Deployment options + +Depending on the complexity of the target application, there are a few options as to how to deploy and configure +the DAST template. We provided a set of example applications with their configurations in our +[DAST demonstrations](https://gitlab.com/gitlab-org/security-products/demos/dast/) project. + +#### Review Apps + +Review Apps are the most involved method of deploying your DAST target application. To assist in the process, +we created a Review App deployment using Google Kubernetes Engine (GKE). This example can be found in our +[Review Apps - GKE](https://gitlab.com/gitlab-org/security-products/demos/dast/review-app-gke) project, along with detailed +instructions in the [README.md](https://gitlab.com/gitlab-org/security-products/demos/dast/review-app-gke/-/blob/master/README.md) +on how to configure Review Apps for DAST. + +#### Docker Services + +If your application utilizes Docker containers you have another option for deploying and scanning with DAST. +After your Docker build job completes and your image is added to your container registry, you can use the image as a +[service](../../../ci/services/index.md). + +By using service definitions in your `gitlab-ci.yml`, you can scan services with the DAST analyzer. + +```yaml +stages: + - build + - dast + +include: + - template: DAST.gitlab-ci.yml + +# Deploys the container to the GitLab container registry +deploy: + services: + - name: docker:dind + alias: dind + image: docker:19.03.5 + stage: build + script: + - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY + - docker pull $CI_REGISTRY_IMAGE:latest || true + - docker build --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --tag $CI_REGISTRY_IMAGE:latest . + - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA + - docker push $CI_REGISTRY_IMAGE:latest + +services: # use services to link your app container to the dast job + - name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA + alias: yourapp + +variables: + DAST_FULL_SCAN_ENABLED: "true" # do a full scan + DAST_ZAP_USE_AJAX_SPIDER: "true" # use the ajax spider +``` + +Most applications depend on multiple services such as databases or caching services. By default, services defined in the services fields cannot communicate +with each another. To allow communication between services, enable the `FF_NETWORK_PER_BUILD` [feature flag](https://docs.gitlab.com/runner/configuration/feature-flags.html#available-feature-flags). + +```yaml +variables: + FF_NETWORK_PER_BUILD: "true" # enable network per build so all services can communicate on the same network + +services: # use services to link the container to the dast job + - name: mongo:latest + alias: mongo + - name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA + alias: yourapp +``` + +## DAST run options + +You can use DAST to examine your web application: + +- Automatically, initiated by a merge request. +- Manually, initiated on demand. + +Some of the differences between these run options: -## Enable DAST +| Automatic scan | On-demand scan | +|:-----------------------------------------------------------------|:------------------------------| +| DAST scan is initiated by a merge request. | DAST scan is initiated manually, outside the DevOps life cycle. | +| CI/CD variables are sourced from `.gitlab-ci.yml`. | CI/CD variables are provided in the UI. | +| All [DAST CI/CD variables](#available-cicd-variables) available. | Subset of [DAST CI/CD variables](#available-cicd-variables) available. | +| `DAST.gitlab-ci.yml` template. | `DAST-On-Demand-Scan.gitlab-ci.yml` template. | -To enable DAST, either: +### Enable automatic DAST run + +To enable DAST to run automatically, either: - Enable [Auto DAST](../../../topics/autodevops/stages.md#auto-dast) (provided by [Auto DevOps](../../../topics/autodevops/index.md)). -- Manually [include the DAST template](#include-the-dast-template) in your existing +- [Include the DAST template](#include-the-dast-template) in your existing `.gitlab-ci.yml` file. -### Include the DAST template +### DAST job order + +When using the `DAST.gitlab-ci.yml` template, the `dast` stage is run last as shown in +the example below. To ensure DAST scans the latest code, deploy your application +in a stage before the `dast` stage. + +```yaml + stages: + - build + - test + - deploy + - dast +``` + +Be aware that if your pipeline is configured to deploy to the same webserver in +each run, running a pipeline while another is still running could cause a race condition +where one pipeline overwrites the code from another pipeline. The site to be scanned +should be excluded from changes for the duration of a DAST scan. +The only changes to the site should be from the DAST scanner. Be aware that any +changes that users, scheduled tasks, database changes, code changes, other pipelines, or other scanners make to +the site during a scan could lead to inaccurate results. + +#### 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. 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 @@ -59,7 +180,7 @@ To include the DAST template: 1. Select the CI/CD template you want to use: - - [`DAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml): + - [`DAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml): Stable version of the DAST CI/CD template. - [`DAST.latest.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST.latest.gitlab-ci.yml): Latest version of the DAST template. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254325) @@ -119,7 +240,7 @@ To include the DAST template: ``` You can see an example of this in our - [Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml) + [Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml) file. The included template creates a `dast` job in your CI/CD pipeline and scans @@ -146,182 +267,12 @@ page. #### Crawling web applications dependent on JavaScript -GitLab has released a new browser-based crawler, an add-on to DAST that uses a browser to crawl web applications for content. This crawler replaces the standard DAST Spider and Ajax Crawler. +GitLab has released a new browser-based crawler, an add-on to DAST that uses a browser to crawl web applications for content. This crawler replaces the standard DAST Spider and Ajax Crawler, and uses the same authentication mechanisms as a normal DAST scan. The browser-based crawler crawls websites by browsing web pages as a user would. This approach works well with web applications that make heavy use of JavaScript, such as Single Page Applications. For more details, including setup instructions, see [DAST browser-based crawler](browser_based.md). -## Deployment options - -Depending on the complexity of the target application, there are a few options as to how to deploy and configure -the DAST template. A set of example applications with their configurations have been made available in our -[DAST demonstrations](https://gitlab.com/gitlab-org/security-products/demos/dast/) project. - -### Review Apps - -Review Apps are the most involved method of deploying your DAST target application. To assist in the process, -we created a Review App deployment using Google Kubernetes Engine (GKE). This example can be found in our -[Review Apps - GKE](https://gitlab.com/gitlab-org/security-products/demos/dast/review-app-gke) project along with detailed -instructions in the [README.md](https://gitlab.com/gitlab-org/security-products/demos/dast/review-app-gke/-/blob/master/README.md) -on how to configure Review Apps for DAST. - -### Docker Services - -If your application utilizes Docker containers you have another option for deploying and scanning with DAST. -After your Docker build job completes and your image is added to your container registry, you can utilize the image as a -[service](../../../ci/services/index.md). - -By using service definitions in your `gitlab-ci.yml`, you can scan services with the DAST analyzer. - -```yaml -stages: - - build - - dast - -include: - - template: DAST.gitlab-ci.yml - -# Deploys the container to the GitLab container registry -deploy: - services: - - name: docker:dind - alias: dind - image: docker:19.03.5 - stage: build - script: - - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY - - docker pull $CI_REGISTRY_IMAGE:latest || true - - docker build --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --tag $CI_REGISTRY_IMAGE:latest . - - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA - - docker push $CI_REGISTRY_IMAGE:latest - -services: # use services to link your app container to the dast job - - name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA - alias: yourapp - -variables: - DAST_FULL_SCAN_ENABLED: "true" # do a full scan - DAST_ZAP_USE_AJAX_SPIDER: "true" # use the ajax spider -``` - -Most applications depend on multiple services such as databases or caching services. By default, services defined in the services fields cannot communicate -with each another. To allow communication between services, enable the `FF_NETWORK_PER_BUILD` [feature flag](https://docs.gitlab.com/runner/configuration/feature-flags.html#available-feature-flags). - -```yaml -variables: - FF_NETWORK_PER_BUILD: "true" # enable network per build so all services can communicate on the same network - -services: # use services to link the container to the dast job - - name: mongo:latest - alias: mongo - - name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA - alias: yourapp -``` - -### DAST application analysis - -DAST can analyze applications in two ways: - -- Passive scan only (DAST default). DAST executes - [ZAP's Baseline Scan](https://www.zaproxy.org/docs/docker/baseline-scan/) and doesn't - actively attack your application. -- Passive and active scan. DAST can be [configured](#full-scan) to also perform an active scan - to attack your application and produce a more extensive security report. It can be very - useful when combined with [Review Apps](../../../ci/review_apps/index.md). - -Note that a pipeline may consist of multiple jobs, including SAST and DAST scanning. If any job -fails to finish for any reason, the security dashboard doesn't show DAST scanner output. For -example, if the DAST job finishes but the SAST job fails, the security dashboard doesn't show DAST -results. On failure, the analyzer outputs an -[exit code](../../../development/integrations/secure.md#exit-code). - -#### DAST job order - -When using the `DAST.gitlab-ci.yml` template, the `dast` job is run last as shown in -the example below. To ensure DAST is scanning the latest code, your CI pipeline -should deploy changes to the web server in one of the jobs preceding the `dast` job. - -```yaml -stages: - - build - - test - - deploy - - dast -``` - -Be aware that if your pipeline is configured to deploy to the same webserver in -each run, running a pipeline while another is still running could cause a race condition -where one pipeline overwrites the code from another pipeline. The site to be scanned -should be excluded from changes for the duration of a DAST scan. -The only changes to the site should be from the DAST scanner. Be aware that any -changes that users, scheduled tasks, database changes, code changes, other pipelines, or other scanners make to -the site during a scan could lead to inaccurate results. - -### Hide sensitive information - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in GitLab 13.1. - -HTTP request and response headers may contain sensitive information, including cookies and -authorization credentials. By default, the following headers are masked: - -- `Authorization`. -- `Proxy-Authorization`. -- `Set-Cookie` (values only). -- `Cookie` (values only). - -Using the [`DAST_MASK_HTTP_HEADERS` CI/CD variable](#available-variables), you can list the -headers whose values you want masked. For details on how to mask headers, see -[Customizing the DAST settings](#customizing-the-dast-settings). - -### Authentication - -It's also possible to authenticate the user before performing the DAST checks. - -NOTE: -We highly recommended that you configure the scanner to authenticate to the application, -otherwise it cannot check most of the application for security risks, as most -of your application is likely not accessible without authentication. It is also recommended -that you periodically confirm the scanner's authentication is still working as this tends to break over -time due to authentication changes to the application. - -Create masked CI/CD variables to pass the credentials that DAST uses. -To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables). -Note that the key of the username variable must be `DAST_USERNAME` -and the key of the password variable must be `DAST_PASSWORD`. - -After DAST has authenticated with the application, all cookies are collected from the web browser. -For each cookie a matching session token is created for use by ZAP. This ensures ZAP is recognized -by the application as correctly authenticated. - -Other variables that are related to authenticated scans are: - -```yaml -include: - - template: DAST.gitlab-ci.yml - -variables: - DAST_WEBSITE: https://example.com - DAST_AUTH_URL: https://example.com/sign-in - DAST_USERNAME_FIELD: session[user] # the name of username field at the sign-in HTML form - DAST_PASSWORD_FIELD: session[password] # the name of password field at the sign-in HTML form - DAST_SUBMIT_FIELD: login # the `id` or `name` of the element that when clicked will submit the login form or the password form of a multi-page login process - DAST_FIRST_SUBMIT_FIELD: next # the `id` or `name` of the element that when clicked will submit the username form of a multi-page login process - DAST_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between - DAST_AUTH_VERIFICATION_URL: http://example.com/loggedin_page # optional, a URL only accessible to logged in users that DAST can use to confirm successful authentication -``` - -The results are saved as a -[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast) -that you can later download and analyze. -Due to implementation limitations, we always take the latest DAST artifact available. - -WARNING: -**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. - ### Full scan DAST can be configured to perform [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan), which @@ -338,126 +289,6 @@ variables: If your DAST job exceeds the job timeout and you need to reduce the scan duration, we shared some tips for optimizing DAST scans in a [blog post](https://about.gitlab.com/blog/2020/08/31/how-to-configure-dast-full-scans-for-complex-web-applications/). -#### Domain validation - -WARNING: -In GitLab 13.8, domain validation, outside of the new on-demand scan site profile validation, was deprecated. In GitLab 14.0, domain validation in CI/CD jobs will be permanently removed. - -The DAST job can be run anywhere, which means you can accidentally hit live web servers -and potentially damage them. You could even take down your production environment. -For that reason, you should use domain validation. - -Domain validation is not required by default. It can be required by setting the -[CI/CD variable](#available-variables) `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` to `"true"`. - -```yaml -include: - - template: DAST.gitlab-ci.yml - -variables: - DAST_FULL_SCAN_ENABLED: "true" - DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED: "true" -``` - -Since ZAP full scan actively attacks the target application, DAST sends a ping -to the target (normally defined in `DAST_WEBSITE` or `environment_url.txt`) beforehand. - -- If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is `false` or unset, the scan - proceeds unless the response to the ping includes a `Gitlab-DAST-Permission` - header with a value of `deny`. -- If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is `true`, the scan exits - unless the response to the ping includes a `Gitlab-DAST-Permission` header with - a value of `allow`. - -Here are some examples of adding the `Gitlab-DAST-Permission` header to a response -in Rails, Django, and Node (with Express). - -##### Ruby on Rails - -Here's how you would add a -[custom header in Ruby on Rails](https://guides.rubyonrails.org/action_controller_overview.html#setting-custom-headers): - -```ruby -class DastWebsiteTargetController < ActionController::Base - def dast_website_target - response.headers['Gitlab-DAST-Permission'] = 'allow' - - head :ok - end -end -``` - -##### Django - -Here's how you would add a -[custom header in Django](https://docs.djangoproject.com/en/2.2/ref/request-response/#setting-header-fields): - -```python -class DastWebsiteTargetView(View): - def head(self, *args, **kwargs): - response = HttpResponse() - response['Gitlab-Dast-Permission'] = 'allow' - - return response -``` - -##### Node (with Express) - -Here's how you would add a -[custom header in Node (with Express)](http://expressjs.com/en/5x/api.html#res.append): - -```javascript -app.get('/dast-website-target', function(req, res) { - res.append('Gitlab-DAST-Permission', 'allow') - res.send('Respond to DAST ping') -}) -``` - -##### Domain validation header via a proxy - -It's also possible to add the `Gitlab-DAST-Permission` header via a proxy. - -###### NGINX - -The following configuration allows NGINX to act as a reverse proxy and add the -`Gitlab-DAST-Permission` [header](http://nginx.org/en/docs/http/ngx_http_headers_module.html#add_header): - -```nginx -# default.conf -server { - listen 80; - server_name localhost; - - location / { - proxy_pass http://test-application; - add_header Gitlab-DAST-Permission allow; - } -} -``` - -###### Apache - -Apache can also be used as a [reverse proxy](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html) -to add the `Gitlab-DAST-Permission` [header](https://httpd.apache.org/docs/current/mod/mod_headers.html). - -To do so, add the following lines to `httpd.conf`: - -```plaintext -# httpd.conf -LoadModule proxy_module modules/mod_proxy.so -LoadModule proxy_connect_module modules/mod_proxy_connect.so -LoadModule proxy_http_module modules/mod_proxy_http.so - -<VirtualHost *:80> - ProxyPass "/" "http://test-application.com/" - ProxyPassReverse "/" "http://test-application.com/" - Header set Gitlab-DAST-Permission "allow" -</VirtualHost> -``` - -[This snippet](https://gitlab.com/gitlab-org/security-products/dast/snippets/1894732) contains a complete `httpd.conf` file -configured to act as a remote proxy and add the `Gitlab-DAST-Permission` header. - ### API scan > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10928) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. @@ -661,7 +492,7 @@ is no longer supported. When overriding the template, you must use [`rules`](../ The DAST settings can be changed through CI/CD variables by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. -These variables are documented in [available variables](#available-variables). +These variables are documented in [available variables](#available-cicd-variables). For example: @@ -677,47 +508,296 @@ variables: Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable takes precedence. -### Available variables +#### Enabling and disabling rules + +A complete list of the rules that DAST uses to scan for vulnerabilities can be +found in the [ZAP docs](https://www.zaproxy.org/docs/alerts/). + +`DAST_EXCLUDE_RULES` disables the rules with the given IDs. + +`DAST_ONLY_INCLUDE_RULES` restricts the set of rules used in the scan to +those with the given IDs. + +`DAST_EXCLUDE_RULES` and `DAST_ONLY_INCLUDE_RULES` are mutually exclusive and a +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/master/src/config/exclude_rules.yml). + +### Hide sensitive information + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in GitLab 13.1. + +HTTP request and response headers may contain sensitive information, including cookies and +authorization credentials. By default, the following headers are masked: + +- `Authorization`. +- `Proxy-Authorization`. +- `Set-Cookie` (values only). +- `Cookie` (values only). + +Using the [`DAST_MASK_HTTP_HEADERS` CI/CD variable](#available-cicd-variables), you can list the +headers whose values you want masked. For details on how to mask headers, see +[Customizing the DAST settings](#customizing-the-dast-settings). + +## Authentication + +NOTE: +We highly recommend you configure the scanner to authenticate to the application. If you don't, it cannot check most of the application for security risks, as most +of your application is likely not accessible without authentication. We also recommend +you periodically confirm the scanner's authentication is still working, as this tends to break over +time due to authentication changes to the application. + +Create masked CI/CD variables to pass the credentials that DAST uses. +To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables). +The key of the username variable must be `DAST_USERNAME`, +and the key of the password variable must be `DAST_PASSWORD`. + +After DAST has authenticated with the application, all cookies are collected from the web browser. +For each cookie a matching session token is created for use by ZAP. This ensures ZAP is recognized +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. + +Variables that are related to authenticated scans are: + +```yaml +include: + - template: DAST.gitlab-ci.yml + +dast: + variables: + DAST_WEBSITE: "https://example.com" + DAST_AUTH_URL: "https://login.example.com/" + DAST_USERNAME: "admin" + DAST_PASSWORD: "P@55w0rd!" + DAST_USERNAME_FIELD: "name:username" # a selector describing the element containing the username field at the sign-in HTML form + DAST_PASSWORD_FIELD: "id:password" # a selector describing the element containing the password field at the sign-in HTML form + DAST_FIRST_SUBMIT_FIELD: "css:button[type='user-submit']" # optional, the selector of the element that when clicked will submit the username form of a multi-page login process + DAST_SUBMIT_FIELD: "css:button[type='submit']" # the selector of the element that when clicked will submit the login form or the password form of a multi-page login process + DAST_EXCLUDE_URLS: "http://example.com/sign-out" # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between + DAST_AUTH_VERIFICATION_URL: "http://example.com/loggedin_page" # optional, used to verify authentication is successful by expecting this URL once the login form has been submitted + DAST_AUTH_VERIFICATION_SELECTOR: "css:.user-profile" # optional, used to verify authentication is successful by expecting a selector to be present on the page once the login form has been submitted + DAST_AUTH_VERIFICATION_LOGIN_FORM: "true" # optional, used to verify authentication is successful by ensuring there are no login forms on the page once the login form has been submitted + DAST_AUTH_REPORT: "true" # optionally output an authentication debug report +``` + +WARNING: +**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. + +### Log in using automatic detection of the login form + +By providing a `DAST_USERNAME`, `DAST_PASSWORD`, and `DAST_AUTH_URL`, DAST will attempt to authenticate to the +target application by locating the login form based on a determination about whether or not the form contains username or password fields. + +Automatic detection is "best-effort", and depending on the application being scanned may provide either a resilient login experience or one that fails to authenticate the user. + +Login process: + +1. The `DAST_AUTH_URL` is loaded into the browser, and any forms on the page are located. + 1. If a form contains a username and password field, `DAST_USERNAME` and `DAST_PASSWORD` is inputted into the respective fields, the form submit button is clicked and the user is logged in. + 1. If a form contains only a username field, it is assumed that the login form is multi-step. + 1. The `DAST_USERNAME` is inputted into the username field and the form submit button is clicked. + 1. The subsequent pages loads where it is expected that a form exists and contains a password field. If found, `DAST_PASSWORD` is inputted, form submit button is clicked and the user is logged in. + +### Log in using explicit selection of the login form + +By providing a `DAST_USERNAME_FIELD`, `DAST_PASSWORD_FIELD`, and `DAST_SUBMIT_FIELD`, in addition to the fields required for automatic login, +DAST will attempt to authenticate to the target application by locating the login form based on the selectors provided. +Most applications will benefit from this approach to authentication. + +Login process: + +1. The `DAST_AUTH_URL` is loaded into the browser, and any forms on the page are located. + 1. If the `DAST_FIRST_SUBMIT_FIELD` is not defined, then `DAST_USERNAME` is inputted into `DAST_USERNAME_FIELD`, `DAST_PASSWORD` is inputted into `DAST_PASSWORD_FIELD`, `DAST_SUBMIT_FIELD` is clicked and the user is logged in. + 1. If the `DAST_FIRST_SUBMIT_FIELD` is defined, then it is assumed that the login form is multi-step. + 1. The `DAST_USERNAME` is inputted into the `DAST_USERNAME_FIELD` field and the `DAST_FIRST_SUBMIT_FIELD` is clicked. + 1. The subsequent pages loads where the `DAST_PASSWORD` is inputted into the `DAST_PASSWORD_FIELD` field, the `DAST_SUBMIT_FIELD` is clicked and the user is logged in. + +### Verifying successful login + +Once the login form has been submitted, DAST determines if the login was successful. Unsuccessful attempts at authentication cause the scan to halt. + +Following the submission of the login form, authentication is determined to be unsuccessful when: + +- A `400` or `500` series HTTP response status code is returned. +- A new cookie/browser storage value determined to be sufficiently random has not been set. + +In addition to these checks, the user can configure their own verification checks. +Each of the following checks can be used in conjunction with one another, if none are configured by default the presence of a login form is checked. + +#### Verifying based on the URL + +When `DAST_AUTH_VERIFICATION_URL` is configured, the URL displayed in the browser tab post login form submission is directly compared to the URL in the CI/CD variable. +If these are not exactly the same, authentication is deemed to be unsuccessful. + +For example: + +```yaml +include: + - template: DAST.gitlab-ci.yml + +dast: + variables: + DAST_WEBSITE: "https://example.com" + ... + DAST_AUTH_VERIFICATION_URL: "https://example.com/user/welcome" +``` + +#### Verify based on presence of an element + +When `DAST_AUTH_VERIFICATION_SELECTOR` is configured, the page displayed in the browser tab is searched for an element described by the selector in the CI/CD variable. +If no element is found, authentication is deemed to be unsuccessful. + +For example: + +```yaml +include: + - template: DAST.gitlab-ci.yml + +dast: + variables: + DAST_WEBSITE: "https://example.com" + ... + DAST_AUTH_VERIFICATION_SELECTOR: "css:.welcome-user" +``` + +#### Verify based on presence of a login form + +When `DAST_AUTH_VERIFICATION_LOGIN_FORM` is configured, the page displayed in the browser tab is searched for a form that is detected to be a login form. +If any such form is found, authentication is deemed to be unsuccessful. + +For example: + +```yaml +include: + - template: DAST.gitlab-ci.yml + +dast: + variables: + DAST_WEBSITE: "https://example.com" + ... + DAST_AUTH_VERIFICATION_LOGIN_FORM: "true" +``` + +### Configure the authentication debug output + +It is often difficult to understand the cause of an authentication failure when running DAST in a CI/CD pipeline. +To assist users in debugging authentication issues, a debug report can be generated and saved as a job artifact. +This HTML report contains all steps made during the login process, along with HTTP requests and responses, the Document Object Model (DOM) and screenshots. + + + +An example configuration where the authentication debug report is exported may look like the following: + +```yaml +dast: + variables: + DAST_WEBSITE: "https://example.com" + ... + DAST_AUTH_REPORT: "true" + artifacts: + paths: [gl-dast-debug-auth-report.html] +``` + +### Available CI/CD variables DAST can be [configured](#customizing-the-dast-settings) using CI/CD variables. -| CI/CD variable | Type | Description | -|------------------------------| --------|-------------| -| `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | -| `DAST_WEBSITE` | URL | The URL of the website to scan. `DAST_API_OPENAPI` must be specified if this is omitted. | -| `DAST_API_OPENAPI` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | -| `DAST_API_SPECIFICATION` | URL or string | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/290241) in GitLab 13.12 and replaced by `DAST_API_OPENAPI`. To be removed in GitLab 15.0. The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | -| `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | -| `DAST_AUTH_URL` | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. | -| `DAST_AUTH_VERIFICATION_URL` | URL | A URL only accessible to logged in users that DAST can use to confirm successful authentication. If provided, DAST will exit if it cannot access the URL. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207335) in GitLab 13.8. -| `DAST_USERNAME` | string | The username to authenticate to in the website. | -| `DAST_PASSWORD` | string | The password to authenticate to in the website. | -| `DAST_USERNAME_FIELD` | string | The name of username field at the sign-in HTML form. | -| `DAST_PASSWORD_FIELD` | string | The name of password field at the sign-in HTML form. | -| `DAST_SKIP_TARGET_CHECK` | boolean | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229067) in GitLab 13.8. | -| `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | -| `DAST_EXCLUDE_URLS` | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. | -| `DAST_FULL_SCAN_ENABLED` | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | -| `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/293595) in GitLab 13.8, to be removed in 14.0. Set to `true` to require [domain validation](#domain-validation) when running DAST full scans. Not supported for API scans. Default: `false` | -| `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false` | -| `DAST_API_HOST_OVERRIDE` | string | Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080` | -| `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). For example, `HTTP Parameter Override` has a rule ID of `10026`. **Note:** In earlier versions of GitLab the excluded rules were executed but alerts they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | -| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. | -| `DAST_REQUEST_HEADERS` | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | -| `DAST_DEBUG` | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_SPIDER_MINS` | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1.| -| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_USE_AJAX_SPIDER` | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | -| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | -| `DAST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when clicked submits the login form or the password form of a multi-page login process. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | -| `DAST_FIRST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when clicked submits the username form of a multi-page login process. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | -| `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` | -| `DAST_AUTH_EXCLUDE_URLS` | URLs | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/289959) in GitLab 13.8, to be removed in 14.0, and replaced by `DAST_EXCLUDE_URLS`. The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. | +| CI/CD variable | Type | Description | +|:--------------------------------------------|:--------------|:-----------------------------------| +| `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | +| `DAST_WEBSITE` (**1**) | URL | The URL of the website to scan. `DAST_API_OPENAPI` must be specified if this is omitted. | +| `DAST_API_OPENAPI` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | +| `DAST_API_SPECIFICATION` (**1**) | URL or string | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/290241) in GitLab 13.12 and replaced by `DAST_API_OPENAPI`. To be removed in GitLab 15.0. The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | +| `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | +| `DAST_AUTH_URL` (**1**) | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. | +| `DAST_AUTH_VERIFICATION_URL` (**1**) | URL | A URL only accessible to logged in users that DAST can use to confirm successful authentication. If provided, DAST exits if it cannot access the URL. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207335) in GitLab 13.8. | +| `DAST_USERNAME` (**1**) | string | The username to enter into the username field on the sign-in HTML form. | +| `DAST_PASSWORD` (**1**) | string | The password to enter into the password field on the sign-in HTML form. | +| `DAST_USERNAME_FIELD` (**1**) | selector | A selector describing the username field on the sign-in HTML form. Example: `id:user` | +| `DAST_PASSWORD_FIELD` (**1**) | selector | A selector describing the password field on the sign-in HTML form. Example: `css:.password-field` | +| `DAST_SKIP_TARGET_CHECK` | boolean | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229067) in GitLab 13.8. | +| `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | +| `DAST_EXCLUDE_URLS` (**1**) | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. | +| `DAST_FULL_SCAN_ENABLED` (**1**) | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | +| `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false` | +| `DAST_API_HOST_OVERRIDE` (**1**) | string | Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080` | +| `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | +| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). Cannot be used when `DAST_EXCLUDE_RULES` is set. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. | +| `DAST_REQUEST_HEADERS` (**1**) | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | +| `DAST_DEBUG` (**1**) | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_TARGET_AVAILABILITY_TIMEOUT` (**1**) | number | Time limit in seconds to wait for target availability. +| `DAST_SPIDER_MINS` (**1**) | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_USE_AJAX_SPIDER` (**1**) | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | +| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | +| `DAST_SUBMIT_FIELD` | selector | A selector describing the element that when clicked submits the login form, or the password form of a multi-page login process. Example: `xpath://input[@value='Login']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | +| `DAST_FIRST_SUBMIT_FIELD` | selector | A selector describing the element that when clicked submits the username form of a multi-page login process. Example: `.submit`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | +| `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` | +| `DAST_AGGREGATE_VULNERABILITIES` | boolean | Vulnerability aggregation is set to `true` by default. To disable this feature and see each vulnerability individually set to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254043) in GitLab 14.0. | +| `DAST_MAX_URLS_PER_VULNERABILITY` | number | The maximum number of URLs reported for a single vulnerability. `DAST_MAX_URLS_PER_VULNERABILITY` is set to `50` by default. To list all the URLs set to `0`. [Introduced](https://gitlab.com/gitlab-org/security-products/dast/-/merge_requests/433) in GitLab 13.12. | +| `DAST_AUTH_REPORT` | boolean | Used in combination with exporting the `gl-dast-debug-auth-report.html` artifact to aid in debugging authentication issues. | +| `DAST_AUTH_VERIFICATION_SELECTOR` | selector | Verifies successful authentication by checking for presence of a selector once the login form has been submitted. Example: `css:.user-photo` | +| `DAST_AUTH_VERIFICATION_LOGIN_FORM` | boolean | Verifies successful authentication by checking for the lack of a login form once the login form has been submitted. | + +1. DAST CI/CD variable available to an on-demand scan. + +#### Selectors + +Selectors are used by CI/CD variables to specify the location of an element displayed on a page in a browser. +Selectors have the format `type`:`search string`. The crawler will search for the selector using the search string based on the type. + +| Selector type | Example | Description | +| ------------- | ---------------------------------- | ----------- | +| `css` | `css:.password-field` | Searches for a HTML element having the supplied CSS selector. Selectors should be as specific as possible for performance reasons. | +| `id` | `id:element` | Searches for an HTML element with the provided element ID. | +| `name` | `name:element` | Searches for an HTML element with the provided element name. | +| `xpath` | `xpath://input[@id="my-button"]/a` | Searches for a HTML element with the provided XPath. Note that XPath searches are expected to be less performant than other searches. | +| None provided | `a.click-me` | Defaults to searching using a CSS selector. | + +##### Find selectors with Google Chrome + +Chrome DevTools element selector tool is an effective way to find a selector. + +1. Open Chrome and navigate to the page where you would like to find a selector, for example, the login page for your site. +1. Open the `Elements` tab in Chrome DevTools with the keyboard shortcut `Command + Shift + c` in macOS or `Ctrl + Shift + c` in Windows. +1. Select the `Select an element in the page to select it` tool. +  +1. Select the field on your page that you would like to know the selector for. +1. Once the tool is active, highlight a field you wish to view the details of. +  +1. Once highlighted, you can see the element's details, including attributes that would make a good candidate for a selector. + +In this example, the `id="user_login"` appears to be a good candidate. You can use this as a selector as the DAST username field by setting `DAST_USERNAME_FIELD: "css:[id=user_login]"`, or more simply, `DAST_USERNAME_FIELD: "id:user_login"`. + +##### Choose the right selector + +Judicious choice of selector leads to a scan that is resilient to the application changing. + +In order of preference, it is recommended to choose as selectors: + +- `id` fields. These are generally unique on a page, and rarely change. +- `name` fields. These are generally unique on a page, and rarely change. +- `class` values specific to the field, such as the selector `"css:.username"` for the `username` class on the username field. +- Presence of field specific data attributes, such as the selector, `"css:[data-username]"` when the `data-username` field has any value on the username field. +- Multiple `class` hierarchy values, such as the selector `"css:.login-form .username"` when there are multiple elements with class `username` but only one nested inside the element with the class `login-form`. + +When using selectors to locate specific fields we recommend you avoid searching on: + +- Any `id`, `name`, `attribute`, `class` or `value` that is dynamically generated. +- Generic class names, such as `column-10` and `dark-grey`. +- XPath searches as they are less performant than other selector searches. +- Unscoped searches, such as those beginning with `css:*` and `xpath://*`. ### DAST command-line options @@ -783,7 +863,7 @@ variables: ### Cloning the project's repository The DAST job does not require the project's repository to be present when running, so by default -[`GIT_STRATEGY`](../../../ci/runners/README.md#git-strategy) is set to `none`. +[`GIT_STRATEGY`](../../../ci/runners/configure_runners.md#git-strategy) is set to `none`. ### Debugging DAST jobs @@ -819,7 +899,7 @@ successfully run. For more information, see [Offline environments](../offline_de To use DAST in an offline environment, you need: -- GitLab Runner with the [`docker` or `kubernetes` executor](#prerequisite). +- GitLab Runner with the [`docker` or `kubernetes` executor](#prerequisites). - Docker Container Registry with a locally available copy of the DAST [container image](https://gitlab.com/gitlab-org/security-products/dast), found in the [DAST container registry](https://gitlab.com/gitlab-org/security-products/dast/container_registry). @@ -993,7 +1073,7 @@ A site profile contains the following: - **Target URL**: The URL that DAST runs against. - **Excluded URLs**: A comma-separated list of URLs to exclude from the scan. - **Request headers**: A comma-separated list of HTTP request headers, including names and values. These headers are added to every request made by DAST. -- **Authentication**: +- **Authentication**: - **Authenticated URL**: The URL of the page containing the sign-in HTML form on the target website. The username and password are submitted with the login form to create an authenticated scan. - **Username**: The username used to authenticate to the website. - **Password**: The password used to authenticate to the website. @@ -1217,11 +1297,6 @@ 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/master/test/end-to-end/expect). -There are two formats of data in the JSON report that are used side by side: - -- The proprietary ZAP format, which is planned to be deprecated. -- A common format that is planned to the default in the future. - ### Other formats Reports can also be generated in Markdown, HTML, and XML. These can be published as artifacts using the following configuration: diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 5e47f545ef9..9a6e1e73330 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -59,6 +59,7 @@ Examples of various configurations can be found here: - [Example HTTP Archive (HAR) project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/har-example) - [Example Postman Collection project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/postman-example) - [Example GraphQL project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/graphql-example) +- [Example SOAP project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/soap-example) WARNING: GitLab 14.0 will require that you place DAST API configuration files (for example, @@ -71,8 +72,8 @@ starting in GitLab 14.0, GitLab will not check your repository's root for config > Support for OpenAPI Specification using YAML format was > [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330583) in GitLab 14.0. -The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an API description format for REST APIs. -This section shows you how to configure API fuzzing using an OpenAPI Specification to provide information about the target API to test. +The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an API description format for REST APIs. +This section shows you how to configure API fuzzing using an OpenAPI Specification to provide information about the target API to test. OpenAPI Specifications are provided as a file system resource or URL. Both JSON and YAML OpenAPI formats are supported. DAST API uses an OpenAPI document to generate the request body. When a request body is required, @@ -85,7 +86,7 @@ the body generation is limited to these body types: Follow these steps to configure DAST API in GitLab with an OpenAPI specification: 1. To use DAST API, you must [include](../../../ci/yaml/README.md#includetemplate) - the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) + the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) that's provided as part of your GitLab installation. Add the following to your `.gitlab-ci.yml` file: @@ -136,7 +137,7 @@ Follow these steps to configure DAST API in GitLab with an OpenAPI specification dynamic environments. To run DAST API against an app dynamically created during a GitLab CI/CD pipeline, have the app persist its URL in an `environment_url.txt` file. DAST API automatically parses that file to find its scan target. You can see an - [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). + [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). Here's an example of using `DAST_API_TARGET_URL`: @@ -184,7 +185,7 @@ Follow these steps to configure DAST API to use a HAR file that provides informa target API to test: 1. To use DAST API, you must [include](../../../ci/yaml/README.md#includetemplate) - the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) + the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) that's provided as part of your GitLab installation. To do so, add the following to your `.gitlab-ci.yml` file: @@ -235,7 +236,7 @@ target API to test: dynamic environments. To run DAST API against an app dynamically created during a GitLab CI/CD pipeline, have the app persist its URL in an `environment_url.txt` file. DAST API automatically parses that file to find its scan target. You can see an - [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). + [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). Here's an example of using `DAST_API_TARGET_URL`: @@ -284,7 +285,7 @@ Follow these steps to configure DAST API to use a Postman Collection file that p information about the target API to test: 1. To use DAST API, you must [include](../../../ci/yaml/README.md#includetemplate) - the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) + the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) that's provided as part of your GitLab installation. To do so, add the following to your `.gitlab-ci.yml` file: @@ -334,7 +335,7 @@ information about the target API to test: dynamic environments. To run DAST API against an app dynamically created during a GitLab CI/CD pipeline, have the app persist its URL in an `environment_url.txt` file. DAST API automatically parses that file to find its scan target. You can see an - [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). + [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). Here's an example of using `DAST_API_TARGET_URL`: @@ -634,6 +635,7 @@ can be added, removed, and modified by creating a custom configuration. | `DAST_API_TARGET_URL` | Base URL of API testing target. | |[`DAST_API_CONFIG`](#configuration-files) | DAST API configuration file. Defaults to `.gitlab-dast-api.yml`. | |[`DAST_API_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | +|[`FUZZAPI_EXCLUDE_PATHS`](#exclude-paths) | Exclude API URL paths from testing. | |[`DAST_API_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | |[`DAST_API_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | |[`DAST_API_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | @@ -847,7 +849,7 @@ variables: ``` In this example `.gitlab-ci.yml`, the `SECRET_OVERRIDES` variable provides the JSON. This is a -[group or instance level CI/CD variable defined in the UI](../../../ci/variables/README.md#instance-cicd-variables): +[group or instance level CI/CD variable defined in the UI](../../../ci/variables/README.md#add-a-cicd-variable-to-an-instance): ```yaml stages: @@ -893,6 +895,47 @@ variables: DAST_API_OVERRIDES_INTERVAL: 300 ``` +### Exclude Paths + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211892) in GitLab 14.0. + +When testing an API it can be useful to exclude certain paths. For example, you might exclude testing of an authentication service or an older version of the API. To exclude paths, use the `FUZZAPI_EXCLUDE_PATHS` CI/CD variable . This variable is specified in your `.gitlab-ci.yml` file. To exclude multiple paths, separate entries using the `;` character. In the provided paths you can use a single character wildcard `?` and `*` for a multiple character wildcard. + +To verify the paths are excluded, review the `Tested Operations` and `Excluded Operations` portion of the job output. You should not see any excluded paths listed under `Tested Operations`. + +```plaintext +2021-05-27 21:51:08 [INF] API Security: --[ Tested Operations ]------------------------- +2021-05-27 21:51:08 [INF] API Security: 201 POST http://target:7777/api/users CREATED +2021-05-27 21:51:08 [INF] API Security: ------------------------------------------------ +2021-05-27 21:51:08 [INF] API Security: --[ Excluded Operations ]----------------------- +2021-05-27 21:51:08 [INF] API Security: GET http://target:7777/api/messages +2021-05-27 21:51:08 [INF] API Security: POST http://target:7777/api/messages +2021-05-27 21:51:08 [INF] API Security: ------------------------------------------------ +``` + +#### Examples + +This example excludes the `/auth` resource. This does not exclude child resources (`/auth/child`). + +```yaml +variables: + DAST_API_EXCLUDE_PATHS=/auth +``` + +To exclude `/auth`, and child resources (`/auth/child`), we use a wildcard. + +```yaml +variables: + DAST_API_EXCLUDE_PATHS=/auth* +``` + +To exclude multiple paths we use the `;` character. In this example we exclude `/auth*` and `/v1/*`. + +```yaml +variables: + DAST_API_EXCLUDE_PATHS=/auth*;/v1/* +``` + ## Running your first scan When configured correctly, a CI/CD pipeline contains a `dast` stage and an `dast_api` job. The job only fails when an invalid configuration is provided. During normal operation, the job always succeeds even if vulnerabilities are identified during testing. @@ -1076,7 +1119,7 @@ The DAST API engine outputs an error message when it cannot establish a connecti **Solution** - Remove the `DAST_API_API` variable from the `.gitlab-ci.yml` file. The value will be inherited from the DAST API CI/CD template. We recommend this method instead of manually setting a value. -- If removing the variable is not possible, check to see if this value has changed in the latest version of the [DAST API CI/CD template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml). If so, update the value in the `.gitlab-ci.yml` file. +- If removing the variable is not possible, check to see if this value has changed in the latest version of the [DAST API CI/CD template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml). If so, update the value in the `.gitlab-ci.yml` file. ### Application cannot determine the base URL for the target API @@ -1088,7 +1131,7 @@ The best-suited solution will depend on whether or not your target API changes f #### Static environment solution -This solution is for pipelines in which the target API URL doesn't change (is static). +This solution is for pipelines in which the target API URL doesn't change (is static). **Add environmental variable** @@ -1105,7 +1148,7 @@ include: #### Dynamic environment solutions -In a dynamic environment your target API changes for each different deployment. In this case, there is more than one possible solution, we recommend you use the `environment_url.txt` file when dealing with dynamic environments. +In a dynamic environment your target API changes for each different deployment. In this case, there is more than one possible solution, we recommend you use the `environment_url.txt` file when dealing with dynamic environments. **Use environment_url.txt** diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index 0faa33e0123..fae0f457a20 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -80,7 +80,7 @@ include: template: Dependency-Scanning.gitlab-ci.yml variables: - DS_EXCLUDED_ANALYZERS: "gemnasium, gemansium-maven, gemnasium-python, bundler-audit, retire.js" + DS_EXCLUDED_ANALYZERS: "gemnasium, gemnasium-maven, gemnasium-python, bundler-audit, retire.js" ``` This is used when one totally relies on [custom analyzers](#custom-analyzers). diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 8e23db89dfd..96fc085e7c6 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -91,7 +91,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) To enable dependency scanning for GitLab 11.9 and later, you must [include](../../../ci/yaml/README.md#includetemplate) the -[`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml) +[`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml) that is provided as a part of your GitLab installation. For GitLab versions earlier than 11.9, you can copy and use the job as defined that template. @@ -112,7 +112,7 @@ always take the latest dependency scanning artifact available. ### Customizing the dependency scanning settings -The dependency scanning settings can be changed through [CI/CD variables](#available-variables) by using the +The dependency scanning settings can be changed through [CI/CD variables](#available-cicd-variables) by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. For example: @@ -157,7 +157,7 @@ gemnasium-dependency_scanning: dependencies: ["build"] ``` -### Available variables +### Available CI/CD variables Dependency scanning can be [configured](#customizing-the-dependency-scanning-settings) using environment variables. @@ -189,7 +189,7 @@ The following variables are used for configuring specific analyzers (used for a | `GEMNASIUM_DB_REMOTE_URL` | `gemnasium` | `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` | Repository URL for fetching the Gemnasium database. | | `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. | -| `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`, `15`. Maven and Gradle use the Java version specified by this value. | +| `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`, `15`, `16`. Maven and Gradle use the Java version specified by this value (Dependency Scanning for Gradle does not currently support Java `16`). | | `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`. | @@ -231,11 +231,11 @@ Read more on [how to use private Maven repositories](../index.md#using-private-m Once a vulnerability is found, you can interact with it. Read more on how to [address the vulnerabilities](../vulnerabilities/index.md). -## Solutions for vulnerabilities (auto-remediation) +## Solutions for vulnerabilities Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. Read more about the -[solutions for vulnerabilities](../vulnerabilities/index.md#remediate-a-vulnerability-automatically). +[solutions for vulnerabilities](../vulnerabilities/index.md#resolve-a-vulnerability). ## Security Dashboard diff --git a/doc/user/application_security/img/unconfigured_security_approval_rules_and_enabled_jobs_v13_4.png b/doc/user/application_security/img/unconfigured_security_approval_rules_and_enabled_jobs_v13_4.png Binary files differdeleted file mode 100644 index 7b04988afdb..00000000000 --- a/doc/user/application_security/img/unconfigured_security_approval_rules_and_enabled_jobs_v13_4.png +++ /dev/null diff --git a/doc/user/application_security/img/unconfigured_security_approval_rules_and_jobs_v13_4.png b/doc/user/application_security/img/unconfigured_security_approval_rules_and_jobs_v13_4.png Binary files differdeleted file mode 100644 index b9b6dd13294..00000000000 --- a/doc/user/application_security/img/unconfigured_security_approval_rules_and_jobs_v13_4.png +++ /dev/null diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 82a018c0ae9..bf812b25b5f 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -1,11 +1,11 @@ --- -stage: secure -group: secure +stage: Secure +group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- -# Application security **(ULTIMATE)** +# Secure your application **(ULTIMATE)** GitLab can check your application for security vulnerabilities including: @@ -92,7 +92,9 @@ For more details about each of the security scanning tools, see their respective By default, GitLab security scanners use `registry.gitlab.com/gitlab-org/security-products/analyzers` as the base address for Docker images. You can override this globally by setting the CI/CD variable -`SECURE_ANALYZERS_PREFIX` to another location. Note that this affects all scanners at once. +`SECURE_ANALYZERS_PREFIX` to another location. Note that this affects all scanners at once, except +the container-scanning analyzer which uses +`registry.gitlab.com/security-products/container-scanning` as its registry. ### Use security scanning tools with Pipelines for Merge Requests @@ -182,84 +184,51 @@ By default, the vulnerability report does not show vulnerabilities of `dismissed > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9928) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.2. -Merge Request Approvals can be configured to require approval from a member of your -security team when a merge request would introduce one of the following security issues: +You can implement merge request approvals to require approval by selected users or a group when a +merge request would introduce one of the following security issues: - A security vulnerability - A software license compliance violation -The security vulnerability threshold is defined as `high`, `critical`, or `unknown` severity. The -`Vulnerability-Check` approver group must approve merge requests that contain vulnerabilities. +When the Vulnerability-Check merge request rule is enabled, additional merge request approval +is required when the latest security report in a merge request: -When GitLab can assess vulnerability severity, the rating can be one of the following: - -- `unknown` -- `low` -- `medium` -- `high` -- `critical` +- Contains a vulnerability of `high`, `critical`, or `unknown` severity that is not present in the + target branch. Note that approval is still required for dismissed vulnerabilities. +- Is not generated during pipeline execution. -The rating `unknown` indicates that the underlying scanner doesn't contain or provide a severity -rating. +An approval is optional when the security report: -### Enabling Security Approvals within a project +- Contains no new vulnerabilities when compared to the target branch. +- Contains only new vulnerabilities of `low` or `medium` severity. -To enable the `Vulnerability-Check` or `License-Check` Security Approvals, a [project approval rule](../project/merge_requests/approvals/rules.md#add-an-approval-rule) -must be created. A [security scanner job](#security-scanning-tools) must be enabled for -`Vulnerability-Check`, and a [license scanning](../compliance/license_compliance/index.md#configuration) -job must be enabled for `License-Check`. When the proper jobs aren't configured, the following -appears: +When the License-Check merge request rule is enabled, additional approval is required if a merge +request contains a denied license. For more details, see [Enabling license approvals within a project](../compliance/license_compliance/index.md#enabling-license-approvals-within-a-project). - +### Enable the Vulnerability-Check rule -If at least one security scanner is enabled, you can enable the `Vulnerability-Check` approval rule. If a license scanning job is enabled, you can enable the `License-Check` rule. +Prerequisites: - +- At least one [security scanner job](#security-scanning-tools) must be enabled. +- Maintainer or Owner [role](../permissions.md#project-members-permissions). -For this approval group, you must set the number of approvals required to greater than zero. You -must have Maintainer or Owner [permissions](../permissions.md#project-members-permissions) -to manage approval rules. +For this approval group, you must set the number of approvals required to greater than zero. Follow these steps to enable `Vulnerability-Check`: -1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. -1. Click **Enable**, or **Edit**. +1. Go to your project and select **Settings > General**. +1. Expand **Merge request approvals**. +1. Select **Enable** or **Edit**. 1. Add or change the **Rule name** to `Vulnerability-Check` (case sensitive). - - +1. Set the **No. of approvals required** to greater than zero. +1. Select the **Target branch**. +1. Select the users or groups to provide approval. +1. Select **Add approval rule**. Once this group is added to your project, the approval rule is enabled for all merge requests. - Any code changes cause the approvals required to reset. -An approval is required when the latest security report in a merge request: - -- Contains a vulnerability of `high`, `critical`, or `unknown` severity that is not present in the - target branch. Note that approval is still required for dismissed vulnerabilities. -- Is not generated during pipeline execution. - -An approval is optional when the security report: - -- Contains no new vulnerabilities when compared to the target branch. -- Contains only new vulnerabilities of `low` or `medium` severity. - -### Enabling License Approvals within a project - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13067) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. - -`License-Check` is a [security approval rule](#enabling-security-approvals-within-a-project) -you can enable to allow an individual or group to approve a merge request that contains a `denied` -license. For instructions on enabling this rule, see -[Enabling license approvals within a project](../compliance/license_compliance/index.md#enabling-license-approvals-within-a-project). - -## Working in an offline environment - -It is possible to run most of the GitLab security scanners when not -connected to the internet, in what is sometimes known as an offline, -limited connectivity, Local Area Network (LAN), Intranet, or "air-gap" -environment. - -Read how to [operate the Secure scanners in an offline environment](offline_deployments/index.md). + ## Using private Maven repositories @@ -290,47 +259,22 @@ under your project's settings: </settings> ``` -## Outdated security reports - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4913) in GitLab 12.7. - -When a security report generated for a merge request becomes outdated, the merge request shows a warning -message in the security widget and prompts you to take an appropriate action. - -This can happen in two scenarios: - -1. Your [source branch is behind the target branch](#source-branch-is-behind-the-target-branch). -1. The [target branch security report is out of date](#target-branch-security-report-is-out-of-date). - -### Source branch is behind the target branch - -This means the most recent common ancestor commit between the target branch and the source branch is -not the most recent commit on the target branch. This is by far the most common situation. - -In this case you must rebase or merge to incorporate the changes from the target branch. - - - -### Target branch security report is out of date - -This can happen for many reasons, including failed jobs or new advisories. When the merge request shows that a -security report is out of date, you must run a new pipeline on the target branch. -You can do it quickly by following the hyperlink given to run a new pipeline. - - - ## DAST On-Demand Scans If you don’t want scans running in your normal DevOps process you can use on-demand scans instead. For more details, see [on-demand scans](dast/index.md#on-demand-scans). This feature is only available for DAST. If you run an on-demand scan against the default branch, it is reported as a "successful pipeline" and these results are included in the security dashboard and vulnerability report. ## Security report validation -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321918) in GitLab 13.11. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321918) in GitLab 13.11. +> - Schema validation message [added](https://gitlab.com/gitlab-org/gitlab/-/issues/321730) in GitLab 14.0. -As of GitLab 13.11, we've introduced the **optional** validation of the security report artifacts based on the +You can optionally enable validation of the security report artifacts based on the [report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/tree/master/dist). If you enable validation, GitLab validates the report artifacts before ingesting the vulnerabilities. -This prevents ingesting broken vulnerability data into the database. +This prevents ingestion of broken vulnerability data into the database. + +In GitLab 14.0 and later, the pipeline's **Security** tab lists any report artifacts +that failed validation. Security report validation must first be enabled. ### Enable security report validation @@ -381,14 +325,41 @@ For more details about which findings or vulnerabilities you can view in each of - Change the status. - Create an issue. - Link it to an existing issue. -- In some cases, [apply an automatic remediation for a vulnerability](vulnerabilities/index.md#remediate-a-vulnerability-automatically). +- [Resolve the vulnerability](vulnerabilities/index.md#resolve-a-vulnerability), if a solution is known. ## Troubleshooting +### Outdated security reports + +When a security report generated for a merge request becomes outdated, the merge request shows a warning +message in the security widget and prompts you to take an appropriate action. + +This can happen in two scenarios: + +- Your [source branch is behind the target branch](#source-branch-is-behind-the-target-branch). +- The [target branch security report is out of date](#target-branch-security-report-is-out-of-date). + +#### Source branch is behind the target branch + +This means the most recent common ancestor commit between the target branch and the source branch is +not the most recent commit on the target branch. This is by far the most common situation. + +In this case you must rebase or merge to incorporate the changes from the target branch. + + + +#### Target branch security report is out of date + +This can happen for many reasons, including failed jobs or new advisories. When the merge request shows that a +security report is out of date, you must run a new pipeline on the target branch. +You can do it quickly by following the hyperlink given to run a new pipeline. + + + ### Getting error message `sast job: stage parameter should be [some stage name here]` When [including](../../ci/yaml/README.md#includetemplate) a `.gitlab-ci.yml` template -like [`SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml), +like [`SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml), the following error may occur, depending on your GitLab CI/CD configuration: ```plaintext @@ -441,7 +412,7 @@ This provides useful information to investigate further. ### Getting error message `sast job: config key may not be used with 'rules': only/except` When [including](../../ci/yaml/README.md#includetemplate) a `.gitlab-ci.yml` template -like [`SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml), +like [`SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml), the following error may occur, depending on your GitLab CI/CD configuration: ```plaintext diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index c9c65e94b32..77a15a37c55 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -5,7 +5,7 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Offline environments +# Offline environments **(ULTIMATE SELF)** It's possible to run most of the GitLab security scanners when not connected to the internet. @@ -64,9 +64,9 @@ Once a vulnerability is found, you can interact with it. Read more on how to Please note that in some cases the reported vulnerabilities provide metadata that can contain external links exposed in the UI. These links might not be accessible within an offline environment. -### Automatic remediation for vulnerabilities +### Resolving vulnerabilities -The [automatic remediation for vulnerabilities](../vulnerabilities/index.md#remediate-a-vulnerability-automatically) feature is available for offline Dependency Scanning and Container Scanning, but may not work +The [resolving vulnerabilities](../vulnerabilities/index.md#resolve-a-vulnerability) feature is available for offline Dependency Scanning and Container Scanning, but may not work depending on your instance's configuration. We can only suggest solutions, which are generally more current versions that have been patched, when we are able to access up-to-date registry services hosting the latest versions of that dependency or image. @@ -93,8 +93,7 @@ above. You can find more information at each of the pages below: ## Loading Docker images onto your offline host -To use many GitLab features, including -[security scans](../index.md#working-in-an-offline-environment) +To use many GitLab features, including security scans and [Auto DevOps](../../../topics/autodevops/index.md), the runner must be able to fetch the relevant Docker images. @@ -129,6 +128,10 @@ This method requires a runner with access to both `gitlab.com` (including to be able to use the `docker` command inside the jobs. This runner can be installed in a DMZ or on a bastion, and used only for this specific project. +WARNING: +This template does not include updates for the container scanning analyzer. Please see +[Container scanning offline directions](../container_scanning/index.md#running-container-scanning-in-an-offline-environment). + #### Scheduling the updates By default, this project's pipeline runs only once, when the `.gitlab-ci.yml` is added to the @@ -136,12 +139,6 @@ repository. To update the GitLab security scanners and signatures, it's necessar regularly. GitLab provides a way to [schedule pipelines](../../../ci/pipelines/schedules.md). For example, you can set this up to download and store the Docker images every week. -Some images can be updated more frequently than others. For example, the [vulnerability database](https://hub.docker.com/r/arminc/clair-db/tags) -for Container Scanning is updated daily. To update this single image, create a new Scheduled -Pipeline that runs daily and set `SECURE_BINARIES_ANALYZERS` to `clair-vulnerabilities-db`. Only -this job is triggered, and the image is updated daily and made available in the project -registry. - #### Using the secure bundle created The project using the `Secure-Binaries.gitlab-ci.yml` template should now host all the required diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 0e69f3b68eb..661a4ee8e82 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -48,7 +48,7 @@ GitLab, but users can also integrate their own **custom images**. For an analyzer to be considered Generally Available, it is expected to minimally support the following features: -- [Customizable configuration](index.md#available-variables) +- [Customizable configuration](index.md#available-cicd-variables) - [Customizable rulesets](index.md#customize-rulesets) - [Scan projects](index.md#supported-languages-and-frameworks) - [Multi-project support](index.md#multi-project-support) @@ -80,27 +80,6 @@ variables: This configuration requires that your custom registry provides images for all the official analyzers. -### Selecting specific analyzers - -WARNING: -`SAST_DEFAULT_ANALYZERS` is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50872) in GitLab 13.8, -and is scheduled for [removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/290777). - -You can select the official analyzers you want to run. Here's how to enable -`bandit` and `flawfinder` while disabling all the other default ones. -In `.gitlab-ci.yml` define: - -```yaml -include: - - template: Security/SAST.gitlab-ci.yml - -variables: - SAST_DEFAULT_ANALYZERS: "bandit,flawfinder" -``` - -`bandit` runs first. When merging the reports, SAST -removes the duplicates and keeps the `bandit` entries. - ### Disabling all default analyzers Setting `SAST_DISABLED` to `true` disables all the official diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 886726d5d67..c11e367a688 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -161,7 +161,7 @@ To configure SAST for a project you can: ### Configure SAST manually For GitLab 11.9 and later, to enable SAST you must [include](../../../ci/yaml/README.md#includetemplate) -the [`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) +the [`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) provided as a part of your GitLab installation. For GitLab versions earlier than 11.9, you can copy and use the job as defined that template. @@ -202,7 +202,7 @@ page: ### Customizing the SAST settings -The SAST settings can be changed through [CI/CD variables](#available-variables) +The SAST settings can be changed through [CI/CD variables](#available-cicd-variables) by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. In the following example, we include the SAST template and at the same time we @@ -239,6 +239,24 @@ spotbugs-sast: FAIL_NEVER: 1 ``` +#### Pinning to minor image version + +While our templates use `MAJOR` version pinning to always ensure the latest analyzer +versions are pulled, there are certain cases where it can be beneficial to pin +an analyzer to a specific release. To do so, override the `SAST_ANALYZER_IMAGE_TAG` CI/CD variable +in the job template directly. + +In the example below, we are pinning to a specific patch version of the `spotbugs` analyzer: + +```yaml +include: + - template: Security/SAST.gitlab-ci.yml + +spotbugs-sast: + variables: + SAST_ANALYZER_IMAGE_TAG: "2.28.1" +``` + ### Customize rulesets **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235382) in GitLab 13.5. @@ -411,7 +429,7 @@ the vendored directory. This configuration can vary per analyzer but in the case can use `MAVEN_REPO_PATH`. See [Analyzer settings](#analyzer-settings) for the complete list of available options. -### Available variables +### Available CI/CD variables SAST can be [configured](#customizing-the-sast-settings) using CI/CD variables. @@ -454,9 +472,8 @@ The following are Docker image-related CI/CD variables. | CI/CD variable | Description | |---------------------------|---------------------------------------------------------------------------------------------------------------------------------------| | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the default images (proxy). Read more about [customizing analyzers](analyzers.md). | -| `SAST_ANALYZER_IMAGE_TAG` | **DEPRECATED:** Override the Docker tag of the default images. Read more about [customizing analyzers](analyzers.md). | -| `SAST_DEFAULT_ANALYZERS` | **DEPRECATED:** Override the names of default images. Scheduled for [removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/290777). | | `SAST_EXCLUDED_ANALYZERS` | Names of default images that should never run. Read more about [customizing analyzers](analyzers.md). | +| `SAST_ANALYZER_IMAGE_TAG` | Override the default version of analyzer image. Read more about [pinning the analyzer image version](#pinning-to-minor-image-version). | #### Vulnerability filters @@ -492,9 +509,10 @@ Some analyzers can be customized with CI/CD variables. | `MAVEN_REPO_PATH` | SpotBugs | Path to the Maven local repository (shortcut for the `maven.repo.local` property). | | `SBT_PATH` | SpotBugs | Path to the `sbt` executable. | | `FAIL_NEVER` | SpotBugs | Set to `1` to ignore compilation failure. | -| `SAST_GOSEC_CONFIG` | Gosec | Path to configuration for Gosec (optional). | +| `SAST_GOSEC_CONFIG` | Gosec | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/328301)** in GitLab 14.0 - use custom rulesets instead. Path to configuration for Gosec (optional). | | `PHPCS_SECURITY_AUDIT_PHP_EXTENSIONS` | phpcs-security-audit | Comma separated list of additional PHP Extensions. | -| `SAST_DISABLE_BABEL` | NodeJsScan | Disable Babel processing for the NodeJsScan scanner. Set to `true` to disable Babel processing. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33065) in GitLab 13.2. | +| `SAST_DISABLE_BABEL` | NodeJsScan | Disable Babel processing for the NodeJsScan scanner. Set to `true` to disable Babel processing. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33065) in GitLab 13.2. +| `SAST_SEMGREP_METRICS` | Semgrep | Set to `"false"` to disable sending anonymized scan metrics to [r2c](https://r2c.dev/). Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330565) in GitLab 14.0. | #### Custom CI/CD variables @@ -772,3 +790,7 @@ For Maven builds, add the following to your `pom.xml` file: ### Flawfinder encoding error This occurs when Flawfinder encounters an invalid UTF-8 character. To fix this, convert all source code in your project to UTF-8 character encoding. This can be done with [`cvt2utf`](https://github.com/x1angli/cvt2utf) or [`iconv`](https://www.gnu.org/software/libiconv/documentation/libiconv-1.13/iconv.1.html) either over the entire project or per job using the [`before_script`](../../../ci/yaml/README.md#before_script) feature. + +### Semgrep slowness, unexpected results, or other errors + +If Semgrep is slow, reports too many false positives or false negatives, crashes, fails, or is otherwise broken, see the Semgrep docs for [troubleshooting GitLab SAST](https://semgrep.dev/docs/troubleshooting/gitlab-sast/). diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 02d117b1c0a..f4aa9dc2787 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -62,6 +62,9 @@ The [default ruleset provided by Gitleaks](https://gitlab.com/gitlab-org/securit - Password in URL - U.S. Social Security Number +WARNING: +Gitleaks does not support scanning binary files. + ## Requirements To run Secret Detection jobs, by default, you need GitLab Runner with the @@ -97,7 +100,8 @@ as shown in the following table: ## Configuration -> GitLab 13.1 splits Secret Detection from the [SAST configuration](../sast#configuration) into its own CI/CD template. If you're using GitLab 13.0 or earlier and SAST is enabled, then Secret Detection is already enabled. +> - In GitLab 13.1, Secret Detection was split from the [SAST configuration](../sast#configuration) into its own CI/CD template. If you're using GitLab 13.0 or earlier and SAST is enabled, then Secret Detection is already enabled. +> - [In GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/297269), Secret Detection jobs `secret_detection_default_branch` and `secret_detection` were consolidated into one job, `secret_detection`. Secret Detection is performed by a [specific analyzer](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Secret-Detection.gitlab-ci.yml) during the `secret-detection` job. It runs regardless of your app's programming language. @@ -160,7 +164,7 @@ that you can review and merge to complete the configuration. ### Customizing settings -The Secret Detection scan settings can be changed through [CI/CD variables](#available-variables) +The Secret Detection scan settings can be changed through [CI/CD variables](#available-cicd-variables) by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. @@ -174,7 +178,7 @@ is no longer supported. When overriding the template, you must use [`rules`](../ #### GIT_DEPTH -The [`GIT_DEPTH` CI/CD variable](../../../ci/runners/README.md#shallow-cloning) affects Secret Detection. +The [`GIT_DEPTH` CI/CD variable](../../../ci/runners/configure_runners.md#shallow-cloning) affects Secret Detection. The Secret Detection analyzer relies on generating patches between commits to scan content for secrets. If you override the default, ensure the value is greater than 1. If the number of commits in an MR is greater than the GIT_DEPTH value, Secret Detection will [fail to detect secrets](#error-couldnt-run-the-gitleaks-command-exit-status-2). @@ -196,7 +200,7 @@ secret_detection: Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable takes precedence. -#### Available variables +#### Available CI/CD variables Secret Detection can be customized by defining available CI/CD variables: @@ -298,7 +302,7 @@ want to perform a full secret scan. Running a secret scan on the full history ca especially for larger repositories with lengthy Git histories. We recommend not setting this CI/CD variable as part of your normal job definition. -A new configuration variable ([`SECRET_DETECTION_HISTORIC_SCAN`](#available-variables)) +A new configuration variable ([`SECRET_DETECTION_HISTORIC_SCAN`](#available-cicd-variables)) can be set to change the behavior of the GitLab Secret Detection scan to run on the entire Git history of a repository. We have created a [short video walkthrough](https://youtu.be/wDtc_K00Y0A) showcasing how you can perform a full history secret scan. @@ -396,7 +400,7 @@ ERRO[2020-11-18T18:05:52Z] object not found [ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ Gitleaks analysis failed: exit status 2 ``` -To resolve the issue, set the [`GIT_DEPTH` CI/CD variable](../../../ci/runners/README.md#shallow-cloning) +To resolve the issue, set the [`GIT_DEPTH` CI/CD variable](../../../ci/runners/configure_runners.md#shallow-cloning) to a higher value. To apply this only to the Secret Detection job, the following can be added to your `.gitlab-ci.yml` file: diff --git a/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png b/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png Binary files differindex 74592e2cea5..6578c0bf4cf 100644 --- a/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png +++ b/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index f0b3d895df5..01de066367c 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -150,8 +150,7 @@ the following:  -To view the Security Center, from the navigation bar at the top of the page, select -**More > Security**. +To view the Security Center, on the top bar, select **Menu > Security**. ### Adding projects to the Security Center diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index 1316f1b9644..ce30accfb4d 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Secure and Protect terminology +# Secure and Protect terminology **(FREE)** This terminology list for GitLab Secure and Protect aims to: @@ -101,7 +101,7 @@ of the finding's [first identifier](https://gitlab.com/gitlab-org/security-produ combine to create the value. Examples of primary identifiers include `PluginID` for OWASP Zed Attack Proxy (ZAP), or `CVE` for -Klar. Note that the identifier must be stable. Subsequent scans must return the same value for the +Trivy. Note that the identifier must be stable. Subsequent scans must return the same value for the same finding, even if the location has slightly changed. ### Report finding @@ -122,7 +122,7 @@ The type of scan. This must be one of the following: ### Scanner Software that can scan for vulnerabilities. The resulting scan report is typically not in the -[Secure report format](#secure-report-format). Examples include ESLint, Klar, and ZAP. +[Secure report format](#secure-report-format). Examples include ESLint, Trivy, and ZAP. ### Secure product diff --git a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png Binary files differindex 1f02fd30f8e..e165c7e6ceb 100644 --- a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png +++ b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 825bc64d52b..e1200c60419 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -16,34 +16,8 @@ Monitoring** page. GitLab supports statistics for the following security features: -- [Web Application Firewall](../../clusters/applications.md#web-application-firewall-modsecurity) - [Container Network Policies](../../../topics/autodevops/stages.md#network-policy) -## Web Application Firewall - -The Web Application Firewall section provides metrics for the NGINX -Ingress controller and ModSecurity firewall. This section has the -following prerequisites: - -- Project has to have at least one [environment](../../../ci/environments/index.md). -- [Web Application Firewall](../../clusters/applications.md#web-application-firewall-modsecurity) has to be enabled. -- [Elastic Stack](../../clusters/applications.md#web-application-firewall-modsecurity) has to be installed. - -If you are using custom Helm values for the Elastic Stack you have to -configure Filebeat similarly to the [vendored values](https://gitlab.com/gitlab-org/gitlab/-/blob/f610a080b1ccc106270f588a50cb3c07c08bdd5a/vendor/elastic_stack/values.yaml). - -The **Web Application Firewall** section displays the following information -about your Ingress traffic: - -- The total amount of requests to your application -- The proportion of traffic that is considered anomalous according to - the configured rules -- The request breakdown graph for the selected time interval - -If a significant percentage of traffic is anomalous, you should -investigate it for potential threats by -[examining the Web Application Firewall logs](../../clusters/applications.md#web-application-firewall-modsecurity). - ## Container Network Policy > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. @@ -88,7 +62,7 @@ investigate it for potential threats by The **Threat Monitoring** page's **Policy** tab displays deployed network policies for all available environments. You can check a -network policy's `yaml` manifest, toggle the policy's enforcement +network policy's `yaml` manifest, its enforcement status, and create and edit deployed policies. This section has the following prerequisites: @@ -97,8 +71,7 @@ following prerequisites: Network policies are fetched directly from the selected environment's deployment platform. Changes performed outside of this tab are -reflected upon refresh. Enforcement status changes are deployed -directly to a deployment namespace of the selected environment. +reflected upon refresh. By default, the network policy list contains predefined policies in a disabled state. Once enabled, a predefined policy deploys to the @@ -115,8 +88,9 @@ users must make changes by following the To change a network policy's enforcement status: - Click the network policy you want to update. -- Click the **Enforcement status** toggle to update the selected policy. -- Click the **Apply changes** button to deploy network policy changes. +- Click the **Edit policy** button. +- Click the **Policy status** toggle to update the selected policy. +- Click the **Save changes** button to deploy network policy changes. Disabled network policies have the `network-policy.gitlab.com/disabled_by: gitlab` selector inside the `podSelector` block. This narrows the scope of such a policy and as a result it doesn't affect @@ -165,7 +139,8 @@ button at the bottom of the editor. ### Configuring Network Policy Alerts -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) and [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) and [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. +> - The feature flag was removed and the Threat Monitoring Alerts Project was [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in GitLab 14.0. You can use policy alerts to track your policy's impact. Alerts are only available if you've [installed](../../clusters/agent/repository.md) @@ -186,25 +161,6 @@ There are two ways to create policy alerts: Once added, the UI updates and displays a warning about the dangers of too many alerts. -#### Enable or disable Policy Alerts **(ULTIMATE)** - -Policy Alerts is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -Feature.enable(:threat_monitoring_alerts) -``` - -To disable it: - -```ruby -Feature.disable(:threat_monitoring_alerts) -``` - ### Container Network Policy Alert list > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. diff --git a/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_dropdown_v13_1.png b/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_dropdown_v13_1.png Binary files differdeleted file mode 100644 index 05ca74c3d5c..00000000000 --- a/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_dropdown_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 965b856504d..9866709bacc 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -9,44 +9,47 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13561) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. -Each security vulnerability in a project's [Vulnerability Report](../vulnerability_report/index.md) has an individual page which includes: +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: -- Details of the vulnerability. -- The status of the vulnerability in the project. -- Available actions for the vulnerability. -- Any issues related to the vulnerability. +- Description +- When it was detected +- Current status +- Available actions +- Linked issues +- Actions log On the vulnerability's page, you can: - [Change the vulnerability's status](#change-vulnerability-status). - [Create an issue](#create-an-issue-for-a-vulnerability). -- [Link issues to the vulnerability](#link-gitlab-issues-to-the-vulnerability). -- [Remediate a vulnerability automatically](#remediate-a-vulnerability-automatically), if an - automatic solution is available. -- [Remediate a vulnerability manually](#remediate-a-vulnerability-manually), if a solution is +- [Link issues to the vulnerability](#linked-issues). +- [Resolve a vulnerability](#resolve-a-vulnerability), if a solution is available. -## Change vulnerability status +## Vulnerability status values + +A vulnerability's status can be one of the following: -You can change the status of a vulnerability using the **Status** dropdown to one of -the following values: +| Status | Description | +|:----------|:------------| +| Detected | The default state for a newly discovered vulnerability. | +| Confirmed | A user has seen this vulnerability and confirmed it to be accurate. | +| Dismissed | A user has seen this vulnerability and dismissed it because it is not accurate or otherwise not to be resolved. | +| Resolved | The vulnerability has been fixed and is no longer valid. | -| Status | Description | -|-----------|----------------------------------------------------------------------------------------------------------------| -| Detected | The default state for a newly discovered vulnerability | -| Confirmed | A user has seen this vulnerability and confirmed it to be accurate | -| Dismissed | A user has seen this vulnerability and dismissed it because it is not accurate or otherwise not to be resolved | -| Resolved | The vulnerability has been fixed and is no longer valid | +## Change vulnerability status -A timeline shows you when the vulnerability status has changed -and allows you to comment on a change. +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. ## Create 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. -From a vulnerability you can create either: +You can create either: - [A GitLab issue](#create-a-gitlab-issue-for-a-vulnerability) (default). - [A Jira issue](#create-a-jira-issue-for-a-vulnerability). @@ -68,14 +71,7 @@ The issue is then opened so you can take further action. ### Create a Jira issue for a vulnerability > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4677) in GitLab 13.9. -> - It's [deployed behind a feature flag](../../../user/feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to -> [disable it](#enable-or-disable-jira-integration-for-vulnerabilities). - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/283850) in GitLab 13.12. Prerequisites: @@ -92,54 +88,47 @@ To create a Jira issue for a vulnerability: 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. -### Enable or disable Jira integration for vulnerabilities **(ULTIMATE SELF)** - -The option to create a Jira issue for a vulnerability is under development but ready for production -use. It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -Feature.enable(:jira_for_vulnerabilities) -``` +Unlike GitLab issues, the status of whether a Jira issue is open or closed does not display in the GitLab user interface. -To disable it: - -```ruby -Feature.disable(:jira_for_vulnerabilities) -``` - -## Link GitLab issues to the vulnerability +## Linked 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 the vulnerability. This allows you to -indicate that this vulnerability affects multiple issues. It also allows you to indicate -that the resolution of one issue would resolve multiple vulnerabilities. - -Linked issues are shown in the Vulnerability Report and the vulnerability's page. +You can link one or more existing GitLab issues to a vulnerability. Adding a link helps track +the issue that resolves or mitigates a vulnerability. -## Link to an existing issue +Issues linked to a vulnerability are shown in the Vulnerability Report and the vulnerability's page. -If you already have an open issue, you can link to it from the vulnerability. +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. - An issue can only be related to one vulnerability at a time. - Issues can be linked across groups and projects. -To link to an existing issue: +## Link to existing issues + +To link a vulnerability to existing issues: + +1. Go to the vulnerability's page. +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. + +## Resolve a vulnerability -1. Open the vulnerability. -1. [Add a linked issue](../../project/issues/related_issues.md). +For some vulnerabilities a solution is already known. In those instances, a vulnerability's page +includes a **Resolve with merge request** option. -## Remediate a vulnerability automatically +To resolve a vulnerability, you can either: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5656) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.7. +- [Resolve a vulnerability with a merge request](#resolve-a-vulnerability-with-a-merge-request). +- [Resolve a vulnerability manually](#resolve-a-vulnerability-manually). -Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. The following scanners are supported: - [Dependency Scanning](../dependency_scanning/index.md). @@ -147,42 +136,33 @@ The following scanners are supported: `yarn`. - [Container Scanning](../container_scanning/index.md). -### Remediate a vulnerability manually + -To manually apply the patch that GitLab generated for a vulnerability: +### 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**. -1. Select the **Resolve with merge request** dropdown, then select **Download patch to resolve**: +A merge request is created which applies the patch required to resolve the vulnerability. +Process the merge request according to your standard workflow. -  +### Resolve a vulnerability manually +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. Ensure your local project has the same commit checked out that was used to generate the patch. 1. Run `git apply remediation.patch`. 1. Verify and commit the changes to your branch. -### Create a merge request with the suggested patch - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9224) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. - -In some cases, you can create a merge request that automatically remediates the -vulnerability. Any vulnerability that has a -[solution](#remediate-a-vulnerability-automatically) can have a merge -request created to automatically solve the issue. - -If this action is available: - -1. Select the **Resolve with merge request** dropdown, then select **Resolve with merge request**. - -  - -A merge request is created. It applies the solution to the source branch. - ## Vulnerability scanner maintenance The following vulnerability scanners and their databases are regularly updated: | Secure scanning tool | Vulnerabilities database updates | |:----------------------------------------------------------------|----------------------------------| -| [Container Scanning](../container_scanning/index.md) | Uses either `trivy` or `clair`. For the `trivy` scanner, a job runs on a daily basis to build a new image with the latest vulnerability database updates from the [upstream `trivy-db`](https://github.com/aquasecurity/trivy-db). For the `clair` scanner, the latest `clair-db` version is used; `clair-db` database [is updated daily according to the author](https://github.com/arminc/clair-local-scan#clair-server-or-local). | +| [Container Scanning](../container_scanning/index.md) | A job runs on a daily basis to build new images with the latest vulnerability database updates from the upstream scanner. | | [Dependency Scanning](../dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for npm packages), and `gemnasium` (the GitLab tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated at least once a week. See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | | [Dynamic Application Security Testing (DAST)](../dast/index.md) | The scanning engine is updated on a periodic basis. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/master/Dockerfile#L1). The scanning rules are downloaded at scan runtime. | | [Static Application Security Testing (SAST)](../sast/index.md) | Relies exclusively on [the tools GitLab wraps](../sast/index.md#supported-languages-and-frameworks). The underlying analyzers are updated at least once per month if a relevant update is available. The vulnerabilities database is updated by the upstream tools. | diff --git a/doc/user/application_security/vulnerabilities/severities.md b/doc/user/application_security/vulnerabilities/severities.md index 75366a49a55..f3e8e98bce3 100644 --- a/doc/user/application_security/vulnerabilities/severities.md +++ b/doc/user/application_security/vulnerabilities/severities.md @@ -5,7 +5,7 @@ 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 severity levels +# Vulnerability severity levels **(ULTIMATE)** GitLab vulnerability analyzers attempt to return vulnerability severity level values whenever possible. The following is a list of available GitLab vulnerability severity levels, ranked from @@ -62,10 +62,9 @@ the following tables: ## Container Scanning -| GitLab scanner | Outputs severity levels? | Native severity level type | Native severity level example | +| GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example | |------------------------------------------------------------------------|--------------------------|----------------------------|--------------------------------------------------------------| -| [`clair`](https://gitlab.com/gitlab-org/security-products/analyzers/klar) | **{check-circle}** Yes | String | `Negligible`, `Low`, `Medium`, `High`, `Critical`, `Defcon1` | -| [`trivy`](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning)| **{check-circle}** Yes | String | `Unknown`, `Low`, `Medium`, `High`, `Critical` | +| [`container-scanning`](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning)| **{check-circle}** Yes | String | `Unknown`, `Low`, `Medium`, `High`, `Critical` | ## Fuzz Testing diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index f68fb0c5cbb..07025d193af 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -128,10 +128,12 @@ To view the relevant file, select the filename in the vulnerability's details. ## View issues raised for a vulnerability The **Activity** column indicates the number of issues that have been created for the vulnerability. -Hover over an **Activity** entry and select a link go to that issue. +Hover over an **Activity** entry and select a link go to that issue. The status of whether the issue is open or closed also displays in the hover menu.  +If Jira issue support is enabled, the issue link found in the Activity entry links out to the issue in Jira. Unlike GitLab issues, the status of whether a Jira issue is Open or Closed does not display in the GitLab UI. + ## Change status of vulnerabilities > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292636) in GitLab 13.10, all statuses became selectable. diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 5e272f2a816..414ed8377db 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -462,7 +462,7 @@ The setup process follows the same steps as [GitOps](#get-started-with-gitops-an with the following differences: - When you define a configuration repository, you must do so with [Cilium settings](#define-a-configuration-repository-with-cilium-settings). -- You do not need to create a `manifest.yaml`. +- You do not need to specify the `gitops` configuration section. ### Define a configuration repository with Cilium settings @@ -486,7 +486,7 @@ cilium: ## Management interfaces Users with at least the [Developer](../../permissions.md) can access the user interface -for the GitLab Kubernetes agent at **Operations > Kubernetes** under the +for the GitLab Kubernetes agent at **Infrastructure > Kubernetes clusters**, under the **GitLab Agent managed clusters** tab. This page lists all registered agents for the current project, and the configuration directory for each agent: diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index 49e5e8c58df..cd40cc6810e 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -8,6 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the Kubernetes Agent became available on GitLab.com. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed. WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -38,16 +39,7 @@ with Kubernetes resource definitions in YAML or JSON format. The Agent monitors each project you declare, and when the project changes, GitLab deploys the changes using the Agent. -To use multiple YAML files, specify a `paths` attribute in the `gitops` section. - -By default, the Agent monitors all -[Kubernetes object types](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields). -You can exclude some types of resources from monitoring. This enables you to reduce -the permissions needed by the GitOps feature, through `resource_exclusions`. - -To enable a specific named resource, first use `resource_inclusions` to enable desired resources. -The following file excerpt includes specific `api_groups` and `kinds`. The `resource_exclusions` -which follow excludes all other `api_groups` and `kinds`: +To use multiple YAML files, specify a `paths` attribute in the `gitops.manifest_projects` section. ```yaml gitops: @@ -58,28 +50,6 @@ gitops: # The `id` is a path to a Git repository with Kubernetes resource definitions # in YAML or JSON format. - id: gitlab-org/cluster-integration/gitlab-agent - # Holds the only API groups and kinds of resources that gitops will monitor. - # Inclusion rules are evaluated first, then exclusion rules. - # If there is still no match, resource is monitored. - # Resources: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields - # Groups: https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-groups-and-versioning - resource_inclusions: - - api_groups: - - apps - kinds: - - '*' - - api_groups: - - '' - kinds: - - 'ConfigMap' - # Holds the API groups and kinds of resources to exclude from gitops watch. - # Inclusion rules are evaluated first, then exclusion rules. - # If there is still no match, resource is monitored. - resource_exclusions: - - api_groups: - - '*' - kinds: - - '*' # Namespace to use if not set explicitly in object manifest. default_namespace: my-ns # Paths inside of the repository to scan for manifest files. @@ -93,6 +63,87 @@ gitops: - glob: '/team2/apps/**/*.yaml' # If 'paths' is not specified or is an empty list, the configuration below is used - glob: '/**/*.{yaml,yml,json}' + # Reconcile timeout defines whether the applier should wait + # until all applied resources have been reconciled, and if so, + # how long to wait. + reconcile_timeout: 3600s # 1 hour by default + # Dry run strategy defines whether changes should actually be performed, + # or if it is just talk and no action. + # https://github.com/kubernetes-sigs/cli-utils/blob/d6968048dcd80b1c7b55d9e4f31fc25f71c9b490/pkg/common/common.go#L68-L89 + # Can be: none, client, server + dry_run_strategy: none # 'none' by default + # Prune defines whether pruning of previously applied + # objects should happen after apply. + prune: true # enabled by default + # Prune timeout defines whether we should wait for all resources + # to be fully deleted after pruning, and if so, how long we should + # wait. + prune_timeout: 3600s # 1 hour by default + # Prune propagation policy defines the deletion propagation policy + # that should be used for pruning. + # https://github.com/kubernetes/apimachinery/blob/44113beed5d39f1b261a12ec398a356e02358307/pkg/apis/meta/v1/types.go#L456-L470 + # Can be: orphan, background, foreground + prune_propagation_policy: foreground # 'foreground' by default + # InventoryPolicy defines if an inventory object can take over + # objects that belong to another inventory object or don't + # belong to any inventory object. + # This is done by determining if the apply/prune operation + # can go through for a resource based on the comparison + # the inventory-id value in the package and the owning-inventory + # annotation in the live object. + # https://github.com/kubernetes-sigs/cli-utils/blob/d6968048dcd80b1c7b55d9e4f31fc25f71c9b490/pkg/inventory/policy.go#L12-L66 + # Can be: must_match, adopt_if_no_inventory, adopt_all + inventory_policy: must_match # 'must_match' by default +``` + +### Using multiple manifest projects + +Storing Kubernetes manifests in more than one repository can be handy, for example: + +- You may store manifests for different applications in separate repositories. +- Different teams can work on manifests of independent projects in separate repositories. + +To use multiple repositories as the source of Kubernetes manifests, specify them in the list of +`manifest_projects` in your `config.yaml`: + +```yaml +gitops: + manifest_projects: + - id: group1/project1 + - id: group2/project2 +``` + +Note that repositories are synchronized **concurrently** and **independently** from each other, +which means that, ideally, there should **not** be any dependencies shared by these repositories. +Storing a logical group of manifests in a single repository may work better than distributing it across several +repositories. + +You cannot use a single repository as a source for multiple concurrent synchronization +operations. If such functionality is needed, you may use multiple agents reading +manifests from the same repository. + +Ensure not to specify "overlapping" globs to avoid synchronizing the same files more than once. +This is detected by the GitLab Kubernetes Agent and leads to an error. + +INCORRECT - both globs match `*.yaml` files in the root directory: + +```yaml +gitops: + manifest_projects: + - id: project1 + paths: + - glob: '/**/*.yaml' + - glob: '/*.yaml' +``` + +CORRECT - single globs matches all `*.yaml` files recursively: + +```yaml +gitops: + manifest_projects: + - id: project1 + paths: + - glob: '/**/*.yaml' ``` ## Surface network security alerts from cluster to GitLab diff --git a/doc/user/clusters/agent/runner.md b/doc/user/clusters/agent/runner.md index bbf07d4ea84..c40733bd7a5 100644 --- a/doc/user/clusters/agent/runner.md +++ b/doc/user/clusters/agent/runner.md @@ -1,5 +1,6 @@ --- redirect_to: 'https://docs.gitlab.com/runner/install/kubernetes-agent.html' +remove_date: '2022-02-01' --- This document was moved to [another location](https://docs.gitlab.com/runner/install/kubernetes-agent.html). diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 212823853e4..a6aa4e00005 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -6,12 +6,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Managed Apps (DEPRECATED) **(FREE)** +NOTE: +The new recommended way to manage cluster applications is to use the [cluster management project template](management_project_template.md). +If you want to migrate your GitLab managed apps management to this template, reference to [migrating from GitLab managed apps to project template](migrating_from_gma_to_project_template.md). + **GitLab Managed Apps** was created to help you configure applications in your cluster directly from GitLab. You could use this feature through two different methods: "one-click install" and "CI/CD template". Both methods are **deprecated**: -- The **one-click install** method was deprecated in GitLab 13.9 and **will be - removed** in GitLab 14.0. +- The **one-click install** method was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63348) in GitLab 14.0. - The **CI/CD template method** was deprecated in GitLab 13.12 and is scheduled to be removed in GitLab 15.0. @@ -19,23 +22,17 @@ Both methods were limiting as you couldn't fully customize your third-party apps through GitLab Managed Apps. Therefore, we decided to deprecate this feature and provide better [GitOps-driven alternatives](https://about.gitlab.com/direction/configure/kubernetes_management/#gitlab-managed-applications) to our users, such as [cluster integrations](integrations.md#cluster-integrations) and [cluster management project](management_project.md). -Read the sections below according to the installation method you chose to -learn how to proceed to keep your apps up and running: - -- [One-click install method](#install-with-one-click-deprecated) -- [CI/CD template method](#install-using-gitlab-cicd-deprecated) - ## Install using GitLab CI/CD (DEPRECATED) > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20822) in GitLab 12.6. > - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 13.12. WARNING: -The GitLab Managed Apps CI/CD installation method was [deprecated in 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/327908). +The GitLab Managed Apps CI/CD installation method was [deprecated in 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/327908). Your applications continue to work. However, we no longer support and maintain the GitLab CI/CD template for Managed Apps (`Managed-Cluster-Applications.gitlab-ci.yml`). -As a replacement, we are working on a [cluster management project template](https://gitlab.com/gitlab-org/gitlab/-/issues/327908), -still to be released. +The new recommended way to manage cluster applications is to use the [cluster management project template](management_project_template.md). +If you want to migrate your GitLab managed apps management to this template, reference to [migrating from GitLab managed apps to project template](migrating_from_gma_to_project_template.md). The CI/CD template was the primary method for installing applications to clusters via GitLab Managed Apps and customize them through Helm. @@ -401,6 +398,10 @@ These values can be specified using [CI/CD variables](../../ci/variables/README. - `GITLAB_RUNNER_GITLAB_URL` is used for `gitlabUrl`. - `GITLAB_RUNNER_REGISTRATION_TOKEN` is used for `runnerRegistrationToken` +The methods of specifying these values are mutually exclusive. Either specify variables `GITLAB_RUNNER_REGISTRATION_TOKEN` and `GITLAB_RUNNER_TOKEN` as CI variables (recommended) or provide values for `runnerRegistrationToken:` and `runnerToken:` in `.gitlab/managed-apps/gitlab-runner/values.yaml`. If you choose to use CI variables, comment out or remove `runnerRegistrationToken:` and `runnerToken:` from `.gitlab/managed-apps/gitlab-runner/values`. + +The runner registration token allows connection to a project by a runner and therefore should be treated as a secret to prevent malicious use and code exfiltration through a runner. For this reason, we recommend that you specify the runner registration token as a [protected variable](../../ci/variables/README.md#protect-a-cicd-variable) and [masked variable](../../ci/variables/README.md#mask-a-cicd-variable) and do not commit them to the Git repository in the `values.yaml` file. + You can customize the installation of GitLab Runner by defining `.gitlab/managed-apps/gitlab-runner/values.yaml` file in your cluster management project. Refer to the @@ -453,7 +454,7 @@ for the available configuration options. You can check Cilium's installation status on the cluster management page: - [Project-level cluster](../project/clusters/index.md): Navigate to your project's - **Operations > Kubernetes** page. + **Infrastructure > Kubernetes clusters** page. - [Group-level cluster](../group/clusters/index.md): Navigate to your group's **Kubernetes** page. @@ -462,7 +463,10 @@ Installation and removal of the Cilium requires a **manual** [restart](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-gke/#restart-unmanaged-pods) of all affected pods in all namespaces to ensure that they are [managed](https://docs.cilium.io/en/v1.8/operations/troubleshooting/#ensure-managed-pod) -by the correct networking plugin. +by the correct networking plugin. Whenever Hubble is enabled, its related pod might require a +restart depending on whether it started prior to Cilium. For more information, see +[Failed Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#failed-deployment) +in the Kubernetes docs. NOTE: Major upgrades might require additional setup steps. For more information, see @@ -814,11 +818,6 @@ management project. Refer to the [chart](https://gitlab.com/gitlab-org/charts/elastic-stack) for all available configuration options. -NOTE: -In this alpha implementation of installing Elastic Stack through CI, reading the -environment logs through Elasticsearch is unsupported. This is supported if -[installed with the UI](#elastic-stack). - Support for installing the Elastic Stack managed application is provided by the GitLab APM group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at @@ -1026,691 +1025,37 @@ GitLab Container Security group. If you run into unknown issues, at least 2 people from the [Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). -## Browse applications logs - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36769) in GitLab 13.2. - -Logs produced by pods running **GitLab Managed Apps** can be browsed using -[**Log Explorer**](../project/clusters/kubernetes_pod_logs.md). - -## Install with one click (DEPRECATED) - -WARNING: -The one-click installation method was deprecated in GitLab 13.9 and will be removed in [GitLab 14.0](https://gitlab.com/groups/gitlab-org/-/epics/4280). -The removal does not break nor uninstall any apps you have installed but removes the GitLab UI page -for installing and updating your GitLab Managed Apps. -Follow the process to [take ownership of your GitLab Managed Apps](#take-ownership-of-your-gitlab-managed-apps). - -Applications managed by GitLab are installed onto the `gitlab-managed-apps` -namespace. This namespace: - -- Is different from the namespace used for project deployments. -- Is created once. -- Has a non-configurable name. - -To view a list of available applications to install for a: - -- [Project-level cluster](../project/clusters/index.md), navigate to your project's - **Operations > Kubernetes**. -- [Group-level cluster](../group/clusters/index.md), navigate to your group's - **Kubernetes** page. - -You can install the following applications with one click: - -- [Helm](#helm) -- [Ingress](#ingress) -- [cert-manager](#cert-manager) -- [Prometheus](#prometheus) -- [GitLab Runner](#gitlab-runner) -- [JupyterHub](#jupyterhub) -- [Knative](#knative) -- [Crossplane](#crossplane) -- [Elastic Stack](#elastic-stack) -- [Fluentd](#fluentd) - -With the exception of Knative, the applications are installed in a dedicated -namespace called `gitlab-managed-apps`. - -Some applications are installable only for a project-level cluster. -Support for installing these applications in a group-level cluster is -planned for future releases. -For updates, see the [issue tracking progress](https://gitlab.com/gitlab-org/gitlab/-/issues/24411). - -WARNING: -If you have an existing Kubernetes cluster with Helm already installed, -you should be careful as GitLab cannot detect it. In this case, installing -Helm with the applications results in the cluster having it twice, which -can lead to confusion during deployments. - -In GitLab versions 11.6 and greater, Helm is upgraded to the latest version -supported by GitLab before installing any of the applications. - -### Helm - -> - Introduced in GitLab 10.2 for project-level clusters. -> - Introduced in GitLab 11.6 for group-level clusters. -> - [Uses a local Tiller](https://gitlab.com/gitlab-org/gitlab/-/issues/209736) in GitLab 13.2 and later. -> - [Uses Helm 3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46267) for clusters created with GitLab 13.6 and later. -> - [Offers legacy Tiller removal](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47457) in GitLab 13.7 and later. - -[Helm](https://helm.sh/docs/) is a package manager for Kubernetes and is -used to install the GitLab-managed apps. GitLab runs each `helm` command -in a pod in the `gitlab-managed-apps` namespace inside the cluster. - -- For clusters created in GitLab 13.6 and newer, GitLab uses Helm 3 to manage - applications. -- For clusters created on versions of GitLab prior to 13.6, GitLab uses Helm 2 - with a local [Tiller](https://v2.helm.sh/docs/glossary/#tiller) server. Prior - to [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/209736), GitLab - used an in-cluster Tiller server in the `gitlab-managed-apps` namespace. You - can safely uninstall the server from the GitLab application page if you have - previously installed it. This doesn't affect your other applications. - -The GitLab Helm integration does not support installing applications behind a proxy, -but a [workaround](../../topics/autodevops/index.md#install-applications-behind-a-proxy) -is available. - -#### Upgrade a cluster to Helm 3 - -GitLab does not offer a way to migrate existing application management -on existing clusters from Helm 2 to Helm 3. To migrate a cluster to Helm 3: - -1. Uninstall all applications on your cluster. -1. [Remove the cluster integration](../project/clusters/add_remove_clusters.md#removing-integration). -1. [Re-add the cluster](../project/clusters/add_remove_clusters.md#existing-kubernetes-cluster) as - an existing cluster. - -### cert-manager - -> Introduced in GitLab 11.6 for project- and group-level clusters. - -[cert-manager](https://cert-manager.io/docs/) is a native Kubernetes certificate -management controller that helps with issuing certificates. Installing -cert-manager on your cluster issues a certificate by [Let's Encrypt](https://letsencrypt.org/) -and ensures that certificates are valid and up-to-date. - -The chart used to install this application depends on the version of GitLab used. In: - -- GitLab 12.3 and newer, the [`jetstack/cert-manager`](https://github.com/jetstack/cert-manager) - chart is used with a - [`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/cert_manager/values.yaml) - file. -- GitLab 12.2 and older, the - [`stable/cert-manager`](https://github.com/helm/charts/tree/master/stable/cert-manager) - chart was used. - -If you installed cert-manager prior to GitLab 12.3, Let's Encrypt -[blocks requests](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753) -from older versions of `cert-manager`. To resolve this: - -1. [Back up any additional configuration](https://cert-manager.io/docs/tutorials/backup/). -1. Uninstall cert-manager. -1. Install cert-manager again. - -### GitLab Runner - -> - Introduced in GitLab 10.6 for project-level clusters. -> - Introduced in GitLab 11.10 for group-level clusters. - -[GitLab Runner](https://docs.gitlab.com/runner/) is the open source project that -is used to run your jobs and send the results back to GitLab. It's used in -conjunction with [GitLab CI/CD](../../ci/README.md), the open-source continuous -integration service included with GitLab that coordinates the jobs. - -If the project is on GitLab.com, [shared runners](../gitlab_com/index.md#shared-runners) -are available. You don't have to deploy one if they are enough for your -needs. If a project-specific runner is desired, or there are no shared runners, -you can deploy one. - -The deployed runner is set as **privileged**. Root access to the underlying -server is required to build Docker images, so it's the default. Be sure to read -the [security implications](../project/clusters/index.md#security-implications) -before deploying one. - -The [`runner/gitlab-runner`](https://gitlab.com/gitlab-org/charts/gitlab-runner) -chart is used to install this application, using -[a preconfigured `values.yaml`](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/blob/master/values.yaml) -file. Customizing the installation by modifying this file is not supported. This -also means you cannot modify `config.toml` file for this Runner. If you want to -have that possibility and still deploy Runner in Kubernetes, consider using the -[Cluster management project](management_project.md) or installing Runner manually -via [GitLab Runner Helm Chart](https://docs.gitlab.com/runner/install/kubernetes.html). - -### Ingress - -> - Introduced in GitLab 10.2 for project-level clusters. -> - Introduced in GitLab 11.6 for group-level clusters. - -[Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) -provides load balancing, SSL termination, and name-based virtual hosting -out of the box. It acts as a web proxy for your applications and is useful -if you want to use [Auto DevOps](../../topics/autodevops/index.md) or deploy your own web apps. - -The Ingress Controller installed is -[Ingress-NGINX](https://kubernetes.io/docs/concepts/services-networking/ingress/), -which is supported by the Kubernetes community. - -With the following procedure, a load balancer must be installed in your cluster -to obtain the endpoint. You can use either -Ingress, or Knative's own load balancer ([Istio](https://istio.io)) if using Knative. - -To publish your web application, you first need to find the endpoint, which is either an IP -address or a hostname associated with your load balancer. - -To install it, click on the **Install** button for Ingress. GitLab attempts -to determine the external endpoint and it should be available in a few minutes. - -#### Determining the external endpoint automatically - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17052) in GitLab 10.6. - -After you install Ingress, the external endpoint should be available in a few minutes. - -NOTE: -This endpoint can be used for the -[Auto DevOps base domain](../../topics/autodevops/index.md#auto-devops-base-domain) -using the `KUBE_INGRESS_BASE_DOMAIN` environment variable. - -If the endpoint doesn't appear and your cluster runs on Google Kubernetes Engine: - -1. [Examine your Kubernetes cluster](https://console.cloud.google.com/kubernetes) - on Google Kubernetes Engine to ensure there are no errors on its nodes. -1. Ensure you have enough [Quotas](https://console.cloud.google.com/iam-admin/quotas) - on Google Kubernetes Engine. For more information, see - [Resource Quotas](https://cloud.google.com/compute/quotas). -1. Review [Google Cloud's Status](https://status.cloud.google.com/) for service - disruptions. - -The [`stable/nginx-ingress`](https://github.com/helm/charts/tree/master/stable/nginx-ingress) -chart is used to install this application with a -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/ingress/values.yaml) -file. - -After installing, you may see a `?` for **Ingress IP Address** depending on the -cloud provider. For EKS specifically, this is because the ELB is created -with a DNS name, not an IP address. If GitLab is still unable to -determine the endpoint of your Ingress or Knative application, you can -[determine it manually](#determining-the-external-endpoint-manually). - -#### Determining the external endpoint manually - -See the [Base domain section](../project/clusters/index.md#base-domain) for a -guide on how to determine the external endpoint manually. - -#### Using a static IP - -By default, an ephemeral external IP address is associated to the cluster's load -balancer. If you associate the ephemeral IP with your DNS and the IP changes, -your apps aren't reachable, and you'd have to change the DNS record again. -To avoid that, change it into a static reserved IP. - -Read how to [promote an ephemeral external IP address in GKE](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip). - -#### Pointing your DNS at the external endpoint - -After you have set up the external endpoint, associate it with a -[wildcard DNS record](https://en.wikipedia.org/wiki/Wildcard_DNS_record) (such -as `*.example.com.`) to reach your apps. If your external endpoint is an IP -address, use an A record. If your external endpoint is a hostname, use a CNAME -record. - -#### Web Application Firewall (ModSecurity) - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21966) in GitLab 12.7. - -WARNING: -The Web Application Firewall is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/271276) -in GitLab 13.6, and planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/271349) -in GitLab 14.0. - -A Web Application Firewall (WAF) examines traffic being sent or received, -and can block malicious traffic before it reaches your application. The benefits -of a WAF are: - -- Real-time security monitoring for your application. -- Logging of all your HTTP traffic to the application. -- Access control for your application. -- Highly configurable logging and blocking rules. - -By default, GitLab provides you with a WAF known as [`ModSecurity`](https://www.modsecurity.org/), -which is a toolkit for real-time web application monitoring, logging, and access -control. GitLab applies the [OWASP's Core Rule Set](https://coreruleset.org/), -which provides generic attack detection capabilities. - -This feature: - -- Runs in "Detection-only mode" unless configured otherwise. -- Is viewable by checking your Ingress controller's `modsec` log for rule violations. - For example: - - ```shell - kubectl -n gitlab-managed-apps logs -l app=nginx-ingress,component=controller -c modsecurity-log -f - ``` - -To enable WAF, switch its respective toggle to the enabled position when installing -or updating [Ingress application](#ingress). - -If this is your first time using the GitLab WAF, we recommend you follow the -[quick start guide](../project/clusters/protect/web_application_firewall/quick_start_guide.md). - -There is a small performance overhead by enabling ModSecurity. If this is -considered significant for your application, you can disable ModSecurity's -rule engine for your deployed application in any of the following ways: - -1. Set the [deployment variable](../../topics/autodevops/index.md) - `AUTO_DEVOPS_MODSECURITY_SEC_RULE_ENGINE` to `Off` to prevent ModSecurity - from processing any requests for the given application or environment. -1. Switch its respective toggle to the disabled position, and then apply changes - by selecting **Save changes** to reinstall Ingress with the recent changes. - - - -##### Logging and blocking modes - -To help you tune your WAF rules, you can globally set your WAF to either -*Logging* or *Blocking* mode: - -- *Logging mode*: Allows traffic matching the rule to pass, and logs the event. -- *Blocking mode*: Prevents traffic matching the rule from passing, and logs the event. - -To change your WAF's mode: - -1. If you haven't already done so, - [install ModSecurity](../project/clusters/protect/web_application_firewall/quick_start_guide.md). -1. Navigate to **Operations > Kubernetes**. -1. In **Applications**, scroll to **Ingress**. -1. Under **Global default**, select your desired mode. -1. Select **Save changes**. - -##### WAF version updates - -Enabling, disabling, or changing the logging mode for **ModSecurity** is only -allowed in same version of [Ingress](#ingress) due to limitations in -[Helm](https://helm.sh/) which might be overcome in future releases. - -The **ModSecurity** user interface controls are disabled if the version deployed -differs from the one available in GitLab. However, actions at the [Ingress](#ingress) -level, such as uninstalling, can still be performed: - - - -Update [Ingress](#ingress) to the most recent version to take advantage of bug -fixes, security fixes, and performance improvements. To update the -[Ingress application](#ingress), you must first uninstall it, and then re-install -it as described in [Install ModSecurity](../project/clusters/protect/web_application_firewall/quick_start_guide.md). - -##### Viewing Web Application Firewall traffic - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14707) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. - -You can view Web Application Firewall traffic by navigating to your project's -**Security & Compliance > Threat Monitoring** page. From there, you can see -tracked over time: - -- The total amount of traffic to your application. -- The proportion of traffic that's considered anomalous by the Web Application - Firewall's default [OWASP ruleset](https://coreruleset.org/). - -If a significant percentage of traffic is anomalous, investigate it for potential threats -by [examining the Web Application Firewall logs](#web-application-firewall-modsecurity). - - - -### JupyterHub - -> - Introduced in GitLab 11.0 for project-level clusters. -> - Introduced in GitLab 12.3 for group and instance-level clusters. - -[JupyterHub](https://jupyterhub.readthedocs.io/en/stable/) is a multi-user service -for managing notebooks across a team. [Jupyter Notebooks](https://jupyter-notebook.readthedocs.io/en/latest/) -provide a web-based interactive programming environment used for data analysis, -visualization, and machine learning. - -The [`jupyter/jupyterhub`](https://jupyterhub.github.io/helm-chart/) -chart is used to install this application with a -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/jupyter/values.yaml) -file. - -Authentication is enabled only for [project members](../project/members/index.md) -for project-level clusters and group members for group-level clusters with -[Developer or higher](../permissions.md) access to the associated project or group. - -GitLab uses a [custom Jupyter image](https://gitlab.com/gitlab-org/jupyterhub-user-image/blob/master/Dockerfile) -that installs additional relevant packages on top of the base Jupyter. Ready-to-use -DevOps Runbooks built with Nurtch's [Rubix library](https://github.com/Nurtch/rubix) -are also available. +## Install with one click (REMOVED) -More information on creating executable runbooks can be found in -[our Runbooks documentation](../project/clusters/runbooks/index.md#configure-an-executable-runbook-with-gitlab). -Ingress must be installed and have an IP address assigned before -JupyterHub can be installed. +> [Removed](https://gitlab.com/groups/gitlab-org/-/epics/4280) in GitLab 14.0. -#### Jupyter Git Integration +The one-click installation method was deprecated in GitLab 13.9 and removed in [GitLab 14.0](https://gitlab.com/groups/gitlab-org/-/epics/4280). +The removal does not break nor uninstall any apps you have installed, it only +removes the "Applications" tab from the cluster page. +The new recommended way to manage cluster applications is to use the [cluster management project template](management_project_template.md). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28783) in GitLab 12.0 for project-level clusters. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/32512) in GitLab 12.3 for group and instance-level clusters. +- If you want to migrate your GitLab managed apps management to this template, read + [migrating from GitLab managed apps to project template](migrating_from_gma_to_project_template.md). +- If you don't want to use the template, you can also manually manage your applications. + For that, follow the process to + [take ownership of your GitLab Managed Apps](#take-ownership-of-your-gitlab-managed-apps). -When installing JupyterHub onto your Kubernetes cluster, -[JupyterLab's Git extension](https://github.com/jupyterlab/jupyterlab-git) -is provisioned and configured using the authenticated user's: +If you are not yet on GitLab 14.0 or later, you can refer to [an older version of this document](https://docs.gitlab.com/13.12/ee/user/clusters/applications.html#install-with-one-click-deprecated). -- Name. -- Email. -- Newly created access token. - -JupyterLab's Git extension enables full version control of your notebooks, and -issuance of Git commands in Jupyter. You can issue Git commands through the -**Git** tab on the left panel, or through Jupyter's command-line prompt. - -JupyterLab's Git extension stores the user token in the JupyterHub DB in encrypted -format, and in the single user Jupyter instance as plain text, because -[Git requires storing credentials as plain text](https://git-scm.com/docs/git-credential-store) -Potentially, if a nefarious user finds a way to read from the file system in the -single-user Jupyter instance, they could retrieve the token. - - - -You can clone repositories from the files tab in Jupyter: - - - -### Knative - -> - Introduced in GitLab 11.5 for project-level clusters. -> - Introduced in GitLab 12.3 for group- and instance-level clusters. - -[Knative](https://cloud.google.com/knative/) provides a platform to -create, deploy, and manage serverless workloads from a Kubernetes -cluster. It's used in conjunction with, and includes -[Istio](https://istio.io) to provide an external IP address for all -programs hosted by Knative. - -The [`knative/knative`](https://storage.googleapis.com/triggermesh-charts) -chart is used to install this application. - -During installation, you must enter a wildcard domain where your applications -are exposed. Configure your DNS server to use the external IP address for that -domain. Applications created and installed are accessible as -`<program_name>.<kubernetes_namespace>.<domain_name>`, which requires -your Kubernetes cluster to have -[RBAC enabled](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). - -### Prometheus - -> - Introduced in GitLab 10.4 for project-level clusters. -> - Introduced in GitLab 11.11 for group-level clusters. - -[Prometheus](https://prometheus.io/docs/introduction/overview/) is an -open-source monitoring and alerting system you can use to supervise your -deployed applications. - -GitLab is able to monitor applications by using the -[Prometheus integration](../project/integrations/prometheus.md). Kubernetes container CPU and -memory metrics are collected, and response metrics are also retrieved -from NGINX Ingress. - -The [`stable/prometheus`](https://github.com/helm/charts/tree/master/stable/prometheus) -chart is used to install this application with a -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/prometheus/values.yaml) -file. - -To enable monitoring, install Prometheus into the cluster with the **Install** -button. - -### Crossplane - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34702) in GitLab 12.5 for project-level clusters. - -[Crossplane](https://crossplane.github.io/docs/v0.9/) is a multi-cloud control plane -to help you manage applications and infrastructure across multiple clouds. It extends the -Kubernetes API using: - -- Custom resources. -- Controllers that watch those custom resources. - -Crossplane allows provisioning and lifecycle management of infrastructure components -across cloud providers in a uniform manner by abstracting cloud provider-specific -configurations. - -The Crossplane GitLab-managed application: - -- Installs Crossplane with a provider of choice on a Kubernetes cluster attached to the - project repository. -- Can then be used to provision infrastructure or managed applications such as - PostgreSQL (for example, CloudSQL from GCP or RDS from AWS) and other services - required by the application with the Auto DevOps pipeline. - -[`alpha/crossplane`](https://github.com/crossplane/crossplane/tree/v0.4.1/cluster/charts/crossplane) chart v0.4.1 is used to -install Crossplane using the -[`values.yaml`](https://github.com/crossplane/crossplane/blob/master/cluster/charts/crossplane/values.yaml.tmpl) -file. - -For information about configuring Crossplane installed on the cluster, see -[Crossplane configuration](crossplane.md). - -### Elastic Stack - -> Introduced in GitLab 12.7 for project- and group-level clusters. - -[Elastic Stack](https://www.elastic.co/elastic-stack) is a complete end-to-end -log analysis solution which helps in deep searching, analyzing and visualizing the logs -generated from different machines. - -GitLab can gather logs from pods in your cluster. Filebeat runs as a DaemonSet -on each node in your cluster, and ships container logs to Elasticsearch for -querying. GitLab then connects to Elasticsearch for logs, instead of the -Kubernetes API, giving you access to more advanced querying capabilities. Log -data is deleted after 30 days, using [Curator](https://www.elastic.co/guide/en/elasticsearch/client/curator/5.5/about.html). - -The Elastic Stack cluster application is intended as a log aggregation solution -and is not related to our [Advanced Search](../search/advanced_search.md) -functionality, which uses a separate Elasticsearch cluster. - -To enable log shipping: - -1. Ensure your cluster contains at least three nodes of instance types larger - than `f1-micro`, `g1-small`, or `n1-standard-1`. -1. Navigate to **Operations > Kubernetes**. -1. In **Kubernetes Cluster**, select a cluster. -1. In the **Applications** section, find **Elastic Stack**, and then select - **Install**. - -The [`gitlab/elastic-stack`](https://gitlab.com/gitlab-org/charts/elastic-stack) -chart is used to install this application with a -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/elastic_stack/values.yaml) -file. The chart deploys three identical Elasticsearch pods which can't be -colocated, and each requires one CPU and 2 GB of RAM, making them -incompatible with clusters containing fewer than three nodes, or consisting of -`f1-micro`, `g1-small`, `n1-standard-1`, or `*-highcpu-2` instance types. - -#### Optional: deploy Kibana to perform advanced queries - -If you are an advanced user and have direct access to your Kubernetes cluster -using `kubectl` and `helm`, you can deploy Kibana manually. The following assumes -that `helm` has been [initialized](https://v2.helm.sh/docs/helm/) with `helm init`. - -Save the following to `kibana.yml`: - -```yaml -elasticsearch: - enabled: false - -filebeat: - enabled: false - -kibana: - enabled: true - elasticsearchHosts: http://elastic-stack-elasticsearch-master.gitlab-managed-apps.svc.cluster.local:9200 -``` - -Then install it on your cluster: - -```shell -helm repo add gitlab https://charts.gitlab.io -helm install --name kibana gitlab/elastic-stack --values kibana.yml -``` - -To access Kibana, forward the port to your local machine: - -```shell -kubectl port-forward svc/kibana-kibana 5601:5601 -``` - -Then, you can visit Kibana at `http://localhost:5601`. - -### Fluentd - -> Introduced in GitLab 12.10 for project- and group-level clusters. - -[Fluentd](https://www.fluentd.org/) is an open source data collector, which enables -you to unify the data collection and consumption to better use and understand -your data. Fluentd sends logs in syslog format. - -To enable Fluentd: - -1. Navigate to **Operations > Kubernetes** and click - **Applications**. Enter a host, port, and protocol - for sending the WAF logs with syslog. -1. Provide the host domain name or URL in **SIEM Hostname**. -1. Provide the host port number in **SIEM Port**. -1. Select a **SIEM Protocol**. -1. Select at least one of the available logs (such as WAF or Cilium). -1. Click **Save changes**. - - - -## Upgrading applications - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24789) in GitLab 11.8. - -The applications below can be upgraded. - -| Application | GitLab version | -| ----------- | -------------- | -| GitLab Runner | 11.8+ | - -To upgrade an application: - -1. For a: - - [Project-level cluster](../project/clusters/index.md), - navigate to your project's **Operations > Kubernetes**. - - [Group-level cluster](../group/clusters/index.md), - navigate to your group's **Kubernetes** page. -1. Select your cluster. -1. If an upgrade is available, the **Upgrade** button is displayed. Click the button to upgrade. - -Upgrades reset values back to the values built into the `runner` chart, plus the values set by -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/runner/values.yaml) - -## Uninstalling applications - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/60665) in GitLab 11.11. - -The applications below can be uninstalled. - -| Application | GitLab version | Notes | -| ----------- | -------------- | ----- | -| cert-manager | 12.2+ | The associated private key is deleted and cannot be restored. Deployed applications continue to use HTTPS, but certificates aren't renewed. Before uninstalling, you may want to [back up your configuration](https://cert-manager.io/docs/tutorials/backup/) or [revoke your certificates](https://letsencrypt.org/docs/revoking/). | -| GitLab Runner | 12.2+ | Any running pipelines are canceled. | -| Helm | 12.2+ | The associated Tiller pod, the `gitlab-managed-apps` namespace, and all of its resources are deleted and cannot be restored. | -| Ingress | 12.1+ | The associated load balancer and IP are deleted and cannot be restored. Furthermore, it can only be uninstalled if JupyterHub is not installed. | -| JupyterHub | 12.1+ | All data not committed to GitLab are deleted and cannot be restored. | -| Knative | 12.1+ | The associated IP are deleted and cannot be restored. | -| Prometheus | 11.11+ | All data are deleted and cannot be restored. | -| Crossplane | 12.5+ | All data are deleted and cannot be restored. | -| Elastic Stack | 12.7+ | All data are deleted and cannot be restored. | -| Sentry | 12.6+ | The PostgreSQL persistent volume remains and should be manually removed for complete uninstall. | - -To uninstall an application: - -1. For a: - - [Project-level cluster](../project/clusters/index.md), - navigate to your project's **Operations > Kubernetes**. - - [Group-level cluster](../group/clusters/index.md), - navigate to your group's **Kubernetes** page. -1. Select your cluster. -1. Click the **Uninstall** button for the application. - -Support for uninstalling all applications is planned for progressive rollout. -To follow progress, see the [relevant epic](https://gitlab.com/groups/gitlab-org/-/epics/1201). - -## Troubleshooting applications - -Applications can fail with the following error: - -```plaintext -Error: remote error: tls: bad certificate -``` - -To avoid installation errors: - -- Before starting the installation of applications, make sure that time is synchronized - between your GitLab server and your Kubernetes cluster. -- Ensure certificates are not out of sync. When installing applications, GitLab - expects a new cluster with no previous installation of Helm. - - You can confirm that the certificates match by using `kubectl`: - - ```shell - kubectl get configmaps/values-content-configuration-ingress -n gitlab-managed-apps -o \ - "jsonpath={.data['cert\.pem']}" | base64 -d > a.pem - kubectl get secrets/tiller-secret -n gitlab-managed-apps -o "jsonpath={.data['ca\.crt']}" | base64 -d > b.pem - diff a.pem b.pem - ``` - -### Error installing managed apps on EKS cluster - -If you're using a managed cluster on AWS EKS, and you are not able to install some of the managed -apps, consider checking the logs. - -You can check the logs by running the following commands: - -```shell -kubectl get pods --all-namespaces -kubectl get services --all-namespaces -``` - -If you are getting the `Failed to assign an IP address to container` error, it's probably due to the -instance type you've specified in the AWS configuration. -The number and size of nodes might not have enough IP addresses to run or install those pods. - -For reference, all the AWS instance IP limits are found -[in this AWS repository on GitHub](https://github.com/aws/amazon-vpc-cni-k8s/blob/master/pkg/awsutils/vpc_ip_resource_limit.go) (search for `InstanceENIsAvailable`). - -### Unable to install Prometheus - -Installing Prometheus is failing with the following error: - -```shell -# kubectl -n gitlab-managed-apps logs install-prometheus -... -Error: Could not get apiVersions from Kubernetes: unable to retrieve the complete list of server APIs: admission.certmanager.k8s.io/v1beta1: the server is currently unable to handle the request -``` - -This is a bug that was introduced in Helm `2.15` and fixed in `3.0.2`. As a workaround, -ensure [`cert-manager`](#cert-manager) is installed successfully prior to installing Prometheus. - -### Unable to create a Persistent Volume Claim with DigitalOcean - -Trying to create additional block storage volumes might lead to the following error when using DigitalOcean: +## Browse applications logs -```plaintext -Server requested -[Warning] pod has unbound immediate PersistentVolumeClaims (repeated 2 times) -[Normal] pod didn't trigger scale-up (it wouldn't fit if a new node is added): -Spawn failed: Timeout -``` +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36769) in GitLab 13.2. -This is due to DigitalOcean imposing a few limits with regards to creating additional block storage volumes. -[Learn more about DigitalOcean Block Storage Volumes limits.](https://www.digitalocean.com/docs/volumes/#limits) +Logs produced by pods running **GitLab Managed Apps** can be browsed using +[**Log Explorer**](../project/clusters/kubernetes_pod_logs.md). ## Take ownership of your GitLab Managed Apps > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327803) in GitLab 13.12. -With the removal of the [One-click install method](#install-with-one-click-deprecated) in GitLab 14.0, -the **Applications** tab (under your project's **Operations > Kubernetes**) -will no longer be displayed: +With the removal of the One-click install method in GitLab 14.0, +the **Applications** tab (under your project's **Infrastructure > Kubernetes clusters**) +is no longer displayed:  @@ -1781,10 +1126,10 @@ If you choose to keep using Helm v2 (B), follow the steps below to manage your a ### Cluster integrations -Some applications were not only installed in your cluster by GitLab through Managed Apps but were also -directly integrated with GitLab so that you could benefit from seeing, controlling, or getting notified -about them through GitLab. -To keep them integrated, read the documentation for: +Some applications were not only installed in your cluster by GitLab through +Managed Apps but were also directly integrated with GitLab. If you had one of +these applications installed before GitLab 14.0, then a corresponding [cluster +integration](integrations.md) has been automatically enabled: - [Prometheus cluster integration](integrations.md#prometheus-cluster-integration) - [Elastic Stack cluster integration](integrations.md#elastic-stack-cluster-integration) diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md index d1df5642514..26611c26e5e 100644 --- a/doc/user/clusters/cost_management.md +++ b/doc/user/clusters/cost_management.md @@ -33,9 +33,9 @@ permissions in a project or group. 1. Connect GitLab with Prometheus, depending on your configuration: - *If Prometheus is already configured,* navigate to **Settings > Integrations > Prometheus** to provide the API endpoint of your Prometheus server. - - *For GitLab-managed Prometheus,* navigate to your cluster's **Details** page, - select the **Applications** tab, and install Prometheus. The integration is - auto-configured for you. + - *To use the Prometheus cluster integration,* navigate to your cluster's **Details** page, + select the **Integrations** tab, and follow the instructions to enable the Prometheus + cluster integration. 1. Set up the Prometheus integration on the cloned example project. 1. Add the Kubecost `cost-model` to your cluster: - *For non-managed clusters*, deploy it with GitLab CI/CD. @@ -46,7 +46,7 @@ permissions in a project or group. kubectl apply -f kubernetes/ --namespace cost-model ``` -To access the cost insights, navigate to **Operations > Metrics** and select +To access the cost insights, navigate to **Monitor > Metrics** and select the `default_costs.yml` dashboard. You can [customize](#customize-the-cost-dashboard) this dashboard. diff --git a/doc/user/clusters/crossplane.md b/doc/user/clusters/crossplane.md index bdf9d582b93..8906d1224b1 100644 --- a/doc/user/clusters/crossplane.md +++ b/doc/user/clusters/crossplane.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Crossplane configuration **(FREE)** -After [installing](applications.md#crossplane) Crossplane, you must configure it for use. +After [installing](applications.md#install-crossplane-using-gitlab-cicd) Crossplane, you must configure it for use. The process of configuring Crossplane includes: 1. [Configure RBAC permissions](#configure-rbac-permissions). diff --git a/doc/user/clusters/img/fluentd_v13_0.png b/doc/user/clusters/img/fluentd_v13_0.png Binary files differdeleted file mode 100644 index edc73285238..00000000000 --- a/doc/user/clusters/img/fluentd_v13_0.png +++ /dev/null diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md index a8b181f8726..6c87efaf5a3 100644 --- a/doc/user/clusters/integrations.md +++ b/doc/user/clusters/integrations.md @@ -14,6 +14,17 @@ To enable cluster integrations, first add a Kubernetes cluster to a GitLab [group](../group/clusters/index.md#group-level-kubernetes-clusters) or [instance](../instance/clusters/index.md). +You can install your applications manually as shown in the following sections, or use the +[Cluster management project template](management_project_template.md) that automates the +installation. + +Although, the [Cluster management project template](management_project_template.md) still +requires that you manually do the last steps of these sections, +[Enable Prometheus integration for your cluster](#enable-prometheus-integration-for-your-cluster) +or [Enable Elastic Stack integration for your cluster](#enable-elastic-stack-integration-for-your-cluster) +depending on which application you are installing. We plan to also automate this step in the future, +see the [opened issue](https://gitlab.com/gitlab-org/gitlab/-/issues/326565). + ## Prometheus cluster integration > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55244) in GitLab 13.11. @@ -43,10 +54,8 @@ it up using [Helm](https://helm.sh/) as follows: kubectl create ns gitlab-managed-apps # Download Helm chart values that is compatible with the requirements above. -# You should substitute the tag that corresponds to the GitLab version in the URL -# - https://gitlab.com/gitlab-org/gitlab/-/raw/<tag>/vendor/prometheus/values.yaml -# -wget https://gitlab.com/gitlab-org/gitlab/-/raw/v13.9.0-ee/vendor/prometheus/values.yaml +# These are included in the Cluster Management project template. +wget https://gitlab.com/gitlab-org/project-templates/cluster-management/-/raw/master/applications/prometheus/values.yaml # Add the Prometheus community Helm chart repository helm repo add prometheus-community https://prometheus-community.github.io/helm-charts @@ -64,7 +73,7 @@ To enable the Prometheus integration for your cluster: 1. Go to the cluster's page: - For a [project-level cluster](../project/clusters/index.md), navigate to your project's - **Operations > Kubernetes**. + **Infrastructure > Kubernetes clusters**. - For a [group-level cluster](../group/clusters/index.md), navigate to your group's **Kubernetes** page. - For an [instance-level cluster](../instance/clusters/index.md), navigate to your instance's @@ -103,10 +112,8 @@ running: kubectl create namespace gitlab-managed-apps # Download Helm chart values that is compatible with the requirements above. -# You should substitute the tag that corresponds to the GitLab version in the URL -# - https://gitlab.com/gitlab-org/gitlab/-/raw/<tag>/vendor/elastic_stack/values.yaml -# -wget https://gitlab.com/gitlab-org/gitlab/-/raw/v13.9.0-ee/vendor/elastic_stack/values.yaml +# These are included in the Cluster Management project template. +wget https://gitlab.com/gitlab-org/project-templates/cluster-management/-/raw/master/applications/elastic-stack/values.yaml # Add the GitLab Helm chart repository helm repo add gitlab https://charts.gitlab.io @@ -121,7 +128,7 @@ To enable the Elastic Stack integration for your cluster: 1. Go to the cluster's page: - For a [project-level cluster](../project/clusters/index.md), navigate to your project's - **Operations > Kubernetes**. + **Infrastructure > Kubernetes clusters**. - For a [group-level cluster](../group/clusters/index.md), navigate to your group's **Kubernetes** page. - For an [instance-level cluster](../instance/clusters/index.md), navigate to your instance's diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index e728577e194..f741ab2d95a 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -6,10 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Cluster management project **(FREE)** -WARNING: -This is an _alpha_ feature, and it is subject to change at any time without -prior notice. - > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32810) in GitLab 12.5 A project can be designated as the management project for a cluster. @@ -20,7 +16,7 @@ privileges. This can be useful for: -- Creating pipelines to install cluster-wide applications into your cluster, see [Install using GitLab CI/CD (beta)](applications.md#install-using-gitlab-cicd-deprecated) for details. +- Creating pipelines to install cluster-wide applications into your cluster, see [management project template](management_project_template.md) for details. - Any jobs that require `cluster-admin` privileges. ## Permissions @@ -50,7 +46,7 @@ To select a cluster management project to use: 1. Navigate to the appropriate configuration page. For a: - [Project-level cluster](../project/clusters/index.md), navigate to your project's - **Operations > Kubernetes** page. + **Infrastructure > Kubernetes clusters** page. - [Group-level cluster](../group/clusters/index.md), navigate to your group's **Kubernetes** page. - [Instance-level cluster](../instance/clusters/index.md), navigate to Admin Area's **Kubernetes** diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md new file mode 100644 index 00000000000..52390cb18b0 --- /dev/null +++ b/doc/user/clusters/management_project_template.md @@ -0,0 +1,86 @@ +--- +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 +--- + +# Cluster Management Project Template **(FREE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25318) in GitLab 12.10 with Helmfile support via Helm v2. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63577) in GitLab 14.0 with Helmfile support via Helm v3 instead, and a much more flexible usage of Helmfile. This introduces breaking changes that are detailed below. + +This [GitLab built-in project template](../project/working_with_projects.md#built-in-templates) +provides a quicker start for users interested in managing cluster +applications via [Helm v3](https://helm.sh/) charts. More specifically, taking advantage of the +[Helmfile](https://github.com/roboll/helmfile) utility client. The template consists of some pre-configured apps that +should help you get started quickly using various GitLab features. Still, you have all the flexibility to remove the ones you do not +need, or even add new ones that are not built-in. + +## How to use this template + +1. Create a new project, choosing "GitLab Cluster Management" from the list of [built-in project templates](../project/working_with_projects.md#built-in-templates). +1. Make this project a [cluster management project](management_project.md). +1. If you used the [GitLab Managed Apps](applications.md), refer to + [Migrating from GitLab Manged Apps](migrating_from_gma_to_project_template.md). + +### Components + +In the repository of the newly-created project, you will find: + +- A predefined [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/blob/master/.gitlab-ci.yml) + file, with a CI pipeline already configured. +- A main [`helmfile.yaml`](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/blob/master/helmfile.yaml) to toggle which applications you would like to manage. +- An `applications` directory with a `helmfile.yaml` configured for each application GitLab provides. + +#### The `.gitlab-ci.yml` file + +The base image used in your pipeline is built by the [cluster-applications](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications) +project. This image consists of a set of Bash utility scripts to support [Helm v3 releases](https://helm.sh/docs/intro/using_helm/#three-big-concepts): + +- `gl-fail-if-helm2-releases-exist {namespace}`: It tries to detect whether you have apps deployed through Helm v2 + releases for a given namespace. If so, it will fail the pipeline and ask you to manually + [migrate your Helm v2 releases to Helm v3](https://helm.sh/docs/topics/v2_v3_migration/). +- `gl-ensure-namespace {namespace}`: It creates the given namespace if it does not exist and adds the necessary label + for the [Cilium](https://github.com/cilium/cilium/) app network policies to work. +- `gl-adopt-resource-with-helm-v3 {arguments}`: Used only internally in the [cert-manager's](https://cert-manager.io/) Helmfile to + facilitate the GitLab Managed Apps adoption. +- `gl-adopt-crds-with-helm-v3 {arguments}`: Used only internally in the [cert-manager's](https://cert-manager.io/) Helmfile to + facilitate the GitLab Managed Apps adoption. +- `gl-helmfile {arguments}`: A thin wrapper that triggers the [Helmfile](https://github.com/roboll/helmfile) command. + +#### The main `helmfile.yml` file + +This file has a list of paths to other Helmfiles for each app. They're all commented out by default, so you must uncomment +the paths for the apps that you would like to manage. + +By default, each `helmfile.yaml` in these sub-paths will have the attribute `installed: true`, which signifies that everytime +the pipeline runs, Helmfile will try to either install or update your apps according to the current state of your +cluster and Helm releases. If you change this attribute to `installed: false`, Helmfile will try to uninstall this app +from your cluster. [Read more](https://github.com/roboll/helmfile) about how Helmfile works. + +Furthermore, each app has an `applications/{app}/values.yaml` file. This is the +place where you can define some default values for your app's Helm chart. Some apps will already have defaults +pre-defined by GitLab. + +#### Built-in applications + +The built-in applications are intended to provide an easy way to get started with various Kubernetes oriented GitLab features. + +The [built-in supported applications](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/tree/master/applications) are: + +- Apparmor +- Cert-manager +- Cilium +- Elastic Stack +- Falco +- Fluentd +- GitLab Runner +- Ingress +- Prometheus +- Sentry +- Vault + +### Migrating from GitLab Managed Apps + +If you had GitLab Managed Apps, either One-Click or CI/CD install, read the docs on how to +[migrate from GitLab Managed Apps to project template](migrating_from_gma_to_project_template.md) diff --git a/doc/user/clusters/migrating_from_gma_to_project_template.md b/doc/user/clusters/migrating_from_gma_to_project_template.md new file mode 100644 index 00000000000..7fa6ccea433 --- /dev/null +++ b/doc/user/clusters/migrating_from_gma_to_project_template.md @@ -0,0 +1,95 @@ +--- +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 +--- + +# Migrating from GitLab Managed Apps to a management project template + +The [GitLab Managed Apps](applications.md) are deprecated in GitLab 14.0. To migrate to the new way of managing them: + +1. Read how the [management project template](management_project_template.md) works, and + create a new project based on the "GitLab Cluster Management" template. +1. Create a new project as explained in the [management project template](management_project_template.md). +1. Detect apps deployed through Helm v2 releases by using the pre-configured [`.gitlab-ci.yml`](management_project_template.md#the-gitlab-ciyml-file) file: + - In case you had overwritten the default GitLab Managed Apps namespace, edit `.gitlab-ci.yml`, + and make sure the script is receiving the correct namespace as an argument: + + ```yaml + script: + - gl-fail-if-helm2-releases-exist <your_custom_namespace> + ``` + + - If you kept the default name (`gitlab-managed-apps`), then the script is already + set up. + + Either way, [run a pipeline manually](../../ci/pipelines/index.md#run-a-pipeline-manually) and read the logs of the + `detect-helm2-releases` job to know if you have any Helm v2 releases and which are they. + +1. If you have no Helm v2 releases, skip this step. Otherwise, follow the official Helm docs on + [how to migrate from Helm v2 to Helm v3](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/), + and clean up the Helm v2 releases after you are confident that they have been successfully migrated. + +1. In this step you should already have only Helm v3 releases. + Uncomment from the main [`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file) the paths for the + applications that you would like to manage with this project. Although you could uncomment all the ones you want to + managed at once, we recommend you repeat the following steps separately for each app, so you do not get lost during + the process. +1. Edit the associated `applications/{app}/helmfiles.yaml` to match the chart version currently deployed + for your app. Take a GitLab Runner Helm v3 release as an example: + + The following command lists the releases and their versions: + + ```shell + helm ls -n gitlab-managed-apps + + NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION + runner gitlab-managed-apps 1 2021-06-09 19:36:55.739141644 +0000 UTC deployed gitlab-runner-0.28.0 13.11.0 + ``` + + Take the version from the `CHART` column which is in the format `{release}-v{chart_version}`, + then edit the `version:` attribute in the `./applications/gitlab-runner/helmfile.yaml`, so that it matches the version + you have currently deployed. This is a safe step to avoid upgrading versions during this migration. + Make sure you replace `gitlab-managed-apps` from the above command if you have your apps deployed to a different + namespace. + +1. Edit the `applications/{app}/values.yaml` associated with your app to match the currently + deployed values. For example, for GitLab Runner: + + 1. Copy the output of the following command (it might be big): + + ```shell + helm get values runner -n gitlab-managed-apps -a --output yaml + ``` + + 1. Overwrite `applications/gitlab-runner/values.yaml` with the output of the previous command. + + This safe step will guarantee that no unexpected default values overwrite your currently deployed values. + For instance, your GitLab Runner could have its `gitlabUrl` or `runnerRegistrationToken` overwritten by mistake. + +1. Some apps require special attention: + + - Ingress: Due to an existing [chart issue](https://github.com/helm/charts/pull/13646), you might see + `spec.clusterIP: Invalid value` when trying to run the [`./gl-helmfile`](management_project_template.md#the-gitlab-ciyml-file) + command. To work around this, after overwriting the release values in `applications/ingress/values.yaml`, + you might need to overwrite all the occurrences of `omitClusterIP: false`, setting it to `omitClusterIP: true`. + Another approach,could be to collect these IPs by running `kubectl get services -n gitlab-managed-apps` + and then overwriting each `ClusterIP` that it complains about with the value you got from that command. + + - Vault: This application introduces a breaking change from the chart we used in Helm v2 to the chart + used in Helm v3. So, the only way to integrate it with this Cluster Management Project is to actually uninstall this app and accept the + chart version proposed in `applications/vault/values.yaml`. + +1. After following all the previous steps, [run a pipeline manually](../../ci/pipelines/index.md#run-a-pipeline-manually) + and watch the `apply` job logs to see if any of your applications were successfully detected, installed, and whether they got any + unexpected updates. + + Some annotation checksums are expected to be updated, as well as this attribute: + + ```diff + --- heritage: Tiller + +++ heritage: Tiller + ``` + +After getting a successful pipeline, repeat these steps for any other deployed apps +you want to manage with the Cluster Management Project. diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 43dbafb8f6f..f757a548aee 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -91,11 +91,11 @@ To run a License Compliance scanning job, you need GitLab Runner with the For GitLab 12.8 and later, to enable License Compliance, you must [include](../../../ci/yaml/README.md#includetemplate) the -[`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/License-Scanning.gitlab-ci.yml) +[`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/License-Scanning.gitlab-ci.yml) that's provided as a part of your GitLab installation. For older versions of GitLab from 11.9 to 12.7, you must [include](../../../ci/yaml/README.md#includetemplate) the -[`License-Management.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/License-Management.gitlab-ci.yml). +[`License-Management.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/d2cc841c55d65bc8134bfb3a467e66c36ac32b0a/lib/gitlab/ci/templates/Security/License-Management.gitlab-ci.yml). For GitLab versions earlier than 11.9, you can copy and use the job as defined that template. @@ -121,7 +121,7 @@ always take the latest License Compliance artifact available. Behind the scenes, [GitLab License Compliance Docker image](https://gitlab.com/gitlab-org/security-products/analyzers/license-finder) is used to detect the languages/frameworks and in turn analyzes the licenses. -The License Compliance settings can be changed through [CI/CD variables](#available-variables) by using the +The License Compliance settings can be changed through [CI/CD variables](#available-cicd-variables) by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. ### When License Compliance runs @@ -129,7 +129,7 @@ The License Compliance settings can be changed through [CI/CD variables](#availa When using the GitLab `License-Scanning.gitlab-ci.yml` template, the License Compliance job doesn't wait for other stages to complete. -### Available variables +### Available CI/CD variables License Compliance can be configured using CI/CD variables. @@ -153,7 +153,7 @@ License Compliance can be configured using CI/CD variables. > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. -The `license_management` image already embeds many auto-detection scripts, languages, +The `license_finder` image already embeds many auto-detection scripts, languages, and packages. Nevertheless, it's almost impossible to cover all cases for all projects. That's why sometimes it's necessary to install extra packages, or to have extra steps in the project automated setup, like the download and installation of a certificate. @@ -265,11 +265,11 @@ license_scanning: ### Custom root certificates for Python You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables). +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). #### Using private Python repositories -If you have a private Python repository you can use the `PIP_INDEX_URL` [CI/CD variable](#available-variables) +If you have a private Python repository you can use the `PIP_INDEX_URL` [CI/CD variable](#available-cicd-variables) to specify its location. ### Configuring npm projects @@ -292,7 +292,7 @@ registry = https://npm.example.com #### Custom root certificates for npm You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables). +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). To disable TLS verification you can provide the [`strict-ssl`](https://docs.npmjs.com/using-npm/config/#strict-ssl) setting. @@ -323,7 +323,7 @@ npmRegistryServer: "https://npm.example.com" #### Custom root certificates for Yarn You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables). +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). ### Configuring Bower projects @@ -347,7 +347,7 @@ For example: #### Custom root certificates for Bower You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables), or by +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), or by specifying a `ca` setting in a [`.bowerrc`](https://bower.io/docs/config/#bowerrc-specification) file. @@ -368,7 +368,7 @@ source "https://gems.example.com" #### Custom root certificates for Bundler You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables), or by +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), or by specifying a [`BUNDLE_SSL_CA_CERT`](https://bundler.io/v2.0/man/bundle-config.1.html) [variable](../../../ci/variables/README.md#custom-cicd-variables) in the job definition. @@ -392,7 +392,7 @@ my-registry = { index = "https://my-intranet:8080/git/index" } To supply a custom root certificate to complete TLS verification, do one of the following: -- Use the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables). +- Use the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). - Specify a [`CARGO_HTTP_CAINFO`](https://doc.rust-lang.org/cargo/reference/environment-variables.html) [variable](../../../ci/variables/README.md#custom-cicd-variables) in the job definition. @@ -425,7 +425,7 @@ For example: #### Custom root certificates for Composer You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables), or by +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), or by specifying a [`COMPOSER_CAFILE`](https://getcomposer.org/doc/03-cli.md#composer-cafile) [variable](../../../ci/variables/README.md#custom-cicd-variables) in the job definition. @@ -499,7 +499,7 @@ You can provide custom certificates by adding a `.conan/cacert.pem` file to the setting [`CA_CERT_PATH`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-cacert-path) to `.conan/cacert.pem`. -If you specify the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables), this +If you specify the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), this variable's X.509 certificates are installed in the Docker image's default trust store and Conan is configured to use this as the default `CA_CERT_PATH`. @@ -507,7 +507,7 @@ configured to use this as the default `CA_CERT_PATH`. To configure [Go modules](https://github.com/golang/go/wiki/Modules) based projects, specify [CI/CD variables](https://golang.org/pkg/cmd/go/#hdr-Environment_variables) -in the `license_scanning` job's [variables](#available-variables) section in `.gitlab-ci.yml`. +in the `license_scanning` job's [variables](#available-cicd-variables) section in `.gitlab-ci.yml`. If a project has [vendored](https://golang.org/pkg/cmd/go/#hdr-Vendor_Directories) its modules, then the combination of the `vendor` directory and `mod.sum` file are used to detect the software @@ -556,10 +556,13 @@ For example: #### Custom root certificates for NuGet You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables). +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). ### Migration from `license_management` to `license_scanning` +WARNING: +The `license_management` job was deprecated in GitLab 12.8. The `License-Management.gitlab-ci.yml` template was removed from GitLab 14.0. + In GitLab 12.8 a new name for `license_management` job was introduced. This change was made to improve clarity around the purpose of the scan, which is to scan and collect the types of licenses present in a projects dependencies. GitLab 13.0 drops support for `license_management`. If you're using a custom setup for License Compliance, you're required @@ -730,8 +733,9 @@ Developers of the project can view the policies configured in a project. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13067) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. -`License-Check` is a [security approval](../../application_security/index.md#enabling-security-approvals-within-a-project) rule you can enable to allow an individual or group to approve a -merge request that contains a `denied` license. +`License-Check` is a [merge request approval](../../project/merge_requests/approvals/index.md) rule +you can enable to allow an individual or group to approve a merge request that contains a `denied` +license. You can enable `License-Check` one of two ways: @@ -816,7 +820,7 @@ license_scanning: ASDF_RUBY_VERSION: '2.7.2' ``` -A full list of variables can be found in [CI/CD variables](#available-variables). +A full list of variables can be found in [CI/CD variables](#available-cicd-variables). To find out what tools are pre-installed in the `license_scanning` Docker image use the following command: diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 50007545a65..cf57afb8324 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -7,7 +7,8 @@ type: reference, howto # Threads **(FREE)** -GitLab encourages communication through comments, threads, and suggestions. +GitLab encourages communication through comments, threads, and +[code suggestions](../project/merge_requests/reviews/suggestions.md). For example, you can create a comment in the following places: @@ -22,8 +23,10 @@ There are standard comments, and you also have the option to create a comment in the form of a thread. A comment can also be [turned into a thread](#start-a-thread-by-replying-to-a-standard-comment) when it receives a reply. -The comment area supports [Markdown](../markdown.md) and [quick actions](../project/quick_actions.md). You can edit your own -comment at any time, and anyone with [Maintainer access level](../permissions.md) or +The comment area supports [Markdown](../markdown.md) and [quick actions](../project/quick_actions.md). +You can [suggest code changes](../project/merge_requests/reviews/suggestions.md) in your comment, +which the user can accept through the user interface. You can edit your own +comment at any time, and anyone with the [Maintainer role](../permissions.md) or higher can also edit a comment made by someone else. You can also reply to a comment notification email to reply to the comment if diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index cdb4ca52c9c..223d3363186 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -153,289 +153,19 @@ content directly from common public CDN hostnames. ## Webhooks -A limit of: +The following limits apply for [Webhooks](../project/integrations/webhooks.md): -- 100 webhooks applies to projects. -- 50 webhooks applies to groups. **(BRONZE ONLY)** -- Payload is limited to 25MB +| Setting | GitLab.com | Default | +| ------- | ---------- | ------- | +| [Webhook rate limit](../../administration/instance_limits.md#webhook-rate-limit) | `120` calls per minute for Free tier, unlimited for all paid tiers | Unlimited +| [Number of webhooks](../../administration/instance_limits.md#number-of-webhooks) | `100` per-project, `50` per-group | `100` per-project, `50` per-group +| Maximum payload size | `25 MB` | `25 MB` ## Shared runners -GitLab offers Linux and Windows shared runners hosted on GitLab.com for executing your pipelines. +GitLab has shared runners on GitLab.com that you can use to run your CI jobs. -NOTE: -Shared runners provided by GitLab are **not** configurable. Consider [installing your own runner](https://docs.gitlab.com/runner/install/) if you have specific configuration needs. - -### Linux shared runners - -Linux shared runners on GitLab.com run in autoscale mode and are powered by Google Cloud Platform. - -Autoscaling means reduced queue times to spin up CI/CD jobs, and isolated VMs for each project, thus maximizing security. These shared runners are available for users and customers on GitLab.com. - -GitLab offers Ultimate tier capabilities and included CI/CD minutes per group per month for our [Open Source](https://about.gitlab.com/solutions/open-source/join/), [Education](https://about.gitlab.com/solutions/education/), and [Startups](https://about.gitlab.com/solutions/startups/) programs. For private projects, GitLab offers various [plans](https://about.gitlab.com/pricing/), starting with a Free tier. - -All your CI/CD jobs run on [n1-standard-1 instances](https://cloud.google.com/compute/docs/machine-types) with 3.75GB of RAM, CoreOS and the latest Docker Engine -installed. Instances provide 1 vCPU and 25GB of HDD disk space. The default -region of the VMs is US East1. -Each instance is used only for one job, this ensures any sensitive data left on the system can't be accessed by other people their CI jobs. - -The `gitlab-shared-runners-manager-X.gitlab.com` fleet of runners are dedicated for GitLab projects as well as community forks of them. They use a slightly larger machine type (n1-standard-2) and have a bigger SSD disk size. They don't run untagged jobs and unlike the general fleet of shared runners, the instances are re-used up to 40 times. - -Jobs handled by the shared runners on GitLab.com (`shared-runners-manager-X.gitlab.com`), -**time out after 3 hours**, regardless of the timeout configured in a -project. Check the issues [4010](https://gitlab.com/gitlab-com/infrastructure/-/issues/4010) and [4070](https://gitlab.com/gitlab-com/infrastructure/-/issues/4070) for the reference. - -Below are the shared runners settings. - -| Setting | GitLab.com | Default | -| ----------- | ----------------- | ---------- | -| [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) | [Runner versions dashboard](https://dashboards.gitlab.com/d/000000159/ci?from=now-1h&to=now&refresh=5m&orgId=1&panelId=12&fullscreen&theme=light) | - | -| Executor | `docker+machine` | - | -| Default Docker image | `ruby:2.5` | - | -| `privileged` (run [Docker in Docker](https://hub.docker.com/_/docker/)) | `true` | `false` | - -#### Pre-clone script - -Linux shared runners on GitLab.com provide a way to run commands in a CI -job before the runner attempts to run `git init` and `git fetch` to -download a GitLab repository. The -[`pre_clone_script`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) -can be used for: - -- Seeding the build directory with repository data -- Sending a request to a server -- Downloading assets from a CDN -- Any other commands that must run before the `git init` - -To use this feature, define a [CI/CD variable](../../ci/variables/README.md#custom-cicd-variables) called -`CI_PRE_CLONE_SCRIPT` that contains a bash script. - -[This example](../../development/pipelines.md#pre-clone-step) -demonstrates how you might use a pre-clone step to seed the build -directory. - -#### `config.toml` - -The full contents of our `config.toml` are: - -NOTE: -Settings that are not public are shown as `X`. - -**Google Cloud Platform** - -```toml -concurrent = X -check_interval = 1 -metrics_server = "X" -sentry_dsn = "X" - -[[runners]] - name = "docker-auto-scale" - request_concurrency = X - url = "https://gitlab.com/" - token = "SHARED_RUNNER_TOKEN" - pre_clone_script = "eval \"$CI_PRE_CLONE_SCRIPT\"" - executor = "docker+machine" - environment = [ - "DOCKER_DRIVER=overlay2", - "DOCKER_TLS_CERTDIR=" - ] - limit = X - [runners.docker] - image = "ruby:2.5" - privileged = true - volumes = [ - "/certs/client", - "/dummy-sys-class-dmi-id:/sys/class/dmi/id:ro" # Make kaniko builds work on GCP. - ] - [runners.machine] - IdleCount = 50 - IdleTime = 3600 - MaxBuilds = 1 # For security reasons we delete the VM after job has finished so it's not reused. - MachineName = "srm-%s" - MachineDriver = "google" - MachineOptions = [ - "google-project=PROJECT", - "google-disk-size=25", - "google-machine-type=n1-standard-1", - "google-username=core", - "google-tags=gitlab-com,srm", - "google-use-internal-ip", - "google-zone=us-east1-d", - "engine-opt=mtu=1460", # Set MTU for container interface, for more information check https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3214#note_82892928 - "google-machine-image=PROJECT/global/images/IMAGE", - "engine-opt=ipv6", # This will create IPv6 interfaces in the containers. - "engine-opt=fixed-cidr-v6=fc00::/7", - "google-operation-backoff-initial-interval=2" # Custom flag from forked docker-machine, for more information check https://github.com/docker/machine/pull/4600 - ] - [[runners.machine.autoscaling]] - Periods = ["* * * * * sat,sun *"] - Timezone = "UTC" - IdleCount = 70 - IdleTime = 3600 - [[runners.machine.autoscaling]] - Periods = ["* 30-59 3 * * * *", "* 0-30 4 * * * *"] - Timezone = "UTC" - IdleCount = 700 - IdleTime = 3600 - [runners.cache] - Type = "gcs" - Shared = true - [runners.cache.gcs] - CredentialsFile = "/path/to/file" - BucketName = "bucket-name" -``` - -### Windows shared runners (beta) - -The Windows shared runners are in [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) -and shouldn't be used for production workloads. - -During this beta period, the [shared runner pipeline quota](../admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota) -applies for groups and projects in the same manner as Linux runners. This may -change when the beta period ends, as discussed in this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30834). - -Windows shared runners on GitLab.com autoscale by launching virtual machines on -the Google Cloud Platform. This solution uses an -[autoscaling driver](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/tree/master/docs/readme.md) -developed by GitLab for the [custom executor](https://docs.gitlab.com/runner/executors/custom.html). -Windows shared runners execute your CI/CD jobs on `n1-standard-2` instances with -2 vCPUs and 7.5 GB RAM. You can find a full list of available Windows packages in -the [package documentation](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/gcp/windows-containers/blob/master/cookbooks/preinstalled-software/README.md). - -We want to keep iterating to get Windows shared runners in a stable state and -[generally available](https://about.gitlab.com/handbook/product/gitlab-the-product/#generally-available-ga). -You can follow our work towards this goal in the -[related epic](https://gitlab.com/groups/gitlab-org/-/epics/2162). - -#### Configuration - -The full contents of our `config.toml` are: - -NOTE: -Settings that aren't public are shown as `X`. - -```toml -concurrent = X -check_interval = 3 - -[[runners]] - name = "windows-runner" - url = "https://gitlab.com/" - token = "TOKEN" - executor = "custom" - builds_dir = "C:\\GitLab-Runner\\builds" - cache_dir = "C:\\GitLab-Runner\\cache" - shell = "powershell" - [runners.custom] - config_exec = "C:\\GitLab-Runner\\autoscaler\\autoscaler.exe" - config_args = ["--config", "C:\\GitLab-Runner\\autoscaler\\config.toml", "custom", "config"] - prepare_exec = "C:\\GitLab-Runner\\autoscaler\\autoscaler.exe" - prepare_args = ["--config", "C:\\GitLab-Runner\\autoscaler\\config.toml", "custom", "prepare"] - run_exec = "C:\\GitLab-Runner\\autoscaler\\autoscaler.exe" - run_args = ["--config", "C:\\GitLab-Runner\\autoscaler\\config.toml", "custom", "run"] - cleanup_exec = "C:\\GitLab-Runner\\autoscaler\\autoscaler.exe" - cleanup_args = ["--config", "C:\\GitLab-Runner\\autoscaler\\config.toml", "custom", "cleanup"] -``` - -The full contents of our `autoscaler/config.toml` are: - -```toml -Provider = "gcp" -Executor = "winrm" -OS = "windows" -LogLevel = "info" -LogFormat = "text" -LogFile = "C:\\GitLab-Runner\\autoscaler\\autoscaler.log" -VMTag = "windows" - -[GCP] - ServiceAccountFile = "PATH" - Project = "some-project-df9323" - Zone = "us-east1-c" - MachineType = "n1-standard-2" - Image = "IMAGE" - DiskSize = 50 - DiskType = "pd-standard" - Subnetwork = "default" - Network = "default" - Tags = ["TAGS"] - Username = "gitlab_runner" - -[WinRM] - MaximumTimeout = 3600 - ExecutionMaxRetries = 0 - -[ProviderCache] - Enabled = true - Directory = "C:\\GitLab-Runner\\autoscaler\\machines" -``` - -#### Example - -Below is a simple `.gitlab-ci.yml` file to show how to start using the -Windows shared runners: - -```yaml -.shared_windows_runners: - tags: - - shared-windows - - windows - - windows-1809 - -stages: - - build - - test - -before_script: - - Set-Variable -Name "time" -Value (date -Format "%H:%m") - - echo ${time} - - echo "started by ${GITLAB_USER_NAME}" - -build: - extends: - - .shared_windows_runners - stage: build - script: - - echo "running scripts in the build job" - -test: - extends: - - .shared_windows_runners - stage: test - script: - - echo "running scripts in the test job" -``` - -#### Limitations and known issues - -- All the limitations mentioned in our [beta - definition](https://about.gitlab.com/handbook/product/#beta). -- The average provisioning time for a new Windows VM is 5 minutes. - This means that you may notice slower build start times - on the Windows shared runner fleet during the beta. In a future - release we intend to update the autoscaler to enable - the pre-provisioning of virtual machines. This is intended to significantly reduce - the time it takes to provision a VM on the Windows fleet. You can - follow along in the [related issue](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/-/issues/32). -- The Windows shared runner fleet may be unavailable occasionally - for maintenance or updates. -- The Windows shared runner virtual machine instances do not use the - GitLab Docker executor. This means that you can't specify - [`image`](../../ci/yaml/README.md#image) or [`services`](../../ci/yaml/README.md#services) in - your pipeline configuration. -- For the beta release, we have included a set of software packages in - the base VM image. If your CI job requires additional software that's - not included in this list, then you must add installation - commands to [`before_script`](../../ci/yaml/README.md#before_script) or [`script`](../../ci/yaml/README.md#script) to install the required - software. Note that each job runs on a new VM instance, so the - installation of additional software packages needs to be repeated for - each job in your pipeline. -- The job may stay in a pending state for longer than the - Linux shared runners. -- There is the possibility that we introduce breaking changes which will - require updates to pipelines that are using the Windows shared runner - fleet. +For more information, see [choosing a runner](../../ci/runners/README.md). ## Sidekiq @@ -502,26 +232,12 @@ for `shared_buffers` is quite high and as such we are looking into adjusting it. More information on this particular change can be found at <https://gitlab.com/gitlab-com/infrastructure/-/issues/1555>. An up to date list of proposed changes can be found at -<https://gitlab.com/gitlab-com/infrastructure/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=database&label_name[]=change>. +<https://gitlab.com/gitlab-com/infrastructure/-/issues?scope=all&state=opened&label_name[]=database&label_name[]=change>. ## Puma GitLab.com uses the default of 60 seconds for [Puma request timeouts](https://docs.gitlab.com/omnibus/settings/puma.html#worker-timeout). -## Unicorn - -GitLab.com adjusts the memory limits for the [unicorn-worker-killer](https://rubygems.org/gems/unicorn-worker-killer) gem. - -Base default: - -- `memory_limit_min` = 750MiB -- `memory_limit_max` = 1024MiB - -Web front-ends: - -- `memory_limit_min` = 1024MiB -- `memory_limit_max` = 1280MiB - ## GitLab.com-specific rate limits NOTE: diff --git a/doc/user/group/bulk_editing/index.md b/doc/user/group/bulk_editing/index.md index 48644b7427d..feceafd0991 100644 --- a/doc/user/group/bulk_editing/index.md +++ b/doc/user/group/bulk_editing/index.md @@ -1,5 +1,6 @@ --- redirect_to: '../../../user/group/index.md' +remove_date: '2021-08-13' --- This document was moved to [another location](../../../user/group/index.md). diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 87b259df9d8..4de464822f7 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -17,12 +17,11 @@ your group, enabling you to use the same cluster across multiple projects. To view your group level Kubernetes clusters, navigate to your project and select **Kubernetes** from the left-hand menu. -## Installing applications +## Cluster management project -GitLab can install and manage some applications in your group-level -cluster. For more information on installing, upgrading, uninstalling, -and troubleshooting applications for your group cluster, see -[GitLab Managed Apps](../../clusters/applications.md). +Attach a [cluster management project](../../clusters/management_project.md) +to your cluster to manage shared resources requiring `cluster-admin` privileges for +installation, such as an Ingress controller. ## RBAC compatibility @@ -72,9 +71,6 @@ for deployments with a cluster not managed by GitLab, you must ensure: (this is [not automatic](https://gitlab.com/gitlab-org/gitlab/-/issues/31519)). Editing `KUBE_NAMESPACE` directly is discouraged. -If you [install applications](#installing-applications) on your cluster, GitLab creates -the resources required to run them, even if you choose to manage your own cluster. - ### Clearing the cluster cache > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31759) in GitLab 12.6. @@ -100,7 +96,7 @@ per [multiple Kubernetes clusters](#multiple-kubernetes-clusters) When specifyin this is automatically set as an environment variable (`KUBE_INGRESS_BASE_DOMAIN`) during the [Auto DevOps](../../../topics/autodevops/index.md) stages. -The domain should have a wildcard DNS configured to the Ingress IP address. +The domain should have a wildcard DNS configured to the Ingress IP address. [More details](../../project/clusters/index.md#base-domain). ## Environment scopes **(PREMIUM)** diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index 016bda329b2..d544003536e 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -9,26 +9,29 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6861) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.6. -Custom project templates are useful for organizations that need to create many similar types of [projects](../project/index.md) and want to start from the same jumping-off point. +Custom project templates are useful for organizations that need to create many similar types of +[projects](../project/index.md). +Projects created from these templates serve as a common starting point. ## Setting up group-level project templates -To use a custom project template for a new project you need to: +To use a custom project template for a new project: -1. [Create a 'templates' subgroup](subgroups/index.md). -1. [Add repositories (projects) to the that new subgroup](index.md#add-projects-to-a-group), as your templates. -1. Edit your group's settings to look to your 'templates' subgroup for templates: - 1. In the left-hand menu, click **{settings}** **Settings > General**. +1. [Create a `templates` subgroup](subgroups/index.md). +1. [Add repositories (projects) to that new subgroup](index.md#add-projects-to-a-group), + as your templates. +1. Edit your group's settings to look to your _templates_ subgroup for templates: - NOTE: - If you don't have access to the group's settings, you may not have sufficient privileges (for example, you may need developer or higher permissions). - - 1. Scroll to **Custom project templates** and click **Expand**. If no **Custom project templates** section displays, make sure you've created a subgroup, and added a project (repository) to it. - 1. Select the 'templates' subgroup. + 1. In the left menu, select **Settings > General**. If you don't have access to the + group's settings, you may not have sufficient privileges (for example, you may need developer + or higher permissions). + 1. Scroll to **Custom project templates** and select **Expand**. If no **Custom project templates** + section displays, make sure you've created a subgroup and added a project (repository) to it. + 1. Select the **templates** subgroup. ### Example structure -Here is a sample group/project structure for a hypothetical "Acme Co" for project templates: +Here's a sample group/project structure for project templates, for a hypothetical _Acme Co_: ```plaintext # GitLab instance and group @@ -53,24 +56,22 @@ gitlab.com/acmeco/ ### Adjust Settings -Users can configure a GitLab group that serves as template -source under a group's **Settings > General > Custom project templates**. - -NOTE: -GitLab administrators can -[set project templates for an entire GitLab instance](../admin_area/custom_project_templates.md). - -Within this section, you can configure the group where all the custom project -templates are sourced. Every project _template_ directly under the group namespace is -available to every signed-in user, if all enabled [project features](../project/settings/index.md#sharing-and-permissions) except for GitLab Pages are set to **Everyone With Access**. - -However, private projects will be available only if the user is a member of the project. +Users can configure a GitLab group that serves as template source under a group's +**Settings > General > Custom project templates**. NOTE: -Only direct subgroups can be set as the template source. Projects of nested subgroups of a selected template source cannot be used. - -Repository and database information that are copied over to each new project are -identical to the data exported with the [GitLab Project Import/Export](../project/settings/import_export.md). +GitLab administrators can [set project templates for an entire GitLab instance](../admin_area/custom_project_templates.md). + +Within this section, you can configure the group where all the custom project templates are sourced. +If all enabled [project features](../project/settings/index.md#sharing-and-permissions) +(except for GitLab Pages) are set to **Everyone With Access**, then every project template directly +under the group namespace is available to every signed-in user. However, private projects are +available only if the user is a member of the project. Also note that only direct subgroups can be +set as the template source. Projects of nested subgroups of a selected template source cannot be +used. + +Repository and database information that are copied over to each new project are identical to the +data exported with the [GitLab Project Import/Export](../project/settings/import_export.md). <!-- ## Troubleshooting diff --git a/doc/user/group/devops_adoption/img/group_devops_adoption_v13_11.png b/doc/user/group/devops_adoption/img/group_devops_adoption_v13_11.png Binary files differdeleted file mode 100644 index a6ece47ba9a..00000000000 --- a/doc/user/group/devops_adoption/img/group_devops_adoption_v13_11.png +++ /dev/null diff --git a/doc/user/group/devops_adoption/img/group_devops_adoption_v14_0.png b/doc/user/group/devops_adoption/img/group_devops_adoption_v14_0.png Binary files differnew file mode 100644 index 00000000000..91055f660da --- /dev/null +++ b/doc/user/group/devops_adoption/img/group_devops_adoption_v14_0.png diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md index 5a23e1559bc..f98325143cc 100644 --- a/doc/user/group/devops_adoption/index.md +++ b/doc/user/group/devops_adoption/index.md @@ -18,21 +18,25 @@ Refer to this feature's version history for more details. Prerequisites: -- A minimum of [Reporter access](../../permissions.md) to the group. +- You must have at least the [Reporter role](../../permissions.md) for the group. To access Group DevOps Adoption, go to your group and select **Analytics > DevOps Adoption**. Group DevOps Adoption shows you how individual groups and sub-groups within your organization use the following features: -- Approvals -- Deployments -- Issues -- Merge Requests -- Pipelines -- Runners -- Scans - -When managing groups in the UI, you can manage your sub-groups with the **Add/Remove sub-groups** +- Dev + - Issues + - Merge Requests + - Approvals + - Code owners +- Sec + - Scans +- Ops + - Runners + - Pipelines + - Deployments + +When managing groups in the UI, you can add your sub-groups with the **Add sub-group to table** button, in the top right hand section of your Groups pages. With DevOps Adoption you can: @@ -41,7 +45,7 @@ With DevOps Adoption you can: - Identify specific sub-groups that are lagging in their adoption of GitLab so you can help them along in their DevOps journey. - Find the sub-groups that have adopted certain features and can provide guidance to other sub-groups on how to use those features. - + ## Enable data processing diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md index 343f7c496b1..2f9dc27d87f 100644 --- a/doc/user/group/epics/epic_boards.md +++ b/doc/user/group/epics/epic_boards.md @@ -6,17 +6,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Epic Boards **(PREMIUM)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2864) in GitLab 13.10. -> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../../administration/feature_flags.md). - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -The GitLab Epic Board is a software project management tool used to plan, -organize, and visualize a workflow for a feature or product release. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5067) in GitLab 13.10. +> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/290039) in GitLab 14.0. +> - Enabled on GitLab.com. +> - Recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](../../../administration/feature_flags.md). Epic boards build on the existing [epic tracking functionality](index.md) and [labels](../../project/labels.md). Your epics appear as cards in vertical lists, organized by their assigned @@ -24,45 +19,156 @@ labels. To view an epic board, in a group, select **Epics > Boards**. - + ## Create an epic board +Prerequisites: + +- A minimum of [Reporter](../../permissions.md#group-members-permissions) access to a group in GitLab. + To create a new epic board: -1. Select the dropdown with the current board name in the upper left corner of the Epic Boards page. +1. Go to your group and select **Epics > Boards**. +1. In the upper left corner, select the dropdown with the current board name. 1. Select **Create new board**. -1. Enter the new board's name and select **Create**. +1. Enter the new board's title. +1. Optional. To hide the Open or Closed lists, clear the **Show the Open list** and + **Show the Closed list** checkboxes. +1. Optional. Set board scope: + 1. Next to **Scope**, select **Expand**. + 1. Next to **Labels**, select **Edit** and select the labels to use as board scope. +1. Select **Create board**. + +Now you can [add some lists](#create-a-new-list). +To change these options later, [edit the board](#edit-the-scope-of-an-epic-board). + +## Delete an epic board + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5079) in GitLab 14.0. + +Prerequisites: + +- A minimum of [Reporter](../../permissions.md#group-members-permissions) access to a group in GitLab. +- A minimum of two boards present in a group. + +To delete the active epic board: + +1. Select the dropdown with the current board name in the upper left corner of the Epic Boards page. +1. Select **Delete board**. +1. Select **Delete**. + +## Actions you can take on an epic board + +- [Create a new list](#create-a-new-list). +- [Remove an existing list](#remove-a-list). +- [Filter epics](#filter-epics). +- Create workflows, like when using [issue boards](../../project/issue_board.md#create-workflows). +- [Move epics and lists](#move-epics-and-lists). +- Change epic labels (by dragging an epic between lists). +- Close an epic (by dragging it to the **Closed** list). +- [Edit the scope of a board](#edit-the-scope-of-an-epic-board). + +### Create a new list + +Prerequisites: + +- A minimum of [Reporter](../../permissions.md#group-members-permissions) access to a group in GitLab. + +To create a new list: + +1. Go to your group and select **Epics > Boards**. +1. In the upper-right corner, select **Create list**. +1. In the **New list** column expand the **Select a label** dropdown and select the label to use as + list scope. +1. Select **Add to board**. + +### Remove a list + +Removing a list doesn't have any effect on epics and labels, as it's just the +list view that's removed. You can always create it again later if you need. + +Prerequisites: + +- A minimum of [Reporter](../../permissions.md#group-members-permissions) access to a group in GitLab. + +To remove a list from an epic board: -## Limitations of epic boards +1. On the top of the list you want to remove, select the **List settings** icon (**{settings}**). + The list settings sidebar opens on the right. +1. Select **Remove list**. A confirmation dialog appears. +1. Select **OK**. -As of GitLab 13.10, these limitations apply: +### Filter epics -- Epic Boards need to be enabled by an administrator. -- Epic Boards can be created but not deleted. -- Lists can be added to the board but not deleted. -- There is no sidebar on the board. To edit an epic, go to the epic's page. -- There is no drag and drop support yet. To move an epic between lists, edit epic labels on the epic's page. -- Epics cannot be re-ordered within the list. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5079) in GitLab 14.0. -To learn more about the future iterations of this feature, visit -[epic 5067](https://gitlab.com/groups/gitlab-org/-/epics/5067). +Use the filters on top of your epic board to show only +the results you want. It's similar to the filtering used in the epic list, +as the metadata from the epics and labels is re-used in the epic board. -## Enable or disable Epic Boards +You can filter by the following: -Epic Boards are under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. +- Author +- Label + +### Move epics and lists + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5079) in GitLab 14.0. + +You can move epics and lists by dragging them. + +Prerequisites: + +- A minimum of [Reporter](../../permissions.md#group-members-permissions) access to a group in GitLab. + +To move an epic, select the epic card and drag it to another position in its current list or +into another list. Learn about possible effects in [Dragging epics between lists](#dragging-epics-between-lists). + +To move a list, select its top bar, and drag it horizontally. +You can't move the **Open** and **Closed** lists, but you can hide them when editing an epic board. + +#### Dragging epics between lists + +When you drag epics between lists, the result is different depending on the source list +and the target list. + +| | To Open | To Closed | To label B list | +| --------------------- | -------------- | ---------- | ------------------------------ | +| **From Open** | - | Close epic | Add label B | +| **From Closed** | Reopen epic | - | Reopen epic and add label B | +| **From label A list** | Remove label A | Close epic | Remove label A and add label B | + +### Edit the scope of an epic board + +Prerequisites: + +- A minimum of [Reporter](../../permissions.md#group-members-permissions) access to a group in GitLab. + +To edit the scope of an epic board: + +1. In the upper-right corner, select **Edit board**. +1. Optional: + - Edit the board's title. + - Show or hide the Open and Closed columns. + - Select other labels as the board's scope. +1. Select **Save changes**. + +## Enable or disable epic boards + +Epic boards are under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. +can disable it. -To enable it: +To disable it: ```ruby -Feature.enable(:epic_boards) +Feature.disable(:epic_boards) ``` -To disable it: +To enable it: ```ruby -Feature.disable(:epic_boards) +Feature.enable(:epic_boards) ``` diff --git a/doc/user/group/epics/img/epic_board_v13_10.png b/doc/user/group/epics/img/epic_board_v13_10.png Binary files differdeleted file mode 100644 index 85a131ea605..00000000000 --- a/doc/user/group/epics/img/epic_board_v13_10.png +++ /dev/null diff --git a/doc/user/group/epics/img/epic_board_v14_0.png b/doc/user/group/epics/img/epic_board_v14_0.png Binary files differnew file mode 100644 index 00000000000..e6b4e40aa05 --- /dev/null +++ b/doc/user/group/epics/img/epic_board_v14_0.png diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 7bb021b4b1f..89fd32a8db1 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -385,32 +385,7 @@ To remove a child epic from a parent epic: ## Cached epic count > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299540) in GitLab 13.11. -> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-cached-epic-count). - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/327320) in GitLab 14.0. In a group, the sidebar displays the total count of open epics and this value is cached if higher than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. - -### Enable or disable cached epic count **(PREMIUM SELF)** - -Cached epic count in the left sidebar is under development but ready for production use. It is -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable it. - -To disable it: - -```ruby -Feature.disable(:cached_sidebar_open_epics_count) -``` - -To enable it: - -```ruby -Feature.enable(:cached_sidebar_open_epics_count) -``` diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index 14464ff1a5f..8bf995a4fd9 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -69,6 +69,8 @@ The following resources are migrated to the target instance: - name - link URL - image URL +- Boards +- Board Lists Any other items are **not** migrated. @@ -105,7 +107,7 @@ on an existing group's page.  -1. On the New Group page, select the **Import group** tab. +1. On the New Group page, select **Import group**.  @@ -115,7 +117,8 @@ on an existing group's page. ### Selecting which groups to import -After you have authorized access to GitLab instance, you are redirected to the GitLab Group Migration importer page and your remote GitLab groups are listed. +After you have authorized access to the GitLab instance, you are redirected to the GitLab Group +Migration importer page. Your remote GitLab groups, which you have Owner access to, are listed. 1. By default, the proposed group namespaces match the names as they exist in remote instance, but based on your permissions, you can choose to edit these names before you proceed to import any of them. diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 7f2e502b94b..104ea57db4a 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -23,7 +23,8 @@ For larger organizations, you can also create [subgroups](subgroups/index.md). To view groups: -1. In the top menu, select **Groups > Your Groups**. All groups you are a member of are displayed. +1. On the top bar, select **Menu > Groups**. +1. Select **Your Groups**. All groups you are a member of are displayed. 1. To view a list of public groups, select **Explore public groups**. You can also view groups by namespace. @@ -48,9 +49,10 @@ For example, consider a user named Alex: To create a group: -1. From the top menu, either: - - Select **Groups > Your Groups**, and on the right, select the **New group** button. +1. On the top bar, either: + - Select **Menu > Groups**, and on the right, select **Create group**. - To the left of the search box, select the plus sign and then **New group**. +1. Select **Create group**. 1. For the **Group name**, use only: - Alphanumeric characters - Emojis @@ -74,18 +76,20 @@ For details about groups, watch [GitLab Namespaces (users, groups and subgroups) You can give a user access to all projects in a group. -1. From the top menu, select **Groups > Your Groups**. +1. On the top bar, select **Menu > Groups**. +1. Select **Your Groups**. 1. Find your group and select it. 1. From the left sidebar, select **Members**. 1. Fill in the fields. - - The role applies to all projects in the group. [Learn more about permissions](../permissions.md#permissions). + - The role applies to all projects in the group. [Learn more about permissions](../permissions.md). - On the **Access expiration date**, the user can no longer access projects in the group. ## Request access to a group As a user, you can request to be a member of a group, if an administrator allows it. -1. From the top menu, select **Groups > Your Groups**. +1. On the top bar, select **Menu > Groups**. +1. Select **Your Groups**. 1. Find the group and select it. 1. Under the group name, select **Request Access**. @@ -100,7 +104,8 @@ If you change your mind before your request is approved, select As a group owner, you can prevent non-members from requesting access to your group. -1. From the top menu, select **Groups > Your Groups**. +1. On the top bar, select **Menu > Groups**. +1. Select **Your Groups**. 1. Find the group and select it. 1. From the left menu, select **Settings > General**. 1. Expand the **Permissions, LFS, 2FA** section. @@ -110,22 +115,22 @@ your group. ## Change the owner of a group You can change the owner of a group. Each group must always have at least one -member with [Owner permission](../permissions.md#group-members-permissions). +member with the [Owner role](../permissions.md#group-members-permissions). - As an administrator: 1. Go to the group and from the left menu, select **Members**. - 1. Give a different member **Owner** permissions. - 1. Refresh the page. You can now remove **Owner** permissions from the original owner. + 1. Give a different member the **Owner** role. + 1. Refresh the page. You can now remove the **Owner** role from the original owner. - As the current group's owner: 1. Go to the group and from the left menu, select **Members**. - 1. Give a different member **Owner** permissions. - 1. Have the new owner sign in and remove **Owner** permissions from you. + 1. Give a different member the **Owner** role. + 1. Have the new owner sign in and remove the **Owner** role from you. ## Remove a member from the group Prerequisites: -- You must have [Owner permissions](../permissions.md#group-members-permissions). +- You must have the [Owner role](../permissions.md#group-members-permissions). - The member must have direct membership in the group. If membership is inherited from a parent group, then the member can be removed from the parent group only. @@ -245,9 +250,10 @@ These Group Activity Analytics can be enabled with the `group_activity_analytics You can view the most recent actions taken in a group. -1. From the top menu, select **Groups > Your Groups**. +1. On the top bar, select **Menu > Groups**. +1. Select **Your Groups**. 1. Find the group and select it. -1. From the left menu, select **Group overview > Activity**. +1. On the left sidebar, select **Group information > Activity**. To view the activity feed in Atom format, select the **RSS** (**{rss}**) icon. @@ -270,7 +276,7 @@ To share a given group, for example, `Frontend` with another group, for example, 1. From the left menu, select **Members**. 1. Select the **Invite group** tab. 1. In the **Select a group to invite** list, select `Engineering`. -1. For the **Max access level**, select an access level. +1. For the **Max role**, select a [role](../permissions.md). 1. Select **Invite**. All the members of the `Engineering` group are added to the `Frontend` group. @@ -292,7 +298,7 @@ To share a group after enabling this feature: 1. Go to your group's page. 1. In the left sidebar, go to **Members**, and then select **Invite a group**. -1. Select a group, and select a **Max access level**. +1. Select a group, and select a **Max role**. 1. (Optional) Select an **Access expiration date**. 1. Select **Invite**. @@ -351,7 +357,7 @@ You can transfer groups in the following ways: When transferring groups, note: -- Changing a group's parent can have unintended side effects. See [Redirects when changing repository paths](../project/repository/index.md#redirects-when-changing-repository-paths). +- Changing a group's parent can have unintended side effects. See [what happens when a repository path changes](../project/repository/index.md#what-happens-when-a-repository-path-changes). - You can only transfer groups to groups you manage. - You must update your local repositories to point to the new location. - If the immediate parent group's visibility is lower than the group's current visibility, visibility levels for subgroups and projects change to match the new parent group's visibility. @@ -361,7 +367,7 @@ When transferring groups, note: ## Change a group's path Changing a group's path (group URL) can have unintended side effects. Read -[how redirects behave](../project/repository/index.md#redirects-when-changing-repository-paths) +[how redirects behave](../project/repository/index.md#what-happens-when-a-repository-path-changes) before you proceed. If you are changing the path so it can be claimed by another group or user, @@ -419,6 +425,30 @@ To restore a group that is marked for deletion: 1. Expand the **Path, transfer, remove** section. 1. In the Restore group section, select **Restore group**. +## Prevent group sharing outside the group hierarchy + +This setting is only available on top-level groups. It affects all subgroups. + +When checked, any group within the top-level group hierarchy can be shared only with other groups within the hierarchy. + +For example, with these groups: + +- **Animals > Dogs** +- **Animals > Cats** +- **Plants > Trees** + +If you select this setting in the **Animals** group: + +- **Dogs** can be shared with **Cats**. +- **Dogs** cannot be shared with **Trees**. + +To prevent sharing outside of the group's hierarchy: + +1. Go to the group's **Settings > General** page. +1. Expand the **Permissions, LFS, 2FA** section. +1. Select **Prevent members from sending invitations to groups outside of `<group_name>` and its subgroups**. +1. Select **Save changes**. + ## Prevent a project from being shared with groups Prevent projects in a group from [sharing diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index 4975b27a66d..18177d656ab 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -28,7 +28,7 @@ the project that holds your `.gitlab/insights.yml` configuration file:  If no configuration was set, a [default configuration file]( -https://gitlab.com/gitlab-org/gitlab/blob/master/ee/fixtures/insights/default.yml) +https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/fixtures/insights/default.yml) will be used. See the [Project's Insights documentation](../../project/insights/index.md) for diff --git a/doc/user/group/issues_analytics/img/issues_created_per_month_v12_8_a.png b/doc/user/group/issues_analytics/img/issues_created_per_month_v12_8_a.png Binary files differindex 5994cbfa401..2e19aa38412 100644 --- a/doc/user/group/issues_analytics/img/issues_created_per_month_v12_8_a.png +++ b/doc/user/group/issues_analytics/img/issues_created_per_month_v12_8_a.png diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index ef47ceadd88..b9f94d96b48 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -69,7 +69,9 @@ For each day that a coverage report was generated by a job in a project's pipeli If the project's code coverage was calculated more than once in a day, we will take the last value from that day. NOTE: -[In GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/270102), group code coverage data is taken from the configured [default branch](../../project/repository/branches/default.md). In earlier versions, it is taken from the `master` branch. +[In GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/270102), group code coverage +data is taken from the configured [default branch](../../project/repository/branches/default.md). +In earlier versions, it is taken from the `master` branch. <!-- ## Troubleshooting diff --git a/doc/user/group/saml_sso/img/member_enterprise_badge_v14_0.png b/doc/user/group/saml_sso/img/member_enterprise_badge_v14_0.png Binary files differnew file mode 100644 index 00000000000..f9534b14a51 --- /dev/null +++ b/doc/user/group/saml_sso/img/member_enterprise_badge_v14_0.png diff --git a/doc/user/group/saml_sso/img/saml_group_links_v13_9.png b/doc/user/group/saml_sso/img/saml_group_links_v13_9.png Binary files differnew file mode 100644 index 00000000000..9bd2473f90c --- /dev/null +++ b/doc/user/group/saml_sso/img/saml_group_links_v13_9.png diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 1864547c57f..8a5cdb79186 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -152,6 +152,10 @@ We recommend: - **Unique User Identifier (Name identifier)** set to `user.objectID`. - **nameid-format** set to persistent. +If using [Group Sync](#group-sync), customize the name of the group claim to match the required attribute. + +See the [troubleshooting page](../../../administration/troubleshooting/group_saml_scim.md#azure-active-directory) 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/overview/) with the notes below for consideration. @@ -324,18 +328,23 @@ Ensure your SAML identity provider sends an attribute statement named `Groups` o </saml:AttributeStatement> ``` +NOTE: +To inspect the SAML response, you can use one of these [SAML debugging tools](#saml-debugging-tools). +Also note that the value for `Groups` or `groups` in the SAML reponse can be either the group name or +the group ID depending what the IdP sends to GitLab. + When SAML SSO is enabled for the top-level group, `Maintainer` and `Owner` level users -see a new menu item in group **Settings > SAML Group Links**. Each group (parent or subgroup) can specify -one or more group links to map a SAML identity provider group name to a GitLab access level. +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 `Freelancers` group in the attribute statement example above: +To link the SAML groups from the `saml:AttributeStatement` example above: -1. Enter `Freelancers` in the `SAML Group Name` field. +1. Enter the value of `saml:AttributeValue` in the `SAML Group Name` field. 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 @@ -450,7 +459,7 @@ SAML configuration for GitLab.com is mostly the same as for self-managed instanc However, self-managed GitLab instances use a configuration file that supports more options as described in the external [OmniAuth SAML documentation](https://github.com/omniauth/omniauth-saml/). Internally that uses the [`ruby-saml` library](https://github.com/onelogin/ruby-saml), so we sometimes check there to verify low level details of less commonly used options. -It can also help to compare the XML response from your provider with our [example XML used for internal testing](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/spec/fixtures/saml/response.xml). +It can also help to compare the XML response from your provider with our [example XML used for internal testing](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/spec/fixtures/saml/response.xml). ### Searching Rails log diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 65b3e2d095d..fd75c49fa6c 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -175,6 +175,10 @@ We recommend users do this prior to turning on sync, because while synchronizati New users and existing users on subsequent visits can access the group through the identify provider's dashboard or by visiting links directly. +[In GitLab 14.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/325712), GitLab users created with a SCIM identity display with an **Enterprise** badge in the **Members** view. + + + For role information, please see the [Group SAML page](index.md#user-access-and-management) ### Blocking access diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index 5d375e2abd9..c097790ef16 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -4,7 +4,7 @@ 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 +# Group import/export **(FREE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2888) in GitLab 13.0 as an experimental feature. May change in future releases. @@ -21,9 +21,9 @@ See also: To enable GitLab import/export: -1. Navigate to **Admin Area > Settings > Visibility and access controls**. -1. Scroll to **Import sources** -1. Enable desired **Import sources** +1. On the top bar, go to **Menu > Admin > Settings > General > Visibility and access controls**. +1. Scroll to **Import sources**. +1. Enable the desired **Import sources**. ## Important Notes @@ -58,7 +58,7 @@ The following items are **not** exported: NOTE: For more details on the specific data persisted in a group export, see the -[`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/import_export/group/import_export.yml) file. +[`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/group/import_export.yml) file. ## Exporting a Group diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index df0d297a82a..4532a391eef 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -67,8 +67,6 @@ Another example of GitLab as a company would be the following: - (project) Chef cookbooks - Category Subgroup - Executive team ---- - When performing actions such as transferring or importing a project between subgroups, the behavior is the same as when performing these actions at the `group/project` level. @@ -85,13 +83,20 @@ By default, groups created in: The setting can be changed for any group by: -- A group owner. Select the group, and navigate to **Settings > General > Permissions, LFS, 2FA**. -- An administrator. Navigate to **Admin Area > Overview > Groups**, select the group, and choose **Edit**. +- A group owner: + 1. Select the group. + 1. On the left sidebar, select **Settings > General**. + 1. Expand the **Permissions, LFS, 2FA** section. +- An administrator: + 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the left sidebar, select **Overview > Groups**. + 1. Select the group, and select **Edit**. + +For: -For more information check the -[permissions table](../../permissions.md#group-members-permissions). For a list -of words that are not allowed to be used as group names see the -[reserved names](../../reserved_names.md). +- More information, check the [permissions table](../../permissions.md#group-members-permissions). +- A list of words that are not allowed to be used as group names, see the + [reserved names](../../reserved_names.md). Users can always create subgroups if they are explicitly added as an Owner (or Maintainer, if that setting is enabled) to an immediate parent group, even if group @@ -163,7 +168,7 @@ added to), add the user to the new subgroup again with a higher set of permissio For example, if User 1 was first added to group `one/two` with Developer permissions, then they inherit those permissions in every other subgroup -of `one/two`. To give them Maintainer access to group `one/two/three/four`, +of `one/two`. To give them the [Maintainer role](../../permissions.md) for group `one/two/three/four`, you would add them again in that group as Maintainer. Removing them from that group, the permissions fall back to those of the ancestor group. diff --git a/doc/user/group/value_stream_analytics/img/delete_value_stream_v13_12.png b/doc/user/group/value_stream_analytics/img/delete_value_stream_v13_12.png Binary files differindex c02f259ae8c..ef532986100 100644 --- a/doc/user/group/value_stream_analytics/img/delete_value_stream_v13_12.png +++ b/doc/user/group/value_stream_analytics/img/delete_value_stream_v13_12.png diff --git a/doc/user/group/value_stream_analytics/img/new_value_stream_v13_12.png b/doc/user/group/value_stream_analytics/img/new_value_stream_v13_12.png Binary files differindex b2b6ce04a14..d64ec31aabf 100644 --- a/doc/user/group/value_stream_analytics/img/new_value_stream_v13_12.png +++ b/doc/user/group/value_stream_analytics/img/new_value_stream_v13_12.png diff --git a/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13_12.png b/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13_12.png Binary files differindex ee0d007a778..834556df051 100644 --- a/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13_12.png +++ b/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13_12.png diff --git a/doc/user/group/value_stream_analytics/img/vsa_label_based_stage_v14_0.png b/doc/user/group/value_stream_analytics/img/vsa_label_based_stage_v14_0.png Binary files differindex 1f47670462c..648ab53dd12 100644 --- a/doc/user/group/value_stream_analytics/img/vsa_label_based_stage_v14_0.png +++ b/doc/user/group/value_stream_analytics/img/vsa_label_based_stage_v14_0.png diff --git a/doc/user/group/value_stream_analytics/img/vsa_overview_stage_v13_11.png b/doc/user/group/value_stream_analytics/img/vsa_overview_stage_v13_11.png Binary files differindex 7d47003972c..8d77c53db7f 100644 --- a/doc/user/group/value_stream_analytics/img/vsa_overview_stage_v13_11.png +++ b/doc/user/group/value_stream_analytics/img/vsa_overview_stage_v13_11.png diff --git a/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_12.png b/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_12.png Binary files differindex 63bae51afef..68d9741bed8 100644 --- a/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_12.png +++ b/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_12.png diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 4b473c9217d..c1dd363c313 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -65,7 +65,7 @@ To filter results: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 12.4. -GitLab provides the ability to filter analytics based on a date range. To filter results: +GitLab provides the ability to filter analytics based on a date range. Data is shown for workflow items created during the selected date range. To filter results: 1. Select a group. 1. Optionally select a project. @@ -104,7 +104,7 @@ Each stage of Value Stream Analytics is further described in the table below. | **Stage** | **Description** | | --------- | --------------- | -| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whatever comes first. The label will be tracked only if it already has an [Issue Board list](../../project/issue_board.md) created for it. | +| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whatever comes first. The label is tracked only if it already has an [Issue Board list](../../project/issue_board.md) created for it. | | Plan | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. The very first commit of the branch is the one that triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch needs to contain the related issue number (e.g., `#42`). If none of the commits in the branch mention the related issue number, it is not considered to the measurement time of the stage. | | Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR) related to that commit. The key to keep the process tracked is to include the [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically) to the description of the merge request (for example, `Closes #xxx`, where `xxx` is the number of the issue related to this merge request). If the closing pattern is not present, then the calculation takes the creation time of the first commit in the merge request as the start time. | | Test | Measures the median time to run the entire pipeline for that project. It's related to the time GitLab CI/CD takes to run every job for the commits pushed to that merge request defined in the previous stage. It is basically the start->finish time for all pipelines. | diff --git a/doc/user/img/completed_tasks_v13_3.png b/doc/user/img/completed_tasks_v13_3.png Binary files differindex 31e051852cb..b12d95f0a23 100644 --- a/doc/user/img/completed_tasks_v13_3.png +++ b/doc/user/img/completed_tasks_v13_3.png diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index b202359847c..05ffab93f85 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -20,7 +20,7 @@ for GitLab versions 13.5 and later: ```yaml include: - - template: Terraform.latest.gitlab-ci.yml + - template: Terraform.gitlab-ci.yml variables: # If not using GitLab's HTTP backend, remove this line and specify TF_HTTP_* variables @@ -30,15 +30,14 @@ variables: # TF_ROOT: terraform/production ``` -This template uses `.latest.`, instead of stable, and may include breaking changes. -This template also includes some opinionated decisions, which you can override: +This template includes some opinionated decisions, which you can override: - Including the latest [GitLab Terraform Image](https://gitlab.com/gitlab-org/terraform-images). - Using the [GitLab managed Terraform State](#gitlab-managed-terraform-state) as the Terraform state storage backend. -- Creating [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml): +- Creating [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml): `init`, `validate`, `build`, and `deploy`. These stages - [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.latest.gitlab-ci.yml) + [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml) `init`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on `master`. This video from January 2021 walks you through all the GitLab Terraform integration features: @@ -74,6 +73,12 @@ Neither Terraform nor GitLab encrypts the plan file by default. If your Terrafor includes sensitive data such as passwords, access tokens, or certificates, GitLab strongly recommends encrypting plan output or modifying the project visibility settings. +## Terraform module registry + +GitLab can be used as a [Terraform module registry](../packages/terraform_module_registry/index.md) +to create and publish Terraform modules to a private registry specific to your +top-level namespace. + ## Terraform integration in Merge Requests Collaborating around Infrastructure as Code (IaC) changes requires both code changes diff --git a/doc/user/infrastructure/terraform_state.md b/doc/user/infrastructure/terraform_state.md index 2cd5ed8ac78..0b92ea46338 100644 --- a/doc/user/infrastructure/terraform_state.md +++ b/doc/user/infrastructure/terraform_state.md @@ -28,10 +28,10 @@ before using this feature. ## Permissions for using Terraform -In GitLab version 13.1, [Maintainer access](../permissions.md) was required to use a -GitLab managed Terraform state backend. In GitLab versions 13.2 and greater, -[Maintainer access](../permissions.md) is required to lock, unlock and write to the state -(using `terraform apply`), while [Developer access](../permissions.md) is required to read +In GitLab version 13.1, the [Maintainer role](../permissions.md) was required to use a +GitLab managed Terraform state backend. In GitLab versions 13.2 and greater, the +[Maintainer role](../permissions.md) is required to lock, unlock, and write to the state +(using `terraform apply`), while the [Developer role](../permissions.md) is required to read the state (using `terraform plan -lock=false`). ## Set up GitLab-managed Terraform state @@ -41,7 +41,8 @@ To get started with a GitLab-managed Terraform state, there are two different op - [Use a local machine](#get-started-using-local-development). - [Use GitLab CI](#get-started-using-gitlab-ci). -Terraform States can be found by navigating to a Project's **{cloud-gear}** **Operations > Terraform** page. +Terraform States can be found by navigating to a Project's +**{cloud-gear}** **Infrastructure > Terraform** page. ### Get started using local development @@ -351,8 +352,8 @@ location. You can then go back to running it in GitLab CI/CD. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273592) in GitLab 13.8. Users with Developer and greater [permissions](../permissions.md) can view the -state files attached to a project at **Operations > Terraform**. Users with -Maintainer permissions can perform commands on the state files. The user interface +state files attached to a project at **Infrastructure > Terraform**. Users with the +Maintainer role can perform commands on the state files. The user interface contains these fields:  @@ -376,7 +377,7 @@ are planned. Users with Maintainer and greater [permissions](../permissions.md) can use the following options to remove a state file: -- **GitLab UI**: Go to **Operations > Terraform**. In the **Actions** column, +- **GitLab UI**: Go to **Infrastructure > Terraform**. In the **Actions** column, click the vertical ellipsis (**{ellipsis_v}**) button and select **Remove state file and versions**. - **GitLab REST API**: You can remove a state file by making a request to the diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index 33366c658d7..24fabbc5a42 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -14,7 +14,10 @@ instance-level Kubernetes clusters allow you to connect a Kubernetes cluster to the GitLab instance, which enables you to use the same cluster across multiple projects. -The instance level Kubernetes clusters can be found in the top menu by navigating to your instance's **{admin}** **Admin Area > Kubernetes**. +To view the instance level Kubernetes clusters: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Kubernetes**. ## Cluster precedence diff --git a/doc/user/markdown.md b/doc/user/markdown.md index cbd5bf1553a..fdfd953e52a 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -5,25 +5,36 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# GitLab Markdown **(FREE)** +# GitLab Flavored Markdown **(FREE)** -This Markdown guide is **valid only for the GitLab internal Markdown rendering system for entries and files**. -It is **not** valid for the [GitLab documentation website](https://docs.gitlab.com) -or the [GitLab main website](https://about.gitlab.com), as they both use -[Kramdown](https://kramdown.gettalong.org) as their Markdown engine. The documentation -website uses an extended Kramdown gem, [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown). -Consult the [GitLab Kramdown Guide](https://about.gitlab.com/handbook/markdown-guide/) -for a complete Kramdown reference. +GitLab automatically renders Markdown content. For example, when you add a comment to an issue, +you type the text in the Markdown language. When you save the issue, the text is rendered +with a set of styles. These styles are described on this page. -NOTE: -We encourage you to view this document as [rendered by GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md). +For example, in Markdown, an ordered list looks like this: + +```markdown +- Cat +- Dog +- Turtle +``` + +When this list is rendered, it looks like this: + +- Cat +- Dog +- Turtle + +These styles are **valid for GitLab only**. The [GitLab documentation website](https://docs.gitlab.com) +and the [main GitLab website](https://about.gitlab.com) use [Kramdown](https://kramdown.gettalong.org) instead. -## GitLab Flavored Markdown +You should not view this page in the documentation, but instead [view these styles as they appear on GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md). -GitLab uses "GitLab Flavored Markdown". It extends the [CommonMark specification](https://spec.commonmark.org/current/) -(which is based on standard Markdown) in several ways to add more features. +GitLab Flavored Markdown extends the [CommonMark specification](https://spec.commonmark.org/current/). It was inspired by [GitHub Flavored Markdown](https://docs.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax). +## Where you can use GitLab Flavored Markdown + You can use GitLab Flavored Markdown in the following areas: - Comments @@ -33,86 +44,29 @@ You can use GitLab Flavored Markdown in the following areas: - Snippets (the snippet must be named with a `.md` extension) - Wiki pages - Markdown documents inside repositories -- Epics **(ULTIMATE)** +- Epics You can also use other rich text files in GitLab. You might have to install a dependency -to do so. Please see the [`gitlab-markup` gem project](https://gitlab.com/gitlab-org/gitlab-markup) -for more information. - -### Transition from Redcarpet to CommonMark +to do so. For more information, see the [`gitlab-markup` gem project](https://gitlab.com/gitlab-org/gitlab-markup). -- In GitLab version 11.8, the [Redcarpet Ruby library](https://github.com/vmg/redcarpet) - was removed. All issues and comments, including those from pre-11.1, are now processed - using the [CommonMark Ruby Library](https://github.com/gjtorikian/commonmarker). -- GitLab versions 11.3 and greater use CommonMark to process wiki pages and Markdown - files (`*.md`) in repositories. -- GitLab versions 11.1 and greater use the [CommonMark Ruby Library](https://github.com/gjtorikian/commonmarker) - for Markdown processing of all new issues, merge requests, comments, and other Markdown - content in the GitLab system. +### Differences between GitLab Flavored Markdown and standard Markdown -The documentation website migrated its Markdown engine -[from Redcarpet to Kramdown](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/108) -in October 2018. +GitLab uses standard CommonMark formatting. However, GitLab Flavored Markdown +extends standard Markdown with features made specifically for GitLab. -You may have older issues, merge requests, or Markdown documents in your -repository that relied upon nuances of the GitLab RedCarpet version -of Markdown. Because CommonMark uses slightly stricter syntax, these documents -may now appear differently after the transition to CommonMark. - -For example, numbered lists with nested lists may -render incorrectly: - -```markdown -1. Chocolate - - dark - - milk -``` - -To correct their rendering, add a space to each nested item to align the `-` with the first -character of the top list item (`C` in this case): - -```markdown -1. Chocolate - - dark - - milk -``` - -1. Chocolate - - dark - - milk - -We flag any significant differences between Redcarpet and CommonMark Markdown in this document. - -If you have many Markdown files, it can be tedious to determine -if they display correctly or not. You can use the -[`diff_redcarpet_cmark`](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) -tool to generate a list of files and the -differences between how RedCarpet and CommonMark render the files. It indicates -if any changes are needed. - -`diff_redcarpet_cmark` is not an officially supported product. +Features not found in standard Markdown: -### GitLab Flavored Markdown extends standard Markdown - -GitLab makes full use of the standard (CommonMark) formatting, but also includes more -helpful features for GitLab users. - -It makes use of [new Markdown features](#new-gitlab-flavored-markdown-extensions), -not found in standard Markdown: - -- [Color chips written in HEX, RGB or HSL](#colors) +- [Color chips written in `HEX`, `RGB` or `HSL`](#colors) - [Diagrams and flowcharts](#diagrams-and-flowcharts) -- [Emoji](#emoji) +- [Emoji](#emojis) - [Front matter](#front-matter) - [Inline diffs](#inline-diff) - [Math equations and symbols written in LaTeX](#math) -- [Special GitLab references](#special-gitlab-references) - [Task Lists](#task-lists) - [Table of Contents](#table-of-contents) - [Wiki specific Markdown](#wiki-specific-markdown) -It also has [extended Markdown features](#standard-markdown-and-extensions-in-gitlab), without -changing how standard Markdown is used: +Features [extended from standard Markdown](#features-extended-from-standard-markdown): | Standard Markdown | Extended Markdown in GitLab | | ------------------------------------- | ------------------------- | @@ -124,22 +78,23 @@ changing how standard Markdown is used: | [line breaks](#line-breaks) | [more line break control](#newlines) | | [links](#links) | [automatically linking URLs](#url-auto-linking) | -## New GitLab Flavored Markdown extensions +## Features not found in standard Markdown + +The following features are not found in standard Markdown. ### Colors -If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#colors). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#colors). -It's possible to have color written in HEX, RGB, or HSL format rendered with a color -indicator. +You can write a color in the formats: `HEX`, `RGB`, or `HSL`. -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])` `` +Named colors are not supported. -Color written inside backticks is followed by a color "chip": +Colors in backticks are followed by a color indicator: ```markdown - `#F00` @@ -165,8 +120,8 @@ Color written inside backticks is followed by a color "chip": ### Diagrams and flowcharts -It's possible to generate diagrams and flowcharts from text in GitLab using [Mermaid](https://mermaidjs.github.io/) or [PlantUML](https://plantuml.com). -It's also possible to use [Kroki](https://kroki.io) to create a wide variety of diagrams. +You can generate diagrams and flowcharts from text by using [Mermaid](https://mermaidjs.github.io/) or [PlantUML](https://plantuml.com). +You can also use [Kroki](https://kroki.io) to create a wide variety of diagrams. #### Mermaid @@ -197,7 +152,7 @@ graph TD; C-->D; ``` -Subgraphs can also be included: +You can also include subgraphs: ````markdown ```mermaid @@ -237,16 +192,17 @@ end #### PlantUML -To make PlantUML available in GitLab, a GitLab administrator needs to enable it first. Read more in [PlantUML & GitLab](../administration/integration/plantuml.md). +To make PlantUML available in GitLab, a GitLab administrator must enable it. For more information, see the +[PlantUML & GitLab](../administration/integration/plantuml.md) page. #### Kroki -To make Kroki available in GitLab, a GitLab administrator needs to enable it first. -Read more in the [Kroki integration](../administration/integration/kroki.md) page. +To make Kroki available in GitLab, a GitLab administrator must enable it. +For more information, see the [Kroki integration](../administration/integration/kroki.md) page. -### Emoji +### Emojis -If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#emoji). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#emojis). ```markdown Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: @@ -270,13 +226,13 @@ If you're new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-f Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/thumbsup.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> -#### Emoji and your OS +#### Emojis and your operating system -The emoji example above uses hard-coded images for this documentation. Rendered emoji -in GitLab may appear different depending on the OS and browser used. +The previous emoji example uses hard-coded images. Rendered emojis +in GitLab may be different depending on the OS and browser used. -Most emoji are natively supported on macOS, Windows, iOS, Android, and fall back on image-based -emoji where there is no support. +Most emojis are natively supported on macOS, Windows, iOS, Android, and fall back on image-based +emojis where there is no support. <!-- vale gitlab.Spelling = NO --> @@ -291,17 +247,17 @@ this font installed by default. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23331) in GitLab 11.6. Front matter is metadata included at the beginning of a Markdown document, preceding -its content. This data can be used by static site generators such as [Jekyll](https://jekyllrb.com/docs/front-matter/), +the content. This data can be used by static site generators like [Jekyll](https://jekyllrb.com/docs/front-matter/), [Hugo](https://gohugo.io/content-management/front-matter/), and many other applications. -When you view a Markdown file rendered by GitLab, any front matter is displayed as-is, +When you view a Markdown file rendered by GitLab, front matter is displayed as-is, in a box at the top of the document. The HTML content displays after the front matter. To view an example, you can toggle between the source and rendered version of a -[GitLab documentation file](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/README.md). +[GitLab documentation file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/README.md). -In GitLab, front matter is only used in Markdown files and wiki pages, not the other +In GitLab, front matter is used only in Markdown files and wiki pages, not the other places where Markdown formatting is supported. It must be at the very top of the document -and must be between delimiters, as explained below. +and must be between delimiters. The following delimiters are supported: @@ -352,9 +308,9 @@ $example = array( ### Inline diff -If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-diff). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#inline-diff). -With inline diff tags you can display `{+ additions +}` or `[- deletions -]`. +With inline diff tags, you can display `{+ additions +}` or `[- deletions -]`. The wrapping tags can be either curly braces or square brackets: @@ -369,7 +325,7 @@ The wrapping tags can be either curly braces or square brackets: --- -However, the wrapping tags can't be mixed: +However, you cannot mix the wrapping tags: ```markdown - {+ addition +] @@ -379,7 +335,7 @@ However, the wrapping tags can't be mixed: ``` If your diff includes words in `` `code` `` font, make sure to escape each backtick `` ` `` with a -backslash `\`, otherwise the diff highlight don't render correctly: +backslash `\`. Otherwise the diff highlight does not render correctly: ```markdown - {+ Just regular text +} @@ -391,18 +347,18 @@ backslash `\`, otherwise the diff highlight don't render correctly: ### Math -If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#math). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#math). -It's possible to have math written with LaTeX syntax rendered using [KaTeX](https://github.com/KaTeX/KaTeX). +Math written in LaTeX syntax is rendered with [KaTeX](https://github.com/KaTeX/KaTeX). -Math written between dollar signs `$` are rendered inline with the text. Math written -inside a [code block](#code-spans-and-blocks) with the language declared as `math`, are rendered +Math written between dollar signs `$` is rendered inline with the text. Math written +in a [code block](#code-spans-and-blocks) with the language declared as `math` is rendered on a separate line: ````markdown This math is inline $`a^2+b^2=c^2`$. -This is on a separate line +This is on a separate line: ```math a^2+b^2=c^2 @@ -417,71 +373,22 @@ This is on a separate line a^2+b^2=c^2 ``` -_Be advised that KaTeX only supports a [subset](https://katex.org/docs/supported.html) of LaTeX._ +_KaTeX only supports a [subset](https://katex.org/docs/supported.html) of LaTeX._ -This also works for the Asciidoctor `:stem: latexmath`. For details, see +This syntax also works for the Asciidoctor `:stem: latexmath`. For details, see the [Asciidoctor user manual](https://asciidoctor.org/docs/user-manual/#activating-stem-support). -### Special GitLab references - -GitLab Flavored Markdown recognizes special GitLab related references. For example, you can reference -an issue, a commit, a team member, or even an entire project team. GitLab Flavored Markdown turns -that reference into a link so you can navigate between them. - -Additionally, GitLab Flavored Markdown recognizes certain cross-project references and also has a shorthand -version to reference other projects from the same namespace. - -GitLab Flavored Markdown recognizes the following: - -| references | input | cross-project reference | shortcut inside same namespace | -| :------------------------------ | :------------------------- | :-------------------------------------- | :----------------------------- | -| specific user | `@user_name` | | | -| specific group | `@group_name` | | | -| entire team | `@all` | | | -| project | `namespace/project>` | | | -| issue | ``#123`` | `namespace/project#123` | `project#123` | -| merge request | `!123` | `namespace/project!123` | `project!123` | -| snippet | `$123` | `namespace/project$123` | `project$123` | -| epic **(ULTIMATE)** | `&123` | `group1/subgroup&123` | | -| vulnerability **(ULTIMATE)** (1)| `[vulnerability:123]` | `[vulnerability:namespace/project/123]` | `[vulnerability:project/123]` | -| feature flag | `[feature_flag:123]` | `[feature_flag:namespace/project/123]` | `[feature_flag:project/123]` | -| label by ID | `~123` | `namespace/project~123` | `project~123` | -| one-word label by name | `~bug` | `namespace/project~bug` | `project~bug` | -| multi-word label by name | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | -| scoped label by name | `~"priority::high"` | `namespace/project~"priority::high"` | `project~"priority::high"` | -| project milestone by ID | `%123` | `namespace/project%123` | `project%123` | -| one-word milestone by name | `%v1.23` | `namespace/project%v1.23` | `project%v1.23` | -| multi-word milestone by name | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` | -| specific commit | `9ba12248` | `namespace/project@9ba12248` | `project@9ba12248` | -| commit range comparison | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` | -| repository file references | `[README](doc/README.md)` | | | -| repository file line references | `[README](doc/README.md#L13)` | | | -| [alert](../operations/incident_management/alerts.md) | `^alert#123` | `namespace/project^alert#123` | `project^alert#123` | - -1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222483) in GitLab 13.7. - -For example, referencing an issue by using `#123` formats the output as a link -to issue number 123 with text `#123`. Likewise, a link to issue number 123 is -recognized and formatted with text `#123`. If you don't want `#123` to link to an issue, -add a leading backslash `\#123`. - -In addition to this, links to some objects are also recognized and formatted. Some examples of these are: - -- Comments on issues: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234#note_101075757"`, which are rendered as `#1234 (comment 101075757)` -- The issues designs tab: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs"`, which are rendered as `#1234 (designs)`. -- Links to individual designs: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs/layout.png"`, which are rendered as `#1234[layout.png]`. - ### Task lists -If this section isn't rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#task-lists). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#task-lists). -You can add task lists anywhere Markdown is supported, but only issues, merge requests, and -comments support clicking to toggle the boxes. In other -places, you must edit the Markdown manually to change the status by adding or -removing an `x` inside the square brackets. +You can add task lists anywhere Markdown is supported. -To create a task list, add a specially-formatted Markdown list. You can use either -unordered or ordered lists: +- 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 + by adding or removing an `x` in the brackets. + +To create a task list, follow the format of an ordered or unordered list: ```markdown - [x] Completed task @@ -496,13 +403,14 @@ unordered or ordered lists: 1. [x] Sub-task 2 ``` - + ### Table of contents -Add a table of contents to a Markdown file, wiki page, issue request, or merge request -description by adding the tag `[[_TOC_]]` on its own line. -It displays an unordered list that links to subheadings in the document. +A table of contents is an unordered list that links to subheadings in the document. + +To add a table of contents to a Markdown file, wiki page, issue request, or merge request +description, add the `[[_TOC_]]` tag on its own line. ```markdown This is an intro sentence to my Wiki page. @@ -522,14 +430,14 @@ Second section content. ### Wiki-specific Markdown -The following examples show how links inside wikis behave. +The following topics show how links inside wikis behave. #### Wiki - direct page link -A link which just includes the slug for a page points to that page, -_at the base level of the wiki_. +A direct page link includes the slug for a page that points to that page, +at the base level of the wiki. -This snippet would link to a `documentation` page at the root of your wiki: +This example links to a `documentation` page at the root of your wiki: ```markdown [Link to Documentation](documentation) @@ -537,10 +445,10 @@ This snippet would link to a `documentation` page at the root of your wiki: #### Wiki - direct file link -Links with a file extension point to that file, _relative to the current page_. +A direct file link points to a file extension for a file, relative to the current page. -If the snippet below was placed on a page at `<your_wiki>/documentation/related`, -it would link to `<your_wiki>/documentation/file.md`: +If the following example is on a page at `<your_wiki>/documentation/related`, +it links to `<your_wiki>/documentation/file.md`: ```markdown [Link to File](file.md) @@ -548,32 +456,32 @@ it would link to `<your_wiki>/documentation/file.md`: #### Wiki - hierarchical link -A link can be constructed relative to the current wiki page using `./<page>`, +A hierarchical link can be constructed relative to the current wiki page by using `./<page>`, `../<page>`, and so on. -If this snippet was placed on a page at `<your_wiki>/documentation/main`, -it would link to `<your_wiki>/documentation/related`: +If this example is on a page at `<your_wiki>/documentation/main`, +it links to `<your_wiki>/documentation/related`: ```markdown [Link to Related Page](related) ``` -If this snippet was placed on a page at `<your_wiki>/documentation/related/content`, -it would link to `<your_wiki>/documentation/main`: +If this example is on a page at `<your_wiki>/documentation/related/content`, +it links to `<your_wiki>/documentation/main`: ```markdown [Link to Related Page](../main) ``` -If this snippet was placed on a page at `<your_wiki>/documentation/main`, -it would link to `<your_wiki>/documentation/related.md`: +If this example is on a page at `<your_wiki>/documentation/main`, +it links to `<your_wiki>/documentation/related.md`: ```markdown [Link to Related Page](related.md) ``` -If this snippet was placed on a page at `<your_wiki>/documentation/related/content`, -it would link to `<your_wiki>/documentation/main.md`: +If this example is on a page at `<your_wiki>/documentation/related/content`, +it links to `<your_wiki>/documentation/main.md`: ```markdown [Link to Related Page](../main.md) @@ -581,26 +489,75 @@ it would link to `<your_wiki>/documentation/main.md`: #### Wiki - root link -A link starting with a `/` is relative to the wiki root. +A root link starts with a `/` and is relative to the wiki root. -This snippet links to `<wiki_root>/documentation`: +This example links to `<wiki_root>/documentation`: ```markdown [Link to Related Page](/documentation) ``` -This snippet links to `<wiki_root>/miscellaneous.md`: +This example links to `<wiki_root>/miscellaneous.md`: ```markdown [Link to Related Page](/miscellaneous.md) ``` +## GitLab-specific references + +GitLab Flavored Markdown renders GitLab-specific references. For example, you can reference +an issue, a commit, a team member, or even an entire project team. GitLab Flavored Markdown turns +that reference into a link so you can navigate between them. + +Additionally, GitLab Flavored Markdown recognizes certain cross-project references and also has a shorthand +version to reference other projects from the same namespace. + +GitLab Flavored Markdown recognizes the following: + +| references | input | cross-project reference | shortcut inside same namespace | +| :------------------------------ | :------------------------- | :-------------------------------------- | :----------------------------- | +| specific user | `@user_name` | | | +| specific group | `@group_name` | | | +| entire team | `@all` | | | +| project | `namespace/project>` | | | +| issue | ``#123`` | `namespace/project#123` | `project#123` | +| merge request | `!123` | `namespace/project!123` | `project!123` | +| snippet | `$123` | `namespace/project$123` | `project$123` | +| epic **(ULTIMATE)** | `&123` | `group1/subgroup&123` | | +| vulnerability **(ULTIMATE)** (1)| `[vulnerability:123]` | `[vulnerability:namespace/project/123]` | `[vulnerability:project/123]` | +| feature flag | `[feature_flag:123]` | `[feature_flag:namespace/project/123]` | `[feature_flag:project/123]` | +| label by ID | `~123` | `namespace/project~123` | `project~123` | +| one-word label by name | `~bug` | `namespace/project~bug` | `project~bug` | +| multi-word label by name | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | +| scoped label by name | `~"priority::high"` | `namespace/project~"priority::high"` | `project~"priority::high"` | +| project milestone by ID | `%123` | `namespace/project%123` | `project%123` | +| one-word milestone by name | `%v1.23` | `namespace/project%v1.23` | `project%v1.23` | +| multi-word milestone by name | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` | +| specific commit | `9ba12248` | `namespace/project@9ba12248` | `project@9ba12248` | +| commit range comparison | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` | +| repository file references | `[README](doc/README.md)` | | | +| repository file line references | `[README](doc/README.md#L13)` | | | +| [alert](../operations/incident_management/alerts.md) | `^alert#123` | `namespace/project^alert#123` | `project^alert#123` | + +1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222483) in GitLab 13.7. + +For example, referencing an issue by using `#123` formats the output as a link +to issue number 123 with text `#123`. Likewise, a link to issue number 123 is +recognized and formatted with text `#123`. If you don't want `#123` to link to an issue, +add a leading backslash `\#123`. + +In addition to this, links to some objects are also recognized and formatted. Some examples of these are: + +- Comments on issues: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234#note_101075757"`, which are rendered as `#1234 (comment 101075757)` +- The issues designs tab: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs"`, which are rendered as `#1234 (designs)`. +- Links to individual designs: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs/layout.png"`, which are rendered as `#1234[layout.png]`. + ### Embedding metrics in GitLab Flavored Markdown Metric charts can be embedded in GitLab Flavored Markdown. Read [Embedding Metrics in GitLab flavored Markdown](../operations/metrics/embed.md) for more details. -## Standard Markdown and extensions in GitLab +## Features extended from standard Markdown All standard Markdown formatting should work as expected in GitLab. Some standard functionality is extended with additional features, without affecting the standard usage. @@ -629,7 +586,7 @@ Quote break. #### Multiline blockquote -If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#multiline-blockquote). +If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#multiline-blockquote). GitLab Flavored Markdown extends the standard Markdown by also supporting multi-line blockquotes fenced by `>>>`: @@ -713,7 +670,7 @@ Tildes are OK too. #### Colored code and syntax highlighting If this section isn't rendered correctly, -[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#colored-code-and-syntax-highlighting). +[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#colored-code-and-syntax-highlighting). GitLab uses the [Rouge Ruby library](http://rouge.jneen.net/) for more colorful syntax highlighting in code blocks. For a list of supported languages visit the @@ -804,7 +761,7 @@ Strikethrough uses two tildes. ~~Scratch this.~~ #### Multiple underscores in words and mid-word emphasis If this section isn't rendered correctly, -[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#multiple-underscores-in-words). +[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#multiple-underscores-in-words). Avoid italicizing a portion of a word, especially when you're dealing with code and names that often appear with multiple underscores. @@ -995,7 +952,7 @@ Do not change to a reference style link. #### Videos -If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#videos). +If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#videos). Image tags that link to files with a video extension are automatically converted to a video player. The valid video extensions are `.mp4`, `.m4v`, `.mov`, `.webm`, and `.ogv`: @@ -1012,7 +969,7 @@ Here's a sample video: #### Audio -If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#audio). +If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#audio). Similar to videos, link tags for files with an audio extension are automatically converted to an audio player. The valid audio extensions are `.mp3`, `.oga`, `.ogg`, `.spx`, and `.wav`: @@ -1030,7 +987,7 @@ Here's a sample audio clip: ### Inline HTML To see the second example of Markdown rendered in HTML, -[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-html). +[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#inline-html). You can also use raw HTML in your Markdown, and it usually works pretty well. @@ -1095,7 +1052,7 @@ Markdown is fine in GitLab. #### Collapsible section To see the second Markdown example rendered in HTML, -[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#details-and-summary). +[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#details-and-summary). Content can be collapsed using HTML's [`<details>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) and [`<summary>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary) @@ -1439,26 +1396,32 @@ while the equation for the theory of relativity is E = mc<sup>2</sup>. Tables are not part of the core Markdown spec, but they are part of GitLab Flavored Markdown. 1. The first line contains the headers, separated by "pipes" (`|`). -1. The second line separates the headers from the cells, and must contain three or more dashes. +1. The second line separates the headers from the cells. + - The cells can contain only empty spaces, hyphens, and + (optionally) colons for horizontal alignment. + - Each cell must contain at least one hyphen, but adding more hyphens to a + cell does not change the cell's rendering. + - Any content other than hyphens, whitespace, or colons is not allowed 1. The third, and any following lines, contain the cell values. - You **can't** have cells separated over many lines in the Markdown, they must be kept to single lines, but they can be very long. You can also include HTML `<br>` tags to force newlines if needed. - The cell sizes **don't** have to match each other. They are flexible, but must be separated by pipes (`|`). - You **can** have blank cells. +1. Column widths are calculated dynamically based on the content of the cells. Example: ```markdown | header 1 | header 2 | header 3 | -| --- | ------ |----------| +| --- | --- | --- | | cell 1 | cell 2 | cell 3 | | cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's ok. It eventually wraps the text when the cell is too large for the display size. | | cell 7 | | cell 9 | ``` | header 1 | header 2 | header 3 | -| --- | ------ |----------| +| --- | --- | --- | | cell 1 | cell 2 | cell 3 | | cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's ok. It eventually wraps the text when the cell is too large for the display size. | | cell 7 | | cell 9 | @@ -1467,18 +1430,18 @@ Additionally, you can choose the alignment of text in columns by adding colons ( to the sides of the "dash" lines in the second row. This affects every cell in the column: ```markdown -| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned | -| :--- | :---: | ---: | :----------- | :------: | ------------: | -| Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 5 | Cell 6 | -| Cell 7 | Cell 8 | Cell 9 | Cell 10 | Cell 11 | Cell 12 | +| Left Aligned | Centered | Right Aligned | +| :--- | :---: | ---: | +| Cell 1 | Cell 2 | Cell 3 | +| Cell 4 | Cell 5 | Cell 6 | ``` -| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned | -| :--- | :---: | ---: | :----------- | :------: | ------------: | -| Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 5 | Cell 6 | -| Cell 7 | Cell 8 | Cell 9 | Cell 10 | Cell 11 | Cell 12 | +| Left Aligned | Centered | Right Aligned | +| :--- | :---: | ---: | +| Cell 1 | Cell 2 | Cell 3 | +| Cell 4 | Cell 5 | Cell 6 | -[In GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#tables), +[In GitLab itself](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#tables), the headers are always left-aligned in Chrome and Firefox, and centered in Safari. You can use HTML formatting to adjust the rendering of tables. For example, you can @@ -1486,13 +1449,13 @@ use `<br>` tags to force a cell to have multiple lines: ```markdown | Name | Details | -|------|---------| +| --- | --- | | Item1 | This is on one line | | Item2 | This item has:<br>- Multiple items<br>- That we want listed separately | ``` | Name | Details | -|------|---------| +| --- | --- | | Item1 | This is on one line | | Item2 | This item has:<br>- Multiple items<br>- That we want listed separately | @@ -1501,7 +1464,7 @@ but they do not render properly on `docs.gitlab.com`: ```markdown | header 1 | header 2 | -|----------|----------| +| --- | --- | | cell 1 | cell 2 | | cell 3 | <ul><li> - [ ] Task one </li><li> - [ ] Task two </li></ul> | ``` @@ -1529,3 +1492,56 @@ entry and paste the spreadsheet: at Daring Fireball is an excellent resource for a detailed explanation of standard Markdown. - You can find the detailed specification for CommonMark in the [CommonMark Spec](https://spec.commonmark.org/current/). - The [CommonMark Dingus](https://spec.commonmark.org/dingus/) helps you test CommonMark syntax. + +## Transition from Redcarpet to CommonMark + +- In GitLab 11.8, the [Redcarpet Ruby library](https://github.com/vmg/redcarpet) + was removed. All issues and comments, including those in 11.1 and earlier, are now processed + by using the [CommonMark Ruby Library](https://github.com/gjtorikian/commonmarker). +- In GitLab 11.3 and later, CommonMark processes wiki pages and Markdown + files (`*.md`) in repositories. +- In GitLab 11.1 and later, the [CommonMark Ruby Library](https://github.com/gjtorikian/commonmarker) + for Markdown processes all new issues, merge requests, comments, and other Markdown + content. + +The documentation website migrated its Markdown engine +[from Redcarpet to Kramdown](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/108) +in October 2018. + +You may have older issues, merge requests, or Markdown documents in your +repository that relied upon nuances of the GitLab RedCarpet version +of Markdown. Because CommonMark uses slightly stricter syntax, these documents +may now appear differently after the transition to CommonMark. + +For example, numbered lists with nested lists may +render incorrectly: + +```markdown +1. Chocolate + - dark + - milk +``` + +To fix this issue, add a space to each nested item. The `-` must be aligned with the first +character of the top list item (`C` in this case): + +```markdown +1. Chocolate + - dark + - milk +``` + +1. Chocolate + - dark + - milk + +We flag any significant differences between Redcarpet and CommonMark Markdown in this document. + +If you have many Markdown files, it can be tedious to determine +if they display correctly or not. You can use the +[`diff_redcarpet_cmark`](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) +tool to generate a list of files and the +differences between how RedCarpet and CommonMark render the files. It indicates +if any changes are needed. + +`diff_redcarpet_cmark` is not an officially supported product. diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index be3454dbd02..29ca3a48e70 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w The Operations Dashboard provides a summary of each project's operational health, including pipeline and alert status. -The dashboard can be accessed from the top bar, by clicking **More > Operations**. +To access the dashboard, on the top bar, select **Menu > Operations**. ## Adding a project to the dashboard diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index bc1e59e4ac2..b5170dfa55b 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -120,7 +120,7 @@ You can publish a Composer package to the Package Registry as part of your CI/CD deploy: stage: deploy script: - - 'curl --header "Job-Token: $CI_JOB_TOKEN" --data tag=<tag> "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/packages/composer"' + - 'curl --header "Job-Token: $CI_JOB_TOKEN" --data tag=<tag> "${CI_API_V4_URL}/projects/$CI_PROJECT_ID/packages/composer"' ``` 1. Run the pipeline. @@ -131,7 +131,7 @@ To view the published package, go to **Packages & Registries > Package Registry* A more detailed Composer CI/CD file is also available as a `.gitlab-ci.yml` template: -1. On the left sidebar, click **Project overview**. +1. On the left sidebar, select **Project information**. 1. Above the file list, click **Set up CI/CD**. If this button is not available, select **CI/CD Configuration** and then **Edit**. 1. From the **Apply a template** list, select **Composer**. diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 53d191cbcfe..a429e746cf2 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -281,7 +281,7 @@ image: conanio/gcc7 create_package: stage: deploy script: - - conan remote add gitlab https://gitlab.example.com/api/v4/packages/conan + - conan remote add gitlab ${CI_API_V4_URL}/projects/$CI_PROJECT_ID/packages/conan - conan new <package-name>/0.1 -t - conan create . <group-name>+<project-name>/stable - CONAN_LOGIN_USERNAME=ci_user CONAN_PASSWORD=${CI_JOB_TOKEN} conan upload <package-name>/0.1@<group-name>+<project-name>/stable --all --remote=gitlab diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 6d7b009bb09..9d65c5d37ad 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -512,6 +512,17 @@ On GitLab.com, the execution time for the cleanup policy is limited, and some of the Container Registry after the policy runs. The next time the policy runs, the remaining tags are included, so it may take multiple runs for all tags to be deleted. +WARNING: +GitLab self-managed installs support for third-party container registries that comply with the +[Docker Registry HTTP API V2](https://docs.docker.com/registry/spec/api/) +specification. However, this specification does not include a tag delete operation. Therefore, when +interacting with third-party container registries, GitLab uses a workaround to delete tags. See the +[related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/15737) +for more information. Due to possible implementation variations, this workaround is not guaranteed +to work with all third-party registries in the same predictable way. If you use the GitLab Container +Registry, this workaround is not required because we implemented a special tag delete operation. In +this case, you can expect cleanup policies to be consistent and predictable. + ### Create a cleanup policy You can create a cleanup policy in [the API](#use-the-cleanup-policy-api) or the UI. @@ -633,7 +644,9 @@ Examples: - Select all tags, keep at least 1 tag per image, clean up any tag older than 14 days, run once a month, preserve any images with the name `master` and the policy is enabled: ```shell - curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-master"}}' "https://gitlab.example.com/api/v4/projects/2" + curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" \ + --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-master"}}' \ + "https://gitlab.example.com/api/v4/projects/2" ``` Valid values for `cadence` when using the API are: diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index b871a08c133..f0bf2fc3363 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -46,7 +46,6 @@ guides you through the process. | Puppet | [#36897](https://gitlab.com/gitlab-org/gitlab/-/issues/36897) | | RPM | [#5932](https://gitlab.com/gitlab-org/gitlab/-/issues/5932) | | SBT | [#36898](https://gitlab.com/gitlab-org/gitlab/-/issues/36898) | -| Terraform | [Draft: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834) | | Vagrant | [#36899](https://gitlab.com/gitlab-org/gitlab/-/issues/36899) | <!-- vale gitlab.Spelling = YES --> @@ -54,6 +53,16 @@ guides you through the process. The GitLab [Container Registry](container_registry/index.md) is a secure and private registry for container images. It's built on open source software and completely integrated within GitLab. Use GitLab CI/CD to create and publish images. Use the GitLab [API](../../api/container_registry.md) to manage the registry across groups and projects. +## Infrastructure Registry + +The GitLab [Infrastructure Registry](infrastructure_registry/index.md) is a secure and private registry for infrastructure packages. You can use GitLab CI/CD to create and publish infrastructure packages. + +The Infrastructure Registry supports the following formats: + +| Package type | GitLab version | +| ------------ | -------------- | +| [Terraform Module](terraform_module_registry/index.md) | 14.0+ | + ## Dependency Proxy The [Dependency Proxy](dependency_proxy/index.md) is a local proxy for frequently-used upstream images and packages. diff --git a/doc/user/packages/infrastructure_registry/index.md b/doc/user/packages/infrastructure_registry/index.md new file mode 100644 index 00000000000..00370bd2f48 --- /dev/null +++ b/doc/user/packages/infrastructure_registry/index.md @@ -0,0 +1,93 @@ +--- +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 +--- + +# Infrastructure Registry **(FREE)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3221) in GitLab 14.0. + +With the GitLab Infrastructure Registry, you can use GitLab projects as a +private registry for infrastructure packages. You can create and publish +packages with GitLab CI/CD, which can then be consumed from other private +projects. + +## View packages + +To view packages within your project or group: + +1. Go to the project or group. +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: + +- [Terraform modules](../terraform_module_registry/index.md) + +## Use GitLab CI/CD to build packages + +To use [GitLab CI/CD](../../../ci/README.md) to build packages, you can +authenticate with the [`CI_JOB_TOKEN` predefined variable](../../../ci/variables/predefined_variables.md). + +CI/CD templates, which you can use to get started, are in [this repository](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). + +Learn more about using CI/CD to build: + +- [Terraform modules](../terraform_module_registry/index.md#publish-a-terraform-module-by-using-cicd) + +If you use CI/CD to build a package, you can find extended activity information +when you view the package details: + + + +You can see the pipeline that published the package as well as the commit and the user who triggered it. However, the history is limited to five updates per package. + +## Download a package + +To download a package: + +1. Go to **Packages & Registries > Infrastructure Registry**. +1. Select the name of the package you want to download. +1. In the **Activity** section, select the name of the package you want to download. + +## Delete a package + +You cannot edit a package after you publish it in the Infrastructure Registry. Instead, you +must delete and recreate it. + +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: + +1. Go to **Packages & Registries > Infrastructure Registry**. +1. Find the name of the package you want to delete. +1. Select **Delete**. + +The package is permanently deleted. + +## Disable the Infrastructure Registry + +The Infrastructure Registry is automatically enabled. + +For self-managed instances, a GitLab administrator can +[disable](../../../administration/packages/index.md) **Packages & Registries**, +which removes this menu item from the sidebar. **(FREE SELF)** + +You can also remove the Infrastructure Registry for a specific project: + +1. In your project, go to **Settings > General**. +1. Expand the **Visibility, project features, permissions** section and toggle **Packages** off (in gray). +1. Select **Save changes**. + +To enable it back, follow the same steps above and toggle it on (in blue). diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index ba7b55dc47d..2567cc3b828 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -341,7 +341,7 @@ file: ```groovy repositories { maven { - url "https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven" + url "${CI_API_V4_URL}/groups/<group>/-/packages/maven" name "GitLab" credentials(HttpHeaderCredentials) { name = 'Job-Token' @@ -611,8 +611,11 @@ Now navigate to your project's **Packages & Registries** page and view the publi ### Publishing a package with the same name or version -When you publish a package with the same name or version as an existing package, -the existing package is overwritten. +When you publish a package with the same name and version as an existing package, the new package +files are added to the existing package. You can still use the UI or API to access and view the +existing package's older files. + +To delete these older package versions, consider using the Packages API or the UI. #### Do not allow duplicate Maven packages @@ -742,17 +745,17 @@ You can create a new package each time the `master` branch is updated. <repositories> <repository> <id>gitlab-maven</id> - <url>${env.CI_SERVER_URL}/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + <url>$env{CI_API_V4_URL}/projects/${env.CI_PROJECT_ID}/packages/maven</url> </repository> </repositories> <distributionManagement> <repository> <id>gitlab-maven</id> - <url>${env.CI_SERVER_URL}/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + <url>${CI_API_V4_URL}/projects/${env.CI_PROJECT_ID}/packages/maven</url> </repository> <snapshotRepository> <id>gitlab-maven</id> - <url>${env.CI_SERVER_URL}/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + <url>${CI_API_V4_URL}/projects/${env.CI_PROJECT_ID}/packages/maven</url> </snapshotRepository> </distributionManagement> ``` diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index ace432b305f..735873be237 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -110,7 +110,8 @@ To authenticate, use one of the following: - It's not recommended, but you can use [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow). Standard OAuth tokens cannot authenticate to the GitLab npm Registry. You must use a personal access token with OAuth headers. - A [CI job token](#authenticate-with-a-ci-job-token). -- Your npm package name must be in the format of [@scope/package-name](#package-naming-convention). It must match exactly, including the case. +- Your npm package name must be in the format of [`@scope/package-name`](#package-naming-convention). + It must match exactly, including the case. ### Authenticate with a personal access token or deploy token @@ -282,7 +283,7 @@ Prerequisites: - [Authenticate](#authenticate-to-the-package-registry) to the Package Registry. - Set a [project-level npm endpoint](#use-the-gitlab-endpoint-for-npm-packages). -- Your npm package name must be in the format of [@scope/package-name](#package-naming-convention). +- Your npm package name must be in the format of [`@scope/package-name`](#package-naming-convention). It must match exactly, including the case. This is different than the npm naming convention, but it is required to work with the GitLab Package Registry. @@ -300,7 +301,7 @@ stages: deploy: stage: deploy script: - - echo "//gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc + - echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc - npm publish ``` @@ -532,7 +533,7 @@ If you get this error, ensure that: ### `npm publish` returns `npm ERR! 400 Bad Request` If you get this error, your package name may not meet the -[@scope/package-name package naming convention](#package-naming-convention). +[`@scope/package-name` package naming convention](#package-naming-convention). Ensure the name meets the convention exactly, including the case. Then try to publish again. diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 7e59b19076a..f19d565ef36 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -336,7 +336,7 @@ updated: stage: deploy script: - dotnet pack -c Release - - dotnet nuget add source "$CI_SERVER_URL/api/v4/projects/$CI_PROJECT_ID/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text + - dotnet nuget add source "${CI_API_V4_URL}/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text - dotnet nuget push "bin/Release/*.nupkg" --source gitlab only: - master diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index f04f6f1316e..52ce7d62940 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -40,14 +40,16 @@ authenticate with GitLab by using the `CI_JOB_TOKEN`. CI/CD templates, which you can use to get started, are in [this repository](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). -Learn more about using CI/CD to build: +Learn more about using the GitLab Package Registry with CI/CD: -- [Composer packages](../composer_repository/index.md#publish-a-composer-package-by-using-cicd) -- [Conan packages](../conan_repository/index.md#publish-a-conan-package-by-using-cicd) -- [Generic packages](../generic_packages/index.md#publish-a-generic-package-by-using-cicd) -- [Maven packages](../maven_repository/index.md#create-maven-packages-with-gitlab-cicd) -- [npm packages](../npm_registry/index.md#publish-an-npm-package-by-using-cicd) -- [NuGet packages](../nuget_repository/index.md#publish-a-nuget-package-by-using-cicd) +- [Composer](../composer_repository/index.md#publish-a-composer-package-by-using-cicd) +- [Conan](../conan_repository/index.md#publish-a-conan-package-by-using-cicd) +- [Generic](../generic_packages/index.md#publish-a-generic-package-by-using-cicd) +- [Maven](../maven_repository/index.md#create-maven-packages-with-gitlab-cicd) +- [npm](../npm_registry/index.md#publish-an-npm-package-by-using-cicd) +- [NuGet](../nuget_repository/index.md#publish-a-nuget-package-by-using-cicd) +- [PyPI](../pypi_repository/#authenticate-with-a-ci-job-token) +- [RubyGems](../rubygems_registry/#authenticate-with-a-ci-job-token) If you use CI/CD to build a package, extended activity information is displayed when you view the package details: @@ -81,6 +83,22 @@ To delete a package in the UI, from your group or project: The package is permanently deleted. +## Delete files associated with a package + +To delete package files, you must have suitable [permissions](../../permissions.md). + +You can delete packages by using [the API](../../../api/packages.md#delete-a-package-file) or the UI. + +To delete package files in the UI, from your group or project: + +1. Go to **Packages & Registries > Package Registry**. +1. Find the name of the package you want to delete. +1. Select the package to view additional details. +1. Find the name of the file you would like to delete. +1. Expand the ellipsis and select **Delete file**. + +The package files are permanently deleted. + ## Disable the Package Registry The Package Registry is automatically enabled. @@ -100,6 +118,9 @@ The **Packages & Registries > Package Registry** entry is removed from the sideb ## Package workflows -Learn how to use the GitLab Package Registry to build your own custom package workflow. +Learn how to use the GitLab Package Registry to build your own custom package workflow: + +- [Use a project as a package registry](../workflows/project_registry.md) + to publish all of your packages to one project. -- [Use a project as a package registry](../workflows/project_registry.md) to publish all of your packages to one project. +- Publish multiple different packages from one [monorepo project](../workflows/working_with_monorepos.md). diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 17b51e313fa..2dd00fdc273 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -216,7 +216,7 @@ run: script: - pip install twine - python setup.py sdist bdist_wheel - - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine upload --repository-url https://gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/pypi dist/* + - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine upload --repository-url ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi dist/* ``` You can also use `CI_JOB_TOKEN` in a `~/.pypirc` file that you check in to @@ -233,6 +233,14 @@ username = gitlab-ci-token password = ${env.CI_JOB_TOKEN} ``` +### Authenticate to access packages within a group + +Follow the instructions above for the token type, but use the group URL in place of the project URL: + +```shell +https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/pypi +``` + ## Publish a PyPI package Prerequisites: @@ -316,6 +324,8 @@ more than once, a `404 Bad Request` error occurs. ## Install a PyPI package +### Install from the project level + To install the latest version of a package, use the following command: ```shell @@ -350,6 +360,33 @@ Installing collected packages: mypypipackage Successfully installed mypypipackage-0.0.1 ``` +### Install from the group level + +To install the latest version of a package from a group, use the following command: + +```shell +pip install --index-url https://<personal_access_token_name>:<personal_access_token>@gitlab.example.com/api/v4/groups/<group_id>/-/packages/pypi/simple --no-deps <package_name> +``` + +In this command: + +- `<package_name>` is the package name. +- `<personal_access_token_name>` is a personal access token name with the `read_api` scope. +- `<personal_access_token>` is a personal access token with the `read_api` scope. +- `<group_id>` is the group ID. + +In these commands, you can use `--extra-index-url` instead of `--index-url`. However, using +`--extra-index-url` makes you vulnerable to dependency confusion attacks because it checks the PyPi +repository for the package before it checks the custom repository. `--extra-index-url` adds the +provided URL as an additional registry which the client checks if the package is present. +`--index-url` tells the client to check for the package at the provided URL only. + +If you're following the guide and want to install the `MyPyPiPackage` package, you can run: + +```shell +pip install mypypipackage --no-deps --index-url https://<personal_access_token_name>:<personal_access_token>@gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/pypi/simple +``` + ### Package names GitLab looks for packages that use diff --git a/doc/user/packages/rubygems_registry/index.md b/doc/user/packages/rubygems_registry/index.md index e4d297ac1d8..743bc229e11 100644 --- a/doc/user/packages/rubygems_registry/index.md +++ b/doc/user/packages/rubygems_registry/index.md @@ -88,11 +88,11 @@ run: - mkdir ~/.gem - echo "---" > ~/.gem/credentials - | - echo "https://gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/rubygems: '${CI_JOB_TOKEN}'" >> ~/.gem/credentials + echo "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/rubygems: '${CI_JOB_TOKEN}'" >> ~/.gem/credentials - chmod 0600 ~/.gem/credentials # rubygems requires 0600 permissions on the credentials file script: - gem build my_gem - - gem push my_gem-0.0.1.gem --host https://gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/rubygems + - gem push my_gem-0.0.1.gem --host ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/rubygems ``` You can also use `CI_JOB_TOKEN` in a `~/.gem/credentials` file that you check in to diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md new file mode 100644 index 00000000000..efb2b8ddf8e --- /dev/null +++ b/doc/user/packages/terraform_module_registry/index.md @@ -0,0 +1,124 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Terraform module registry **(FREE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3221) in GitLab 14.0. + +Publish Terraform modules in your project's Infrastructure Registry, then reference them using GitLab +as a Terraform module registry. + +## Authenticate to the Terraform module registry + +To authenticate to the Terraform module registry, you need either: + +- A [personal access token](../../../api/README.md#personalproject-access-tokens) with at least `read_api` rights. +- A [CI/CD job token](../../../api/README.md#gitlab-cicd-job-token). + +## Publish a Terraform Module + +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/README.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 +``` + +| Attribute | Type | Required | Description | +| -------------------| --------------- | ---------| -------------------------------------------------------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/README.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 (`-`). +| `module_system` | string | yes | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), or hyphens (`-`). +| `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. + +Example request using a personal access token: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" \ + --upload-file path/to/file.tgz \ + "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/terraform/modules/my-module/my-system/0.0.1/file" +``` + +Example response: + +```json +{ + "message":"201 Created" +} +``` + +Example request using a deploy token: + +```shell +curl --header "DEPLOY-TOKEN: <deploy_token>" \ + --upload-file path/to/file.tgz \ + "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/terraform/modules/my-module/my-system/0.0.1/file" +``` + +Example response: + +```json +{ + "message":"201 Created" +} +``` + +## Reference a Terraform Module + +Prerequisites: + +- You need to [authenticate with the API](../../../api/README.md#authentication). If authenticating with a personal access token, it must be configured with the `read_api` scope. + +Authentication tokens (Job Token or Personal Access Token) can be provided for `terraform` in your `~/.terraformrc` file: + +```plaintext +credentials "gitlab.com" { + token = "<TOKEN>" +} +``` + +Where `gitlab.com` can be replaced with the hostname of your self-managed GitLab instance. + +You can then reference your Terraform Module from a downstream Terraform project: + +```plaintext +module "<module>" { + source = "gitlab.com/<namespace>/<module_name>/<module_system>" +} +``` + +## Publish a Terraform module by using CI/CD + +To work with Terraform modules in [GitLab CI/CD](../../../ci/README.md), you can use +`CI_JOB_TOKEN` in place of the personal access token in your commands. + +For example: + +```yaml +image: curlimages/curl:latest + +stages: + - upload + +upload: + stage: upload + 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"' +``` + +## Example projects + +For examples of the Terraform module registry, check the projects below: + +- The [_GitLab local file_ project](https://gitlab.com/mattkasa/gitlab-local-file) creates a minimal Terraform module and uploads it into the Terraform module registry using GitLab CI/CD. +- The [_Terraform module test_ project](https://gitlab.com/mattkasa/terraform-module-test) uses the module from the previous example. diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index 3e1c1e7f2ad..12978ad72a5 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -34,8 +34,8 @@ of each package management system to publish different package types to the same Let's take a look at how you might create a public place to hold all of your public packages. -1. Create a new project in GitLab. The project doesn't require any code or content. Note the project ID - that's displayed on the project overview page. +1. Create a new project in GitLab. The project doesn't require any code or content. +1. On the left sidebar, select **Project information**, and note the project ID. 1. Create an access token. All package types in the Package Registry are accessible by using [GitLab personal access tokens](../../profile/personal_access_tokens.md). If you're using CI/CD, you can use CI job tokens (`CI_JOB_TOKEN`) to authenticate. diff --git a/doc/user/packages/workflows/working_with_monorepos.md b/doc/user/packages/workflows/working_with_monorepos.md new file mode 100644 index 00000000000..4e431b036de --- /dev/null +++ b/doc/user/packages/workflows/working_with_monorepos.md @@ -0,0 +1,64 @@ +--- +stage: Package +group: Package +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Monorepo package management workflows + +One project or Git repository can contain multiple different subprojects or submodules that are all +packaged and published individually. + +## Publishing different packages to the parent project + +The number and name of packages you can publish to one project is not limited. +You can accomplish this by setting up different configuration files for each +package. See the documentation for the package manager of your choice since +each has its own specific files and instructions to follow to publish +a given package. + +The example here uses [NPM](../npm_registry/index.md). +In this example, `MyProject` is the parent project. It contains a sub-project `Foo` in the +`components` directory: + +```plaintext +MyProject/ + |- src/ + | |- components/ + | |- Foo/ + |- package.json +``` + +The goal is to publish the packages for `MyProject` and `Foo`. Following the instructions in the +[GitLab NPM registry documentation](../npm_registry/index.md), +you can publish `MyProject` by modifying the `package.json` file with a `publishConfig` section, +and by doing one of the following: + +- Modify your local NPM configuration with CLI commands like `npm config set`. +- Save a `.npmrc` file in the root of the project specifying these configuration settings. + +If you follow the instructions, you can publish `MyProject` by running `npm publish` from the root +directory. + +Publishing `Foo` is almost exactly the same. Simply follow the same steps while in the `Foo` +directory. `Foo` needs its own `package.json` file, which you can add manually by using `npm init`. +`Foo` also needs its own configuration settings. Since you are publishing to the same place, if you +used `npm config set` to set the registry for the parent project, then no additional setup is +necessary. If you used an `.npmrc` file, you need an additional `.npmrc` file in the `Foo` directory. +Be sure to add `.npmrc` files to the `.gitignore` file or use environment variables in place of your +access tokens to prevent your tokens from being exposed. This `.npmrc` file can be identical to the +one you used in `MyProject`. You can now run `npm publish` from the `Foo` directory and you can +publish `Foo` separately from `MyProject`. + +You could follow a similar process for Conan packages. However, instead of `.npmrc` and +`package.json`, you have `conanfile.py` in multiple locations within the project. + +## Publishing to other projects + +A package is associated with a project on GitLab, but the package does not need to be associated +with the code in that project. When configuring NPM or Maven, you only use the `Project ID` to set +the registry URL that the package uploads to. If you set this to any project that you have access to +and update any other configuration similarly depending on the package type, your packages are +published to that project. This means you can publish multiple packages to one project, even if +their code does not exist in the same place. See the [project registry workflow documentation](project_registry.md) +for more information. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 245efc0e908..6739d08e156 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -4,20 +4,17 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Permissions +# Permissions and roles -Users have different abilities depending on the access level they have in a +Users have different abilities depending on the role they have in a particular group or project. If a user is both in a project's group and the -project itself, the highest permission level is used. +project itself, the highest role is used. -On public and internal projects, the Guest role is not enforced. All users can: +On [public and internal projects](../api/projects.md#project-visibility-level), the Guest role +(not to be confused with [Guest user](#free-guest-users)) is not enforced. -- Create issues. -- Leave comments. -- Clone or download the project code. - -When a member leaves a team's project, all the assigned [Issues](project/issues/index.md) and [Merge Requests](project/merge_requests/index.md) -are unassigned automatically. +When a member leaves a team's project, all the assigned [issues](project/issues/index.md) and +[merge requests](project/merge_requests/index.md) are automatically unassigned. GitLab [administrators](../administration/index.md) receive all permissions. @@ -39,11 +36,11 @@ usernames. A GitLab administrator can configure the GitLab instance to NOTE: In GitLab 11.0, the Master role was renamed to Maintainer. -The Owner permission is only available at the group or personal namespace level (and for instance administrators) and is inherited by its projects. +The Owner role is only available at the group or personal namespace level (and for instance administrators) and is inherited by its projects. While Maintainer is the highest project-level role, some actions can only be performed by a personal namespace or group owner, or an instance administrator, who receives all permissions. For more information, see [projects members documentation](project/members/index.md). -The following table depicts the various user permission levels in a project. +The following table lists project permissions available for each role: | Action | Guest | Reporter | Developer |Maintainer| Owner | |---------------------------------------------------|---------|------------|-------------|----------|--------| @@ -71,7 +68,7 @@ The following table depicts the various user permission levels in a project. | View requirements **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View Issue analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View Merge Request analytics **(STARTER)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| View Merge Request analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View Value Stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | | Manage user-starred metrics dashboards (*7*) | ✓ | ✓ | ✓ | ✓ | ✓ | | View confidential issues | (*2*) | ✓ | ✓ | ✓ | ✓ | @@ -80,6 +77,7 @@ The following table depicts the various user permission levels in a project. | Label issues | | ✓ | ✓ | ✓ | ✓ | | Set issue weight | | ✓ | ✓ | ✓ | ✓ | | [Set issue estimate and record time spent](project/time_tracking.md) | | ✓ | ✓ | ✓ | ✓ | +| View a time tracking report | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | Lock issue threads | | ✓ | ✓ | ✓ | ✓ | | Manage issue tracker | | ✓ | ✓ | ✓ | ✓ | | Manage linked issues | | ✓ | ✓ | ✓ | ✓ | @@ -91,7 +89,7 @@ The following table depicts the various user permission levels in a project. | See [DORA metrics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | | See a list of merge requests | | ✓ | ✓ | ✓ | ✓ | | View CI/CD analytics | | ✓ | ✓ | ✓ | ✓ | -| View Code Review analytics **(STARTER)** | | ✓ | ✓ | ✓ | ✓ | +| View Code Review analytics **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | | View Repository analytics | | ✓ | ✓ | ✓ | ✓ | | View Error Tracking list | | ✓ | ✓ | ✓ | ✓ | | View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | @@ -103,6 +101,7 @@ The following table depicts the various user permission levels in a project. | Move [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | | Reopen [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | | Pull [packages](packages/index.md) | | ✓ | ✓ | ✓ | ✓ | +| View project statistics | | ✓ | ✓ | ✓ | ✓ | | Publish [packages](packages/index.md) | | | ✓ | ✓ | ✓ | | Create/edit/delete a Cleanup policy | | | ✓ | ✓ | ✓ | | Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | @@ -119,7 +118,6 @@ The following table depicts the various user permission levels in a project. | Lock merge request threads | | | ✓ | ✓ | ✓ | | Approve merge requests (*9*) | | | ✓ | ✓ | ✓ | | Manage/Accept merge requests | | | ✓ | ✓ | ✓ | -| View project statistics | | | ✓ | ✓ | ✓ | | Create new environments | | | ✓ | ✓ | ✓ | | Stop environments | | | ✓ | ✓ | ✓ | | Enable Review Apps | | | ✓ | ✓ | ✓ | @@ -256,16 +254,18 @@ NOTE: In GitLab 11.0, the Master role was renamed to Maintainer. Any user can remove themselves from a group, unless they are the last Owner of -the group. The following table depicts the various user permission levels in a -group. +the group. + +The following table lists group permissions available for each role: | Action | Guest | Reporter | Developer | Maintainer | Owner | |--------------------------------------------------------|-------|----------|-----------|------------|-------| | Browse group | ✓ | ✓ | ✓ | ✓ | ✓ | | View group wiki pages **(PREMIUM)** | ✓ (6) | ✓ | ✓ | ✓ | ✓ | | View Insights charts **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View group epic **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| Create/edit group epic **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | +| View group epic **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| Create/edit group epic **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | +| Create/edit/delete epic boards **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | | Manage group labels | | ✓ | ✓ | ✓ | ✓ | | See a container registry | | ✓ | ✓ | ✓ | ✓ | | Pull [packages](packages/index.md) | | ✓ | ✓ | ✓ | ✓ | @@ -289,8 +289,8 @@ group. | Create/Delete group deploy tokens | | | | | ✓ | | Manage group members | | | | | ✓ | | Delete group | | | | | ✓ | -| Delete group epic **(PREMIUM)** | | | | | ✓ | -| Edit SAML SSO Billing **(PREMIUM SAAS)** | ✓ | ✓ | ✓ | ✓ | ✓ (4) | +| Delete group epic **(PREMIUM)** | | | | | ✓ | +| Edit SAML SSO Billing **(PREMIUM SAAS)** | ✓ | ✓ | ✓ | ✓ | ✓ (4) | | View group Audit Events | | | ✓ (7) | ✓ (7) | ✓ | | Disable notification emails | | | | | ✓ | | View Contribution analytics | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -359,10 +359,11 @@ External users still count towards a license seat. An administrator can flag a user as external by either of the following methods: -- Either [through the API](../api/users.md#user-modification). -- Or by navigating to the **Admin Area > Overview > Users** to create a new user - or edit an existing one. There, you can find the option to flag the user as - external. +- [Through the API](../api/users.md#user-modification). +- Using the GitLab UI: + 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the left sidebar, select **Overview > Users** to create a new user or edit an existing one. + There, you can find the option to flag the user as external. Additionally users can be set as external users using [SAML groups](../integration/saml.md#external-groups) and [LDAP groups](../administration/auth/ldap/index.md#external-groups). @@ -370,7 +371,11 @@ and [LDAP groups](../administration/auth/ldap/index.md#external-groups). ### Setting new users to external By default, new users are not set as external users. This behavior can be changed -by an administrator on the **Admin Area > Settings > General** page, under **Account and limit**. +by an administrator: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > General**. +1. Expand the **Account and limit** section. If you change the default behavior of creating new users as external, you have the option to narrow it down by defining a set of internal users. @@ -455,33 +460,32 @@ NOTE: In GitLab 11.0, the Master role was renamed to Maintainer. GitLab CI/CD permissions rely on the role the user has in GitLab. There are four -permission levels in total: - -- admin -- maintainer -- developer -- guest/reporter - -The admin user can perform any action on GitLab CI/CD in scope of the GitLab -instance and project. In addition, all admins can use the admin interface under -`/admin/runners`. - -| Action | Guest, Reporter | Developer |Maintainer| Admin | -|---------------------------------------|-----------------|-------------|----------|--------| -| See commits and jobs | ✓ | ✓ | ✓ | ✓ | -| Retry or cancel job | | ✓ | ✓ | ✓ | -| Erase job artifacts and job logs | | ✓ (*1*) | ✓ | ✓ | -| Delete project | | | ✓ | ✓ | -| Create project | | | ✓ | ✓ | -| Change project configuration | | | ✓ | ✓ | -| Add specific runners | | | ✓ | ✓ | -| Add shared runners | | | | ✓ | -| See events in the system | | | | ✓ | -| Admin interface | | | | ✓ | +roles: + +- Administrator +- Maintainer +- Developer +- Guest/Reporter + +The Administrator role can perform any action on GitLab CI/CD in scope of the GitLab +instance and project. + +| Action | Guest, Reporter | Developer |Maintainer| Administrator | +|---------------------------------------|-----------------|-------------|----------|---------------| +| See commits and jobs | ✓ | ✓ | ✓ | ✓ | +| Retry or cancel job | | ✓ | ✓ | ✓ | +| Erase job artifacts and job logs | | ✓ (*1*) | ✓ | ✓ | +| Delete project | | | ✓ | ✓ | +| Create project | | | ✓ | ✓ | +| Change project configuration | | | ✓ | ✓ | +| Add specific runners | | | ✓ | ✓ | +| Add shared runners | | | | ✓ | +| See events in the system | | | | ✓ | +| Admin Area | | | | ✓ | 1. Only if the job was: - Triggered by the user - - [In GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/35069) and later, not run for a protected branch + - [In GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/35069) and later, run for a non-protected branch. ### Job permissions diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index 91688989e55..972414dbf0b 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -14,16 +14,21 @@ You can create users: ## Create users on sign in page -If you have [sign-up enabled](../../admin_area/settings/sign_up_restrictions.md), users can create their own accounts by selecting "Register now" on the sign-in page, or navigate to `https://gitlab.example.com/users/sign_up`. +If you have [sign-up enabled](../../admin_area/settings/sign_up_restrictions.md), users can create +their own accounts by either: + +- Selecting the **Register now** link on the sign-in page. +- Navigating to `https://gitlab.example.com/users/sign_up`.  ## Create users in Admin Area -As an admin user, you can manually create users by: +As an Admin user, you can manually create users: -1. Navigating to **Admin Area > Overview > Users** (`/admin/users` page). -1. Selecting the **New User** button. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Overview > Users** (`/admin/users`). +1. Select **New user**. You can also [create users through the API](../../../api/users.md) as an admin. @@ -33,9 +38,11 @@ You can also [create users through the API](../../../api/users.md) as an admin. ## Create users through authentication integrations -Users will be: +Users are: - Automatically created upon first sign in with the [LDAP integration](../../../administration/auth/ldap/index.md). -- Created when first signing in via an [OmniAuth provider](../../../integration/omniauth.md) if the `allow_single_sign_on` setting is present. -- Created when first signing with [Group SAML](../../group/saml_sso/index.md) -- Automatically created by [SCIM](../../group/saml_sso/scim_setup.md) when the user is created in the identity provider. +- Created when first signing in using an [OmniAuth provider](../../../integration/omniauth.md) if + the `allow_single_sign_on` setting is present. +- Created when first signing with [Group SAML](../../group/saml_sso/index.md). +- Automatically created by [SCIM](../../group/saml_sso/scim_setup.md) when the user is created in + the identity provider. diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 361353a0f8c..c4ab54736bc 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -13,7 +13,7 @@ Users can be deleted from a GitLab instance, either by: - An administrator. NOTE: -Deleting a user will delete all projects in that user namespace. +Deleting a user deletes all projects in that user namespace. ## As a user @@ -28,7 +28,8 @@ As a user, to delete your own account: As an administrator, to delete a user account: -1. Go to **Admin Area > Overview > Users**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Overview > Users**. 1. Select a user. 1. Under the **Account** tab, select: - **Delete user** to delete only the user but maintain their diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index c763226015e..3f42fc0d131 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -505,7 +505,18 @@ Feature.disable(:webauthn) If you are receiving an `invalid pin code` error, this may indicate that there is a time sync issue between the authentication application and the GitLab instance itself. -Most authentication apps have a feature in the settings for syncing the time for the codes themselves. For Google Authenticator for example, go to `Settings > Time correction for codes`. +To avoid the time sync issue, enable time synchronization in the device that generates the codes. For example: + +- For Android (Google Authenticator): + 1. Go to the Main Menu in Google Authenticator. + 1. Select Settings. + 1. Select the Time correction for the codes. + 1. Select Sync now. +- For iOS: + 1. Go to Settings. + 1. Select General. + 1. Select Date & Time. + 1. Enable Set Automatically. If it’s already enabled, disable it, wait a few seconds, and re-enable. <!-- ## Troubleshooting diff --git a/doc/user/profile/img/notification_global_settings_v13_12.png b/doc/user/profile/img/notification_global_settings_v13_12.png Binary files differindex 2989543c2d8..0998bb89778 100644 --- a/doc/user/profile/img/notification_global_settings_v13_12.png +++ b/doc/user/profile/img/notification_global_settings_v13_12.png diff --git a/doc/user/profile/img/unknown_sign_in_email_v13_1.png b/doc/user/profile/img/unknown_sign_in_email_v13_1.png Binary files differdeleted file mode 100644 index 586be483be9..00000000000 --- a/doc/user/profile/img/unknown_sign_in_email_v13_1.png +++ /dev/null diff --git a/doc/user/profile/img/unknown_sign_in_email_v14_0.png b/doc/user/profile/img/unknown_sign_in_email_v14_0.png Binary files differnew file mode 100644 index 00000000000..dec1251addb --- /dev/null +++ b/doc/user/profile/img/unknown_sign_in_email_v14_0.png diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 17c24a6b63f..9d714a6efd0 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -42,7 +42,7 @@ If you don't know your current password, select the **I forgot my password** lin Your username has a unique [namespace](../group/index.md#namespaces), which is updated when you change your username. Before you change your username, read about -[how redirects behave](../project/repository/index.md#redirects-when-changing-repository-paths). +[how redirects behave](../project/repository/index.md#what-happens-when-a-repository-path-changes). If you do not want to update the namespace, you can create a new user or group and transfer projects to it instead. Prerequisites: @@ -107,6 +107,20 @@ To show private contributions: 1. In the **Main settings** section, select the **Include private contributions on my profile** checkbox. 1. Select **Update profile settings**. +## Add your gender pronouns + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332405) in GitLab 14.0. + +You can add your gender pronouns to your GitLab account to be displayed next to +your name in your profile. + +To specify your pronouns: + +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the **Pronouns** field, enter your pronouns. +1. Select **Update profile settings**. + ## Set your current status > - Introduced in GitLab 11.2. diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index c0d232ba491..b9410be791e 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -176,6 +176,7 @@ Users are notified of the following events: | Event | Sent to | Settings level | |------------------------------|---------------------|------------------------------| | New SSH key added | User | Security email, always sent. | +| SSH key has expired | User | Security email, always sent. | | New email added | User | Security email, always sent. | | Email changed | User | Security email, always sent. | | Password changed | User | Security email, always sent when user changes their own password | diff --git a/doc/user/profile/unknown_sign_in_notification.md b/doc/user/profile/unknown_sign_in_notification.md index 1eec351e4da..7aa1ae89c9f 100644 --- a/doc/user/profile/unknown_sign_in_notification.md +++ b/doc/user/profile/unknown_sign_in_notification.md @@ -30,4 +30,4 @@ for a notification email to be sent. ## Example email - + diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 1834bc20aee..64a375c6a1d 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -15,7 +15,7 @@ points to. Examples for badges can be the [pipeline status](../../ci/pipelines/s [test coverage](../../ci/pipelines/settings.md#test-coverage-report-badge), or ways to contact the project maintainers. - + ## Project badges @@ -90,6 +90,35 @@ default branch or commit SHA when the project is configured to have a private repository. This is by design, as badges are intended to be used publicly. Avoid using these placeholders if the information is sensitive. +## Use custom badge images + +Use custom badge images in a project or a group if you want to use badges other than the default +ones. + +Prerequisites: + +- A valid URL that points directly to the desired image for the badge. + If the image is located in a GitLab repository, use the raw link to the image. + +Using placeholders, here is an example badge image URL referring to a raw image at the root of a repository: + +```plaintext +https://gitlab.example.com/<project_path>/-/raw/<default_branch>/my-image.svg +``` + +To add a new badge to a group or project with a custom image: + +1. Go to your group or project and select **Settings > General**. +1. Expand **Badges**. +1. Under **Name**, enter the name for the badge. +1. Under **Link**, enter the URL that the badge should point to. +1. Under **Badge image URL**, enter the URL that points directly to the custom image that should be + displayed. +1. Select **Add badge**. + +To learn how to use custom images generated via a pipeline, see our documentation on +[accessing the latest job artifacts by URL](../../ci/pipelines/job_artifacts.md#access-the-latest-job-artifacts-by-url). + ## API You can also configure badges via the GitLab API. As in the settings, there is diff --git a/doc/user/project/bulk_editing.md b/doc/user/project/bulk_editing.md index d9e268251b7..1ecfb3b7292 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -1,5 +1,6 @@ --- redirect_to: 'issues/managing_issues.md' +remove_date: '2021-08-12' --- This document was moved to [another location](issues/managing_issues.md). diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index f7394093a3a..c3900d33cb8 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -91,7 +91,7 @@ Here's an example setup flow from scratch: 1. Prepare an [Auto DevOps-enabled](../../topics/autodevops/index.md) project. 1. Set up a [Kubernetes Cluster](../../user/project/clusters/index.md) in your project. -1. Install [Ingress](../../user/clusters/applications.md#ingress) as a GitLab Managed App. +1. Install [NGINX Ingress](https://github.com/kubernetes/ingress-nginx/tree/master/charts/ingress-nginx) in your cluster. 1. Set up [the base domain](../../user/project/clusters/index.md#base-domain) based on the Ingress Endpoint assigned above. 1. Check if [`v2.0.0+` of `auto-deploy-image` is used in your Auto DevOps pipelines](../../topics/autodevops/upgrading_auto_deploy_dependencies.md#verify-dependency-versions). @@ -116,7 +116,7 @@ or by sending requests to the [GraphQL API](../../api/graphql/getting_started.md To use your [Deploy Board](../../user/project/deploy_boards.md): -1. Navigate to **Operations > Environments** for your project. +1. Navigate to **Deployments > Environments** for your project. 1. Set the new weight with the dropdown on the right side. 1. Confirm your selection. diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index c0fb8f5848f..58bdb3d698f 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -74,10 +74,10 @@ Instance profiles dynamically retrieve temporary credentials from AWS when neede To create and add a new Kubernetes cluster to your project, group, or instance: 1. Navigate to your: - - Project's **Operations > Kubernetes** page, for a project-level cluster. + - Project's **Infrastructure > Kubernetes clusters** page, for a project-level cluster. - Group's **Kubernetes** page, for a group-level cluster. - **Admin Area > Kubernetes**, for an instance-level cluster. -1. Click **Add Kubernetes cluster**. +1. Click **Integrate with a cluster certificate**. 1. Under the **Create new cluster** tab, click **Amazon EKS** to display an `Account ID` and `External ID` needed for later steps. 1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM policy: @@ -184,13 +184,10 @@ To create and add a new Kubernetes cluster to your project, group, or instance: See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. 1. Finally, click the **Create Kubernetes cluster** button. -After about 10 minutes, your cluster is ready to go. You can now proceed -to install some [pre-defined applications](index.md#installing-applications). +After about 10 minutes, your cluster is ready to go. NOTE: -You must add your AWS external ID to the -[IAM Role in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-xaccount) -to manage your cluster using `kubectl`. +If you have [installed and configured](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl) `kubectl` and you would like to manage your cluster with it, you must add your AWS external ID in the AWS configuration. For more information on how to configure AWS CLI, see [using an IAM role in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-xaccount). ### Cluster creation flow @@ -292,7 +289,7 @@ you've assigned the role the correct permissions. ### Key Pairs are not loaded -GitLab loads the key pairs from the **Cluster Region** specified. Ensure that key pair exists in that region. +GitLab loads the key pairs from the **Cluster Region** specified. Ensure that key pair exists in that region. #### `ROLLBACK_FAILED` during cluster creation diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index af3a17dc60c..9f0e5603785 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -46,10 +46,11 @@ Note the following: To create and add a new Kubernetes cluster to your project, group, or instance: 1. Navigate to your: - - Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. + - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level + cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. -1. Click **Add Kubernetes cluster**. +1. Click **Integrate with a cluster certificate**. 1. Under the **Create new cluster** tab, click **Google GKE**. 1. Connect your Google account if you haven't done already by clicking the **Sign in with Google** button. @@ -70,8 +71,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. 1. Finally, click the **Create Kubernetes cluster** button. -After a couple of minutes, your cluster is ready. You can now proceed -to install some [pre-defined applications](index.md#installing-applications). +After a couple of minutes, your cluster is ready. ### Cloud Run for Anthos @@ -79,8 +79,8 @@ to install some [pre-defined applications](index.md#installing-applications). You can choose to use Cloud Run for Anthos in place of installing Knative and Istio separately after the cluster has been created. This means that Cloud Run -(Knative), Istio, and HTTP Load Balancing are enabled on the cluster at -create time and cannot be [installed or uninstalled](../../clusters/applications.md) separately. +(Knative), Istio, and HTTP Load Balancing are enabled on the cluster +from the start, and cannot be installed or uninstalled. ## Existing GKE cluster diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 1b4b4f38f4b..2ecbc4a2ff5 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -4,7 +4,16 @@ 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 --- -# Adding and removing Kubernetes clusters **(FREE)** +# Add a cluster using cluster certificates **(FREE)** + +> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/6049) in GitLab 14.0. + +WARNING: +Creating a new cluster or adding an existing cluster to GitLab through the certificate-based method +is deprecated and no longer recommended. Kubernetes cluster, similar to any other +infrastructure, should be created, updated, and maintained using [Infrastructure as Code](../../infrastructure/index.md). +GitLab is developing a built-in capability to create clusters with Terraform. +You can follow along in this [epic](https://gitlab.com/groups/gitlab-org/-/epics/6049). GitLab offers integrated cluster creation for the following Kubernetes providers: @@ -35,9 +44,9 @@ Before [adding a Kubernetes cluster](#create-new-cluster) using GitLab, you need - A [self-managed installation](https://about.gitlab.com/pricing/#self-managed) with GitLab version 12.5 or later. This ensures the GitLab UI can be used for cluster creation. - The following GitLab access: - - [Maintainer access to a project](../../permissions.md#project-members-permissions) for a + - [Maintainer role for a project](../../permissions.md#project-members-permissions) for a project-level cluster. - - [Maintainer access to a group](../../permissions.md#group-members-permissions) for a + - [Maintainer role for a group](../../permissions.md#group-members-permissions) for a group-level cluster. - [Admin Area access](../../admin_area/index.md) for a self-managed instance-level cluster. **(FREE SELF)** @@ -52,16 +61,10 @@ When creating a cluster in GitLab, you are asked if you would like to create eit cluster, which is the GitLab default and recommended option. - An [Attribute-based access control (ABAC)](https://kubernetes.io/docs/reference/access-authn-authz/abac/) cluster. -GitLab creates the necessary service accounts and privileges to install and run -[GitLab managed applications](index.md#installing-applications). When GitLab creates the cluster, +When GitLab creates the cluster, a `gitlab` service account with `cluster-admin` privileges is created in the `default` namespace to manage the newly created cluster. -The first time you install an application into your cluster, the `tiller` service -account is created with `cluster-admin` privileges in the -`gitlab-managed-apps` namespace. This service account is used by Helm to -install and run [GitLab managed applications](index.md#installing-applications). - Helm also creates additional service accounts and other resources for each installed application. Consult the documentation of the Helm charts for each application for details. @@ -132,11 +135,8 @@ If you don't want to use a runner in privileged mode, either: - Use shared runners on GitLab.com. They don't have this security issue. - Set up your own runners using the configuration described at - [shared runners](../../gitlab_com/index.md#shared-runners). This involves: - 1. Making sure that you don't have it installed via - [the applications](index.md#installing-applications). - 1. Installing a runner - [using `docker+machine`](https://docs.gitlab.com/runner/executors/docker_machine.html). + [shared runners](../../gitlab_com/index.md#shared-runners) using + [`docker+machine`](https://docs.gitlab.com/runner/executors/docker_machine.html). ## Create new cluster @@ -144,36 +144,38 @@ New clusters can be created using GitLab on Google Kubernetes Engine (GKE) or Amazon Elastic Kubernetes Service (EKS) at the project, group, or instance level: 1. Navigate to your: - - Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. + - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level + cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. -1. Click **Add Kubernetes cluster**. +1. Click **Integrate with a cluster certificate**. 1. Click the **Create new cluster** tab. 1. Click either **Amazon EKS** or **Google GKE**, and follow the instructions for your desired service: - [Amazon EKS](add_eks_clusters.md#new-eks-cluster). - [Google GKE](add_gke_clusters.md#creating-the-cluster-on-gke). -After creating a cluster, you can install runners for it as described in -[GitLab Managed Apps](../../clusters/applications.md). +After creating a cluster, you can [install runners](https://docs.gitlab.com/runner/install/kubernetes.html), +add a [cluster management project](../../clusters/management_project.md), +configure [Auto DevOps](../../../topics/autodevops/index.md), +or start [deploying right away](index.md#deploying-to-a-kubernetes-cluster). ## Add existing cluster If you have an existing Kubernetes cluster, you can add it to a project, group, -or instance. - -Kubernetes integration isn't supported for arm64 clusters. See the issue -[Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab/-/issues/29838) -for details. +or instance, and [install runners](https://docs.gitlab.com/runner/install/kubernetes.html) +on it (the cluster does not need to be added to GitLab first). -After adding an existing cluster, you can install runners for it as described in -[GitLab Managed Apps](../../clusters/applications.md). +After adding a cluster, you can add a [cluster management project](../../clusters/management_project.md), +configure [Auto DevOps](../../../topics/autodevops/index.md), +or start [deploying right away](index.md#deploying-to-a-kubernetes-cluster). ### Existing Kubernetes cluster To add a Kubernetes cluster to your project, group, or instance: 1. Navigate to your: - 1. Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. + 1. Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level + cluster. 1. Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. 1. **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. @@ -316,8 +318,7 @@ To add a Kubernetes cluster to your project, group, or instance: 1. Finally, click the **Create Kubernetes cluster** button. -After a couple of minutes, your cluster is ready. You can now proceed -to install some [pre-defined applications](index.md#installing-applications). +After a couple of minutes, your cluster is ready. #### Disable Role-Based Access Control (RBAC) (optional) @@ -351,7 +352,8 @@ The Kubernetes cluster integration enables after you have successfully either cr a new cluster or added an existing one. To disable Kubernetes cluster integration: 1. Navigate to your: - - Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. + - Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level + cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. 1. Click on the name of the cluster. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index c2d06e0a22c..97296d22dd9 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -31,7 +31,7 @@ Besides integration at the project level, Kubernetes clusters can also be integrated at the [group level](../../group/clusters/index.md) or [GitLab instance level](../../instance/clusters/index.md). -To view your project level Kubernetes clusters, navigate to **Operations > Kubernetes** +To view your project level Kubernetes clusters, navigate to **Infrastructure > Kubernetes** from your project. On this page, you can [add a new cluster](#adding-and-removing-clusters) and view information about your existing clusters, such as: @@ -61,6 +61,9 @@ Kubernetes version to any supported version at any time: Some GitLab features may support versions outside the range provided here. +NOTE: +[GKE Cluster creation](add_remove_clusters.md#create-new-cluster) by GitLab is currently not supported for Kubernetes 1.19+. For these versions you can create the cluster through GCP, then [Add existing cluster](add_remove_clusters.md#add-existing-cluster). See [the related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/331922) for more information. + ### Adding and removing clusters See [Adding and removing Kubernetes clusters](add_remove_clusters.md) for details on how @@ -169,14 +172,9 @@ for your deployment jobs to use. Otherwise, a namespace is created for you. #### Important notes -Note the following with GitLab and clusters: - -- If you [install applications](#installing-applications) on your cluster, GitLab will - create the resources required to run these even if you have chosen to manage your own - cluster. -- Be aware that manually managing resources that have been created by GitLab, like - namespaces and service accounts, can cause unexpected errors. If this occurs, try - [clearing the cluster cache](#clearing-the-cluster-cache). +Be aware that manually managing resources that have been created by GitLab, like +namespaces and service accounts, can cause unexpected errors. If this occurs, try +[clearing the cluster cache](#clearing-the-cluster-cache). #### Clearing the cluster cache @@ -189,7 +187,7 @@ your cluster. This can cause deployment jobs to fail. To clear the cache: -1. Navigate to your project's **Operations > Kubernetes** page, and select your cluster. +1. Navigate to your project's **Infrastructure > Kubernetes** page, and select your cluster. 1. Expand the **Advanced settings** section. 1. Click **Clear cluster cache**. @@ -197,19 +195,15 @@ To clear the cache: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24580) in GitLab 11.8. -You do not need to specify a base domain on cluster settings when using GitLab Serverless. The domain in that case -is specified as part of the Knative installation. See [Installing Applications](#installing-applications). - Specifying a base domain automatically sets `KUBE_INGRESS_BASE_DOMAIN` as an deployment variable. If you are using [Auto DevOps](../../../topics/autodevops/index.md), this domain is used for the different stages. For example, Auto Review Apps and Auto Deploy. The domain should have a wildcard DNS configured to the Ingress IP address. -After Ingress has been installed (see [Installing Applications](#installing-applications)), -you can either: +You can either: - Create an `A` record that points to the Ingress IP address with your domain provider. -- Enter a wildcard DNS address using a service such as nip.io or xip.io. For example, `192.168.1.1.xip.io`. +- Enter a wildcard DNS address using a service such as `nip.io` or `xip.io`. For example, `192.168.1.1.xip.io`. To determine the external Ingress IP address, or external Ingress hostname: @@ -259,13 +253,11 @@ This list provides a generic solution, and some GitLab-specific approaches: If you see a trailing `%` on some Kubernetes versions, do not include it. -## Installing applications +## Cluster management project -GitLab can install and manage some applications like Helm, GitLab Runner, Ingress, -Prometheus, and so on, in your project-level cluster. For more information on -installing, upgrading, uninstalling, and troubleshooting applications for -your project cluster, see -[GitLab Managed Apps](../../clusters/applications.md). +Attach a [Cluster management project](../../clusters/management_project.md) +to your cluster to manage shared resources requiring `cluster-admin` privileges for +installation, such as an Ingress controller. ## Auto DevOps @@ -351,16 +343,17 @@ You can customize the deployment namespace in a few ways: When you customize the namespace, existing environments remain linked to their current namespaces until you [clear the cluster cache](#clearing-the-cluster-cache). -WARNING: +#### Protecting credentials + By default, anyone who can create a deployment job can access any CI/CD variable in an environment's deployment job. This includes `KUBECONFIG`, which gives access to any secret available to the associated service account in your cluster. To keep your production credentials safe, consider using [protected environments](../../../ci/environments/protected_environments.md), -combined with either +combined with *one* of the following: -- a GitLab-managed cluster and namespace per environment, -- *or*, an environment-scoped cluster per protected environment. The same cluster +- A GitLab-managed cluster and namespace per environment. +- An environment-scoped cluster per protected environment. The same cluster can be added multiple times with multiple restricted service accounts. ### Integrations @@ -453,6 +446,6 @@ Automatically detect and monitor Kubernetes metrics. Automatic monitoring of > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4701) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/208224) to GitLab Free in 13.2. -When [Prometheus is deployed](#installing-applications), GitLab monitors the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start. +When [the Prometheus cluster integration is enabled](../../clusters/integrations.md#prometheus-cluster-integration), GitLab monitors the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start.  diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index bafb7d472c6..7a9c7eb423d 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4752) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26383) to [GitLab Free](https://about.gitlab.com/pricing/) 12.9. -GitLab makes it easy to view the logs of running pods or managed applications in +GitLab makes it easy to view the logs of running pods in [connected Kubernetes clusters](index.md). By displaying the logs directly in GitLab in the **Log Explorer**, developers can avoid managing console tools or jumping to a different interface. The **Log Explorer** interface provides a set of filters @@ -18,10 +18,11 @@ above the log file data, depending on your configuration:  - **Namespace** - Select the environment to display. Users with Maintainer or - greater [permissions](../../permissions.md) can also select Managed Apps. -- **Search** - Only available if the Elastic Stack managed application is installed. -- **Select time range** - Select the range of time to display. Only available if the - Elastic Stack managed application is installed. + greater [permissions](../../permissions.md) can also see pods in the + `gitlab-managed-apps` namespace. +- **Search** - Only available if the [Elastic Stack integration](../../clusters/integrations.md#elastic-stack-cluster-integration) is enabled. +- **Select time range** - Select the range of time to display. + Only available if the [Elastic Stack integration](../../clusters/integrations.md#elastic-stack-cluster-integration) is enabled. - **Scroll to bottom** **{scroll_down}** - Scroll to the end of the displayed logs. - **Refresh** **{retry}** - Reload the displayed logs. @@ -43,12 +44,11 @@ a [metrics dashboard](../../../operations/metrics/index.md) and select **View lo 1. Sign in as a user with the _View pod logs_ [permissions](../../permissions.md#project-members-permissions) in the project. -1. *To navigate to the **Log Explorer** from the sidebar menu,* go to - **{cloud-gear}** **Operations > Pod logs**. - ([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 12.5.) -1. *To navigate to the **Log Explorer** from a specific pod on a [Deploy Board](../deploy_boards.md):* +1. To navigate to the **Log Explorer** from the sidebar menu, go to **Monitor > Logs** + ([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 12.5.). +1. To navigate to the **Log Explorer** from a specific pod on a [Deploy Board](../deploy_boards.md): - 1. Go to **{cloud-gear}** **Operations > Environments** and find the environment + 1. Go to **Deployments > Environments** and find the environment which contains the desired pod, like `production`. 1. On the **Environments** page, you should see the status of the environment's pods with [Deploy Boards](../deploy_boards.md). @@ -81,7 +81,7 @@ Support for historical data is coming > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197879) in GitLab 12.8. -When you enable [Elastic Stack](../../clusters/applications.md#elastic-stack) +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. @@ -90,7 +90,7 @@ Click **Show last** in the **Log Explorer** to see the available options. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21656) in GitLab 12.7. -When you enable [Elastic Stack](../../clusters/applications.md#elastic-stack) on your cluster, +When you enable [Elastic Stack](../../clusters/integrations.md#elastic-stack-cluster-integration) on your cluster, you can search the content of your logs through a search bar. The search is passed to Elasticsearch using the [simple_query_string](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-simple-query-string-query.html) diff --git a/doc/user/project/clusters/protect/container_host_security/index.md b/doc/user/project/clusters/protect/container_host_security/index.md index 102001d4f87..5e4df6009f0 100644 --- a/doc/user/project/clusters/protect/container_host_security/index.md +++ b/doc/user/project/clusters/protect/container_host_security/index.md @@ -4,7 +4,7 @@ group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Container Host Security +# Container Host Security **(FREE)** Container Host Security in GitLab provides Intrusion Detection and Prevention capabilities that can monitor and (optionally) block activity inside the containers themselves. This is done by leveraging @@ -28,8 +28,8 @@ users define profiles for these technologies. See the [installation guide](quick_start_guide.md) for the recommended steps to install the Container Host Security capabilities. This guide shows the recommended way of installing Container -Host Security through GMAv2. However, it's also possible to do a manual installation through our -Helm chart. +Host Security through the Cluster Management Project. However, it's also possible to do a manual +installation through our Helm chart. ## Features diff --git a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md index fa4a5fb61d0..ebcd56078ae 100644 --- a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md @@ -4,11 +4,9 @@ group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Getting started with Container Host Security +# Getting started with Container Host Security **(FREE)** -The following steps are recommended for installing Container Host Security. Although you can install -some capabilities through GMAv1, we [recommend](#using-gmav1-with-gmav2) that you install -applications through GMAv2 exclusively when using Container Network Security. +The following steps are recommended for installing Container Host Security. ## Installation steps @@ -21,8 +19,7 @@ The following steps are recommended to install and use Container Host Security t 1. Install and configure an Ingress node: - - [Install the Ingress node via CI/CD (GMAv2)](../../../../clusters/applications.md#install-ingress-using-gitlab-cicd). - - [Determine the external endpoint via the manual method](../../../../clusters/applications.md#determining-the-external-endpoint-manually). + - [Install the Ingress node via CI/CD (Cluster Management Project)](../../../../clusters/applications.md#install-ingress-using-gitlab-cicd). - Navigate to the Kubernetes page and enter the [DNS address for the external endpoint](../../index.md#base-domain) into the **Base domain** field on the **Details** tab. Save the changes to the Kubernetes cluster. @@ -63,19 +60,6 @@ initial troubleshooting steps that resolve the most common problems: `kubectl delete namespaces <insert-some-namespace-name>` in your Kubernetes cluster. - Rerun the application project pipeline to redeploy the application. -### Using GMAv1 with GMAv2 - -When GMAv1 and GMAv2 are used together on the same cluster, users may experience problems with -applications being uninstalled or removed from the cluster. This is because GMAv2 actively -uninstalls applications that are installed with GMAv1 and not configured to be installed with GMAv2. -It's possible to use a mixture of applications installed with GMAv1 and GMAv2 by ensuring that the -GMAv1 applications are installed **after** the GMAv2 cluster management project pipeline runs. GMAv1 -applications must be reinstalled after each run of that pipeline. This approach isn't recommended as -it's error-prone and can lead to downtime as applications are uninstalled and later reinstalled. -When using Container Network Security, the preferred and recommended path is to install all -necessary components with GMAv2 and the cluster management project. - **Related documentation links:** -- [GitLab Managed Apps v1 (GMAv1)](../../../../clusters/applications.md#install-with-one-click-deprecated) -- [GitLab Managed Apps v2 (GMAv2)](../../../../clusters/management_project.md) +- [Cluster Management Project](../../../../clusters/management_project.md) diff --git a/doc/user/project/clusters/protect/container_network_security/index.md b/doc/user/project/clusters/protect/container_network_security/index.md index a7cdd73acd7..3daa48e1811 100644 --- a/doc/user/project/clusters/protect/container_network_security/index.md +++ b/doc/user/project/clusters/protect/container_network_security/index.md @@ -4,7 +4,7 @@ group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Container Network Security +# Container Network Security **(FREE)** Container Network Security in GitLab provides basic firewall functionality by leveraging Cilium NetworkPolicies to filter traffic going in and out of the cluster as well as traffic between pods @@ -20,8 +20,8 @@ disabled by default, as they must usually be customized to match application-spe See the [installation guide](quick_start_guide.md) for the recommended steps to install GitLab Container Network Security. This guide shows the recommended way of installing Container Network -Security through GMAv2. However, it's also possible to install Cilium manually through our Helm -chart. +Security through the Cluster Management Project. However, it's also possible to install Cilium +manually through our Helm chart. ## Features diff --git a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md index bf419c69885..33aefec224a 100644 --- a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md @@ -4,11 +4,9 @@ group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Getting started with Container Network Security +# Getting started with Container Network Security **(FREE)** -The following steps are recommended for installing Container Network Security. Although you can -install some capabilities through GMAv1, we [recommend](#using-gmav1-with-gmav2) that you install -applications through GMAv2 exclusively when using Container Network Security. +The following steps are recommended for installing Container Network Security. ## Installation steps @@ -21,8 +19,7 @@ The following steps are recommended to install and use Container Network Securit 1. Install and configure an Ingress node: - - [Install the Ingress node via CI/CD (GMAv2)](../../../../clusters/applications.md#install-ingress-using-gitlab-cicd). - - [Determine the external endpoint via the manual method](../../../../clusters/applications.md#determining-the-external-endpoint-manually). + - [Install the Ingress node via CI/CD (Cluster Management Project)](../../../../clusters/applications.md#install-ingress-using-gitlab-cicd). - Navigate to the Kubernetes page and enter the [DNS address for the external endpoint](../../index.md#base-domain) into the **Base domain** field on the **Details** tab. Save the changes to the Kubernetes cluster. @@ -60,7 +57,7 @@ use both methods simultaneously, when the application project pipeline runs the NetworkPolicy in the `auto-deploy-values.yaml` file may override policies configured in the UI editor. -## Monitoring throughput `**(ULTIMATE)**` +## Monitoring throughput **(ULTIMATE)** To view statistics for Container Network Security, you must follow the installation steps above and configure GitLab integration with Prometheus. Also, if you use custom Helm values for Cilium, you @@ -83,12 +80,8 @@ Additional information about the statistics page is available in the ## Forwarding logs to a SIEM Cilium logs can be forwarded to a SIEM or an external logging system through syslog protocol by -installing and configuring Fluentd. Fluentd can be installed through GitLab in two ways: - -- The [GMAv1 method](../../../../clusters/applications.md#fluentd) -- The [GMAv2 method](../../../../clusters/applications.md#install-fluentd-using-gitlab-cicd) - -GitLab strongly encourages using only the GMAv2 method to install Fluentd. +installing and configuring Fluentd. Fluentd can be installed through the GitLab +[Cluster Management Project](../../../../clusters/applications.md#install-fluentd-using-gitlab-cicd). ## Viewing the logs @@ -135,19 +128,6 @@ initial troubleshooting steps that resolve the most common problems: - Delete the relevant namespace in Kubernetes by running `kubectl delete namespaces <insert-some-namespace-name>` in your Kubernetes cluster. - Rerun the application project pipeline to redeploy the application. -### Using GMAv1 with GMAv2 - -When GMAv1 and GMAv2 are used together on the same cluster, users may experience problems with -applications being uninstalled or removed from the cluster. This is because GMAv2 actively -uninstalls applications that are installed with GMAv1 and not configured to be installed with GMAv2. -It's possible to use a mixture of applications installed with GMAv1 and GMAv2 by ensuring that the -GMAv1 applications are installed **after** the GMAv2 cluster management project pipeline runs. GMAv1 -applications must be reinstalled after each run of that pipeline. This approach isn't recommended as -it's error-prone and can lead to downtime as applications are uninstalled and later reinstalled. -When using Container Network Security, the preferred and recommended path is to install all -necessary components with GMAv2 and the cluster management project. - **Related documentation links:** -- [GitLab Managed Apps v1 (GMAv1)](../../../../clusters/applications.md#install-with-one-click-deprecated) -- [GitLab Managed Apps v2 (GMAv2)](../../../../clusters/management_project.md) +- [Cluster Management Project](../../../../clusters/management_project.md) diff --git a/doc/user/project/clusters/protect/index.md b/doc/user/project/clusters/protect/index.md index c489a0ddd30..1314a1948d5 100644 --- a/doc/user/project/clusters/protect/index.md +++ b/doc/user/project/clusters/protect/index.md @@ -4,7 +4,7 @@ group: Container Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Protecting your deployed applications +# Protecting your deployed applications **(FREE)** GitLab makes it straightforward to protect applications deployed in [connected Kubernetes clusters](index.md). These protections are available in the Kubernetes network layer and in the container itself. At @@ -18,9 +18,6 @@ containers themselves. The following capabilities are available to protect deployed applications in Kubernetes: -- Web Application Firewall - - [Overview](web_application_firewall/index.md) - - [Installation guide](web_application_firewall/quick_start_guide.md) - Container Network Security - [Overview](container_network_security/index.md) - [Installation guide](container_network_security/quick_start_guide.md) diff --git a/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_disabled_settings_v12_10.png b/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_disabled_settings_v12_10.png Binary files differdeleted file mode 100644 index 2dd6df3d37b..00000000000 --- a/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_disabled_settings_v12_10.png +++ /dev/null diff --git a/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_installation_v12_10.png b/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_installation_v12_10.png Binary files differdeleted file mode 100644 index e88f62a2eba..00000000000 --- a/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_installation_v12_10.png +++ /dev/null diff --git a/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_save_changes_v12_10.png b/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_save_changes_v12_10.png Binary files differdeleted file mode 100644 index 1c99d4f7f96..00000000000 --- a/doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_save_changes_v12_10.png +++ /dev/null diff --git a/doc/user/project/clusters/protect/web_application_firewall/index.md b/doc/user/project/clusters/protect/web_application_firewall/index.md deleted file mode 100644 index 6e2e71c6ced..00000000000 --- a/doc/user/project/clusters/protect/web_application_firewall/index.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -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 ---- - -# Web Application Firewall - -WARNING: -The Web Application Firewall is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/271276) -in GitLab 13.6, and planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/271349) -in GitLab 14.0. - -A web application firewall (or WAF) filters, monitors, and blocks HTTP traffic to -and from a web application. By inspecting HTTP traffic, it can prevent attacks -stemming from web application security flaws. It can be used to detect SQL injection, -Cross-Site Scripting (XSS), Remote File Inclusion, Security Misconfigurations, and -much more. - -## Overview - -GitLab provides a WAF out of the box after Ingress is deployed. All you need to do is deploy your -application along with a service and Ingress resource. In the GitLab [Ingress](../../../../clusters/applications.md#ingress) -deployment, the [ModSecurity](https://modsecurity.org/) -module is loaded into Ingress-NGINX by default and monitors the traffic to the applications -which have an Ingress. The ModSecurity module runs with the [OWASP Core Rule Set (CRS)](https://coreruleset.org/) -by default. The OWASP CRS detects and logs a wide range of common attacks. - -By default, the WAF is deployed in Detection-only mode and only logs attack attempts. - -## Requirements - -The Web Application Firewall requires: - -- **Kubernetes** - - To enable the WAF, you need: - - - Kubernetes 1.12+. - - A load balancer. You can use NGINX-Ingress by deploying it to your - Kubernetes cluster by either: - - Using the [`nginx-ingress` Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). - - Installing the [Ingress GitLab Managed App](../../../../clusters/applications.md#ingress) with WAF enabled. - -- **Configured Kubernetes objects** - - To use the WAF on an application, you need to deploy the following Kubernetes resources: - - - [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) - - [Service](https://kubernetes.io/docs/concepts/services-networking/service/) - - [Ingress Resource](https://kubernetes.io/docs/concepts/services-networking/ingress/) - -## Quick start - -If you are using GitLab.com, see the [quick start guide](quick_start_guide.md) for -how to use the WAF with GitLab.com and a Kubernetes cluster on Google Kubernetes Engine (GKE). - -If you are using a self-managed instance of GitLab, you must configure the -[Google OAuth2 OmniAuth Provider](../../../../../integration/google.md) before -you can configure a cluster on GKE. Once this is set up, you can follow the steps on the -[quick start guide](quick_start_guide.md) -to get started. - -NOTE: -This guide shows how the WAF can be deployed using Auto DevOps. The WAF -is available by default to all applications no matter how they are deployed, -as long as they are using Ingress. - -## Network firewall vs. Web Application Firewall - -A network firewall or packet filter looks at traffic at the Network (L3) and Transport (L4) layers -of the [OSI Model](https://en.wikipedia.org/wiki/OSI_model), and denies packets from entry based on -a set of rules regarding the network in general. - -A Web Application Firewall operates at the Application (L7) layer of the OSI Model and can -examine all the packets traveling to and from a specific application. A WAF can set -more advanced rules around threat detection. - -## Features - -ModSecurity is enabled with the [OWASP Core Rule Set (CRS)](https://github.com/coreruleset/coreruleset/) by -default. The OWASP CRS logs attempts to the following attacks: - -- [SQL Injection](https://wiki.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_SQL_Injection) -- [Cross-Site Scripting](https://wiki.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_Cross-Site_Scripting_(XSS)) -- [Local File Inclusion](https://wiki.owasp.org/index.php/Testing_for_Local_File_Inclusion) -- [Remote File Inclusion](https://wiki.owasp.org/index.php/OWASP_Periodic_Table_of_Vulnerabilities_-_Remote_File_Inclusion) -- [Code Injection](https://wiki.owasp.org/index.php/Code_Injection) -- [Session Fixation](https://wiki.owasp.org/index.php/Session_fixation) -- [Scanner Detection](https://wiki.owasp.org/index.php/Category:Vulnerability_Scanning_Tools) -- [Metadata/Error Leakages](https://wiki.owasp.org/index.php/Improper_Error_Handling) - -It is good to have a basic knowledge of the following: - -- [Kubernetes](https://kubernetes.io/docs/home/) -- [Ingress](https://kubernetes.github.io/ingress-nginx/) -- [ModSecurity](https://www.modsecurity.org/) -- [OWASP Core Rule Set](https://github.com/coreruleset/coreruleset/) - -## Roadmap - -You can find more information on the product direction of the WAF in -[Category Direction - Web Application Firewall](https://about.gitlab.com/direction/protect/web_application_firewall/). diff --git a/doc/user/project/clusters/protect/web_application_firewall/quick_start_guide.md b/doc/user/project/clusters/protect/web_application_firewall/quick_start_guide.md deleted file mode 100644 index e7d8d591510..00000000000 --- a/doc/user/project/clusters/protect/web_application_firewall/quick_start_guide.md +++ /dev/null @@ -1,265 +0,0 @@ ---- -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 ---- - -# Getting started with the Web Application Firewall - -WARNING: -The Web Application Firewall is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/271276) -in GitLab 13.6, and planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/271349) -in GitLab 14.0. - -This is a step-by-step guide to help you use the GitLab [Web Application Firewall](index.md) after -deploying a project hosted on GitLab.com to Google Kubernetes Engine using [Auto DevOps](../../../../../topics/autodevops/index.md). - -The GitLab native Kubernetes integration is used, so you do not need -to create a Kubernetes cluster manually using the Google Cloud Platform console. -A simple application is created and deployed based on a GitLab template. - -These instructions also work for a self-managed GitLab instance. However, you -need to ensure your own [runners are configured](../../../../../ci/runners/README.md) and -[Google OAuth is enabled](../../../../../integration/google.md). - -The GitLab Web Application Firewall is deployed with [Ingress](../../../../clusters/applications.md#ingress), -so it is available to your applications no matter how you deploy them to Kubernetes. - -## Configuring your Google account - -Before creating and connecting your Kubernetes cluster to your GitLab project, -you need a Google Cloud Platform account. If you do not already have one, -sign up at <https://console.cloud.google.com>. You need to either sign in with an existing -Google account (for example, one that you use to access Gmail, Drive, etc.) or create a new one. - -1. To enable the required APIs and related services, follow the steps in the ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin). -1. Make sure you have created a [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account). - -NOTE: -Every new Google Cloud Platform (GCP) account receives [$300 in credit](https://console.cloud.google.com/freetrial), -and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with the GitLab -Google Kubernetes Engine integration. All you have to do is [follow this link](https://cloud.google.com/partners/partnercredit/?PCN=a0n60000006Vpz4AAC) and apply for credit. - -## Creating a new project from a template - -We use a GitLab project templates to get started. As the name suggests, -those projects provide a bare-bones application built on some well-known frameworks. - -1. In GitLab, click the plus icon (**+**) at the top of the navigation bar and select - **New project**. -1. Go to the **Create from template** tab where you can choose for example a Ruby on - Rails, Spring, or NodeJS Express project. - Use the Ruby on Rails template. - -  - -1. Give your project a name, optionally a description, and make it public so that - you can take advantage of the features available in the - [GitLab Ultimate plan](https://about.gitlab.com/pricing/). - -  - -1. Click **Create project**. - -Now that the project is created, the next step is to create the Kubernetes cluster -to deploy this application under. - -## Creating a Kubernetes cluster from within GitLab - -1. On the project's landing page, click **Add Kubernetes cluster** - (note that this option is also available when you navigate to **Operations > Kubernetes**). - -  - -1. On the **Create new cluster on GKE** tab, click **Sign in with Google**. - -  - -1. Connect with your Google account and click **Allow** when asked (this - appears only the first time you connect GitLab with your Google account). - -  - -1. The last step is to provide the cluster details. - 1. Give it a name, leave the environment scope as is, and choose the GCP project under which to create the cluster. - (Per the instructions to [configure your Google account](#configuring-your-google-account), a project should have already been created for you.) - 1. Choose the [region/zone](https://cloud.google.com/compute/docs/regions-zones/) to create the cluster in. - 1. Enter the number of nodes you want it to have. - 1. Choose the [machine type](https://cloud.google.com/compute/docs/machine-types). - -  - -1. Click **Create Kubernetes cluster**. - -After a couple of minutes, the cluster is created. You can also see its -status on your [GCP dashboard](https://console.cloud.google.com/kubernetes). - -The next step is to install some applications on your cluster that are needed -to take full advantage of Auto DevOps. - -## Install Ingress - -The GitLab Kubernetes integration comes with some -[pre-defined applications](../../index.md#installing-applications) -for you to install. - - - -For this guide, we need to install Ingress. Ingress provides load balancing, -SSL termination, and name-based virtual hosting, using NGINX behind -the scenes. Make sure to switch the toggle to the enabled position before installing. - -Both logging and blocking modes are available for WAF. While logging mode is useful for -auditing anomalous traffic, blocking mode ensures the traffic doesn't reach past Ingress. - - - -After Ingress is installed, wait a few seconds and copy the IP address that -is displayed in order to add in your base **Domain** at the top of the page. For -the purpose of this guide, we use the one suggested by GitLab. Once you have -filled in the domain, click **Save changes**. - - - -Prometheus should also be installed. It is an open-source monitoring and -alerting system that is used to supervise the deployed application. -Installing GitLab Runner is not required as we use the shared runners that -GitLab.com provides. - -## Enabling Auto DevOps (optional) - -Starting with GitLab 11.3, Auto DevOps is enabled by default. However, it is possible to disable -Auto DevOps at both the instance-level (for self-managed instances) and the group-level. -Follow these steps if Auto DevOps has been manually disabled: - -1. Navigate to **Settings > CI/CD > Auto DevOps**. -1. Select **Default to Auto DevOps pipeline**. -1. Select the [continuous deployment strategy](../../../../../topics/autodevops/index.md#deployment-strategy) - which automatically deploys the application to production once the pipeline - successfully runs on the `master` branch. -1. Click **Save changes**. - -  - -Once you complete all the above and save your changes, a new pipeline is -automatically created. To view the pipeline, go to **CI/CD > Pipelines**. - - - -The next section explains what each pipeline job does. - -## Deploying the application - -By now you should see the pipeline running, but what is it running exactly? - -To navigate inside the pipeline, click its status badge (its status should be "Running"). -The pipeline is split into a few stages, each running a couple of jobs. - - - -In the **build** stage, the application is built into a Docker image and then -uploaded to your project's [Container Registry](../../../../packages/container_registry/index.md) -([Auto Build](../../../../../topics/autodevops/stages.md#auto-build)). - -In the **test** stage, GitLab runs various checks on the application. - -The **production** stage is run after the tests and checks finish, and it automatically -deploys the application in Kubernetes ([Auto Deploy](../../../../../topics/autodevops/stages.md#auto-deploy)). - -The **production** stage creates Kubernetes objects -like a Deployment, Service, and Ingress resource. The -application is monitored by the WAF automatically. - -## Validating Ingress is running ModSecurity - -Now we can make sure that Ingress is running properly with ModSecurity and send -a request to ensure our application is responding correctly. You must connect to -your cluster either using [Cloud Shell](https://cloud.google.com/shell/) or the [Google Cloud SDK](https://cloud.google.com/sdk/docs/install). - -1. After connecting to your cluster, check if the Ingress-NGINX controller is running and ModSecurity is enabled. - - This is done by running the following commands: - - ```shell - $ kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' - ingress-nginx-ingress-controller-55f9cf6584-dxljn 2/2 Running - - $ kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- cat /etc/nginx/nginx.conf | grep 'modsecurity on;' - modsecurity on; - ``` - -1. Verify the Rails application has been installed properly. - - ```shell - $ kubectl get ns - auto-devv-2-16730183-production Active - - $ kubectl get pods -n auto-devv-2-16730183-production - NAME READY STATUS RESTARTS - production-5778cfcfcd-nqjcm 1/1 Running 0 - production-postgres-6449f8cc98-r7xgg 1/1 Running 0 - ``` - -1. To make sure the Rails application is responding, send a request to it by running: - - ```shell - $ kubectl get ing -n auto-devv-2-16730183-production - NAME HOSTS PORTS - production-auto-deploy fjdiaz-auto-devv-2.34.68.60.207.nip.io,le-16730183.34.68.60.207.nip.io 80, 443 - - $ curl --location --insecure "fjdiaz-auto-devv-2.34.68.60.207.nip.io" | grep 'Rails!' --after 2 --before 2 - <body> - <p>You're on Rails!</p> - </body> - ``` - -Now that we have confirmed our system is properly setup, we can go ahead and test -the WAF with OWASP CRS! - -## Testing out the OWASP Core Rule Set - -Now let's send a potentially malicious request, as if we were a scanner, -checking for vulnerabilities within our application and examine the ModSecurity logs: - -```shell -$ curl --location --insecure "fjdiaz-auto-devv-2.34.68.60.207.nip.io" --header "User-Agent: absinthe" | grep 'Rails!' --after 2 --before 2 -<body> - <p>You're on Rails!</p> -</body> - -$ kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- cat /var/log/modsec/audit.log | grep 'absinthe' -{ - "message": "Found User-Agent associated with security scanner", - "details": { - "match": "Matched \"Operator `PmFromFile' with parameter `scanners-user-agents.data' against variable `REQUEST_HEADERS:user-agent' (Value: `absinthe' )", - "reference": "o0,8v84,8t:lowercase", - "ruleId": "913100", - "file": "/etc/nginx/owasp-modsecurity-crs/rules/REQUEST-913-SCANNER-DETECTION.conf", - "lineNumber": "33", - "data": "Matched Data: absinthe found within REQUEST_HEADERS:user-agent: absinthe", - "severity": "2", - "ver": "OWASP_CRS/3.2.0", - "rev": "", - "tags": ["application-multi", "language-multi", "platform-multi", "attack-reputation-scanner", "OWASP_CRS", "OWASP_CRS/AUTOMATION/SECURITY_SCANNER", "WASCTC/WASC-21", "OWASP_TOP_10/A7", "PCI/6.5.10"], - "maturity": "0", - "accuracy": "0" - } -} -``` - -You can see that ModSecurity logs the suspicious behavior. By sending a request -with the `User Agent: absinthe` header, which [absinthe](https://github.com/cameronhotchkies/Absinthe), -a tool for testing for SQL injections uses, we can detect that someone was -searching for vulnerabilities on our system. Detecting scanners is useful, because we -can learn if someone is trying to exploit our system. - -## Conclusion - -You can now see the benefits of a using a Web Application Firewall. -ModSecurity and the OWASP Core Rule Set, offer many more benefits. -You can explore them in more detail: - -- [Category Direction - Web Application Firewall](https://about.gitlab.com/direction/protect/web_application_firewall/) -- [ModSecurity](https://www.modsecurity.org/) -- [OWASP Core Rule Set](https://github.com/coreruleset/coreruleset/) -- [AutoDevOps](../../../../../topics/autodevops/index.md) diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index e0b8c074fcf..b2054c4befb 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -63,18 +63,93 @@ information. Follow this step-by-step guide to configure an executable runbook in GitLab using the components outlined above and the pre-loaded demo runbook. -1. Add a Kubernetes cluster to your project by following the steps outlined in - [Create new cluster](../add_remove_clusters.md#create-new-cluster). - -1. Click the **Install** button next to the **Ingress** application to install Ingress. - -  - -1. After Ingress has been installed successfully, click the **Install** button next - to the **JupyterHub** application. You need the **Jupyter Hostname** provided - here in the next step. - -  +1. Create an [OAuth Application for JupyterHub](../../../../integration/oauth_provider.md#gitlab-as-oauth2-authentication-service-provider). +1. When [installing JupyterHub with Helm](https://zero-to-jupyterhub.readthedocs.io/en/latest/jupyterhub/installation.html), use the following values + + ```yaml + #----------------------------------------------------------------------------- + # The gitlab and ingress sections must be customized! + #----------------------------------------------------------------------------- + + gitlab: + clientId: <Your OAuth Application ID> + clientSecret: <Your OAuth Application Secret> + callbackUrl: http://<Jupyter Hostname>/hub/oauth_callback, + # Limit access to members of specific projects or groups: + # allowedGitlabGroups: [ "my-group-1", "my-group-2" ] + # allowedProjectIds: [ 12345, 6789 ] + + # ingress is required for OAuth to work + ingress: + enabled: true + host: <JupyterHostname> + # tls: + # - hosts: + # - <JupyterHostanme> + # secretName: jupyter-cert + # annotations: + # kubernetes.io/ingress.class: "nginx" + # kubernetes.io/tls-acme: "true" + + #----------------------------------------------------------------------------- + # NO MODIFICATIONS REQUIRED BEYOND THIS POINT + #----------------------------------------------------------------------------- + + hub: + extraEnv: + JUPYTER_ENABLE_LAB: 1 + extraConfig: | + c.KubeSpawner.cmd = ['jupyter-labhub'] + c.GitLabOAuthenticator.scope = ['api read_repository write_repository'] + + async def add_auth_env(spawner): + ''' + We set user's id, login and access token on single user image to + enable repository integration for JupyterHub. + See: https://gitlab.com/gitlab-org/gitlab-foss/issues/47138#note_154294790 + ''' + auth_state = await spawner.user.get_auth_state() + + if not auth_state: + spawner.log.warning("No auth state for %s", spawner.user) + return + + spawner.environment['GITLAB_ACCESS_TOKEN'] = auth_state['access_token'] + spawner.environment['GITLAB_USER_LOGIN'] = auth_state['gitlab_user']['username'] + spawner.environment['GITLAB_USER_ID'] = str(auth_state['gitlab_user']['id']) + spawner.environment['GITLAB_USER_EMAIL'] = auth_state['gitlab_user']['email'] + spawner.environment['GITLAB_USER_NAME'] = auth_state['gitlab_user']['name'] + + c.KubeSpawner.pre_spawn_hook = add_auth_env + + auth: + type: gitlab + state: + enabled: true + + singleuser: + defaultUrl: "/lab" + image: + name: registry.gitlab.com/gitlab-org/jupyterhub-user-image + tag: latest + lifecycleHooks: + postStart: + exec: + command: + - "sh" + - "-c" + - > + git clone https://gitlab.com/gitlab-org/nurtch-demo.git DevOps-Runbook-Demo || true; + echo "https://oauth2:${GITLAB_ACCESS_TOKEN}@${GITLAB_HOST}" > ~/.git-credentials; + git config --global credential.helper store; + git config --global user.email "${GITLAB_USER_EMAIL}"; + git config --global user.name "${GITLAB_USER_NAME}"; + jupyter serverextension enable --py jupyterlab_git + + proxy: + service: + type: ClusterIP + ``` 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 diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index e355b562c36..e4ac1eabffe 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -15,7 +15,7 @@ Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/git Serverless architectures offer Operators and Developers the ability write highly scalable applications without provisioning a single server. -GitLab supports several ways deploy Serverless applications in both Kubernetes Environments and also major cloud FAAS environments. +GitLab supports several ways deploy Serverless applications in both Kubernetes Environments and also major cloud Function as a Service (FaaS) environments. Currently we support: @@ -35,7 +35,7 @@ of the box through its main components: For more information on Knative, visit the [Knative docs repository](https://github.com/knative/docs). -With GitLab Serverless, you can deploy both functions-as-a-service (FaaS) and serverless applications. +With GitLab Serverless, you can deploy both FaaS and serverless applications. ## Prerequisites @@ -53,7 +53,7 @@ To run Knative on GitLab, you need: The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory. 1. **GitLab Runner:** A runner is required to run the CI jobs that deploy serverless applications or functions onto your cluster. You can install GitLab Runner - onto the existing Kubernetes cluster. See [Installing Applications](../index.md#installing-applications) for more information. + onto the [existing Kubernetes cluster](https://docs.gitlab.com/runner/install/kubernetes.html). 1. **Domain Name:** Knative provides its own load balancer using Istio, and an external IP address or hostname for all the applications served by Knative. Enter a wildcard domain to serve your applications. Configure your DNS server to use the @@ -68,54 +68,18 @@ To run Knative on GitLab, you need: `Dockerfile` in order to build your applications. It should be included at the root of your project's repository and expose port `8080`. `Dockerfile` is not require if you plan to build serverless functions using our [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes). -1. **Prometheus** (optional): Installing Prometheus allows you to monitor the scale and traffic of your serverless function/application. - See [Installing Applications](../index.md#installing-applications) for more information. +1. **Prometheus** (optional): The [Prometheus cluster integration](../../../clusters/integrations.md#prometheus-cluster-integration) + allows you to monitor the scale and traffic of your serverless function/application. 1. **Logging** (optional): Configuring logging allows you to view and search request logs for your serverless function/application. See [Configuring logging](#configuring-logging) for more information. -## Installing Knative via the GitLab Kubernetes integration - -The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB -memory. **RBAC must be enabled.** - -1. [Add a Kubernetes cluster](../add_remove_clusters.md). -1. Select the **Applications** tab and scroll down to the Knative app section. Enter the domain to be used with - your application/functions (e.g. `example.com`) and click **Install**. - -  - -1. After the Knative installation has finished, you can wait for the IP address or hostname to be displayed in the - **Knative Endpoint** field or [retrieve the Istio Ingress Endpoint manually](../../../clusters/applications.md#determining-the-external-endpoint-manually). - - NOTE: - Running `kubectl` commands on your cluster requires setting up access to the cluster first. - For clusters created on GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl), - for other platforms [Install kubectl](https://kubernetes.io/docs/tasks/tools/). - -1. The Ingress is now available at this address and routes incoming requests to the proper service based on the DNS - name in the request. To support this, a wildcard DNS record should be created for the desired domain name. For example, - if your Knative base domain is `knative.info` then you need to create an A record or CNAME record with domain `*.knative.info` - pointing the IP address or hostname of the Ingress. - -  - -You can deploy either [functions](#deploying-functions) or [serverless applications](#deploying-serverless-applications) -on a given project, but not both. The current implementation makes use of a -`serverless.yml` file to signal a FaaS project. - -## Using an existing installation of Knative +## Configuring Knative > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58941) in GitLab 12.0. -The _invocations_ monitoring feature of GitLab serverless is unavailable when -adding an existing installation of Knative. - -It's also possible to use GitLab Serverless with an existing Kubernetes cluster -which already has Knative installed. You must do the following: - 1. Follow the steps to - [add an existing Kubernetes - cluster](../add_remove_clusters.md#add-existing-cluster). + [add a Kubernetes + cluster](../add_remove_clusters.md). 1. Ensure GitLab can manage Knative: - For a non-GitLab managed cluster, ensure that the service account for the token @@ -164,13 +128,17 @@ which already has Knative installed. You must do the following: kubectl apply -f knative-serving-only-role.yaml ``` - If you would rather grant permissions on a per service account basis, you can do this - using a `Role` and `RoleBinding` specific to the service account and namespace. + Alternatively, permissions can be granted on a per-service account basis + using `Role`s and `RoleBinding`s (see the [Kubernetes RBAC + documentation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) + for more information). 1. Follow the steps to deploy [functions](#deploying-functions) or [serverless applications](#deploying-serverless-applications) onto your cluster. +1. **Optional:** For invocation metrics to show in GitLab, additional Istio metrics need to be configured in your cluster. For example, with Knative v0.9.0, you can use [this manifest](https://gitlab.com/gitlab-org/charts/knative/-/raw/v0.10.0/vendor/istio-metrics.yml). + ## Supported runtimes Serverless functions for GitLab can be run using: @@ -183,7 +151,7 @@ If a runtime is not available for the required programming language, consider de ### GitLab-managed runtimes -Currently the following GitLab-managed [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes) +The following GitLab-managed [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes) are available: - `go` (proof of concept) @@ -352,7 +320,7 @@ After the `gitlab-ci.yml` template has been added and the `serverless.yml` file has been created, pushing a commit to your project results in a CI pipeline being executed which deploys each function as a Knative service. After the deploy stage has finished, additional details for the function display -under **Operations > Serverless**. +under **Infrastructure > Serverless platform**.  @@ -486,7 +454,7 @@ With all the pieces in place, the next time a CI pipeline runs the Knative appli ### Function details -Go to the **Operations > Serverless** page to see the final URL of your functions. +Go to the **Infrastructure > Serverless platform** page to see the final URL of your functions.  @@ -499,10 +467,10 @@ rows to bring up the function details page. The pod count gives you the number of pods running the serverless function instances on a given cluster. -For the Knative function invocations to appear, -[Prometheus must be installed](../index.md#installing-applications). +For the Knative function invocations to appear, the +[Prometheus cluster integration must be enabled](../../../clusters/integrations.md#prometheus-cluster-integration). -Once Prometheus is installed, a message may appear indicating that the metrics data _is +Once Prometheus is enabled, a message may appear indicating that the metrics data _is loading or is not available at this time._ It appears upon the first access of the page, but should go away after a few seconds. If the message does not disappear, then it is possible that GitLab is unable to connect to the Prometheus instance running on the @@ -611,7 +579,7 @@ or with other versions of Python. Where `<namespace>` is the namespace created by GitLab for your serverless project (composed of `<project_name>-<project_id>-<environment>`) and `example.com` is the domain being used for your project. If you are unsure what the namespace of your project is, navigate - to the **Operations > Serverless** page of your project and inspect + to the **Infrastructure > Serverless platform** page of your project and inspect the endpoint provided for your function/app.  diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 804c013d317..89c82d4dc6f 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -117,7 +117,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 **Operations > Environments**. +navigate to the environments page under **Deployments > Environments**. Deploy Boards are visible by default. You can explicitly click the triangle next to their respective environment name in order to hide them. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index a6b54474a9e..c0bc97781b6 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -28,7 +28,7 @@ repository in automation, it's a simple solution. A drawback is that your repository could become vulnerable if a remote machine is compromised by a hacker. You should limit access to the remote machine before a deploy key is enabled on your repository. A good rule to follow is to provide access only to trusted users, -and make sure that the allowed users have [maintainer permissions or higher](../../permissions.md) +and make sure that the allowed users have the [Maintainer role or higher](../../permissions.md) in the GitLab project. If this security implication is a concern for your organization, diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index e2fa63ce519..800aa27f612 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -190,4 +190,4 @@ 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, use the workaround in [issue 214014](https://gitlab.com/gitlab-org/gitlab/-/issues/214014). +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. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 4a2bd56b7ba..d2897c7310e 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -106,11 +106,7 @@ instance or the project's parent groups. ### Set instance-level description templates **(PREMIUM SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. -> - [Deployed behind a feature flag](../feature_flags.md), disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56737) in GitLab 13.11. -> - Enabled by default on GitLab.com. -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-issue-and-merge-request-description-templates-at-group-and-instance-level). **(PREMIUM SELF)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321247) in GitLab 14.0. You can set a description template at the **instance level** for issues and merge requests. @@ -132,11 +128,7 @@ Learn more about [instance template repository](../admin_area/settings/instance_ ### Set group-level description templates **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. -> - [Deployed behind a feature flag](../feature_flags.md), disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56737) in GitLab 13.11. -> - Enabled by default on GitLab.com. -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-issue-and-merge-request-description-templates-at-group-and-instance-level). **(PREMIUM SELF)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321247) in GitLab 14.0. With **group-level** description templates, you can store your templates in a single repository and configure the group file templates setting to point to that repository. @@ -184,7 +176,7 @@ provide `issues_template` and `merge_requests_template` attributes in the ## Description template example We use description templates for issues and merge requests in the -[`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/tree/master/.gitlab) of the +[`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/-/tree/master/.gitlab) of the GitLab project, which you can refer to for some examples. NOTE: @@ -231,28 +223,3 @@ it's very hard to read otherwise.) /cc @project-manager /assign @qa-tester ``` - -## Enable or disable issue and merge request description templates at group and instance level **(PREMIUM SELF)** - -Setting issue and merge request description templates at group and instance levels -is under development but ready for production use. It is deployed behind a -feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can disable it. - -To disable it: - -```ruby -Feature.disable(:inherited_issuable_templates) -``` - -To enable it: - -```ruby -Feature.enable(:inherited_issuable_templates) -``` - -The feature flag affects these features: - -- Setting a templates project as issue and merge request description templates source at group level. -- Setting a templates project as issue and merge request description templates source at instance level. diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 576de63d00d..eb963cb74c5 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -80,7 +80,7 @@ Check this document to learn more about [using Git LFS](../../topics/git/lfs/ind ### Configure Exclusive File Locks -You need [Maintainer permissions](../permissions.md) to configure +You need the [Maintainer role](../permissions.md) to configure Exclusive File Locks for your project through the command line. The first thing to do before using File Locking is to tell Git LFS which @@ -201,8 +201,8 @@ This process allows you to lock one file at a time through the GitLab UI and requires access to [GitLab Premium](https://about.gitlab.com/pricing/) or higher tiers. -Default branch file and directory locks only apply to the default branch set in -the project's settings (usually `master`). +Default branch file and directory locks only apply to the +[default branch](repository/branches/default.md) set in the project's settings. Changes to locked files on the default branch are blocked, including merge requests that modify locked files. Unlock the file to allow changes. @@ -226,6 +226,6 @@ who locked the file. The **Locked Files**, accessed from **Project > Repository** left menu, lists all file and directory locks. Locks can be removed by their author, or any user -with Maintainer permissions and above. +with the [Maintainer role](../permissions.md) and above. This list shows all the files locked either through LFS or GitLab UI. diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index 2e5713e10be..aa8cf4549e2 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -45,7 +45,7 @@ To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shen ``` Please note that these configurations only take effect when the `.gitattributes` -file is in your default branch (usually `master`). +file is in your [default branch](repository/branches/default.md). NOTE: The Web IDE does not support `.gitattribute` files, but it's [planned for a future release](https://gitlab.com/gitlab-org/gitlab/-/issues/22014). diff --git a/doc/user/project/img/code_owners_approval_new_protected_branch_v13_10.png b/doc/user/project/img/code_owners_approval_new_protected_branch_v13_10.png Binary files differdeleted file mode 100644 index ee4ee2c6d71..00000000000 --- a/doc/user/project/img/code_owners_approval_new_protected_branch_v13_10.png +++ /dev/null diff --git a/doc/user/project/img/code_owners_approval_protected_branch_v13_10.png b/doc/user/project/img/code_owners_approval_protected_branch_v13_10.png Binary files differdeleted file mode 100644 index 220eb207132..00000000000 --- a/doc/user/project/img/code_owners_approval_protected_branch_v13_10.png +++ /dev/null diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index e77932c6427..802eb3efc51 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -5,7 +5,7 @@ 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 --- -# Import your project from Bitbucket Cloud to GitLab +# Import your project from Bitbucket Cloud to GitLab **(FREE)** NOTE: The Bitbucket Cloud importer works only with Bitbucket.org, not with Bitbucket diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 1e79107d76f..963b9f524ff 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -5,7 +5,7 @@ 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 --- -# Import your project from Bitbucket Server to GitLab +# Import your project from Bitbucket Server to GitLab **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20164) in GitLab 11.2. diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index 7e07ca6f865..27a84476590 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Migrating from ClearCase +# Migrating from ClearCase **(FREE)** [ClearCase](https://www.ibm.com/products/rational-clearcase) is a set of tools developed by IBM which also include a centralized version control system diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index 61d4d29aa4d..55c5feff1f0 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Migrating from CVS +# Migrating from CVS **(FREE)** [CVS](https://savannah.nongnu.org/projects/cvs) is an old centralized version control system similar to [SVN](svn.md). diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 09505d94a8c..d3d77f16200 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -5,7 +5,7 @@ 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 --- -# Import your project from FogBugz to GitLab +# Import your project from FogBugz to GitLab **(FREE)** It only takes a few simple steps to import your project from FogBugz. The importer imports all your cases and comments with original case diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md index 5a4b16d57f5..37460da1289 100644 --- a/doc/user/project/import/gemnasium.md +++ b/doc/user/project/import/gemnasium.md @@ -1,5 +1,6 @@ --- redirect_to: 'index.md' +remove_date: '2021-08-15' --- This document was deleted. diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 41141902468..9364ac4f954 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -5,7 +5,7 @@ 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 --- -# Import your project from Gitea to GitLab +# Import your project from Gitea to GitLab **(FREE)** Import your projects from Gitea to GitLab with minimal effort. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index c8b973b673e..99b3e1acdcf 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -5,7 +5,7 @@ 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 --- -# Import your project from GitHub to GitLab +# Import your project from GitHub to GitLab **(FREE)** Using the importer, you can import your GitHub repositories to GitLab.com or to your self-managed GitLab instance. diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index 9e63b1cb617..f7eb5e43a79 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Project importing from GitLab.com to your private GitLab instance +# Project importing from GitLab.com to your private GitLab instance **(FREE)** You can import your existing GitLab.com projects to your GitLab instance, but keep in mind that it is possible only if GitLab.com integration is enabled on your GitLab instance. diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 3728a486070..05fd04f6e48 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -5,7 +5,7 @@ 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 projects to a GitLab instance +# Migrate projects to a GitLab instance **(FREE)** See these documents to migrate to GitLab: diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index 94eba319a17..131732d2bae 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -5,7 +5,7 @@ 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 --- -# Import multiple repositories by uploading a manifest file +# Import multiple repositories by uploading a manifest file **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28811) in GitLab 11.2. diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index 8040eb07c93..f3843396b79 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Migrating from Perforce Helix +# Migrating from Perforce Helix **(FREE)** [Perforce Helix](https://www.perforce.com/) provides a set of tools which also include a centralized, proprietary version control system similar to Git. diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index 30a63a72cf9..6a1370f3301 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -5,7 +5,7 @@ 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 --- -# Import Phabricator tasks into a GitLab project +# Import Phabricator tasks into a GitLab project **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/60562) in GitLab 12.0. diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 3ff612c51a7..e504f3678a7 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -5,7 +5,7 @@ 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 --- -# Import project from repository by URL +# Import project from repository by URL **(FREE)** You can import your existing repositories by providing the Git URL: diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index e39976e00f6..b88abf91ae1 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -5,7 +5,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Migrating from SVN to GitLab +# Migrating from SVN to GitLab **(FREE)** Subversion (SVN) is a central version control system (VCS) while Git is a distributed version control system. There are some major differences @@ -112,6 +112,10 @@ contact the SubGit team directly at [support@subgit.com](mailto:support@subgit.c ## Cut over migration with svn2git +NOTE: +Any issues with svn2git should be directed to the [relevant project and maintainer](https://github.com/nirvdrum/svn2git). +Check for existing issues and history for update frequency. + If you are currently using an SVN repository, you can migrate the repository to Git and GitLab. We recommend a hard cut over - run the migration command once and then have all developers start using the new GitLab repository immediately. diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md index 705df686fe0..910be690d0b 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -1,11 +1,11 @@ --- -stage: none -group: unassigned +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 type: concepts --- -# Migrate from TFVC to Git +# Migrate from TFVC to Git **(FREE)** Team Foundation Server (TFS), renamed [Azure DevOps Server](https://azure.microsoft.com/en-us/services/devops/server/) in 2019, is a set of tools developed by Microsoft which also includes diff --git a/doc/user/project/index.md b/doc/user/project/index.md index d9283f623d4..0dcbf997452 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Projects **(FREE)** +# Organize work with projects **(FREE)** In GitLab, you can create projects to host your codebase. You can also use projects to track issues, plan work, @@ -97,7 +97,7 @@ Projects include the following [features](https://about.gitlab.com/features/): - [Security Dashboard](../application_security/security_dashboard/index.md) **(ULTIMATE)** - [Syntax highlighting](highlighting.md): Customize your code blocks, overriding the default language choice. -- [Badges](badges.md): Add an image to the project overview. +- [Badges](badges.md): Add an image to the **Project information** page. - [Releases](releases/index.md): Take a snapshot of the source, build output, metadata, and artifacts associated with a released version of your code. diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index ef8c9d59132..ac70c7e4b4e 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -25,7 +25,7 @@ The simplest way to enable the GitLab Slack application for your workspace is to install the [GitLab application](https://slack-platform.slack.com/apps/A676ADMV5-gitlab) from the [Slack App Directory](https://slack.com/apps). -Clicking install takes you to the [GitLab Slack application landing page](https://gitlab.com/profile/slack/edit) +Clicking install takes you to the [GitLab Slack application landing page](https://gitlab.com/-/profile/slack/edit) where you can select a project to enable the GitLab Slack application for.  diff --git a/doc/user/project/integrations/hipchat.md b/doc/user/project/integrations/hipchat.md deleted file mode 100644 index 63772936fd4..00000000000 --- a/doc/user/project/integrations/hipchat.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -redirect_to: 'index.md' ---- - -This document was moved to [another location](index.md). -<!-- This redirect file can be deleted after 2021-06-30. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index c7772ac2238..f9e15ced858 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can find the available integrations under your project's **Settings > Integrations** page. You need to have at least -[maintainer permission](../../permissions.md) on the project. +the [Maintainer role](../../permissions.md) on the project. ## Integrations diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index b91a8a1fb3b..521f15f330e 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -1,5 +1,6 @@ --- redirect_to: '../../../integration/jira/index.md' +remove_date: '2021-07-07' --- This document was moved to [another location](../../../integration/jira/index.md). diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index b3091275835..c9ab4532760 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -1,5 +1,6 @@ --- redirect_to: '../../../integration/jira/jira_cloud_configuration.md' +remove_date: '2021-06-18' --- This document was moved to [another location](../../../integration/jira/jira_cloud_configuration.md). diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md index 485b48df01b..3aacf051c22 100644 --- a/doc/user/project/integrations/jira_integrations.md +++ b/doc/user/project/integrations/jira_integrations.md @@ -1,5 +1,6 @@ --- redirect_to: '../../../integration/jira/index.md' +remove_date: '2021-07-13' --- This document was moved to [another location](../../../integration/jira/index.md). diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index 191b8f207a1..de6eec62b96 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -1,5 +1,6 @@ --- redirect_to: '../../../integration/jira/jira_server_configuration.md' +remove_date: '2021-06-18' --- This document was moved to [another location](../../../integration/jira/jira_server_configuration.md). diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 20f5b73b37c..834bf15c287 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -67,9 +67,9 @@ After you enable custom slash commands in Mattermost, you need configuration information from GitLab. To get this information: 1. In a different browser tab than your current Mattermost session, sign in to - GitLab as a user with [administrator permissions](../../permissions.md). -1. In the top navigation bar, go to **{admin}** **Admin Area**. -1. In the left menu, go to **Settings > Integrations** and select + GitLab as a user with [Administrator role](../../permissions.md). +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left menu, select **Settings > Integrations**, then select **Mattermost slash commands**. 1. GitLab displays potential values for Mattermost settings. Copy the **Request URL** as you need it for the next step. All other values are suggestions. diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 5bd4062b125..b0ae290e7cd 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -80,19 +80,6 @@ instance configuration or provide custom settings. Read more about [Project integration management](../../admin_area/settings/project_integration_management.md). -### Service templates - -[Service templates](services_templates.md) were a way to set predefined values for -a project integration across all new projects on the instance. They are deprecated and -[scheduled to be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) -in GitLab 14.0. - -GitLab recommends you use [project integration management](../../admin_area/settings/project_integration_management.md) -instead of service templates. GitLab versions 13.3 and later provide -[instance-level integrations](../../admin_area/settings/project_integration_management.md#project-integration-management) -you can use. -instead. - ## Troubleshooting integrations Some integrations use service hooks for integration with external applications. To confirm which ones use service hooks, see the [integrations listing](#integrations-listing) above. GitLab stores details of service hook requests made within the last 2 days. To view details of the requests, go to that integration's configuration page. @@ -128,6 +115,6 @@ plugins. This allows the community to keep the plugins up to date so that they always work in newer GitLab versions. For an overview of what integrations are available, please see the -[project_services source directory](https://gitlab.com/gitlab-org/gitlab/tree/master/app/models/project_services). +[project_services source directory](https://gitlab.com/gitlab-org/gitlab/-/tree/master/app/models/project_services). Contributions are welcome! diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 4922c8d9b62..adc98151ce4 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -17,7 +17,7 @@ in the GitLab interface. There are two ways to set up Prometheus integration, depending on where your apps are running: -- For deployments on Kubernetes, GitLab can automatically [deploy and manage Prometheus](#managed-prometheus-on-kubernetes). +- For deployments on Kubernetes, GitLab can be [integrated with an in-cluster Prometheus](#prometheus-cluster-integration) - For other deployment targets, [specify the Prometheus server](#manual-configuration-of-prometheus). Once enabled, GitLab detects metrics from known services in the @@ -27,141 +27,13 @@ Once enabled, GitLab detects metrics from known services in the ## Enabling Prometheus Integration -### Managed Prometheus on Kubernetes +### Prometheus cluster integration -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28916) in GitLab 10.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55244) in GitLab 13.11. +> - [Replaced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62725) the Prometheus cluster applications in GitLab 14.0. -**Deprecated:** Managed Prometheus on Kubernetes is deprecated, and -scheduled for removal in [GitLab -14.0](https://gitlab.com/groups/gitlab-org/-/epics/4280). - -GitLab can seamlessly deploy and manage Prometheus on a -[connected Kubernetes cluster](../clusters/index.md), to help you monitor your apps. - -#### Requirements - -- A [connected Kubernetes cluster](../clusters/index.md) - -#### Getting started - -After you have a connected Kubernetes cluster, you can deploy a managed Prometheus with a single click. - -1. Go to the **Operations > Kubernetes** page to view your connected clusters -1. Select the cluster you would like to deploy Prometheus to -1. Click the **Install** button to deploy Prometheus to the cluster - - - -#### About managed Prometheus deployments - -Prometheus is deployed into the `gitlab-managed-apps` namespace, using the -[official Helm chart](https://github.com/helm/charts/tree/master/stable/prometheus). -Prometheus is only accessible in the cluster, with GitLab communicating through the -[Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/). - -The Prometheus server -[automatically detects and monitors](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) -nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, -set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): - -- `prometheus.io/scrape` to `true` to enable monitoring of the resource. -- `prometheus.io/port` to define the port of the metrics endpoint. -- `prometheus.io/path` to define the path of the metrics endpoint. Defaults to `/metrics`. - -CPU and Memory consumption is monitored, but requires -[naming conventions](prometheus_library/kubernetes.md#specifying-the-environment) -to determine the environment. If you are using -[Auto DevOps](../../../topics/autodevops/index.md), this is handled automatically. - -The [NGINX Ingress](../clusters/index.md#installing-applications) that is deployed -by GitLab to clusters, is automatically annotated for monitoring providing key -response metrics: latency, throughput, and error rates. - -##### Example of Kubernetes service annotations and labels - -As an example, to activate Prometheus monitoring of a service: - -1. Add at least this annotation: `prometheus.io/scrape: 'true'`. -1. Add two labels so GitLab can retrieve metrics dynamically for any environment: - - `application: ${CI_ENVIRONMENT_SLUG}` - - `release: ${CI_ENVIRONMENT_SLUG}` -1. Create a dynamic PromQL query. For example, a query like - `temperature{application="{{ci_environment_slug}}",release="{{ci_environment_slug}}"}` to either: - - Add [custom metrics](../../../operations/metrics/index.md#adding-custom-metrics). - - Add [custom dashboards](../../../operations/metrics/dashboards/index.md). - -The following is a service definition to accomplish this: - -```yaml ---- -# Service -apiVersion: v1 -kind: Service -metadata: - name: service-${CI_PROJECT_NAME}-${CI_COMMIT_REF_SLUG} - # === Prometheus annotations === - annotations: - prometheus.io/scrape: 'true' - labels: - application: ${CI_ENVIRONMENT_SLUG} - release: ${CI_ENVIRONMENT_SLUG} - # === End of Prometheus === -spec: - selector: - app: ${CI_PROJECT_NAME} - ports: - - port: ${EXPOSED_PORT} - targetPort: ${CONTAINER_PORT} -``` - -#### Access the UI of a Prometheus managed application in Kubernetes - -You can connect directly to Prometheus, and view the Prometheus user interface, when -using a Prometheus managed application in Kubernetes: - -1. Find the name of the Prometheus pod in the user interface of your Kubernetes - provider, such as GKE, or by running the following `kubectl` command in your - terminal: - - ```shell - kubectl get pods -n gitlab-managed-apps | grep 'prometheus-prometheus-server' - ``` - - The command should return a result like the following example, where - `prometheus-prometheus-server-55b4bd64c9-dpc6b` is the name of the Prometheus pod: - - ```plaintext - gitlab-managed-apps prometheus-prometheus-server-55b4bd64c9-dpc6b 2/2 Running 0 71d - ``` - -1. Run a `kubectl port-forward` command. In the following example, `9090` is the - Prometheus server's listening port: - - ```shell - kubectl port-forward prometheus-prometheus-server-55b4bd64c9-dpc6b 9090:9090 -n gitlab-managed-apps - ``` - - The `port-forward` command forwards all requests sent to your system's `9090` port - to the `9090` port of the Prometheus pod. If the `9090` port on your system is used - by another application, you can change the port number before the colon to your - desired port. For example, to forward port `8080` of your local system, change the - command to: - - ```shell - kubectl port-forward prometheus-prometheus-server-55b4bd64c9-dpc6b 8080:9090 -n gitlab-managed-apps - ``` - -1. Open `localhost:9090` in your browser to display the Prometheus user interface. - -#### Script access to Prometheus - -You can script the access to Prometheus, extracting the name of the pod automatically like this: - -```shell -POD_INFORMATION=$(kubectl get pods -n gitlab-managed-apps | grep 'prometheus-prometheus-server') -POD_NAME=$(echo $POD_INFORMATION | awk '{print $1;}') -kubectl port-forward $POD_NAME 9090:9090 -n gitlab-managed-apps -``` +GitLab can query an in-cluster Prometheus for your metrics. +See [Prometheus cluster integration](../../clusters/integrations.md#prometheus-cluster-integration) for details. ### Manual configuration of Prometheus @@ -223,12 +95,12 @@ to integrate with. ### Precedence with multiple Prometheus configurations Although you can enable both a [manual configuration](#manual-configuration-of-prometheus) -and [auto configuration](#managed-prometheus-on-kubernetes) of Prometheus, you +and [cluster integration](#prometheus-cluster-integration) of Prometheus, you can use only one: - If you have enabled a [Prometheus manual configuration](#manual-configuration-of-prometheus) - and a [managed Prometheus on Kubernetes](#managed-prometheus-on-kubernetes), + and a [Prometheus cluster integration](#prometheus-cluster-integration), the manual configuration takes precedence and is used to run queries from [custom dashboards](../../../operations/metrics/dashboards/index.md) and [custom metrics](../../../operations/metrics/index.md#adding-custom-metrics). diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index e14c1c0f6fd..1bafa4938af 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -33,7 +33,7 @@ integration services must be enabled. Prometheus needs to be deployed into the cluster and configured properly in order to gather Kubernetes metrics. GitLab supports two methods for doing so: -- GitLab [integrates with Kubernetes](../../clusters/index.md), and can [deploy Prometheus into a connected cluster](../prometheus.md#managed-prometheus-on-kubernetes). It is automatically configured to collect Kubernetes metrics. +- GitLab [integrates with Kubernetes](../../clusters/index.md), and can [query a Prometheus in a connected cluster](../../../clusters/integrations.md#prometheus-cluster-integration). The in-cluster Prometheus can be configured to automatically collect application metrics from your cluster. - To configure your own Prometheus server, you can follow the [Prometheus documentation](https://prometheus.io/docs/introduction/overview/). ## Specifying the Environment diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index 8846aadd420..d1fe58390fe 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -27,28 +27,6 @@ NGINX Ingress versions prior to 0.16.0 offer an included [VTS Prometheus metrics ## Configuring NGINX Ingress monitoring -If you have deployed NGINX Ingress using the GitLab [Kubernetes cluster integration](../../clusters/index.md#installing-applications), Prometheus [automatically monitors it](#about-managed-nginx-ingress-deployments). - -For other deployments, there is [some configuration](#manually-setting-up-nginx-ingress-for-prometheus-monitoring) required depending on your installation: - -- NGINX Ingress should be version 0.16.0 or above, with metrics enabled. -- NGINX Ingress should be annotated for Prometheus monitoring. -- Prometheus should be configured to monitor annotated pods. - -### About managed NGINX Ingress deployments - -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress is [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). - -NGINX is configured for Prometheus monitoring, by setting: - -- `enable-vts-status: "true"`, to export Prometheus metrics. -- `prometheus.io/scrape: "true"`, to enable automatic discovery. -- `prometheus.io/port: "10254"`, to specify the metrics port. - -When used in conjunction with the GitLab deployed Prometheus service, response metrics are automatically collected. - -### Manually setting up NGINX Ingress for Prometheus monitoring - Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) have built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint starts running on port 10254. Next, the Ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index 4752fec976c..6bdd2c64dcf 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -27,28 +27,6 @@ GitLab has support for automatically detecting and monitoring the Kubernetes NGI ## Configuring NGINX Ingress monitoring -If you have deployed NGINX Ingress using the GitLab [Kubernetes cluster integration](../../clusters/index.md#installing-applications), Prometheus [automatically monitors](#about-managed-nginx-ingress-deployments) it. - -For other deployments, there is [some configuration](#manually-setting-up-nginx-ingress-for-prometheus-monitoring) required depending on your installation: - -- NGINX Ingress should be version 0.9.0 or above, with metrics enabled. -- NGINX Ingress should be annotated for Prometheus monitoring. -- Prometheus should be configured to monitor annotated pods. - -### About managed NGINX Ingress deployments - -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress is [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). - -NGINX is configured for Prometheus monitoring, by setting: - -- `enable-vts-status: "true"`, to export Prometheus metrics. -- `prometheus.io/scrape: "true"`, to enable automatic discovery. -- `prometheus.io/port: "10254"`, to specify the metrics port. - -When used in conjunction with the GitLab deployed Prometheus service, response metrics are automatically collected. - -### Manually setting up NGINX Ingress for Prometheus monitoring - Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) has built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint begins running on port 10254. Next, the Ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md index 93ce74eb735..37df48c75f8 100644 --- a/doc/user/project/integrations/services_templates.md +++ b/doc/user/project/integrations/services_templates.md @@ -1,67 +1,9 @@ --- -stage: Create -group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: '../../admin_area/settings/project_integration_management.md' +remove_date: '2021-09-09' --- -# Service templates **(FREE)** +This document was moved to [another location](../../admin_area/settings/project_integration_management.md). -WARNING: -Service templates are [deprecated and scheduled to be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) -in GitLab 14.0. Use [project integration management](#central-administration-of-project-integrations) instead. - -Using a service template, GitLab administrators can: - -- Provide default values for configuring integrations when creating new projects. -- Bulk configure all existing projects in one step. - -When you enable a service template: - -- The defaults are applied to **all** existing projects that either: - - Don't already have the integration enabled. - - Don't have custom values stored for already enabled integrations. -- Values are populated on each project's configuration page for the applicable - integration. -- Settings are stored at the project level. - -If you disable the template: - -- GitLab default values again become the default values for integrations on - new projects. -- Projects previously configured using the template continue to use those settings. - -If you change the template, the revised values are applied to new projects. This feature -does not provide central administration of integration settings. - -## Central administration of project integrations - -A new set of features is being introduced in GitLab to provide more control over -how integrations are configured at the instance, group, and project level. For -more information, read more about: - -- [Setting up project integration management](../../admin_area/settings/project_integration_management.md) (introduced in GitLab 13.3) -- [Our plans for managing integrations](https://gitlab.com/groups/gitlab-org/-/epics/2137). - -## Enable a service template - -Navigate to the **Admin Area > Service Templates** and choose the service -template you wish to create. - -Recommendation: - -- Test the settings on some projects individually before enabling a template. -- Copy the working settings from a project to the template. - -There is no "Test settings" option when enabling templates. If the settings do not work, -these incorrect settings are applied to all existing projects that do not already have -the integration configured. Fixing the integration then needs to be done project-by-project. - -## Service for external issue trackers - -The following image shows an example service template for Redmine. - - - -For each project, you still need to configure the issue tracking -URLs by replacing `:issues_tracker_id` in the above screenshot with the ID used -by your external issue tracker. +<!-- This redirect file can be deleted after <2021-09-09>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index b2bf8e5731a..05515c58161 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -27,7 +27,8 @@ notifications: 1. Navigate to: - **Settings > Integrations** in a project to enable the integration at the project level. - **Settings > Integrations** in a group to enable the integration at the group level. - - **Settings > Integrations** in the Admin Area (**{admin}**) to enable an instance-level integration. + - On the top bar, select **Menu >** **{admin}** **Admin**. Then, in the left sidebar, + select **Settings > Integrations** to enable an instance-level integration. 1. Select the **Webex Teams** integration. 1. Ensure that the **Active** toggle is enabled. 1. Select the checkboxes corresponding to the GitLab events you want to receive in Webex Teams. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index d74a2bec1f6..406b1e9ba6b 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -34,8 +34,10 @@ Webhooks are available: - Per project, at a project's **Settings > Webhooks** menu. **(FREE)** - Additionally per group, at a group's **Settings > Webhooks** menu. **(PREMIUM)** -NOTE: -On GitLab.com, the [maximum number of webhooks and their size](../../../user/gitlab_com/index.md#webhooks) per project, and per group, is limited. +GitLab.com enforces various [webhook limits](../../../user/gitlab_com/index.md#webhooks), including: + +- The maximum number of webhooks and their size, both per project, and per group. +- The number of webhook calls per minute. ## Possible uses for webhooks @@ -308,8 +310,10 @@ X-Gitlab-Event: Issue Hook "duplicated_to_id": null, "time_estimate": 0, "total_time_spent": 0, + "time_change": 0, "human_total_time_spent": null, "human_time_estimate": null, + "human_time_change": null, "weight": null, "iid": 23, "url": "http://example.com/diaspora/issues/23", @@ -1161,6 +1165,7 @@ X-Gitlab-Event: Pipeline Hook "id": 380987, "description": "shared-runners-manager-6.gitlab.com", "active": true, + "runner_type": "instance_type", "is_shared": true, "tags": [ "linux", @@ -1196,7 +1201,8 @@ X-Gitlab-Event: Pipeline Hook "id":380987, "description":"shared-runners-manager-6.gitlab.com", "active":true, - "is_shared":true, + "runner_type": "instance_type", + "is_shared": true, "tags": [ "linux", "docker" @@ -1230,6 +1236,7 @@ X-Gitlab-Event: Pipeline Hook "id": 380987, "description": "shared-runners-manager-6.gitlab.com", "active": true, + "runner_type": "instance_type", "is_shared": true, "tags": [ "linux", @@ -1333,6 +1340,7 @@ X-Gitlab-Event: Job Hook }, "runner": { "active": true, + "runner_type": "project_type", "is_shared": false, "id": 380987, "description": "shared-runners-manager-6.gitlab.com", diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index e1b6956f873..8f71d469e34 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -34,11 +34,11 @@ boards in the same project. Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Tier | Number of project issue boards | Number of [group issue boards](#group-issue-boards) | [Configurable issue boards](#configurable-issue-boards) | [Assignee lists](#assignee-lists) | -|------------------|--------------------------------|------------------------------|---------------------------|----------------| -| Free | Multiple | 1 | No | No | -| Premium | Multiple | Multiple | Yes | Yes | -| Ultimate | Multiple | Multiple | Yes | Yes | +| Tier | Number of project issue boards | Number of [group issue boards](#group-issue-boards) | [Configurable issue boards](#configurable-issue-boards) | [Assignee lists](#assignee-lists) | +| -------- | ------------------------------ | --------------------------------------------------- | ------------------------------------------------------- | --------------------------------- | +| Free | Multiple | 1 | No | No | +| Premium | Multiple | Multiple | Yes | Yes | +| Ultimate | Multiple | Multiple | Yes | Yes | To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards) below. @@ -203,7 +203,7 @@ When visiting a board, issues appear ordered in any list. You're able to change that order by dragging the issues. The changed order is saved, so that anybody who visits the same board later sees the reordering, with some exceptions. -The first time a given issue appears in any board (that is, the first time a user +The first time an issue appears in any board (that is, the first time a user loads a board containing that issue), it is ordered in relation to other issues in that list. The order is done according to [label priority](labels.md#label-priority). @@ -222,6 +222,28 @@ This ordering also affects [issue lists](issues/sorting_issue_lists.md). Changing the order in an issue board changes the ordering in an issue list, and vice versa. +### GraphQL-based issue boards + +<!-- This anchor is linked from #blocked-issues as well. --> + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285074) in GitLab 13.9. +> - [Deployed behind a feature flag](../feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-graphql-based-issue-boards). **(FREE SELF)** + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. + +The work-in-progress GraphQL-based boards come with these features: + +- [Edit more issue attributes](#edit-an-issue) +- [View blocked issues](#blocked-issues) + +The GraphQL-based Issue Board is a work in progress. +Learn more about the known issues in [epic 5596](https://gitlab.com/groups/gitlab-org/-/epics/5596). + ## GitLab Enterprise features for issue boards GitLab issue boards are available on the GitLab Free tier, but some @@ -269,40 +291,12 @@ especially in combination with [assignee lists](#assignee-lists).  -### Group issue boards **(PREMIUM)** +### Group issue boards Accessible at the group navigation level, a group issue board offers the same features as a project-level board. -It can display issues from all projects in that -group and its descendant subgroups. Similarly, you can only filter by group labels for these -boards. When updating milestones and labels for an issue through the sidebar update mechanism, again only -group-level objects are available. - -#### GraphQL-based sidebar for group issue boards **(PREMIUM)** - -<!-- When the feature flag is removed, integrate this section into the above ("Group issue boards"). --> -<!-- This anchor is linked from #blocked-issues as well. --> - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285074) in GitLab 13.9. -> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-graphql-based-sidebar-for-group-issue-boards). **(PREMIUM SELF)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -The work-in-progress GraphQL-based sidebar for group issue boards brings better performance and the -ability to edit issue titles in the issue sidebar. - -To **edit an issue's title** in the issue sidebar: - -1. In a group issue board, select the issue card. The issue sidebar opens on the right. -1. Next to the issue's title, select **Edit**. +It can display issues from all projects that fall under the group and its descendant subgroups. -This is work in progress as of GitLab 13.9. Learn more about the known issues in -[MR 51480](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51480). - -<!-- Add this at the end of the file --> +Users on GitLab Free can use a single group issue board. ### Assignee lists **(PREMIUM)** @@ -318,7 +312,7 @@ assignee list: 1. Search and select the user you want to add as an assignee. Now that the assignee list is added, you can assign or unassign issues to that user -by [dragging issues](#drag-issues-between-lists) to and from an assignee list. +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.  @@ -334,7 +328,7 @@ milestone, giving you more freedom and visibility on the issue board. To add a m 1. Select the **Milestone** tab. 1. Search and click the milestone. -Like the assignee lists, you're able to [drag issues](#drag-issues-between-lists) +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. @@ -361,7 +355,7 @@ iteration. To add an iteration list: 1. In the dropdown, select an iteration. 1. Select **Add to board**. -Like the milestone lists, you're able to [drag issues](#drag-issues-between-lists) +Like the milestone lists, you're able to [drag issues](#move-issues-and-lists) to and from a iteration list to manipulate the iteration of the dragged issues.  @@ -399,7 +393,7 @@ appears on the right. There you can see and edit the issue's: - Weight - Notifications setting -You can also [drag issues](#drag-issues-between-lists) to change their position and epic assignment: +You can also [drag issues](#move-issues-and-lists) to change their position and epic assignment: - To reorder an issue, drag it to the new position within a list. - To assign an issue to another epic, drag it to the epic's horizontal lane. @@ -442,27 +436,49 @@ status. When you hover over the blocked icon (**{issue-block}**), a detailed information popover is displayed. -To enable this in group issue boards, enable the [GraphQL-based sidebar](#graphql-based-sidebar-for-group-issue-boards). -The feature is enabled by default when you use group issue boards with epic swimlanes. +This feature is only supported when using the [GraphQL-based boards](#graphql-based-issue-boards). The feature is enabled by default regardless when you use group issue boards in epic swimlanes mode.  ## Actions you can take on an issue board +- [Edit an issue](#edit-an-issue). - [Create a new list](#create-a-new-list). - [Remove an existing list](#remove-a-list). - [Remove an issue from a list](#remove-an-issue-from-a-list). - [Filter issues](#filter-issues) that appear across your issue board. - [Create workflows](#create-workflows). -- [Drag issues between lists](#drag-issues-between-lists). +- [Move issues and lists](#move-issues-and-lists). - [Multi-select issue cards](#multi-select-issue-cards). - Drag and reorder the lists. - Change issue labels (by dragging an issue between lists). -- Close an issue (by dragging it to the **Done** list). +- Close an issue (by dragging it to the **Closed** list). If you're not able to do some of the things above, make sure you have the right [permissions](#permissions). +### Edit an issue + +You can edit an issue without leaving the board view. +To open the right sidebar, select an issue card (not its title). + +You can edit the following issue attributes in the right sidebar: + +- Assignees +- [Epic](../group/epics/index.md) +- Milestone +- Time tracking value (view only) +- Due date +- Labels +- [Weight](issues/issue_weight.md) +- Notifications setting + +When you use [GraphQL-based boards](#graphql-based-issue-boards), you can also edit the following issue attributes: + +- Title +- [Iteration](../group/iterations/index.md) +- Confidentiality + ### Create a new list Create a new list by clicking the **Add list** dropdown button in the upper right corner of the issue board. @@ -480,12 +496,12 @@ You can now choose it to create a list. ### Remove a list Removing a list doesn't have any effect on issues and labels, as it's just the -list view that's removed. You can always restore it later if you need. +list view that's removed. You can always create it again later if you need. To remove a list from an issue board: -1. Select the **List settings** icon (**{settings}**) on the top of the list you want to remove. The - list settings sidebar opens on the right. +1. On the top of the list you want to remove, select the **List settings** icon (**{settings}**). + The list settings sidebar opens on the right. 1. Select **Remove list**. A confirmation dialog appears. 1. Select **OK**. @@ -516,9 +532,8 @@ The steps depend on the scope of the list: ### Filter issues -You should be able to use the filters on top of your issue board to show only -the results you want. It's similar to the filtering used in the issue tracker, -as the metadata from the issues and labels is re-used in the issue board. +You can use the filters on top of your issue board to show only +the results you want. It's similar to the filtering used in the [issue tracker](issues/index.md). You can filter by the following: @@ -532,6 +547,16 @@ You can filter by the following: - Release - Weight +#### Filtering issues in a group board + +When [filtering issues](#filter-issues) in a **group** board, keep this behavior in mind: + +- Milestones: you can filter by the milestones belonging to the group and its descendant groups. +- Labels: you can only filter by the labels belonging to the group but not its descendant groups. + +When you edit issues individually using the right sidebar, you can additionally select the +milestones and labels from the **project** that the issue is from. + ### Create workflows By reordering your lists, you can create workflows. As lists in issue boards are @@ -570,20 +595,45 @@ to another list, the label changes and a system note is recorded.  -### Drag issues between lists +### Move issues and lists + +You can move issues and lists by dragging them. + +Prerequisites: -When dragging issues between lists, different behavior occurs depending on the source list and the target list. +- A minimum of [Reporter](../permissions.md#project-members-permissions) access to a project in GitLab. -| | To Open | To Closed | To label `B` list | To assignee `Bob` list | -| ------------------------------ | ------------------ | ------------ | ---------------------------- | ------------------------------------- | -| **From Open** | - | Issue closed | `B` added | `Bob` assigned | -| **From Closed** | Issue reopened | - | Issue reopened<br/>`B` added | Issue reopened<br/>`Bob` assigned | -| **From label `A` list** | `A` removed | Issue closed | `A` removed<br/>`B` added | `Bob` assigned | -| **From assignee `Alice` list** | `Alice` unassigned | Issue closed | `B` added | `Alice` unassigned<br/>`Bob` assigned | +To move an issue, select the issue card and drag it to another position in its current list or +into a different list. Learn about possible effects in [Dragging issues between lists](#dragging-issues-between-lists). + +To move a list, select its top bar, and drag it horizontally. +You can't move the **Open** and **Closed** lists, but you can hide them when editing an issue board. + +#### Dragging issues between lists + +To move an issue to another list, select the issue card and drag it onto that list. + +When you drag issues between lists, the result is different depending on the source list +and the target list. + +| | To Open | To Closed | To label B list | To assignee Bob list | +| ---------------------------- | -------------- | ----------- | ------------------------------ | ----------------------------- | +| **From Open** | - | Close issue | Add label B | Assign Bob | +| **From Closed** | Reopen issue | - | Reopen issue and add label B | Reopen issue and assign Bob | +| **From label A list** | Remove label A | Close issue | Remove label A and add label B | Assign Bob | +| **From assignee Alice list** | Unassign Alice | Close issue | Add label B | Unassign Alice and assign Bob | ### Multi-select issue cards -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18954) in GitLab 12.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18954) in GitLab 12.4. +> - [Placed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61955) behind a [feature flag](../feature_flags.md), disabled by default in GitLab 14.0. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-multi-selecting-issue-cards). **(FREE SELF)** + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. You can select multiple issue cards, then drag the group to another position within the list, or to another list. This makes it faster to reorder many issues at once. @@ -626,10 +676,14 @@ A few things to remember: by default. If you have more than 20 issues, start scrolling down and the next 20 appear. -## Enable or disable GraphQL-based sidebar for group issue boards **(PREMIUM SELF)** +### Enable or disable GraphQL-based issue boards **(FREE SELF)** -GraphQL-based sidebar for group issue boards is under development and not ready for production use. -It is deployed behind a feature flag that is **disabled by default**. +NOTE: +When enabling GraphQL-based issue boards, you must also enable the +[new add list form](#enable-or-disable-new-add-list-form). + +GraphQL-based issue boards is not ready for production use. +It is deployed behind a feature flag that is **disabled by default** as of GitLab 13.12. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) can enable it. @@ -685,3 +739,22 @@ To disable it: ```ruby Feature.disable(:iteration_board_lists) ``` + +### Enable or disable multi-selecting issue cards **(FREE SELF)** + +Multi-selecting issue cards is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:board_multi_select) +``` + +To disable it: + +```ruby +Feature.disable(:board_multi_select) +``` diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 25357a1db0b..ed15d7a2e63 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -77,11 +77,11 @@ least [Reporter access](../../permissions.md#project-members-permissions). Howev confidential issues, but can only view the ones that they created themselves. Confidential issues are also hidden in search results for unprivileged users. -For example, here's what a user with Maintainer and Guest access sees in the -project's search results respectively. +For example, here's what a user with the [Maintainer role](../../permissions.md) and Guest access +sees in the project's search results respectively. -| Maintainer access | Guest access | -| :-----------: | :----------: | +| Maintainer role | Guest access | +|:---------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------| |  |  | ## Merge Requests for Confidential Issues diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 5c95665230a..29adf396d4d 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -4,41 +4,46 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Export Issues to CSV +# Export issues to CSV **(FREE)** > Moved to GitLab Free in 12.10. -Issues can be exported as CSV from GitLab and are sent to your default notification email as an attachment. +You can export issues as CSV files from GitLab, which are sent to your default +notification email address as an attachment. -## Overview +**Export Issues to CSV** enables you and your team to export all the data +collected from issues into a **[comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values)** (CSV) +file, which stores tabular data in plain text. -**Export Issues to CSV** enables you and your team to export all the data collected from issues into -a **[comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values)** (CSV) file, -which stores tabular data in plain text. +> _CSVs are a handy way of getting data from one program to another where one +program cannot read the other ones normal output._ [Ref](https://www.quora.com/What-is-a-CSV-file-and-its-uses) -> _CSVs are a handy way of getting data from one program to another where one program cannot read the other ones normal output._ [Ref](https://www.quora.com/What-is-a-CSV-file-and-its-uses) +CSV files can be used with any plotter or spreadsheet-based program, such as +Microsoft Excel, Open Office <!-- vale gitlab.Spelling = NO --> Calc, <!-- vale gitlab.Spelling = NO -->, +or Google Sheets. -CSV files can be used with any plotter or spreadsheet-based program, such as Microsoft Excel, -Open Office <!-- vale gitlab.Spelling = NO --> Calc, <!-- vale gitlab.Spelling = NO --> or Google Spreadsheets. +Here are some of the uses of exporting issues as CSV files: -## Use cases - -Among numerous use cases for exporting issues for CSV, we can name a few: - -- Make a snapshot of issues for offline analysis or to communicate with other teams who may not be in GitLab -- Create diagrams, graphs, and charts from the CSV data -- Present the data in any other format for auditing or sharing reasons -- Import the issues elsewhere to a system outside of GitLab -- Long-term issues' data analysis with multiple snapshots created along the time -- Use the long-term data to gather relevant feedback given in the issues, and improve your product based on real metrics +- Make a snapshot of issues for offline analysis or to communicate with other + teams who may not be in GitLab. +- Create diagrams, graphs, and charts from the CSV data. +- Present the data in any other format for auditing or sharing reasons. +- Import the issues elsewhere to a system outside of GitLab. +- Long-term issues' data analysis with multiple snapshots created along the + time. +- Use the long-term data to gather relevant feedback given in the issues, and + improve your product based on real metrics. ## Choosing which issues to include -After selecting a project, from the issues page you can narrow down which issues to export using the search bar, along with the All/Open/Closed tabs. All issues returned are exported, including those not shown on the first page. +After selecting a project, from the issues page you can narrow down which +issues to export using the search bar, along with the All/Open/Closed tabs. All +issues returned are exported, including those not shown on the first page.  -GitLab asks you to confirm the number of issues and email address for the export, after which the email is prepared. +GitLab asks you to confirm the number of issues and email address for the +export, after which the email is prepared.  @@ -48,33 +53,41 @@ Exported issues are always sorted by `Issue ID`. ## Format -Data is encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row contains the headers, which are listed in the following table along with a description of the values: - -| Column | Description | -|---------|-------------| -| Issue ID | Issue `iid` | -| URL | A link to the issue on GitLab | -| Title | Issue `title` | -| State | `Open` or `Closed` | -| Description | Issue `description` | -| Author | Full name of the issue author | -| Author Username | Username of the author, with the `@` symbol omitted | -| Assignee | Full name of the issue assignee | +Data is encoded with a comma as the column delimiter, with `"` used to quote +fields if needed, and newlines to separate rows. The first row contains the +headers, which are listed in the following table along with a description of +the values: + +| Column | Description | +|-------------------|-------------| +| Issue ID | Issue `iid` | +| URL | A link to the issue on GitLab | +| Title | Issue `title` | +| State | `Open` or `Closed` | +| Description | Issue `description` | +| Author | Full name of the issue author | +| Author Username | Username of the author, with the `@` symbol omitted | +| Assignee | Full name of the issue assignee | | Assignee Username | Username of the author, with the `@` symbol omitted | -| Confidential | `Yes` or `No` | -| Locked | `Yes` or `No` | -| Due Date | Formatted as `YYYY-MM-DD` | -| Created At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | -| Updated At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | -| Milestone | Title of the issue milestone | -| Weight | Issue weight | -| Labels | Title of any labels joined with a `,` | -| Time Estimate | [Time estimate](../time_tracking.md#estimates) in seconds | -| Time Spent | [Time spent](../time_tracking.md#time-spent) in seconds | -| Epic ID | ID of the parent epic **(ULTIMATE)**, introduced in 12.7 | -| Epic Title | Title of the parent epic **(ULTIMATE)**, introduced in 12.7 | +| Confidential | `Yes` or `No` | +| Locked | `Yes` or `No` | +| Due Date | Formatted as `YYYY-MM-DD` | +| Created At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | +| Updated At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | +| Milestone | Title of the issue milestone | +| Weight | Issue weight | +| Labels | Title of any labels joined with a `,` | +| Time Estimate | [Time estimate](../time_tracking.md#estimates) in seconds | +| Time Spent | [Time spent](../time_tracking.md#time-spent) in seconds | +| Epic ID | ID of the parent epic **(ULTIMATE)**, introduced in 12.7 | +| Epic Title | Title of the parent epic **(ULTIMATE)**, introduced in 12.7 | ## Limitations - Export Issues to CSV is not available at the Group's Issues List. -- As the issues are sent as an email attachment, there is a limit on how much data can be exported. Currently this limit is 15MB to ensure successful delivery across a range of email providers. If this limit is reached we suggest narrowing the search before export, perhaps by exporting open and closed issues separately. +- Issues are sent as an email attachment, with a 15 MB export limit to ensure + successful delivery across a range of email providers. If you reach the limit, + we suggest narrowing the search before export, perhaps by exporting open and + closed issues separately. +- CSV files are plain text files. This means that the exported CSV file doesn't + contain any issue attachments. diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index de7a36a4886..02a4f6a4384 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -4,7 +4,7 @@ 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 --- -# Importing issues from CSV +# Importing issues from CSV **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23532) in GitLab 11.7. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 2a003e68a73..e0eb35d1e49 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -48,7 +48,7 @@ If the requirements are not met, the **Designs** tab displays a message to the u Files uploaded must have a file extension of either `png`, `jpg`, `jpeg`, `gif`, `bmp`, `tiff`, `ico`, `webp`, or `svg`. -Support for [PDF](https://gitlab.com/gitlab-org/gitlab/issues/32811) is planned for a future release. +Support for [PDF](https://gitlab.com/gitlab-org/gitlab/-/issues/32811) is planned for a future release. ## Limitations @@ -219,11 +219,14 @@ There are two ways to resolve/unresolve a Design thread:  +Resolving a discussion thread also marks any pending to-do items related to notes +inside the thread as done. This is applicable only for to-do items owned by the user triggering the action. + Note that your resolved comment pins disappear from the Design to free up space for new discussions. However, if you need to revisit or find a resolved discussion, all of your resolved threads are available in the **Resolved Comment** area at the bottom of the right sidebar. -## Add to dos for designs +## Add to-do items for designs > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198439) in GitLab 13.4. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245074) in GitLab 13.5. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index a82823947dc..5b8dd617ab9 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -4,13 +4,9 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Due dates +# Due dates **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3614) in GitLab 8.7. - -Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. - -Due dates can be used in issues to keep track of deadlines and make sure features are +Due dates can be used in [issues](index.md) to keep track of deadlines and make sure features are shipped on time. Users need at least [Reporter permissions](../../permissions.md) to be able to edit the due date. All users with permission to view the issue can view the due date. @@ -24,11 +20,11 @@ the user setting the due date.  -You can also set a due date via the issue sidebar. Expand the -sidebar and click **Edit** to pick a due date or remove the existing one. +You can also set a due date by using the issue sidebar. Expand the +sidebar and select **Edit** to pick a due date or remove the existing one. Changes are saved immediately. - + The last way to set a due date is by using [quick actions](../quick_actions.md), directly in an issue's description or comment: @@ -52,9 +48,9 @@ of the issue. Like the due date, the "day before the due date" is determined by server's timezone. Issues with due dates can also be exported as an iCalendar feed. The URL of the -feed can be added to calendar applications. The feed is accessible by clicking -on the **Subscribe to calendar** button on the following pages: +feed can be added to calendar applications. The feed is accessible by selecting +the **Subscribe to calendar** button on the following pages: -- on the **Assigned Issues** page that is linked on the right-hand side of the GitLab header -- on the **Project Issues** page -- on the **Group Issues** page +- The **Assigned Issues** page linked on the right side of the GitLab header +- The **Project Issues** page +- The **Group Issues** page diff --git a/doc/user/project/issues/img/issue_type_change_v13_12.png b/doc/user/project/issues/img/issue_type_change_v13_12.png Binary files differnew file mode 100644 index 00000000000..3b4864ffbbb --- /dev/null +++ b/doc/user/project/issues/img/issue_type_change_v13_12.png diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 3af6c528db9..13f5beadb16 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -221,7 +221,7 @@ merge request is also listed here. You can award emojis to issues. You can select the "thumbs up" and "thumbs down", or the gray "smiley-face" to choose from the list of available -[GitLab Flavored Markdown Emoji](../../markdown.md#emoji). +[GitLab Flavored Markdown Emoji](../../markdown.md#emojis). NOTE: Posting "+1" as a comment in a thread spams all subscribed participants of that issue, diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 9e8a75743a7..35573518626 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -315,10 +315,15 @@ issues are still displayed, but are not closed automatically.  +The automatic issue closing is also disabled 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). + This only applies to issues affected by new merge requests or commits. Already -closed issues remain as-is. Disabling automatic issue closing only affects merge -requests *in* the project and does not prevent other projects from closing it -via cross-project issues. +closed issues remain as-is. +If issue tracking is enabled, disabling automatic issue closing only applies to merge requests +attempting to automatically close issues within the same project. +Merge requests in other projects can still close another project's issues. #### Customizing the issue closing pattern **(FREE SELF)** @@ -326,9 +331,20 @@ In order to change the default issue closing pattern, GitLab administrators must [`gitlab.rb` or `gitlab.yml` file](../../../administration/issue_closing_pattern.md) of your installation. +## Change the issue type + +Users with [developer permission](../../permissions.md) +can change an issue's type. To do this, edit the issue and select an issue type from the +**Issue type** selector menu: + +- [Issue](index.md) +- [Incident](../../../operations/incident_management/index.md) + + + ## Deleting issues -Users with [project owner permission](../../permissions.md) can delete an issue by +Users with the [Owner role](../../permissions.md) can delete an issue by editing it and selecting **Delete issue**.  diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 0cb5b5d993e..e7adc045e98 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -282,4 +282,4 @@ To resolve the duplication, [in GitLab 13.2](https://gitlab.com/gitlab-org/gitla and later, some duplicate labels have `_duplicate<number>` appended to their titles. You can safely change these labels' titles if you prefer. -For details of the original problem, see [issue 30390](https://gitlab.com/gitlab-org/gitlab/issues/30390). +For details of the original problem, see [issue 30390](https://gitlab.com/gitlab-org/gitlab/-/issues/30390). diff --git a/doc/user/project/members/img/access_requests_management_v13_9.png b/doc/user/project/members/img/access_requests_management_v13_9.png Binary files differdeleted file mode 100644 index b7883e9d134..00000000000 --- a/doc/user/project/members/img/access_requests_management_v13_9.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_email_accept_v13_9.png b/doc/user/project/members/img/add_user_email_accept_v13_9.png Binary files differdeleted file mode 100644 index a6b303e05ca..00000000000 --- a/doc/user/project/members/img/add_user_email_accept_v13_9.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_email_ready_v13_8.png b/doc/user/project/members/img/add_user_email_ready_v13_8.png Binary files differdeleted file mode 100644 index a610b46a176..00000000000 --- a/doc/user/project/members/img/add_user_email_ready_v13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_email_search_v13_8.png b/doc/user/project/members/img/add_user_email_search_v13_8.png Binary files differdeleted file mode 100644 index 934cf19bd3d..00000000000 --- a/doc/user/project/members/img/add_user_email_search_v13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/withdraw_access_request_button.png b/doc/user/project/members/img/withdraw_access_request_button.png Binary files differdeleted file mode 100644 index e5a8fe0b356..00000000000 --- a/doc/user/project/members/img/withdraw_access_request_button.png +++ /dev/null diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 7dc1a9c612f..ab33ff0f6d8 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,10 +1,10 @@ --- -stage: none -group: unassigned +stage: Manage +group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Members of a project +# Members of a project **(FREE)** Members are the users and groups who have access to your project. @@ -17,12 +17,13 @@ to perform actions. Prerequisite: -- You must have maintainer or owner [permissions](../../permissions.md). +- You must have the [Maintainer or Owner role](../../permissions.md). To add a user to a project: 1. Go to your project and select **Members**. -1. On the **Invite member** tab, under **GitLab member of Email address**, type the username or email address. +1. On the **Invite member** tab, under **GitLab member or Email address**, type the username or email address. + In GitLab 13.11 and later, you can [replace this form with a modal window](#add-a-member-modal-window). 1. Select a [role](../../permissions.md). 1. Optional. Choose an expiration date. On that date, the user can no longer access the project. 1. Select **Invite**. @@ -30,15 +31,24 @@ To add a user to a project: If the user has a GitLab account, they are added to the members list. If you used an email address, the user receives an email. +If the invitation is not accepted, GitLab sends reminder emails two, +five, and ten days later. Unaccepted invites are automatically +deleted after 90 days. + +If the user does not have a GitLab account, they are prompted to create an account +using the email address the invitation was sent to. + ## Add groups to a project -When you assign a group to a project, each user in the group gets access to the project, -based on the role they're assigned in the group. However, the user's access is also -limited by the maximum role you choose when you invite the group. +When you add a group to a project, each user in the group gets access to the project. +Each user's access is based on: + +- The role they're assigned in the group. +- The maximum role you choose when you invite the group. Prerequisite: -- You must have maintainer or owner [permissions](../../permissions.md). +- You must have the [Maintainer or Owner role](../../permissions.md). To add groups to a project: @@ -61,7 +71,7 @@ retain the same permissions as the project you import them from. Prerequisite: -- You must have maintainer or owner [permissions](../../permissions.md). +- You must have the [Maintainer or Owner role](../../permissions.md). To import users: @@ -74,20 +84,39 @@ A success message is displayed and the new members are now displayed in the list ## Inherited membership -When your project belongs to a group, group members inherit the membership and permission -level for the project from the group. +When your project belongs to a group, group members inherit their role +from the group.  -From the image above, we can deduce the following things: +In this example: + +- Three members have access to the project. +- **User 0** is a Reporter and has inherited their role from the **demo** group, + which contains the project. +- **User 1** belongs directly to the project. In the **Source** column, they are listed + as a **Direct member**. +- **Administrator** is the [Owner](../../permissions.md) and member of all groups. + They have inherited their role from the **demo** group. + +## Remove a member from a project + +If a user is a direct member of a project, you can remove them. +If membership is inherited from a parent group, then the member can be removed only from the parent +group itself. -- There are 3 members that have access to the project. -- User0 is a Reporter and has inherited their permissions from group `demo` - which contains current project. -- User1 is shown as a **Direct member** in the **Source** column, therefore they belong directly - to the project we're inspecting. -- Administrator is the Owner and member of **all** groups and for that reason, - there is an indication of an ancestor group and inherited Owner permissions. +Prerequisite: + +- You must have the [Owner role](../../permissions.md). +- Optional. Unassign the member from all issues and merge requests that + are assigned to them. + +To remove a member from a project: + +1. Go to your project and select **Members**. +1. Next to the project member you want to remove, select **Remove member** **{remove}**. +1. Optional. In the confirmation box, select the **Also unassign this user from related issues and merge requests** checkbox. +1. Select **Remove member**. ## Filter and sort members @@ -95,22 +124,21 @@ From the image above, we can deduce the following things: > - [Improved](https://gitlab.com/groups/gitlab-org/-/epics/4901) in GitLab 13.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299954) in GitLab 13.10. -The following sections illustrate how you can filter and sort members in a project. To view these options, -navigate to your desired project, go to **Members**, and include the noted search terms. - -### Membership filter - -By default, inherited and direct members are displayed. The membership filter can be used to display only inherited or only direct members. +You can filter and sort members in a project. -#### Display inherited members +### Display inherited members -To display inherited members, include `Membership` `=` `Inherited` in the search text box. +1. Go to your project and select **Members**. +1. In the **Filter members** box, select `Membership` `=` `Inherited`. +1. Press Enter.  -#### Display direct members +### Display direct members -To display direct members, include `Membership` `=` `Direct` in the search text box. +1. Go to your project and select **Members**. +1. In the **Filter members** box, select `Membership` `=` `Direct`. +1. Press Enter.  @@ -126,36 +154,41 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last  -## Invite people using their e-mail address +## Request access to a project -NOTE: -In GitLab 13.11, you can [replace this form with a modal window](#add-a-member-modal-window). +GitLab users can request to become a member of a project. -If a user you want to give access to doesn't have an account on your GitLab -instance, you can invite them just by typing their e-mail address in the -user search field. +1. Go to the project you'd like to be a member of. +1. By the project name, select **Request Access**. - + -As you can imagine, you can mix inviting multiple people and adding existing -GitLab users to the 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. - +If a project does not have any 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 +**Withdraw Access Request**. -Once done, hit **Add users to project** and watch that there is a new member -with the e-mail address we used above. From there on, you can resend the -invitation, change their access level, or even delete them. +## Prevent users from requesting access to a project - +You can prevent users from requesting access to a project. + +Prerequisite: -While unaccepted, the system automatically sends reminder emails on the second, fifth, -and tenth day after the invitation was initially sent. +- You must be the project owner. -After the user accepts the invitation, they are prompted to create a new -GitLab account using the same e-mail address the invitation was sent to. +1. Go to the project and select **Settings > General**. +1. Expand the **Visibility, project features, permissions** section. +1. Under **Project visibility**, select **Users can request access**. +1. Select **Save changes**. -NOTE: -Unaccepted invites are automatically deleted after 90 days. +## Share a project with a group + +Instead of adding users one by one, you can [share a project with an entire group](share_project_with_groups.md). ### Add a member modal window @@ -172,10 +205,10 @@ This feature might not be available to you. Check the **version history** note a In GitLab 13.11, you can optionally replace the form to add a member with a modal window. To add a member after enabling this feature: -1. Go to your project's page. -1. In the left sidebar, go to **Members**, and then select **Invite members**. -1. Enter an email address, and select a role permission for this user. -1. (Optional) Select an **Access expiration date**. +1. Go to your project and select **Members**. +1. Select **Invite members**. +1. Enter an email address and select a role. +1. Optional. Select an **Access expiration date**. 1. Select **Invite**. ### Enable or disable modal window **(FREE SELF)** @@ -196,65 +229,3 @@ To disable it: ```ruby Feature.disable(:invite_members_group_modal) ``` - -## Project membership and requesting access - -Project owners can : - -- Allow non-members to request access to the project. -- Prevent non-members from requesting access. - -To configure this, go to the project settings and click on **Allow users to request access**. - -GitLab users can request to become a member of a project. Go to the project you'd -like to be a member of and click the **Request Access** button on the right -side of your screen. - - - -After access is requested: - -- Up to ten project maintainers are notified of the request via email. - Email is sent to the most recently active project maintainers. -- Any project maintainer can approve or decline the request on the members page. - -NOTE: -If a project does not have any 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, just click the -**Withdraw Access Request** button. - - - -## Share project with group - -Alternatively, you can [share a project with an entire group](share_project_with_groups.md) instead of adding users one by one. - -## Remove a member from the project - -Only users with permissions of [Owner](../../permissions.md#group-members-permissions) can manage -project members. - -You can remove a user from the project if the given member has a direct membership in the project. -If membership is inherited from a parent group, then the member can be removed only from the parent -group itself. - -When removing a member, you can decide whether to unassign the user from all issues and merge -requests they are currently assigned or leave the assignments as they are. - -- **Unassigning the removed member** from all issues and merge requests might be helpful when a user - is leaving a private project and you wish to revoke their access to any issues and merge requests - they are assigned. -- **Keeping the issues and merge requests assigned** might be helpful for projects that accept public - contributions where a user doesn't have to be a member to be able to contribute to issues and - merge requests. - -To remove a member from a project: - -1. Go to your project and select **Members**. -1. Next to the project member you want to remove, select **Remove member** **{remove}**. -1. Optional. In the confirmation box, select the **Also unassign this user from related issues and merge requests** checkbox. -1. Select **Remove member**. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 085e4db0b94..caef5ef60b7 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -60,7 +60,7 @@ To share a project after enabling this feature: 1. Go to your project's page. 1. In the left sidebar, go to **Members**, and then select **Invite a group**. -1. Select a group, and select a **Max access level**. +1. Select a group, and select a **Max role**. 1. (Optional) Select an **Access expiration date**. 1. Select **Invite**. diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index 09770bd447d..76aff18b00d 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Accessibility Testing +# Accessibility testing **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25144) in GitLab 12.8. @@ -17,11 +17,11 @@ impact of pending code changes. GitLab uses [pa11y](https://pa11y.org/), a free and open source tool for measuring the accessibility of web sites, and has built a simple -[CI job template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml). +[CI job template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml). This job outputs accessibility violations, warnings, and notices for each page analyzed to a file called `accessibility`. -## Accessibility Merge Request widget +## Accessibility merge request widget > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39425) in GitLab 13.0 behind the disabled [feature flag](../../../administration/feature_flags.md) `:accessibility_report_view`. > - [Feature Flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/217372) in GitLab 13.1. @@ -29,7 +29,7 @@ analyzed to a file called `accessibility`. In addition to the report artifact that is created, GitLab will also show the Accessibility Report in the merge request widget area: - + ## Configure Accessibility Testing @@ -38,7 +38,7 @@ on your code with GitLab CI/CD using the [GitLab Accessibility Docker image](htt For GitLab 12.9 and later, to define the `a11y` job, you must [include](../../../ci/yaml/README.md#includetemplate) the -[`Accessibility.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) +[`Accessibility.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) included with your GitLab installation, as shown below. Add the following to your `.gitlab-ci.yml` file: @@ -67,7 +67,7 @@ For GitLab 12.10 and earlier, the [artifact generated is named `accessibility.js NOTE: For GitLab versions earlier than 12.9, you can use `include:remote` and use a -link to the [current template in `master`](https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) +link to the [current template in the default branch](https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) NOTE: The job definition provided by the template does not support Kubernetes yet. diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 5917d67c398..63d5119c1b4 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -24,19 +24,17 @@ of the merge request. ## Enabling commit edits from upstream members In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/23308), -this setting is enabled by default. It can be changed by users with Developer -permissions to the source project. Once enabled, upstream members can -retry the pipelines and jobs of the merge request: +this setting is enabled by default. It can be changed by users with the +Developer [role](../../permissions.md) for the source project. After it's enabled, +upstream members can retry the pipelines and jobs of the merge request: -1. While creating or editing a merge request, select the checkbox **Allow - commits from members who can merge to the target branch**. +1. While creating or editing a merge request, scroll to **Contribution** and + then select the **Allow commits from members who can merge to the target branch**. + checkbox. +1. Finish creating your merge request. -  - -1. Once the merge request is created, you can see that commits from members who - can merge to the target branch are allowed. - -  +After you create the merge request, the merge request widget displays a message: +**Members who can merge are allowed to add commits.** ## Pushing to the fork as the upstream member @@ -48,41 +46,39 @@ Assuming that: - The forked project URL is `git@gitlab.com:thedude/awesome-project.git`. - The branch of the merge request is `update-docs`. -Here's how the process would look like: - -1. First, you need to get the changes that the merge request has introduced. - Click the **Check out branch** button that has some pre-populated - commands that you can run. - -  +To find and work with the changes from the fork: -1. Use the copy button to copy the first command and paste them - in your terminal: +1. Open the merge request page, and select the **Overview** tab. +1. Scroll to the merge request widget, and select **Check out branch**: +  +1. In the modal window, select **{copy-to-clipboard}** (**Copy**) for step 1 + to copy the `git fetch` and `git checkout` instructions to your clipboard. + Paste the commands (which look like this example) into your terminal: ```shell git fetch git@gitlab.com:thedude/awesome-project.git update-docs git checkout -b thedude-awesome-project-update-docs FETCH_HEAD ``` - This fetches the branch of the forked project and then create a local branch + These commands fetch the branch from the forked project, and create a local branch based off the fetched branch. -1. Make any changes you want and commit. -1. Push to the forked project: +1. Make your changes to the local copy of the branch, and then commit them. +1. In your terminal, push your local changes back up to the forked project. This + command pushes the local branch `thedude-awesome-project-update-docs` to the + `update-docs` branch of the `git@gitlab.com:thedude/awesome-project.git` repository: ```shell git push git@gitlab.com:thedude/awesome-project.git thedude-awesome-project-update-docs:update-docs ``` - Note the colon (`:`) between the two branches. The above command pushes the - local branch `thedude-awesome-project-update-docs` to the - `update-docs` branch of the `git@gitlab.com:thedude/awesome-project.git` repository. + Note the colon (`:`) between the two branches. ## Troubleshooting ### Pipeline status unavailable from MR page of forked project -When a user forks a project, the permissions on the forked copy are not copied over +When a user forks a project, the permissions of the forked copy are not copied from the original project. The creator of the fork must grant permissions to the forked copy before members in the upstream project can view or merge the changes in the merge request. diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index ac48e44da52..3c47c2af344 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -42,7 +42,7 @@ for more control of the level of oversight and security your project needs, incl - [Require security team approval.](settings.md#security-approvals-in-merge-requests) You can configure your merge request approval rules and settings through the GitLab -user interface or [with the API](../../../../api/merge_request_approvals.md). +user interface or with the [Merge request approvals API](../../../../api/merge_request_approvals.md). ## Approve a merge request @@ -97,36 +97,6 @@ Without the approvals, the work cannot merge. Required approvals enable multiple - [Require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests) before merging code that could introduce a vulnerability. **(ULTIMATE)** -## Notify external services **(ULTIMATE)** - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab Ultimate 13.10. -> - [Deployed behind a feature flag](../../../feature_flags.md), disabled by default. -> - Disabled on GitLab.com. -> - Not recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../../../api/merge_request_approvals.md#enable-or-disable-external-project-level-mr-approvals). **(ULTIMATE SELF)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -You can create an external approval rule to integrate approvals with third-party tools. -When users create, change, or close merge requests, GitLab sends a notification. -The users of the third-party tools can then approve merge requests from outside of GitLab. - -With this integration, you can integrate with third-party workflow tools, like -[ServiceNow](https://www.servicenow.co.uk/), or the custom tool of your choice. -You can modify your external approval rules -[by using the REST API](../../../../api/merge_request_approvals.md#external-project-level-mr-approvals). - -The lack of an external approval doesn't block the merging of a merge request. - -When [approval rule overrides](settings.md#prevent-overrides-of-default-approvals) are allowed, -changes to default approval rules will **not** be applied to existing -merge requests, except for changes to the [target branch](rules.md#approvals-for-protected-branches) -of the rule. - -To learn more about use cases, feature discovery, and development timelines, -see the [External API approval rules epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). - ## Related links - [Merge request approvals API](../../../../api/merge_request_approvals.md) diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 32f0160771f..1e4b0f659ee 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# Merge request approval rules +# Merge request approval rules **(FREE)** Approval rules define how many [approvals](index.md) a merge request must receive before it can be merged, and which users should do the approving. You can define approval rules: @@ -144,7 +144,7 @@ approve in these ways: [**Prevent committers approval**](settings.md#prevent-committers-from-approving-their-own-work) project setting. -### Code owners as eligible approvers +### Code owners as eligible approvers **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in GitLab 11.5. > - Moved to GitLab Premium in 13.9. @@ -162,7 +162,7 @@ You can also [require code owner approval](../../protected_branches.md#protected-branches-approval-by-code-owners) for protected branches. **(PREMIUM)** -## Merge request approval segregation of duties +## Merge request approval segregation of duties **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. > - Moved to GitLab Premium in 13.9. diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 8769f6a7470..97e4b7da396 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# Merge request approval settings +# Merge request approval settings **(FREE)** You can configure the settings for [merge request approvals](index.md) to ensure the approval rules meet your use case. You can also configure diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index aa43d34cdd9..930df65f3fc 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -16,17 +16,17 @@ There are two main ways to have a merge request flow with GitLab: With the protected branch flow everybody works within the same GitLab project. -The project maintainers get Maintainer access and the regular developers get -Developer access. +The project maintainers get the [Maintainer role](../../permissions.md) and the regular developers +get Developer access. -The maintainers mark the authoritative branches as 'Protected'. +Maintainers mark the authoritative branches as 'Protected'. -The developers push feature branches to the project and create merge requests +Developers push feature branches to the project and create merge requests to have their feature branches reviewed and merged into one of the protected branches. -By default, only users with Maintainer access can merge changes into a protected -branch. +By default, only users with the [Maintainer role](../../permissions.md) can merge changes into a +protected branch. **Advantages** @@ -39,14 +39,14 @@ branch. ## Forking workflow -With the forking workflow the maintainers get Maintainer access and the regular +With the forking workflow, maintainers get the [Maintainer role](../../permissions.md) and regular developers get Reporter access to the authoritative repository, which prohibits them from pushing any changes to it. Developers create forks of the authoritative project and push their feature branches to their own forks. -To get their changes into master they need to create a merge request across +To get their changes into the default branch, they need to create a merge request across forks. **Advantages** diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index b33919c7fbe..d11ad53a9d6 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -40,18 +40,18 @@ Consider the following workflow: ## How browser performance testing works First, define a job in your `.gitlab-ci.yml` file that generates the -[Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance). +[Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsbrowser_performance). GitLab then checks this report, compares key performance metrics for each page between the source and target branches, and shows the information in the merge request. -For an example Performance job, see +For an example Browser Performance job, see [Configuring Browser Performance Testing](#configuring-browser-performance-testing). NOTE: If the Browser Performance report has no data to compare, such as when you add the Browser Performance job in your `.gitlab-ci.yml` for the very first time, -the Browser Performance report widget doesn't show. It must have run at least -once on the target branch (`master`, for example), before it displays in a +the Browser Performance report widget doesn't display. It must have run at least +once on the target branch (`main`, for example), before it displays in a merge request targeting that branch.  @@ -70,27 +70,26 @@ using Docker-in-Docker. include: template: Verify/Browser-Performance.gitlab-ci.yml - performance: + browser_performance: variables: URL: https://example.com ``` WARNING: -In GitLab 14.0 and later, the job [is scheduled to be renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/225914) -from `performance` to `browser_performance`. +In GitLab 13.12 and earlier, the job [was named](https://gitlab.com/gitlab-org/gitlab/-/issues/225914) `performance`. The above example: -- Creates a `performance` job in your CI/CD pipeline and runs sitespeed.io against the webpage you +- Creates a `browser_performance` job in your CI/CD pipeline and runs sitespeed.io against the webpage you defined in `URL` to gather key metrics. - Uses a template that doesn't work with Kubernetes clusters. If you are using a Kubernetes cluster, - use [`template: Jobs/Browser-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Browser-Performance-Testing.gitlab-ci.yml) + use [`template: Jobs/Browser-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Browser-Performance-Testing.gitlab-ci.yml) instead. - Uses a CI/CD template that is included in all GitLab installations since 12.4. If you are using GitLab 12.3 or earlier, you must [add the configuration manually](#gitlab-versions-132-and-earlier). The template uses the [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance), -and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance) +and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsbrowser_performance) that you can later download and analyze. This implementation always takes the latest Browser Performance artifact available. If [GitLab Pages](../pages/index.md) is enabled, you can view the report directly in your browser. @@ -108,7 +107,7 @@ makes on the given URL, and change the version: include: template: Verify/Browser-Performance.gitlab-ci.yml -performance: +browser_performance: variables: URL: https://www.sitespeed.io/ SITESPEED_VERSION: 13.2.0 @@ -127,7 +126,7 @@ if the `Total Score` metric degrades by 5 points or more: include: template: Verify/Browser-Performance.gitlab-ci.yml -performance: +browser_performance: variables: URL: https://example.com DEGRADATION_THRESHOLD: 5 @@ -140,13 +139,13 @@ The `Total Score` metric is based on sitespeed.io's [coach performance score](ht The above CI YAML configuration is great for testing against static environments, and it can be extended for dynamic environments, but a few extra steps are required: -1. The `performance` job should run after the dynamic environment has started. +1. The `browser_performance` job should run after the dynamic environment has started. 1. In the `review` job: 1. Generate a URL list file with the dynamic URL. 1. Save the file as an artifact, for example with `echo $CI_ENVIRONMENT_URL > environment_url.txt` in your job's `script`. 1. Pass the list as the URL environment variable (which can be a URL or a file containing URLs) - to the `performance` job. + to the `browser_performance` job. 1. You can now run the sitespeed.io container against the desired hostname and paths. @@ -176,7 +175,7 @@ review: except: - master -performance: +browser_performance: dependencies: - review variables: @@ -191,7 +190,7 @@ GitLab version: - In 13.2 the feature was renamed from `Performance` to `Browser Performance` with additional template CI/CD variables. -- In GitLab 12.4 [a job template was made available](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml). +- In GitLab 12.4 [a job template was made available](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml). - For 11.5 to 12.3 no template is available and the job has to be defined manually as follows: ```yaml diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index adcf4518209..e594f8048e3 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Changes tab in merge requests +# Changes tab in merge requests **(FREE)** The **Changes** tab on a [merge request](index.md), below the main merge request details and next to the discussion tab, shows the changes to files between branches or commits. This view of changes to a @@ -70,21 +70,6 @@ merge request: This change overrides the choice you made in your user preferences and persists until you clear your browser's cookies or change this behavior again. -## Merge requests commit navigation - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. - -To seamlessly navigate among commits in a merge request: - -1. Select the **Commits** tab. -1. Select a commit to open it in the single-commit view. -1. Navigate through the commits by either: - - - Selecting **Prev** and **Next** buttons below the tab buttons. - - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. - - - ## Incrementally expand merge request diffs By default, the diff shows only the parts of a file which are changed. @@ -106,10 +91,6 @@ specific commit page.  -NOTE: -You can append `?w=1` while on the diffs page of a merge request to ignore any -whitespace changes. - ## Mark files as viewed > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9. @@ -149,3 +130,42 @@ To disable it: ```ruby Feature.disable(:local_file_reviews) ``` + +## Show merge request conflicts in diff + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232484) in GitLab 13.5. +> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-merge-request-conflicts-in-diff). **(FREE SELF)** + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../../feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. + +To avoid displaying the changes that are already on target branch in the diff, +we compare the merge request's source branch with HEAD of the target branch. + +When there are conflicts between the source and target branch, we show the +conflicts on the merge request diff as well: + + + +### Enable or disable merge request conflicts in diff **(FREE SELF)** + +Merge request conflicts in diff is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:display_merge_conflicts_in_diff) +``` + +To disable it: + +```ruby +Feature.disable(:display_merge_conflicts_in_diff) +``` diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index eaeef12444e..710638128f3 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -63,10 +63,7 @@ git cherry-pick -m 2 7a39eb0 ### Cherry-pick into a project > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21268) in GitLab 13.11. -> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-cherry-picking-into-a-project). **(FREE SELF)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/324154) in GitLab 14.0 WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -81,24 +78,10 @@ merge request is from a fork: 1. (Optional) Select **Start a new merge request** if you're ready to create a merge request. 1. Click **Cherry-pick**. -### Enable or disable cherry-picking into a project **(FREE SELF)** +## Related links -Cherry-picking into a project is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:pick_into_project) -``` - -To disable it: - -```ruby -Feature.disable(:pick_into_project) -``` +- The [Commits API](../../../api/commits.md) enables you to add custom messages + to changes you cherry-pick through the API. <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 284d66dd591..27642a9bd5d 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -1,6 +1,6 @@ --- -stage: Verify -group: Testing +stage: Secure +group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -54,20 +54,25 @@ See also the Code Climate list of [Supported Languages for Maintainability](http > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.11. > - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 13.12. +> - [Feature enhanced](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) in GitLab 14.0. Changes to files in merge requests can cause Code Quality to fall if merged. In these cases, -an indicator is displayed (**{information-o}** **Code Quality**) on the file in the merge request's diff view. For example: +the merge request's diff view displays an indicator next to lines with new Code Quality violations. For example: + + + +Previously, an indicator was displayed (**{information-o}** **Code Quality**) on the file in the merge request's diff view:  -To disable this feature, a GitLab administrator can run the following in a +To switch to the previous version of this feature, a GitLab administrator can run the following in a [Rails console](../../../administration/operations/rails_console.md): ```ruby # For the instance -Feature.disable(:codequality_mr_diff) +Feature.disable(:codequality_mr_diff_annotations) # For a single project -Feature.disable(:codequality_mr_diff, Project.find(<project id>)) +Feature.disable(:codequality_mr_diff_annotations, Project.find(<project id>)) ``` ## Use cases @@ -527,7 +532,7 @@ This can be due to multiple reasons: - You just added the Code Quality job in your `.gitlab-ci.yml`. The report does not have anything to compare to yet, so no information can be displayed. It only displays after future merge requests have something to compare to. -- Your pipeline is not set to run the code quality job on your default branch. If there is no report generated from the default branch, your MR branch reports have nothing to compare to. +- Your pipeline is not set to run the code quality job on your target branch. If there is no report generated from the target branch, your MR branch reports have nothing to compare to. - If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks), nothing is displayed. - The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md new file mode 100644 index 00000000000..1bda12468a3 --- /dev/null +++ b/doc/user/project/merge_requests/commits.md @@ -0,0 +1,28 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: index, reference +--- + +# Commits tab in merge requests **(FREE)** + +The **Commits** tab in a merge request displays a sequential list of commits +to the Git branch your merge request is based on. From this page, you can review +full commit messages and copy a commit's SHA when you need to +[cherry-pick changes](cherry_pick_changes.md). + +## Merge requests commit navigation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. + +To seamlessly navigate among commits in a merge request: + +1. Select the **Commits** tab. +1. Select a commit to open it in the single-commit view. +1. Navigate through the commits by either: + + - Selecting **Prev** and **Next** buttons below the tab buttons. + - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. + + diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index ce1dac0a96b..430c6488b26 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -168,7 +168,8 @@ Click on **Compare branches and continue** to go to the After forking a project and applying your local changes, complete the following steps to create a merge request from your fork to contribute back to the main project: -1. Go to **Projects > Your Projects** and select your fork of the repository. +1. On the top bar, select **Menu > Project**. +1. Select **Your Projects**, then select your fork of the repository. 1. In the left menu, go to **Merge requests**, and click **New merge request**. 1. In the **Source branch** drop-down list box, select your branch in your forked repository as the source branch. 1. In the **Target branch** drop-down list box, select the branch from the upstream repository as the target branch. diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 459b8fa56ff..ce39f39f0a1 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -67,8 +67,8 @@ After you have created the merge request, you can also: - [Discuss](../../discussions/index.md) your implementation with your team in the merge request thread. - [Perform inline code reviews](reviews/index.md#perform-inline-code-reviews). - Add [merge request dependencies](merge_request_dependencies.md) to restrict it to be merged only when other merge requests have been merged. **(PREMIUM)** -- Preview continuous integration [pipelines on the merge request widget](reviews/index.md#pipeline-status-in-merge-requests-widgets). -- Preview how your changes look directly on your deployed application with [Review Apps](reviews/index.md#live-preview-with-review-apps). +- Preview continuous integration [pipelines on the merge request widget](widgets.md). +- Preview how your changes look directly on your deployed application with [Review Apps](widgets.md#live-preview-with-review-apps). - [Allow collaboration on merge requests across forks](allow_collaboration.md). - Perform a [Review](reviews/index.md) to create multiple comments on a diff and publish them when you're ready. - Add [code suggestions](reviews/suggestions.md) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI. @@ -114,9 +114,6 @@ It is also possible to manage multiple assignees: ### Reviewer -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245190) in GitLab 13.9. - WARNING: Requesting a code review is an important part of contributing code. However, deciding who should review your code and asking for a review are no easy tasks. Using the "assignee" field for both authors and @@ -132,44 +129,7 @@ To request a review of a merge request, expand the **Reviewers** select box in the right-hand sidebar. Search for the users you want to request a review from. When selected, GitLab creates a [to-do list item](../../todos.md) for each reviewer. -#### Approval Rule information for Reviewers **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. - -When editing the **Reviewers** field in a new or existing merge request, GitLab -displays the name of the matching [approval rule](approvals/rules.md) -below the name of each suggested reviewer. [Code Owners](../code_owners.md) are displayed as `Codeowner` without group detail. - -This example shows reviewers and approval rules when creating a new merge request: - - - -This example shows reviewers and approval rules in a merge request sidebar: - - - -#### Requesting a new review - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293933) in GitLab 13.9. - -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 - **{chevron-double-lg-left}** **Expand Sidebar** icon to expand it. -1. In the **Reviewers** section, click 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 -them a notification email. - -#### Approval status - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292936) in GitLab 13.10. - -If a user in the reviewer list has approved the merge request, a green tick symbol is -shown to the right of their name. +To learn more, read [Review and manage merge requests](reviews/index.md). ### Merge requests to close issues @@ -193,7 +153,7 @@ enabled by default for all new merge requests, enable it in the This option is also visible in an existing merge request next to the merge request button and can be selected or deselected before merging. -It is only visible to users with [Maintainer permissions](../../permissions.md) +It is only visible to users with the [Maintainer role](../../permissions.md) in the source project. If the user viewing the merge request does not have the correct @@ -216,18 +176,18 @@ 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 `master`. +- **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 `master` first. Merge request 2 is then - retargeted to `master`. +- 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 `master`. + 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 -`master`, so you don't need to perform this operation manually. Merge requests from +`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 diff --git a/doc/user/project/merge_requests/img/allow_collaboration.png b/doc/user/project/merge_requests/img/allow_collaboration.png Binary files differdeleted file mode 100644 index cc13493646d..00000000000 --- a/doc/user/project/merge_requests/img/allow_collaboration.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/allow_collaboration_after_save.png b/doc/user/project/merge_requests/img/allow_collaboration_after_save.png Binary files differdeleted file mode 100644 index bc7678b21ec..00000000000 --- a/doc/user/project/merge_requests/img/allow_collaboration_after_save.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png b/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png Binary files differnew file mode 100644 index 00000000000..a942420d65e --- /dev/null +++ b/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png diff --git a/doc/user/project/merge_requests/img/commit-button_v13_12.png b/doc/user/project/merge_requests/img/commit-button_v13_12.png Binary files differnew file mode 100644 index 00000000000..be154b9e60b --- /dev/null +++ b/doc/user/project/merge_requests/img/commit-button_v13_12.png diff --git a/doc/user/project/merge_requests/img/conflict_ui_v14_0.png b/doc/user/project/merge_requests/img/conflict_ui_v14_0.png Binary files differnew file mode 100644 index 00000000000..92c532351cb --- /dev/null +++ b/doc/user/project/merge_requests/img/conflict_ui_v14_0.png diff --git a/doc/user/project/merge_requests/reviews/img/merge_request_pipeline.png b/doc/user/project/merge_requests/img/merge_request_pipeline.png Binary files differindex ce1d6bab536..ce1d6bab536 100644 --- a/doc/user/project/merge_requests/reviews/img/merge_request_pipeline.png +++ b/doc/user/project/merge_requests/img/merge_request_pipeline.png diff --git a/doc/user/project/merge_requests/reviews/img/project_merge_requests_list_view_v13_5.png b/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png Binary files differindex 625d47b1142..625d47b1142 100644 --- a/doc/user/project/merge_requests/reviews/img/project_merge_requests_list_view_v13_5.png +++ b/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png diff --git a/doc/user/project/merge_requests/img/status_checks_branches_selector_v14_0.png b/doc/user/project/merge_requests/img/status_checks_branches_selector_v14_0.png Binary files differnew file mode 100644 index 00000000000..65009faf426 --- /dev/null +++ b/doc/user/project/merge_requests/img/status_checks_branches_selector_v14_0.png diff --git a/doc/user/project/merge_requests/img/status_checks_create_form_v14_0.png b/doc/user/project/merge_requests/img/status_checks_create_form_v14_0.png Binary files differnew file mode 100644 index 00000000000..9e6d6c552e5 --- /dev/null +++ b/doc/user/project/merge_requests/img/status_checks_create_form_v14_0.png diff --git a/doc/user/project/merge_requests/img/status_checks_delete_modal_v14_0.png b/doc/user/project/merge_requests/img/status_checks_delete_modal_v14_0.png Binary files differnew file mode 100644 index 00000000000..a305f5c73f8 --- /dev/null +++ b/doc/user/project/merge_requests/img/status_checks_delete_modal_v14_0.png diff --git a/doc/user/project/merge_requests/img/status_checks_list_view_v14_0.png b/doc/user/project/merge_requests/img/status_checks_list_view_v14_0.png Binary files differnew file mode 100644 index 00000000000..6be64112ac6 --- /dev/null +++ b/doc/user/project/merge_requests/img/status_checks_list_view_v14_0.png diff --git a/doc/user/project/merge_requests/img/status_checks_update_form_v14_0.png b/doc/user/project/merge_requests/img/status_checks_update_form_v14_0.png Binary files differnew file mode 100644 index 00000000000..fcfe16bcd97 --- /dev/null +++ b/doc/user/project/merge_requests/img/status_checks_update_form_v14_0.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index f587ab34d11..b5c51c42ae9 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -17,12 +17,93 @@ Merge requests include: - A comment section for discussion threads. - The list of commits. +To get started, read the [introduction to merge requests](getting_started.md). + +## Merge request tabs + Merge requests contain tabs at the top of the page to help you navigate to -important parts of the merge request: **Overview**, **Commits**, **Pipelines**, and **Changes**. +important parts of the merge request:  -To get started, read the [introduction to merge requests](getting_started.md). +- **Overview**: Contains the description, notifications from pipelines, and a + discussion area for [comment threads](../../discussions/index.md#resolvable-comments-and-threads) + and [code suggestions](reviews/suggestions.md). The right sidebar provides fields + to add assignees, reviewers, labels, and a milestone to your work, and the + [merge request widgets area](widgets.md) reports results from pipelines and tests. +- **Commits**: Contains a list of commits added to this merge request. For more + information, read [Commits tab in merge requests](commits.md). +- **Pipelines**: If configured, contains a list of recent [GitLab CI/CD](../../../ci/README.md) + pipelines and their status. +- **Changes**: Contains the diffs of files changed by this merge request. You can + [configure the display](changes.md). + +## View merge requests + +You can view merge requests for a specific project, or for all projects in a group: + +- **Specific project**: Go to your project and select **Merge requests**. +- **All projects in a group**: Go to your group and select **Merge requests**. + If your group contains subgroups, this view also displays merge requests from the subgroup projects. + GitLab displays a count of open merge requests in the left sidebar, but + [caches the value](reviews/index.md#cached-merge-request-count) for groups with a large number of + open merge requests. + +GitLab displays open merge requests, with tabs to filter the list by open and closed status: + + + +You can [search and filter](../../search/index.md#filtering-issue-and-merge-request-lists), +the results, or select a merge request to begin a review. + +## Merge request sidebar + +The **Overview** tab of a merge request displays a sidebar. In this sidebar, you +can assign, categorize, and track progress on a merge request: + +- [**Assignee**](getting_started.md#assignee): Designate the directly responsible + individual (DRI) for a merge request. With + [multiple assignees](getting_started.md#multiple-assignees), you can assign a + merge request to more than one person at a time. +- [**Reviewer**](reviews/index.md): Designate a team member to review a merge request. + Higher tiers can assign multiple reviewers, and [require approvals](approvals/index.md) + from these reviewers. +- [**Milestone**](../milestones/index.md): Track time-sensitive changes. +- [**Time tracking**](../time_tracking.md): Time spent on a merge request. +- [**Labels**](../labels.md): Categorize a merge request and display it on + appropriate [issue boards](../issue_board.md). +- **Participants**: A list of users participating or watching a merge request. +- [**Notifications**](../../profile/notifications.md): A toggle to select whether + or not to receive notifications for updates to a merge request. + +## Close a merge request + +If you decide to permanently stop work on a merge request, +GitLab recommends you close the merge request rather than +[delete it](#delete-a-merge-request). Users with +Developer, Maintainer, or Owner [roles](../../permissions.md) in a project +can close merge requests in the project: + +1. Go to the merge request you want to close. +1. Scroll to the comment box at the bottom of the page. +1. Following the comment box, select **Close merge request**. + +GitLab closes the merge request, but preserves records of the merge request, +its comments, and any associated pipelines. + +### Delete a merge request + +GitLab recommends you close, rather than delete, merge requests. + +WARNING: +You cannot undo the deletion of a merge request. + +To delete a merge request: + +1. Sign in to GitLab as a user with the project Owner [role](../../permissions.md). + Only users with this role can delete merge requests in a project. +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**. ## Merge request workflows diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 865a18a6a05..d1b697add08 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -46,8 +46,8 @@ The key performance metrics that the merge request widget shows after the test c NOTE: If the Load Performance report has no data to compare, such as when you add the Load Performance job in your `.gitlab-ci.yml` for the very first time, -the Load Performance report widget won't show. It must have run at least -once on the target branch (`master`, for example), before it will display in a +the Load Performance report widget doesn't display. It must have run at least +once on the target branch (`main`, for example), before it displays in a merge request targeting that branch. ## Configure the Load Performance Testing job @@ -87,13 +87,13 @@ Refer to the [k6 documentation](https://k6.io/docs/) for detailed information on When your k6 test is ready, the next step is to configure the load performance testing job in GitLab CI/CD. The easiest way to do this is to use the -[`Verify/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Load-Performance-Testing.gitlab-ci.yml) +[`Verify/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Load-Performance-Testing.gitlab-ci.yml) template that is included with GitLab. NOTE: For large scale k6 tests you need to ensure the GitLab Runner instance performing the actual test is able to handle running the test. Refer to [k6's guidance](https://k6.io/docs/testing-guides/running-large-tests#hardware-considerations) -for spec details. The [default shared GitLab.com runners](../../gitlab_com/#linux-shared-runners) +for spec details. The [default shared GitLab.com runners](../../../ci/runners/README.md#linux-shared-runners) likely have insufficient specs to handle most large k6 tests. This template runs the @@ -120,7 +120,7 @@ The above example creates a `load_performance` job in your CI/CD pipeline that r the k6 test. NOTE: -For Kubernetes setups a different template should be used: [`Jobs/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Load-Performance-Testing.gitlab-ci.yml). +For Kubernetes setups a different template should be used: [`Jobs/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Load-Performance-Testing.gitlab-ci.yml). k6 has [various options](https://k6.io/docs/using-k6/options) to configure how it will run tests, such as what throughput (RPS) to run with, how long the test should run, and so on. Almost all options can be configured in the test itself, but as diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 38d6ba062e4..42de04085a9 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -1,5 +1,6 @@ --- redirect_to: 'approvals/index.md' +remove_date: '2021-07-27' --- This document was moved to [another location](approvals/index.md). diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index 4534ce194bf..21282a55ff2 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -38,7 +38,7 @@ For example, given a project `mycorp/awesome-project` that imports a library at `myfriend/awesome-lib`, adding a feature in `awesome-project` may **also** require changes to `awesome-lib`, and so necessitate two merge requests. Merging the `awesome-project` merge request before the `awesome-lib` one would -break the `master`branch. +break the default branch. The `awesome-project` merge request could be [marked as **Draft**](drafts.md), and the reason for the draft stated included in the comments. However, this 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 b1da336aae9..6c1e33a9ace 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -94,7 +94,7 @@ merge-request-pipeline-job: ``` You should avoid configuration like this, and only use branch (`push`) pipelines -or merge request pipelines, when possible. See [`rules` documentation](../../../ci/yaml/README.md#avoid-duplicate-pipelines) +or merge request pipelines, when possible. See [`rules` documentation](../../../ci/jobs/job_control.md#avoid-duplicate-pipelines) for details on avoiding two pipelines for a single merge request. ### Skipped pipelines diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md index 4d5d89d6508..4681ef09388 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -39,8 +39,8 @@ highlighted: After all conflicts have been marked as using 'ours' or 'theirs', the conflict can be resolved. Resolving conflicts merges the target branch of the merge request into the source branch, using the options -chosen. If the source branch is `feature` and the target branch is `master`, -this is similar to performing `git checkout feature; git merge master` locally. +chosen. If the source branch is `feature` and the target branch is `main`, +this is similar to performing `git checkout feature; git merge main` locally. ## Resolve conflicts: inline editor diff --git a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md index 0475996cb9b..b32dce0b230 100644 --- a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md +++ b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md @@ -1,5 +1,6 @@ --- redirect_to: 'reviews/index.md' +remove_date: '2021-08-03' --- This document was moved to [another location](reviews/index.md). diff --git a/doc/user/project/merge_requests/img/reviewer_approval_rules_form_v13_8.png b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v13_8.png Binary files differindex c2aa0689d65..c2aa0689d65 100644 --- a/doc/user/project/merge_requests/img/reviewer_approval_rules_form_v13_8.png +++ b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v13_8.png diff --git a/doc/user/project/merge_requests/img/reviewer_approval_rules_sidebar_v13_8.png b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v13_8.png Binary files differindex 3828868965b..3828868965b 100644 --- a/doc/user/project/merge_requests/img/reviewer_approval_rules_sidebar_v13_8.png +++ b/doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v13_8.png diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index e98a230c0de..317202e9303 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -7,29 +7,14 @@ type: index, reference # Review and manage merge requests **(FREE)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245190) in GitLab 13.9. + [Merge requests](../index.md) are the primary method of making changes to files in a GitLab project. [Create and submit a merge request](../creating_merge_requests.md) -to propose changes. Your team makes [suggestions](suggestions.md) and leaves -[comments](../../../discussions/index.md). When your work is reviewed, your team -members can choose to accept or reject it. - -## View merge requests - -You can view merge requests for a specific project, or for all projects in a group: - -- **Specific project**: Go to your project and select **Merge requests**. -- **All projects in a group**: Go to your group and select **Merge requests**. - If your group contains subgroups, this view also displays merge requests from the subgroup projects. - GitLab displays a count of open merge requests in the left sidebar, but - [caches the value](#cached-merge-request-count) for groups with a large number of - open merge requests. - -GitLab displays open merge requests, with tabs to filter the list by open and closed status: - - - -You can [search and filter](../../../search/index.md#filtering-issue-and-merge-request-lists), -the results, or select a merge request to begin a review. +to propose changes. Your team leaves [comments](../../../discussions/index.md), and +makes [code suggestions](suggestions.md) you can accept from the user interface. +When your work is reviewed, your team members can choose to accept or reject it. ## Bulk edit merge requests at the project level @@ -136,6 +121,45 @@ If you have a review in progress, you will be presented with the option to **Add  +### Approval Rule information for Reviewers **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. + +When editing the **Reviewers** field in a new or existing merge request, GitLab +displays the name of the matching [approval rule](../approvals/rules.md) +below the name of each suggested reviewer. [Code Owners](../../code_owners.md) are displayed as `Codeowner` without group detail. + +This example shows reviewers and approval rules when creating a new merge request: + + + +This example shows reviewers and approval rules in a merge request sidebar: + + + +### Requesting a new review + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293933) in GitLab 13.9. + +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 + **{chevron-double-lg-left}** **Expand Sidebar** icon to expand it. +1. In the **Reviewers** section, click 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 +them a notification email. + +#### Approval status + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292936) in GitLab 13.10. + +If a user in the reviewer list has approved the merge request, a green tick symbol is +shown to the right of their name. + ## Semi-linear history merge requests A merge commit is created for every merge, but the branch is only merged if @@ -180,56 +204,6 @@ Multiline comments display the comment's line numbers above the body of the comm  -## Pipeline status in merge requests widgets - -If you've set up [GitLab CI/CD](../../../../ci/README.md) in your project, -you can see: - -- Both pre-merge and post-merge pipelines and the environment information if any. -- Which deployments are in progress. - -If an application is successfully deployed to an -[environment](../../../../ci/environments/index.md), the deployed environment and the link to the -Review App are both shown. - -NOTE: -When the pipeline fails in a merge request but it can still be merged, -the **Merge** button is colored red. - -### Post-merge pipeline status - -When a merge request is merged, you can see the post-merge pipeline status of -the branch the merge request was merged into. For example, when a merge request -is merged into the [default branch](../../repository/branches/default.md) and then triggers a deployment to the staging -environment. - -Ongoing deployments are shown, and the state (deploying or deployed) -for environments. If it's the first time the branch is deployed, the link -returns a `404` error until done. During the deployment, the stop button is -disabled. If the pipeline fails to deploy, the deployment information is hidden. - - - -For more information, [read about pipelines](../../../../ci/pipelines/index.md). - -### Merge when pipeline succeeds (MWPS) - -Set a merge request that looks ready to merge to -[merge automatically when CI pipeline succeeds](../merge_when_pipeline_succeeds.md). - -### Live preview with Review Apps - -If you configured [Review Apps](https://about.gitlab.com/stages-devops-lifecycle/review-apps/) for your project, -you can preview the changes submitted to a feature branch through a merge request -on a per-branch basis. You don't need to checkout the branch, install, and preview locally. -All your changes are available to preview by anyone with the Review Apps link. - -With GitLab [Route Maps](../../../../ci/review_apps/index.md#route-maps) set, the -merge request widget takes you directly to the pages changed, making it easier and -faster to preview proposed modifications. - -[Read more about Review Apps](../../../../ci/review_apps/index.md). - ## Associated features These features are associated with merge requests: @@ -386,32 +360,7 @@ All the above can be done with the [`git-mr`](https://gitlab.com/glensc/git-mr) ## Cached merge request count > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299542) in GitLab 13.11. -> - It's [deployed behind a feature flag](../../../feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-cached-merge-request-count). - -WARNING: -This feature might not be available to you. Refer to the previous **version history** note for details. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/327319) in GitLab 14.0. In a group, the sidebar displays the total count of open merge requests. This value is cached if it's greater than than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. - -### Enable or disable cached merge request count **(FREE SELF)** - -Cached merge request count in the left sidebar is under development but ready for production use. It is -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../../administration/feature_flags.md) -can disable it. - -To disable it: - -```ruby -Feature.disable(:cached_sidebar_merge_requests_count) -``` - -To enable it: - -```ruby -Feature.enable(:cached_sidebar_merge_requests_count) -``` diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 0c8dd384b88..9409cc569a6 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -140,3 +140,7 @@ to your branch to address your reviewers' requests. WARNING: Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions. + +## Related links + +- [Suggestions API](../../../../api/suggestions.md) diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 4315e5a0305..47c7e208f2d 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -7,7 +7,7 @@ type: reference, concepts # Squash and merge **(FREE)** -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) to GitLab Free in 11.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) from GitLab Premium to GitLab Free in 11.0. With squash and merge you can combine all your merge request's commits into one and retain a clean history. diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md new file mode 100644 index 00000000000..775820870f3 --- /dev/null +++ b/doc/user/project/merge_requests/status_checks.md @@ -0,0 +1,179 @@ +--- +stage: Manage +group: Compliance +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: reference, concepts +disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/status_checks.html' +--- + +# External Status Checks **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab 14.0. +> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-status-checks). **(ULTIMATE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +You can create a status check that sends merge request data to third-party tools. +When users create, change, or close merge requests, GitLab sends a notification. The users or automated workflows +can then update the status of merge requests from outside of GitLab. + +With this integration, you can integrate with third-party workflow tools, like +ServiceNow, or the custom tool of your choice. The third-party tool +respond with an associated status. This status is then displayed as a non-blocking +widget within the merge request to surface this status to the merge request author or reviewers +at the merge request level itself. + +The lack of a status check response does not block the merging of a merge request. + +You can configure merge request status checks for each individual project. These are not shared between projects. + +To learn more about use cases, feature discovery, and development timelines, +see the [external status checks epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). + +## View the status checks on a project + +Within each project's settings, you can see a list of status checks added to the project: + +1. In your project, go to **Settings > General**. +1. Expand the **Merge requests** section. +1. Scroll down to the **Status checks** sub-section. + + + +This list shows the service name, API URL, and targeted branch. +It also provides actions to allow you to create, edit, or remove status checks. + +## Add or update a status check + +### Add a status check + +Within the **Status checks** sub-section, select the **Add status check** button. +The **Add status check** form is then shown. + + + +Filling in the form and selecting the **Add status check** button creates a new status check. + +### Update a status check + +Within the **Status checks** sub-section, select the **Edit** button +next to the status check you want to edit. +The **Update status check** form is then shown. + + + +Changing the values in the form and selecting the **Update status check** button updates the status check. + +### Form values + +For common form errors see the [troubleshooting](#troubleshooting) section below. + +#### Service name + +This name can be any alphanumerical value and **must** be set. The name **must** be unique for +the project. +The name **has** to be unique for the project. + +#### API to check + +This field requires a URL and **must** use either the HTTP or HTTPs protocols. +We **recommend** using HTTPs to protect your merge request data in transit. +The URL **must** be set and **must** be unique for the project. + +#### Target branch + +If you want to restrict the status check to a single branch, +you can use this field to set this limit. + + + +The branches list is populated from the projects [protected branches](../protected_branches.md). + +You can scroll through the list of branches or use the search box +when there are a lot of branches and the branch you are looking +for doesn't appear immediately. The search box requires +**three** alphanumeric characters to be entered for the search to begin. + +If you want the status check to be applied to **all** merge requests, +you can select the **Any branch** option. + +## Delete a status check + +Within the **Status checks** sub-section, select the **Remove...** button +next to the status check you want to delete. +The **Remove status check?** modal is then shown. + + + +To complete the deletion of the status check you must select the +**Remove status check** button. This **permanently** deletes +the status check and it **will not** be recoverable. + +## Troubleshooting + +### Duplicate value errors + +```plaintext +Name is already taken +--- +External API is already in use by another status check +``` + +On a per project basis, status checks can only use a name or API URL once. +These errors mean that either the status checks name or API URL have already +been used in this projects status checks. + +You must either choose a different +value on the current status check or update the value on the existing status check. + +### Invalid URL error + +```plaintext +Please provide a valid URL +``` + +The API to check field requires the URL provided to use either the HTTP or HTTPs protocols. +You must update the value of the field to meet this requirement. + +### Branch list error during retrieval or search + +```plaintext +Unable to fetch branches list, please close the form and try again +``` + +An unexpected response was received from the branches retrieval API. +As suggested, you should close the form and reopen again or refresh the page. This error should be temporary, although +if it persists please check the [GitLab status page](https://status.gitlab.com/) to see if there is a wider outage. + +## Enable or disable status checks **(ULTIMATE SELF)** + +Status checks are under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +# For the instance +Feature.enable(:ff_compliance_approval_gates) +# For a single project +Feature.enable(:ff_compliance_approval_gates, Project.find(<project id>)) +``` + +To disable it: + +```ruby +# For the instance +Feature.disable(:ff_compliance_approval_gates) +# For a single project +Feature.disable(:ff_compliance_approval_gates, Project.find(<project id>) +``` + +## Related links + +- [External status checks API](../../../api/status_checks.md) diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 4960e9d9889..e044d50d246 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Test Coverage Visualization +# Test coverage visualization **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3708) in GitLab 12.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/249811) in GitLab 13.5. @@ -65,53 +65,65 @@ to draw the visualization on the merge request expires **one week** after creati > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217664) in GitLab 13.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284822) in GitLab 13.9. -For the coverage report to properly match the files displayed on a merge request diff, the `filename` of a `class` element -must contain the full path relative to the project root. But in some coverage analysis frameworks, the generated -Cobertura XML has the `filename` path relative to the class package directory instead. +The coverage report properly matches changed files only if the `filename` of a `class` element +contains the full path relative to the project root. However, in some coverage analysis frameworks, +the generated Cobertura XML has the `filename` path relative to the class package directory instead. -To make an intelligent guess on the project root relative `class` path, the Cobertura XML parser attempts to build the -full path by doing the following: +To make an intelligent guess on the project root relative `class` path, the Cobertura XML parser +attempts to build the full path by: -1. Extract a portion of the `source` paths from the `sources` element and combine them with the class `filename` path. -1. Check if the candidate path exists in the project. -1. Use the first candidate that matches as the class full path. +- Extracting a portion of the `source` paths from the `sources` element and combining them with the + class `filename` path. +- Checking if the candidate path exists in the project. +- Using the first candidate that matches as the class full path. -As an example scenario, given the project's full path is `test-org/test-project`, and has the following file tree relative -to the project root: +#### Path correction example -```shell -Auth/User.cs -Lib/Utils/User.cs -src/main/java -``` +As an example, a project with: -In the Cobertura XML, the `filename` attribute in the `class` element assumes the value is a -relative path to project's root. +- A full path of `test-org/test-project`. +- The following files relative to the project root: -```xml -<class name="packet.name" filename="src/main/java" line-rate="0.0" branch-rate="0.0" complexity="5"> -``` + ```shell + Auth/User.cs + Lib/Utils/User.cs + src/main/java + ``` -And the `sources` from Cobertura XML with paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`: +In the: -```xml -<sources> - <source>/builds/test-org/test-project/Auth</source> - <source>/builds/test-org/test-project/Lib/Utils</source> -</sources> -``` +- Cobertura XML, the `filename` attribute in the `class` element assumes the value is a relative + path to the project's root: -The parser extracts `Auth` and `Lib/Utils` from the sources and use these as basis to determine the class path relative to -the project root, combining these extracted sources and the class filename. + ```xml + <class name="packet.name" filename="src/main/java" line-rate="0.0" branch-rate="0.0" complexity="5"> + ``` -If for example there is a `class` element with the `filename` value of `User.cs`, the parser takes the first candidate path -that matches, which is `Auth/User.cs`. +- `sources` from Cobertura XML, the following paths in the format + `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`: -For each `class` element, the parser attempts to look for a match for each extracted `source` path up to `100` iterations. If it reaches this limit without finding a matching path in the file tree, the class will not be included in the final coverage report. + ```xml + <sources> + <source>/builds/test-org/test-project/Auth</source> + <source>/builds/test-org/test-project/Lib/Utils</source> + </sources> + ``` + +The parser: + +- Extracts `Auth` and `Lib/Utils` from the `sources` and uses these to determine the `class` path + relative to the project root. +- Combines these extracted `sources` and the class filename. For example, if there is a `class` + element with the `filename` value of `User.cs`, the parser takes the first candidate path that + matches, which is `Auth/User.cs`. +- For each `class` element, attempts to look for a match for each extracted `source` path up to + 100 iterations. If it reaches this limit without finding a matching path in the file tree, the + class is not included in the final coverage report. NOTE: -The automatic class path correction only works on `source` paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`. If `source` will be ignored if the path does not follow this pattern. The parser assumes that -the `filename` of a `class` element contains the full path relative to the project root. +Automatic class path correction only works on `source` paths in the format `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`. +The `source` is ignored if the path does not follow this pattern. The parser assumes that the +`filename` of a `class` element contains the full path relative to the project root. ## Example test coverage configurations @@ -157,7 +169,7 @@ test-jdk11: coverage-jdk11: # Must be in a stage later than test-jdk11's stage. # The `visualize` stage does not exist by default. - # Please define it first, or chose an existing stage like `deploy`. + # Please define it first, or choose an existing stage like `deploy`. stage: visualize image: registry.gitlab.com/haynes/jacoco2cobertura:1.0.7 script: 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 cc0be389891..55e122dec76 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 @@ -6,7 +6,7 @@ type: index description: "Test your code and display reports in merge requests" --- -# Tests and reports in merge requests +# Tests and reports in merge requests **(FREE)** 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: diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 676af4b2881..1d196de36e2 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -64,7 +64,7 @@ In GitLab 12.10, we added a comparison mode, which shows a diff calculated by simulating how it would look like once merged - a more accurate representation of the changes rather than using the base of the two branches. The new mode is available from the comparison target drop down -by selecting **master (HEAD)**. In GitLab 13.9, it +by selecting **main (HEAD)**. In GitLab 13.9, it [replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/198458) the old default comparison. For technical details, additional information is available in the [developer documentation](../../../development/diffs.md#merge-request-diffs-against-the-head-of-the-target-branch). diff --git a/doc/user/project/merge_requests/widgets.md b/doc/user/project/merge_requests/widgets.md new file mode 100644 index 00000000000..92b2a8f24ef --- /dev/null +++ b/doc/user/project/merge_requests/widgets.md @@ -0,0 +1,64 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: index, reference +--- + +# Merge request widgets **(FREE)** + +The **Overview** page of a merge request displays status updates from services +that perform actions on your merge request. All subscription levels display a +widgets area, but the content of the area depends on your subscription level +and the services you configure for your project. + +## Pipeline information + +If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, +a [merge request](index.md) displays pipeline information in the widgets area +of the **Overview** tab: + +- Both pre-merge and post-merge pipelines, and the environment information, if any. +- Which deployments are in progress. + +If an application is successfully deployed to an +[environment](../../../ci/environments/index.md), the deployed environment and the link to the +[review app](https://about.gitlab.com/stages-devops-lifecycle/review-apps/) are both shown. + +NOTE: +When the pipeline fails in a merge request but it can still be merged, +the **Merge** button is colored red. + +## Post-merge pipeline status + +When a merge request is merged, you can see the post-merge pipeline status of +the branch the merge request was merged into. For example, when a merge request +is merged into the [default branch](../repository/branches/default.md) and then triggers a deployment to the staging +environment. + +Ongoing deployments are shown, and the state (deploying or deployed) +for environments. If it's the first time the branch is deployed, the link +returns a `404` error until done. During the deployment, the stop button is +disabled. If the pipeline fails to deploy, the deployment information is hidden. + + + +For more information, [read about pipelines](../../../ci/pipelines/index.md). + +## Merge when pipeline succeeds (MWPS) + +Set a merge request that looks ready to merge to +[merge automatically when CI pipeline succeeds](merge_when_pipeline_succeeds.md). + +## Live preview with Review Apps + +If you configured [Review Apps](https://about.gitlab.com/stages-devops-lifecycle/review-apps/) for your project, +you can preview the changes submitted to a feature branch through a merge request +on a per-branch basis. You don't need to checkout the branch, install, and preview locally. +All your changes are available to preview by anyone with the Review Apps link. + +With GitLab [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the +merge request widget takes you directly to the pages changed, making it easier and +faster to preview proposed modifications. + +[Read more about Review Apps](../../../ci/review_apps/index.md). diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md index 4b854da116e..8b663b8edf8 100644 --- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md +++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md @@ -1,5 +1,6 @@ --- redirect_to: 'drafts.md' +remove_date: '2021-05-19' --- This document was moved to [another location](drafts.md). diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 2399774c96d..3f7d5b6aac1 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -38,8 +38,8 @@ You can assign **group milestones** to any issue or merge request of any project To view the group milestone list, in a group, go to **{issues}** **Issues > Milestones**. You can also view all milestones you have access to in the dashboard milestones list. -To view both project milestones and group milestones you have access to, select **More > Milestones** -on the top navigation bar. +To view both project milestones and group milestones you have access to, select **Menu > Milestones** +on the top bar. For information about project and group milestones API, see: diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index f7e8d3d140c..55fde63dd47 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -1,5 +1,6 @@ --- redirect_to: '../../ci/README.md' +remove_date: '2021-06-01' --- This document is deprecated. See the latest [GitLab CI/CD documentation](../../ci/README.md). diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index f02697a3cd5..410fdab15e7 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 @@ -5,7 +5,7 @@ group: Release 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 --- -# DNS records overview +# DNS records overview **(FREE)** _Read this document for a brief overview of DNS records in the scope of GitLab Pages, for beginners in web development._ 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 8ed0ef82893..8c77714a2de 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 @@ -5,7 +5,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Custom domains and SSL/TLS Certificates +# Custom domains and SSL/TLS certificates **(FREE)** Setting up GitLab Pages with custom domains, and adding SSL/TLS certificates to them, are optional features of GitLab Pages. @@ -114,7 +114,7 @@ without any `/project-name`. ##### For both root and subdomains -There are a few cases where you need point both subdomain and root +There are a few cases where you need to point both the subdomain and root domain to the same website, for instance, `example.com` and `www.example.com`. They require: 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 86e34842aaf..f0a922ff390 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 @@ -6,7 +6,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Pages integration with Let's Encrypt +# GitLab Pages integration with Let's Encrypt **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28996) in GitLab 12.1. For versions earlier than GitLab 12.1, see the [manual Let's Encrypt instructions](../lets_encrypt_for_gitlab_pages.md). @@ -67,7 +67,7 @@ associated Pages domain. GitLab also renews it automatically. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30146) in GitLab 13.0. -If you get an error **Something went wrong while obtaining the Let's Encrypt certificate**, you can try obtaining the certificate again by following these steps: +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 > Visbility**. 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. 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 f79c60a933a..48412f48c12 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 @@ -5,7 +5,7 @@ group: Release 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 --- -# SSL/TLS Certificates +# SSL/TLS certificates **(FREE)** _Read this document for a brief overview of SSL/TLS certificates in the scope of GitLab Pages, for beginners in web development._ diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index 30dd337d9d8..4f2b62beab1 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -5,7 +5,7 @@ group: Release 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 Pages website by using a CI/CD template +# Create a Pages website by using a CI/CD template **(FREE)** GitLab provides `.gitlab-ci.yml` templates for the most popular Static Site Generators (SSGs). You can create your own `.gitlab-ci.yml` file from one of these templates, and run @@ -17,7 +17,7 @@ Your GitLab repository should contain files specific to an SSG, or plain HTML. After you complete these steps, you may need to do additional configuration for the Pages site to generate properly. -1. In the left sidebar, click **Project overview**. +1. On the left sidebar, select **Project information**. 1. Click **Set up CI/CD**.  diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md index d9ec2aae2b7..386ed566225 100644 --- a/doc/user/project/pages/getting_started/pages_forked_sample_project.md +++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md @@ -5,7 +5,7 @@ group: Release 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 Pages website from a forked sample +# Create a Pages website from a forked sample **(FREE)** GitLab provides [sample projects for the most popular Static Site Generators (SSG)](https://gitlab.com/pages). You can fork one of the sample projects and run the CI/CD pipeline to generate a Pages website. diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index 8368b38bc80..9f80e2e7613 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -4,7 +4,7 @@ group: Release 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 GitLab Pages website from scratch +# Create a GitLab Pages website from scratch **(FREE)** This tutorial shows you how to create a Pages site from scratch. You start with a blank project and create your own CI file, which gives instruction to 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 36371573fd9..f52f64626ac 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 @@ -5,7 +5,7 @@ group: Release 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 Pages website from a template +# Create a Pages website from a template **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47857) in GitLab 11.8. @@ -26,7 +26,6 @@ configured to generate a Pages site. and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your site. -The site can take approximately 30 minutes to deploy. When the pipeline is finished, go to **Settings > Pages** to find the link to your Pages website. diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 9eb80e3287c..32826346eab 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -4,7 +4,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Pages domain names, URLs, and base URLs +# GitLab Pages domain names, URLs, and base URLs **(FREE)** On this document, learn how to name your project for GitLab Pages according to your intended website's URL. diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 2ff91292b1b..1f5e1a6ab45 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -5,7 +5,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Pages +# GitLab Pages **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80) in GitLab Enterprise Edition 8.3. > - Custom CNAMEs with TLS support were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/173) in GitLab Enterprise Edition 8.5. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 18acb360f5a..4d6a8653657 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -4,7 +4,7 @@ group: Release 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 --- -# Exploring GitLab Pages +# Exploring GitLab Pages **(FREE)** This document is a user guide to explore the options and settings GitLab Pages offers. @@ -324,4 +324,4 @@ pages: - public ``` -The `FF_USE_FASTZIP` variable enables the [feature flag](https://docs.gitlab.com/runner/configuration/feature-flags.html#available-feature-flags) which is needed for [`ARTIFACT_COMPRESSION_LEVEL`](../../../ci/runners/README.md#artifact-and-cache-settings). +The `FF_USE_FASTZIP` variable enables the [feature flag](https://docs.gitlab.com/runner/configuration/feature-flags.html#available-feature-flags) which is needed for [`ARTIFACT_COMPRESSION_LEVEL`](../../../ci/runners/configure_runners.md#artifact-and-cache-settings). diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md index b5932fc8766..ce49699785e 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w description: "How to secure GitLab Pages websites with Let's Encrypt (manual process, deprecated)." --- -# Let's Encrypt for GitLab Pages (manual process, deprecated) +# Let's Encrypt for GitLab Pages (manual process, deprecated) **(FREE)** WARNING: This method is still valid but was **deprecated** in favor of the diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 2e0fc87b3df..532a36b2327 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -5,7 +5,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Pages Access Control +# GitLab Pages access control **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33422) in GitLab 11.5. > - Available on GitLab.com in GitLab 12.4. diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index 8c189614102..8ed6f214605 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -4,7 +4,7 @@ group: Release 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 redirects for GitLab Pages +# Create redirects for GitLab Pages **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24) in GitLab Pages 1.25.0 and GitLab 13.4 behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/367) in GitLab 13.5. diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 673a756f18d..4b77236f808 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -36,7 +36,7 @@ The default branch protection level is set in the [Admin Area](../admin_area/set Prerequisite: -- You must have at least maintainer permissions. +- You must have at least the [Maintainer role](../permissions.md). To protect a branch: @@ -163,7 +163,7 @@ To create a new branch through the user interface: ## Delete a protected branch From time to time, you may need to delete or clean up protected branches. -User with [Maintainer permissions](../permissions.md) and greater can manually delete protected +User with the [Maintainer role](../permissions.md) and greater can manually delete protected branches by using the GitLab web interface: 1. Go to **Repository > Branches**. @@ -179,24 +179,22 @@ command line or a Git client application. ## Allow force push on protected branches > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15611) in GitLab 13.10 behind a disabled feature flag. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-allow-force-push-on-protected-branches). +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323431) in GitLab 14.0. WARNING: This feature might not be available to you. Check the **version history** note above for details. -You can allow force pushes to protected branches by either setting **Allow force push** +You can allow [force pushes](../../topics/git/git_rebase.md#force-push) to +protected branches by either setting **Allowed to force push** when you protect a new branch, or by configuring an already-protected branch. To protect a new branch and enable Force push: 1. Navigate to your project's **Settings > Repository**. 1. Expand **Protected branches**, and scroll to **Protect a branch**. -  1. Select a **Branch** or wildcard you'd like to protect. 1. Select the user levels **Allowed to merge** and **Allowed to push**. -1. To allow all users with push access to force push, toggle the **Allow force push** slider. +1. To allow all users with push access to force push, toggle the **Allowed to force push** slider. 1. To reject code pushes that change files listed in the `CODEOWNERS` file, toggle **Require approval from code owners**. 1. Click **Protect**. @@ -205,8 +203,7 @@ To enable force pushes on branches already protected: 1. Navigate to your project's **Settings > Repository**. 1. Expand **Protected branches** and scroll to **Protected branch**. -  -1. Toggle the **Allow force push** slider for the chosen branch. +1. Toggle the **Allowed to force push** slider for the chosen branch. When enabled, members who are allowed to push to this branch can also force push. @@ -226,15 +223,11 @@ To protect a new branch and enable Code Owner's approval: 1. Scroll down to **Protect a branch**, select a **Branch** or wildcard you'd like to protect, select who's **Allowed to merge** and **Allowed to push**, and toggle the **Require approval from code owners** slider. 1. Click **Protect**. - - To enable Code Owner's approval to branches already protected: 1. Navigate to your project's **Settings > Repository** and expand **Protected branches**. 1. Scroll down to **Protected branch** and toggle the **Code owner approval** slider for the chosen branch. - - When enabled, all merge requests targeting these branches require approval by a Code Owner per matched rule before they can be merged. Additionally, direct pushes to the protected branch are denied if a rule is matched. @@ -249,25 +242,6 @@ run CI/CD pipelines and execute actions on jobs that are related to those branch See [Security on protected branches](../../ci/pipelines/index.md#pipeline-security-on-protected-branches) for details about the pipelines security model. -## Enable or disable allow force push on protected branches **(FREE SELF)** - -Allow force push on protected branches is ready for -production use. It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:allow_force_push_to_protected_branches) -``` - -To disable it: - -```ruby -Feature.disable(:allow_force_push_to_protected_branches) -``` - ## Changelog - **13.5**: [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769). diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 260f355349d..17a9cd5c8c6 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -21,7 +21,7 @@ anyone without Maintainer [permissions](../permissions.md) is prevented from cre ## Configuring protected tags -To protect a tag, you need to have at least Maintainer [permissions](../permissions.md). +To protect a tag, you need to have at least the [Maintainer role](../permissions.md). 1. Go to the project's **Settings > Repository**. diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index e1815785fb5..45cb5e74d6c 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -111,7 +111,6 @@ threads. Some quick actions might not be available to all subscription tiers. | `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. | | `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. | | `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. | -| `/wip` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Toggle the draft status. | | `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add Zoom meeting to this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | ## Commit messages diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 1ea21b1f269..71cbff9e545 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -33,7 +33,7 @@ and attach [release assets](#release-assets), like runbooks or packages. To view a list of releases: -- Go to **Project overview > Releases**, or +- On the left sidebar, select **Deployments > Releases**, or - On the project's overview page, if at least one release exists, click the number of releases. @@ -64,8 +64,7 @@ Read more about [Release permissions](../../../user/permissions.md#project-membe To create a new release through the GitLab UI: -1. Navigate to **Project overview > Releases** and click the **New release** - button. +1. On the left sidebar, select **Deployments > Releases** and select **New release**. 1. Open the [**Tag name**](#tag-name) dropdown. Select an existing tag or type in a new tag name. Selecting an existing tag that is already associated with a release will result in a validation error. @@ -105,7 +104,7 @@ Read more about [Release permissions](../../../user/permissions.md#project-membe To edit the details of a release: -1. Navigate to **Project overview > Releases**. +1. On the left sidebar, select **Deployments > Releases**. 1. In the top-right corner of the release you want to modify, click **Edit this release** (the pencil icon). 1. On the **Edit Release** page, change the release's details. 1. Click **Save changes**. @@ -151,12 +150,12 @@ the [Releases API](../../../api/releases/index.md#create-a-release). In the user interface, to associate milestones to a release: -1. Navigate to **Project overview > Releases**. +1. On the left sidebar, select **Deployments > Releases**. 1. In the top-right corner of the release you want to modify, click **Edit this release** (the pencil icon). 1. From the **Milestones** list, select each milestone you want to associate. You can select multiple milestones. 1. Click **Save changes**. -On the **Project overview > Releases** page, the **Milestone** is listed in the top +On the **Deployments > Releases** page, the **Milestone** is listed in the top section, along with statistics about the issues in the milestones.  @@ -176,7 +175,7 @@ You can be notified by email when a new release is created for your project. To subscribe to notifications for releases: -1. Navigate to **Project overview**. +1. On the left sidebar, select **Project information**. 1. Click **Notification setting** (the bell icon). 1. In the list, click **Custom**. 1. Select the **New release** check box. @@ -209,8 +208,8 @@ deploy_to_production: To set a deploy freeze window in the UI, complete these steps: -1. Sign in to GitLab as a user with project Maintainer [permissions](../../permissions.md). -1. Navigate to **Project overview**. +1. Sign in to GitLab as a user with the [Maintainer role](../../permissions.md). +1. On the left sidebar, select **Project information**. 1. In the left navigation menu, navigate to **Settings > CI/CD**. 1. Scroll to **Deploy freezes**. 1. Click **Expand** to see the deploy freeze table. diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index deacf119d38..6c2469ac377 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -65,7 +65,8 @@ GitLab [administrators](../../../permissions.md) of self-managed instances can customize the initial branch for projects hosted on that instance. Individual groups and subgroups can override this instance-wide setting for their projects. -1. Go to **Admin Area > Settings > Repository**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > Repository**. 1. Expand **Default initial branch name**. 1. Change the default initial branch to a custom name of your choice. 1. Select **Save changes**. diff --git a/doc/user/project/repository/img/download_source_code.png b/doc/user/project/repository/img/download_source_code.png Binary files differdeleted file mode 100644 index 8d62d19b291..00000000000 --- a/doc/user/project/repository/img/download_source_code.png +++ /dev/null diff --git a/doc/user/project/repository/img/file_ext_icons_repo_v12_10.png b/doc/user/project/repository/img/file_ext_icons_repo_v12_10.png Binary files differdeleted file mode 100644 index 04a8f38871b..00000000000 --- a/doc/user/project/repository/img/file_ext_icons_repo_v12_10.png +++ /dev/null diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index ed5bcc1f85a..7919850b8cc 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -8,75 +8,142 @@ type: concepts, howto # Repository **(FREE)** A [repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository) -is what you use to store your codebase in GitLab and change it with version control. -A repository is part of a [project](../index.md), which has a lot of other features. +is where you store your code and make changes to it. Your changes are tracked with version control. + +Each [project](../index.md) contains a repository. ## Create a repository -To create a new repository, all you need to do is -[create a new project](../../../user/project/working_with_projects.md#create-a-project) or -[fork an existing project](forking_workflow.md). +To create a repository, you can: + +- [Create a project](../../../user/project/working_with_projects.md#create-a-project) or +- [Fork an existing project](forking_workflow.md). + +## Add files to a repository + +You can add files to a repository: + +- When you create a project. +- After you create a project: + - By using [the web editor](web_editor.md). + - [From the command line](../../../gitlab-basics/command-line-commands.md). + +## Commit changes to a repository + +You can [commit your changes](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository), +to a branch in the repository. When you use the command line, you can commit multiple times before you push. + +- **Commit message:** + A commit message identities what is being changed and why. + In GitLab, you can add keywords to the commit + message to perform one of the following actions: + - **Trigger a GitLab CI/CD pipeline:** + If the project is configured with [GitLab CI/CD](../../../ci/README.md), + you trigger a pipeline per push, not per commit. + - **Skip pipelines:** + Add the [`ci skip`](../../../ci/yaml/README.md#skip-pipeline) keyword to + your commit message to make GitLab CI/CD skip the pipeline. + - **Cross-link issues and merge requests:** + Use [cross-linking](../issues/crosslinking_issues.md#from-commit-messages) + to keep track of related parts of your workflow. + If you mention an issue or a merge request in a commit message, they are displayed + on their respective thread. +- **Cherry-pick a commit:** + In GitLab, you can + [cherry-pick a commit](../merge_requests/cherry_pick_changes.md#cherry-picking-a-commit) + from the UI. +- **Revert a commit:** + [Revert a commit](../merge_requests/revert_changes.md#reverting-a-commit) + from the UI to a selected branch. +- **Sign a commit:** + Use GPG to [sign your commits](gpg_signed_commits/index.md). + +## Clone a repository + +You can [clone a repository by using the command line](../../../gitlab-basics/start-using-git.md#clone-a-repository). + +Alternatively, you can clone directly into a code editor. + +### Clone and open in Apple Xcode + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45820) in GitLab 11.0. + +Projects that contain a `.xcodeproj` or `.xcworkspace` directory can be cloned +into Xcode on macOS. + +1. From the GitLab UI, go to the project's overview page. +1. Select **Clone**. +1. Select **Xcode**. + +The project is cloned onto your computer and you are +prompted to open XCode. + +### Clone and open in Visual Studio Code + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220957) in GitLab 13.10. + +All projects can be cloned into Visual Studio Code. To do that: + +1. From the GitLab UI, go to the project's overview page. +1. Click **Clone**. +1. Select **Clone with Visual Studio Code** under either HTTPS or SSH method. +1. Select a folder to clone the project into. + +When VS Code has successfully cloned your project, it opens the folder. -Once you create a new project, you can add new files via UI -(read the section below) or via command line. -To add files from the command line, follow the instructions -presented on the screen when you create a new project, or read -through them in the [command line basics](../../../gitlab-basics/start-using-git.md) -documentation. +## Download the code in a repository -> **Important:** -For security reasons, when using the command line, we strongly recommend -that you [connect with GitLab via SSH](../../../ssh/README.md). +> - Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/24704) in GitLab 11.11. +> - Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. -## Files +You can download the source code that's stored in a repository. -Use a repository to store your files in GitLab. In [GitLab 12.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33806), -an icon identifying the extension is shown next to the filename: +1. Above the file list, select the download icon (**{download}**). +1. From the options, select the files you want to download. - + - **Source code:** + Download the source code from the current branch you're viewing. + Available extensions: `zip`, `tar`, `tar.gz`, and `tar.bz2`. + - **Directory:** + Download a specific directory. Visible only when you view a subdirectory. + Available extensions: `zip`, `tar`, `tar.gz`, and `tar.bz2`. + - **Artifacts:** + Download the artifacts from the latest CI job. -### Create and edit files +## Repository languages -Host your codebase in GitLab repositories by pushing your files to GitLab. -You can either use the user interface (UI), or connect your local computer -with GitLab [through the command line](../../../gitlab-basics/command-line-commands.md#start-working-on-your-project). +For the default branch of each repository, GitLab determines which programming languages +are used. This information is displayed on the **Project information** page. -To configure [GitLab CI/CD](../../../ci/README.md) to build, test, and deploy -your code, add a file called [`.gitlab-ci.yml`](../../../ci/quick_start/index.md) -to your repository's root. + -**From the user interface:** +When new files are added, this information can take up to five minutes to update. -The GitLab UI allows you to perform lots of Git commands without having to -touch the command line. Even if you use the command line regularly, sometimes -it's easier to do so [via GitLab UI](web_editor.md): +### Add repository languages -- [Create a file](web_editor.md#create-a-file) -- [Upload a file](web_editor.md#upload-a-file) -- [File templates](web_editor.md#template-dropdowns) -- [Create a directory](web_editor.md#create-a-directory) -- [Start a merge request](web_editor.md#tips) -- [Find file history](git_history.md) -- [Identify changes by line (Git blame)](git_blame.md) +Not all files are detected and listed on the **Project information** page. Documentation, +vendor code, and most markup languages are excluded. -**From the command line:** +You can change this behavior by overriding the default settings. -To get started with the command line, please read through the -[command line basics documentation](../../../gitlab-basics/command-line-commands.md). +1. In your repository's root directory, create a file named `.gitattributes`. +1. Add a line that tells GitLab to include files of this type. For example, + to enable `.proto` files, add the following code: -### Find files + ```plaintext + *.proto linguist-detectable=true + ``` -Use the GitLab [file finder](file_finder.md) to search for files in a repository. +View a list of +[supported data types](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml). -### Supported markup languages and extensions +This feature can use excessive CPU. +For more information, see the [troubleshooting section](#repository-languages-excessive-cpu-use). -GitLab supports a number of markup languages (sometimes called [lightweight -markup languages](https://en.wikipedia.org/wiki/Lightweight_markup_language)) -that you can use for the content of your files in a repository. They are mostly -used for documentation purposes. +### Supported markup languages -Just pick the right extension for your files and GitLab renders them -according to the markup language. +If your file has one of the following file extensions, GitLab renders the +contents of the file's [markup language](https://en.wikipedia.org/wiki/Lightweight_markup_language) in the UI. | Markup language | Extensions | | --------------- | ---------- | @@ -90,38 +157,25 @@ according to the markup language. | [creole](http://www.wikicreole.org/) | `creole` | | [MediaWiki](https://www.mediawiki.org/wiki/MediaWiki) | `wiki`, `mediawiki` | -### Repository README and index files - -When a `README` or `index` file is present in a repository, its contents are -automatically pre-rendered by GitLab without opening it. - -They can either be plain text or have an extension of a -[supported markup language](#supported-markup-languages-and-extensions): - -Some things to note about precedence: +### README and index files -1. When both a `README` and an `index` file are present, the `README` always - takes precedence. -1. When more than one file is present with different extensions, they are - ordered alphabetically, with the exception of a file without an extension, - which is always last in precedence. For example, `README.adoc` takes - precedence over `README.md`, and `README.rst` takes precedence over - `README`. +When a `README` or `index` file is present in a repository, GitLab renders its contents. +These files can either be plain text or have the extension of a +[supported markup language](#supported-markup-languages). -### Jupyter Notebook files - -[Jupyter](https://jupyter.org/) Notebook (previously IPython Notebook) files are used for -interactive computing in many fields and contain a complete record of the -user's sessions and include code, narrative text, equations, and rich output. - -[Read how to use Jupyter notebooks with GitLab.](jupyter_notebooks/index.md) +- When both a `README` and an `index` file are present, the `README` always + takes precedence. +- When multiple files have the same name but a different extension, the files are + ordered alphabetically. Any file without an extension is ordered last. + For example, `README.adoc` takes precedence over `README.md`, and `README.rst` + takes precedence over `README`. ### OpenAPI viewer > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19515) in GitLab 12.6. -GitLab can render OpenAPI specification files with its file viewer, provided -their filenames include `openapi` or `swagger` and their extension is `yaml`, +GitLab can render OpenAPI specification files. The filename +must include `openapi` or `swagger` and the extension must be `yaml`, `yml`, or `json`. The following examples are all correct: - `openapi.yml` @@ -138,200 +192,73 @@ their filenames include `openapi` or `swagger` and their extension is `yaml`, - `openapi.gitlab.yml` - `gitlab.openapi.yml` -Then, to render them: +To render an OpenAPI file: -1. Navigate to the OpenAPI file in your repository in the GitLab UI. -1. Click the "Display OpenAPI" button which is located between the "Display source" - and "Edit" buttons (when an OpenAPI file is found, it replaces the - "Display rendered file" button). +1. Go to the OpenAPI file in your repository. +1. Between the **Display source** and **Edit** buttons, select **Display OpenAPI**. When an OpenAPI file is found, it replaces the + **Display rendered file** button. -## Branches +## Repository size -For details, see [Branches](branches/index.md). +The **Project information** page shows the size of all files in the repository. The size is +updated, at most, every 15 minutes. The file size includes repository files, artifacts, and LFS. -## Commits +The size can differ slightly from one instance to another due to compression, housekeeping, and other factors. -When you [commit your changes](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository), -you are introducing those changes to your branch. -Via command line, you can commit multiple times before pushing. +Administrators can set a [repository size limit](../../admin_area/settings/account_and_limit_settings.md). +[GitLab sets the size limits for GitLab.com](../../gitlab_com/index.md#account-and-limit-settings). -- **Commit message:** - A commit message is important to identity what is being changed and, - more importantly, why. In GitLab, you can add keywords to the commit - message that performs one of the actions below: - - **Trigger a GitLab CI/CD pipeline:** - If you have your project configured with [GitLab CI/CD](../../../ci/README.md), - you trigger a pipeline per push, not per commit. - - **Skip pipelines:** - You can add to your commit message the keyword - [`[ci skip]`](../../../ci/yaml/README.md#skip-pipeline), - and GitLab CI/CD skips that pipeline. - - **Cross-link issues and merge requests:** - [Cross-linking](../issues/crosslinking_issues.md#from-commit-messages) - is great to keep track of what's is somehow related in your workflow. - If you mention an issue or a merge request in a commit message, they are shown - on their respective thread. -- **Cherry-pick a commit:** - In GitLab, you can - [cherry-pick a commit](../merge_requests/cherry_pick_changes.md#cherry-picking-a-commit) - right from the UI. -- **Revert a commit:** - Easily [revert a commit](../merge_requests/revert_changes.md#reverting-a-commit) - from the UI to a selected branch. -- **Sign a commit:** - Use GPG to [sign your commits](gpg_signed_commits/index.md). - -## Project and repository size +## Repository contributor graph -A project's size is reported on the project's **Details** page. The reported size is -updated every 15 minutes at most, so may not reflect recent activity. The displayed files size includes repository files, artifacts, and LFS. +All code contributors are displayed under your project's **Repository > Contributors**. -The project size may differ slightly from one instance to another due to compression, housekeeping, and other factors. - -[Repository size limit](../../admin_area/settings/account_and_limit_settings.md) may be set by administrators. -GitLab.com's repository size limit [is set by GitLab](../../gitlab_com/index.md#account-and-limit-settings). - -## Contributors - -All the contributors to your codebase are displayed under your project's **Settings > Contributors**. - -They are ordered from the collaborator with the greatest number -of commits to the fewest, and displayed on a nice graph: +The graph shows the contributor with the most commits to the fewest.  -## Repository graph - -The repository graph displays the history of the repository network visually, including branches and merges. This can help you visualize the Git flow strategy used in the repository: - - - -Find it under your project's **Repository > Graph**. +## Repository history graph -## Repository languages - -For the default branch of each repository, GitLab determines what programming languages -were used and displays this on the project's pages. If this information is missing, it's -added after updating the default branch for the project. This process can take up to five -minutes. - - - -Not all files are detected, among others; documentation, -vendored code, and most markup languages are excluded. This behavior can be -adjusted by overriding the default. For example, to enable `.proto` files to be -detected, add the following to `.gitattributes` in the root of your repository. - -```plaintext -*.proto linguist-detectable=true -``` - -Sometimes this feature can use excessive CPU. -[Read about troubleshooting this](#repository-languages-excessive-cpu-use) -and also more about customizing this feature using `.gitattributes`. - -## Locked files **(PREMIUM)** +A repository graph displays a visual history of the repository network, including branches and merges. +This graph can help you visualize the Git flow strategy used in the repository. -Use [File Locking](../file_lock.md) to -lock your files to prevent any conflicting changes. - -## Repository's API - -You can access your repositories via [repository API](../../../api/repositories.md). - -## Clone a repository - -Learn how to [clone a repository through the command line](../../../gitlab-basics/start-using-git.md#clone-a-repository). - -Alternatively, clone directly into a code editor as documented below. - -### Clone and open in Apple Xcode +Go to your project's **Repository > Graph**. -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45820) in GitLab 11.0. - -Projects that contain a `.xcodeproj` or `.xcworkspace` directory can now be cloned -into Xcode on macOS. To do that: - -1. From the GitLab UI, go to the project's overview page. -1. Click **Clone**. -1. Select **Xcode**. - -The project is cloned onto your computer in a folder of your choice and you are -prompted to open XCode. - -### Clone and open in Visual Studio Code - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220957) in GitLab 13.10. - -All projects can be cloned into Visual Studio Code. To do that: - -1. From the GitLab UI, go to the project's overview page. -1. Click **Clone**. -1. Select **VS Code**. -1. Select a folder to clone the project into. - -When VS Code has successfully cloned your project, it opens the folder. - -## Download source code - -> - Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/24704) in GitLab 11.11. -> - Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. - -The source code stored in a repository can be downloaded from the UI. -By clicking the download icon, a dropdown opens with links to download the following: - - - -- **Source code:** - allows users to download the source code on branch they're currently - viewing. Available extensions: `zip`, `tar`, `tar.gz`, and `tar.bz2`. -- **Directory:** - only shows up when viewing a sub-directory. This allows users to download - the specific directory they're currently viewing. Also available in `zip`, - `tar`, `tar.gz`, and `tar.bz2`. -- **Artifacts:** - allows users to download the artifacts of the latest CI build. - -## Redirects when changing repository paths + -When a repository path changes, it is essential to smoothly transition from the -old location to the new one. GitLab provides two kinds of redirects: the web UI -and Git push/pull redirects. +## What happens when a repository path changes -Depending on the situation, different things apply. +When a repository path changes, GitLab handles the transition from the +old location to the new one with a redirect. -When [renaming a user](../../profile/index.md#change-your-username), -[changing a group path](../../group/index.md#change-a-groups-path) or [renaming a repository](../settings/index.md#renaming-a-repository): +When you [rename a user](../../profile/index.md#change-your-username), +[change a group path](../../group/index.md#change-a-groups-path), or [rename a repository](../settings/index.md#renaming-a-repository): -- Existing web URLs for the namespace and anything under it (such as projects) will - redirect to the new URLs. -- Starting with GitLab 10.3, existing Git remote URLs for projects under the - namespace redirect to the new remote URL. Every time you push/pull to a - repository that has changed its location, a warning message to update - your remote is displayed instead of rejecting your action. - This means that any automation scripts, or Git clients continue to - work after a rename, making any transition a lot smoother. +- URLs for the namespace and everything under it, like projects, are + redirected to the new URLs. +- Git remote URLs for projects under the + namespace redirect to the new remote URL. When you push or pull to a + repository that has changed location, a warning message to update + your remote is displayed. Automation scripts or Git clients continue to + work after a rename. - The redirects are available as long as the original path is not claimed by - another group, user or project. + another group, user, or project. ## Troubleshooting ### Repository Languages: excessive CPU use -GitLab uses a Ruby gem to scan all the files in the repository to determine what languages are used. -[Sometimes this can use excessive CPU](https://gitlab.com/gitlab-org/gitaly/-/issues/1565) if -a file type needs to be parsed by the gem to determine what sort of file it is. +To determine which languages are in a repository's files, GitLab uses a Ruby gem. +When the gem parses a file to determine which type it is, [the process can use excessive CPU](https://gitlab.com/gitlab-org/gitaly/-/issues/1565). The gem contains a [heuristics configuration file](https://github.com/github/linguist/blob/master/lib/linguist/heuristics.yml) -that defines what file extensions need to be parsed. +that defines which file extensions must be parsed. -Excessive CPU use has been reported for files with the extension `.txt` and XML files with -a file extension that is not defined by the gem. +Files with the `.txt` extension and XML files with an extension not defined by the gem can take excessive CPU. -The workaround is to specify what language to assign to specific file extensions. +The workaround is to specify the language to assign to specific file extensions. The same approach should also allow misidentified file types to be fixed. -1. Identify which language to specify. The gem contains a [configuration file for known data types](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml). - The entry for `Text` files, for example: +1. Identify the language to specify. The gem contains a [configuration file for known data types](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml). + To add an entry for text files, for example: ```yaml Text: @@ -350,4 +277,17 @@ The same approach should also allow misidentified file types to be fixed. *.txt linguist-language=Text ``` - `*.txt` files have an entry in the heuristics file. The example above prevents parsing of these files. + `*.txt` files have an entry in the heuristics file. This example prevents parsing of these files. + +## Related topics + +- To lock files and prevent change conflicts, use [file locking](../file_lock.md). +- [Repository API](../../../api/repositories.md). +- [Find files](file_finder.md) in a repository. +- [Branches](branches/index.md). +- [File templates](web_editor.md#template-dropdowns). +- [Create a directory](web_editor.md#create-a-directory). +- [Start a merge request](web_editor.md#tips). +- [Find file history](git_history.md). +- [Identify changes by line (Git blame)](git_blame.md). +- [Use Jupyter notebooks with GitLab](jupyter_notebooks/index.md). diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 4b649bab4d9..2ad1504aac3 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -20,10 +20,9 @@ rendered to HTML when viewed: Interactive features, including JavaScript plots, don't work when viewed in GitLab. -## Jupyter Hub as a GitLab Managed App - -You can deploy [Jupyter Hub as a GitLab managed app](../../../clusters/applications.md#jupyterhub). - ## Jupyter Git integration -Find out how to [leverage JupyterLab's Git extension on your Kubernetes cluster](../../../clusters/applications.md#jupyter-git-integration). +Jupyter can be configured as an OAuth application with repository access, acting +on behalf of the authenticated user. See the +[Runbooks documentation](../../../project/clusters/runbooks/index.md) for an +example configuration. diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 3bbe9e6cb66..e9f214f08ce 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -8,7 +8,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.htm # Repository mirroring **(FREE)** Repository mirroring allows for the mirroring of repositories to and from external sources. You -can use it to mirror branches, tags, and commits between repositories. It's useful when you want to use +can use it to mirror branches, tags, and commits between repositories. It helps you use a repository outside of GitLab. A repository mirror at GitLab updates automatically. You can also manually trigger an update @@ -22,21 +22,22 @@ There are two kinds of repository mirroring supported by GitLab: When the mirror repository is updated, all new branches, tags, and commits are visible in the project's activity feed. -Users with [Maintainer access](../../permissions.md) to the project can also force an +Users with the [Maintainer role](../../permissions.md) for the project can also force an immediate update, unless: - The mirror is already being updated. - The [limit for pull mirroring interval seconds](../../../administration/instance_limits.md#pull-mirroring-interval) has not elapsed since its last update. -For security reasons, the URL to the original repository is only displayed to users with -Maintainer or Owner permissions to the mirrored project. +For security reasons, the URL to the original repository is only displayed to users with the +[Maintainer role](../../permissions.md) or the [Owner role](../../permissions.md) for the mirrored +project. ## Use cases The following are some possible use cases for repository mirroring: - You migrated to GitLab but still need to keep your project in another source. In that case, you - can simply set it up to mirror to GitLab (pull) and all the essential history of commits, tags, + can set it up to mirror to GitLab (pull) and all the essential history of commits, tags, and branches are available in your GitLab instance. **(PREMIUM)** - You have old projects in another source that you don't use actively anymore, but don't want to remove for archiving purposes. In that case, you can create a push mirror so that your active @@ -65,9 +66,9 @@ For an existing project, you can set up push mirroring as follows:  When push mirroring is enabled, only push commits directly to the mirrored repository to prevent the -mirror diverging. +mirror diverging. -Unlike [pull mirroring](#how-it-works), the mirrored repository is not periodically auto-synced. +Unlike [pull mirroring](#how-it-works), the mirrored repository is not periodically auto-synced. The mirrored repository receives all changes only when: - Commits are pushed to GitLab. @@ -93,19 +94,19 @@ You can also create and modify project push mirrors through the By default, if any ref on the remote mirror has diverged from the local repository, the *entire push* fails, and no updates occur. -For example, if a repository has `master`, `develop`, and `stable` branches that +For example, if a repository has `main`, `develop`, and `stable` branches that have been mirrored to a remote, and then a new commit is added to `develop` on -the mirror, the next push attempt fails, leaving `master` and `stable` +the mirror, the next push attempt fails, leaving `main` and `stable` out-of-date despite not having diverged. No change on any branch can be mirrored until the divergence is resolved. With the **Keep divergent refs** option enabled, the `develop` branch is -skipped, allowing `master` and `stable` to be updated. The mirror status +skipped, allowing `main` and `stable` to be updated. The mirror status reflects that `develop` has diverged and was skipped, and be marked as a failed update. NOTE: -After the mirror is created, this option can currently only be modified via the [API](../../../api/remote_mirrors.md). +After the mirror is created, this option can only be modified via the [API](../../../api/remote_mirrors.md). ### Setting up a push mirror from GitLab to GitHub @@ -122,11 +123,15 @@ The repository pushes shortly thereafter. To force a push, select the **Update n ### Setting up a push mirror from GitLab to AWS CodeCommit -AWS CodeCommit push mirroring is currently the best way to connect GitLab repositories to AWS CodePipeline, as GitLab isn't yet supported as one of their Source Code Management (SCM) providers. +AWS CodeCommit push mirroring is the best way to connect GitLab repositories to +AWS CodePipeline, as GitLab isn't yet supported as one of their Source Code Management (SCM) providers. -Each new AWS CodePipeline needs significant AWS infrastructure setup. It also requires an individual pipeline per branch. +Each new AWS CodePipeline needs significant AWS infrastructure setup. It also +requires an individual pipeline per branch. -If AWS CodeDeploy is the final step of a CodePipeline, you can, instead, leverage GitLab CI/CD pipelines and simply use the AWS CLI in the final job in `.gitlab-ci.yml` to deploy to CodeDeploy. +If AWS CodeDeploy is the final step of a CodePipeline, you can, instead, leverage +GitLab CI/CD pipelines and use the AWS CLI in the final job in `.gitlab-ci.yml` +to deploy to CodeDeploy. NOTE: GitLab-to-AWS-CodeCommit push mirroring cannot use SSH authentication until [GitLab issue 34014](https://gitlab.com/gitlab-org/gitlab/-/issues/34014) is resolved. @@ -214,10 +219,9 @@ If it isn't working correctly, a red `error` tag appears and shows the error mes You can set up a repository to automatically have its branches, tags, and commits updated from an upstream repository. -This is useful when a repository you're interested in is located on a different server, and you want -to be able to browse its content and its activity using the familiar GitLab interface. - -To configure mirror pulling for an existing project: +If a repository you're interested in is located on a different server, and you want +to browse its content and its activity using the GitLab interface, you can configure +mirror pulling: 1. If you [configured two-factor authentication (2FA)](https://docs.github.com/en/github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa) for GitHub, create a [personal access token for GitHub](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) @@ -244,7 +248,7 @@ Because GitLab is now set to pull changes from the upstream repository, you shou directly to the repository on GitLab. Instead, any commits should be pushed to the remote repository. Changes pushed to the remote repository are pulled into the GitLab repository, either: -- Automatically within a certain period of time. +- Automatically in a certain period of time. - When a [forced update](#forcing-an-update) is initiated. WARNING: @@ -254,7 +258,7 @@ Deleted branches and tags in the upstream repository are not reflected in the Gi ### How it works -Once the pull mirroring feature has been enabled for a repository, the repository is added to a queue. +After the pull mirroring feature has been enabled for a repository, the repository is added to a queue. Once per minute, a Sidekiq cron job schedules repository mirrors to update, based on: @@ -556,7 +560,7 @@ Bidirectional mirroring should not be used as a permanent configuration. Refer t [Git Fusion](https://www.perforce.com/manuals/git-fusion/#Git-Fusion/section_avy_hyc_gl.html) provides a Git interface to [Perforce Helix](https://www.perforce.com/products) which can be used by GitLab to bidirectionally -mirror projects with GitLab. This may be useful in some situations when migrating from Perforce Helix +mirror projects with GitLab. This can help you in some situations when migrating from Perforce Helix to GitLab where overlapping Perforce Helix workspaces cannot be migrated simultaneously to GitLab. If using mirroring with Perforce Helix, you should only mirror protected branches. Perforce Helix diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 4e8e3f1bbce..cca8d770115 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -144,7 +144,7 @@ This dropdown contains the options **Create merge request and branch** and **Cre  After selecting one of these options, a new branch or branch and merge request -is created based on your project's default branch. By default, this branch is `master`. +is created based on your project's [default branch](branches/default.md). The branch name is based on an internal ID, and the issue title. The example screenshot above creates a branch named `2-make-static-site-auto-deploy-and-serve`. @@ -152,7 +152,7 @@ screenshot above creates a branch named When you click the **Create branch** button in an empty repository project, GitLab performs these actions: -- Creates a `master` branch. +- Creates a default branch. - Commits a blank `README.md` file to it. - Creates and redirects you to a new branch based on the issue title. - _If your project is [configured with a deployment service](../integrations/overview.md) like Kubernetes,_ @@ -183,7 +183,7 @@ request, you can create a new branch upfront.  You can now make changes to any files, as needed. When you're ready to merge -the changes back to `master`, you can use the widget at the top of the screen. +the changes back to your [default branch](branches/default.md), you can use the widget at the top of the screen. This widget only appears for a period of time after you create the branch or modify files. @@ -211,7 +211,7 @@ SHA: ## Tips When creating or uploading a new file or creating a new directory, you can -trigger a new merge request rather than committing directly to `master`: +trigger a new merge request rather than committing directly to your default branch: 1. Enter a new branch name in the **Target branch** field. 1. GitLab displays the **Start a new merge request with these changes** check box. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index f5fa6e37d1c..890784cecf5 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Project import/export +# Project import/export **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/3050) in GitLab 8.9. > - From GitLab 10.0, administrators can disable the project export option on the GitLab instance. @@ -24,9 +24,9 @@ See also: To set up a project import/export: - 1. Navigate to **Admin Area > Settings > Visibility and access controls**. - 1. Scroll to **Import sources** - 1. Enable desired **Import sources** + 1. On the top bar, go to **Menu > Admin > Settings > General > Visibility and access controls**. + 1. Scroll to **Import sources**. + 1. Enable the desired **Import sources**. ## Important notes @@ -43,7 +43,7 @@ Note the following: and are moved to your configured `uploads_directory`. Every 24 hours, a specific worker deletes these export files. - Group members are exported as project members, as long as the user has maintainer or administrator access to the group where the exported project lives. -- Project members with owner access are imported as maintainers. +- Project members with the [Owner role](../../permissions.md) are imported as Maintainers. - Imported users can be mapped by their primary email on self-managed instances, if an administrative user (not an owner) does the import. Otherwise, a supplementary comment is left to mention that the original author and the MRs, notes, or issues are owned by the importer. @@ -139,7 +139,7 @@ The following items are **not** exported: NOTE: For more details on the specific data persisted in a project export, see the -[`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/import_export/project/import_export.yml) file. +[`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/project/import_export.yml) file. ## Exporting a project and its data diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index d3177aa7585..03a77e42765 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -30,7 +30,7 @@ Adjust your project's name, description, avatar, [default branch](../repository/  -The project description also partially supports [standard Markdown](../../markdown.md#standard-markdown-and-extensions-in-gitlab). You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and [line-breaks](../../markdown.md#line-breaks) to add more context to the project description. +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. #### Compliance frameworks **(PREMIUM)** @@ -79,7 +79,7 @@ Example `.compliance-gitlab-ci.yml` ```yaml # Allows compliance team to control the ordering and interweaving of stages/jobs. # Stages without jobs defined will remain hidden. -stages: +stages: - pre-compliance - build - test @@ -93,26 +93,82 @@ variables: # can be overriden by a developer's local .gitlab-ci.yml sast: # none of these attributes can be overriden by a developer's local .gitlab-ci.yml variables: FOO: sast + image: ruby:2.6 stage: pre-compliance + rules: + - when: always + allow_failure: false + before_script: + - "# No before scripts." script: - echo "running $FOO" + after_script: + - "# No after scripts." sanity check: + image: ruby:2.6 stage: pre-deploy-compliance + rules: + - when: always + allow_failure: false + before_script: + - "# No before scripts." script: - echo "running $FOO" + after_script: + - "# No after scripts." audit trail: + image: ruby:2.6 stage: post-compliance + rules: + - when: always + allow_failure: false + before_script: + - "# No before scripts." script: - echo "running $FOO" + after_script: + - "# No after scripts." include: # Execute individual project's configuration project: '$CI_PROJECT_PATH' - file: '$CI_PROJECT_CONFIG_PATH' + file: '$CI_CONFIG_PATH' ``` +##### 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 +can be configured to be: + +- Modified by users. +- Non-modifiable. + +At a high-level, if a value in a compliance job: + +- Is set, it cannot be changed or overridden by project-level configurations. +- Is not set, a project-level configuration may set. + +Either might be wanted or not depending on your use case. + +There are a few best practices for ensuring that these jobs are always run exactly +as you define them and that downstream, project-level pipeline configurations +cannot change them: + +- Add a `rules:when:always` block to each of your compliance jobs. This ensures they are + non-modifiable and are always run. +- Explicitly set any variables the job references. This: + - Ensures that project-level pipeline configurations do not set them and alter their + behavior. + - Includes any jobs that drive the logic of your job. +- Explicitly set the container image file to run the job in. This ensures that your script + steps execute in the correct environment. +- Explicitly set any relevant GitLab pre-defined [job keywords](../../../ci/yaml/README.md#job-keywords). + This ensures that your job uses the settings you intend and that they are not overriden by + project-level pipelines. + ### Sharing and permissions For your repository, you can set up features such as public access, repository features, @@ -123,7 +179,7 @@ section. You can now change the [Project visibility](../../../public_access/public_access.md). If you set **Project Visibility** to public, you can limit access to some features to **Only Project Members**. In addition, you can select the option to -[Allow users to request access](../members/index.md#project-membership-and-requesting-access). +[Allow users to request access](../members/index.md#prevent-users-from-requesting-access-to-a-project). Use the switches to enable or disable the following features: @@ -193,6 +249,7 @@ Set up your project's merge request settings: - Set up the merge request method (merge commit, [fast-forward merge](../merge_requests/fast_forward_merge.md)). - Add merge request [description templates](../description_templates.md#description-templates). - Enable [merge request approvals](../merge_requests/approvals/index.md). +- Enable [status checks](../merge_requests/status_checks.md). - Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). - Enable [merge only when all threads are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved). - Enable [require an associated issue from Jira](../../../integration/jira/issues.md#require-associated-jira-issue-for-merge-requests-to-be-merged). @@ -242,10 +299,11 @@ To find an archived project: 1. If you: - Have the project's URL, open the project's page in your browser. - Don't have the project's URL: - 1. Click **Projects > 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. On the top bar, select **Menu > 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. Next, to unarchive the project: @@ -273,7 +331,7 @@ To rename a repository: 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#redirects-when-changing-repository-paths). +[redirects when renaming repositories](../repository/index.md#what-happens-when-a-repository-path-changes). #### Transferring an existing project into another namespace @@ -283,7 +341,7 @@ to transfer a project. You can transfer an existing project into a [group](../../group/index.md) if: -- You have at least **Maintainer** [permissions](../../permissions.md#project-members-permissions) to that group. +- You have at least the Maintainer** role in that group. - You're at least an **Owner** of the project to be transferred. - The group to which the project is being transferred to must allow creation of new projects. @@ -297,7 +355,7 @@ To transfer a project: Once done, you are redirected to the new project's namespace. At this point, read what happens with the -[redirects from the old project to the new one](../repository/index.md#redirects-when-changing-repository-paths). +[redirects from the old project to the new one](../repository/index.md#what-happens-when-a-repository-path-changes). NOTE: GitLab administrators can use the administration interface to move any project to any @@ -306,7 +364,7 @@ namespace if needed. #### Delete a project NOTE: -Only project owners and administrators have [permissions](../../permissions.md#project-members-permissions) to delete a project. +Only project Owners and administrators have [permissions](../../permissions.md#project-members-permissions) to delete a project. To delete a project: @@ -318,10 +376,10 @@ This action: - Deletes a project including all associated resources (issues, merge requests etc). - From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) on [Premium](https://about.gitlab.com/pricing/) or higher tiers, -group owners can [configure](../../group/index.md#enable-delayed-project-removal) projects within a group -to be deleted after a delayed period. -When enabled, actual deletion happens after number of days -specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). + group Owners can [configure](../../group/index.md#enable-delayed-project-removal) projects within a group + to be deleted after a delayed period. + When enabled, actual deletion happens after number of days + specified in [instance settings](../../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). WARNING: The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to @@ -354,10 +412,10 @@ To do so: 1. Confirm the action by typing the project's path as instructed. NOTE: -Only project owners have the [permissions](../../permissions.md#project-members-permissions) +Only project Owners have the [permissions](../../permissions.md#project-members-permissions) to remove a fork relationship. -## Operations settings +## Monitor settings ### Alerts diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index d37e6144ab3..be8a961d6c0 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -81,6 +81,8 @@ the following table. ## Enable or disable project access token creation +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/287707) in GitLab 13.11. + You may enable or disable project access token creation for all projects in a group in **Group > Settings > General > Permissions, LFS, 2FA > Allow project access token creation**. Even when creation is disabled, you can still use and revoke existing project access tokens. This setting is available only on top-level groups. diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index df76c4682f3..3c9b0341661 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -20,7 +20,7 @@ Time Tracking allows you to: - Record the time spent working on an issue or a merge request. - Add an estimate of the amount of time needed to complete an issue or a merge request. -- View a breakdown of time spent working on an issue or a merge request. +- View a breakdown of time spent working on an issue or a merge request. You don't have to indicate an estimate to enter the time spent, and vice versa. @@ -82,6 +82,10 @@ To remove all the time spent at once, use `/remove_time_spent`. You can view a breakdown of time spent on an issue or merge request. +Prerequisites: + +- You must have at least the [Reporter role](../permissions.md#project-members-permissions) for a project. + To view a time tracking report, go to an issue or a merge request and select **Time tracking report** in the right sidebar. diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 73aed1244db..0e597725611 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -259,19 +259,27 @@ Additionally, for public projects an **Open in CodeSandbox** button is available to transfer the contents of the project into a public CodeSandbox project to quickly share your project with others. -### Enabling Live Preview +### Enable Live Preview -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/268288) in GitLab 12.9, third-party assets and libraries required for Live Preview are hosted at `https://sandbox-prod.gitlab-static.net` when it is enabled. However, some libraries are still served from other third-party services which may or may not be desirable in your environment. +With Live Preview enabled, you can preview projects with a `package.json` file and +a `main` entry point inside the Web IDE. -The Live Preview feature needs to be enabled in the GitLab instance's -Admin Area. Live Preview is enabled for all projects on -GitLab.com +Live Preview is enabled for all projects on GitLab.com. If you are an administrator +of a self-managed GitLab instance, and you want to enable Live Preview: - +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > General**. +1. Scroll to **Web IDE** and select **Expand**: +  +1. Select **Enable Live Preview** and select **Save changes**. -After you have done that, you can preview projects with a `package.json` file and -a `main` entry point inside the Web IDE. An example `package.json` is shown -below. +[In GitLab 12.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/268288), +third-party assets and libraries required for Live Preview are hosted at +`https://sandbox-prod.gitlab-static.net` when it is enabled. However, some libraries +are still served from other third-party services, which may or may not be desirable +in your environment. + +An example `package.json`: ```json { diff --git a/doc/user/project/wiki/img/content_editor_v14.0.png b/doc/user/project/wiki/img/content_editor_v14.0.png Binary files differnew file mode 100644 index 00000000000..b44a633073d --- /dev/null +++ b/doc/user/project/wiki/img/content_editor_v14.0.png diff --git a/doc/user/project/wiki/img/use_new_editor_button_v14.0.png b/doc/user/project/wiki/img/use_new_editor_button_v14.0.png Binary files differnew file mode 100644 index 00000000000..d9a5cf83302 --- /dev/null +++ b/doc/user/project/wiki/img/use_new_editor_button_v14.0.png diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 22915efef94..ed6a51665bd 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -7,7 +7,7 @@ type: reference, how-to # Wiki **(FREE)** -If you don't want to keep your documentation in your repository, but you do want +If you don't want to keep your documentation in your repository, but you want to keep it in the same project as your code, you can use the wiki GitLab provides in each GitLab project. Every wiki is a separate Git repository, so you can create wiki pages in the web interface, or [locally using Git](#create-or-edit-wiki-pages-locally). @@ -34,8 +34,8 @@ with sibling pages listed in alphabetical order. To view a list of all pages, se When a wiki is created, it is empty. On your first visit, create the landing page users see when viewing the wiki: -1. Go to the page for your project or group. -1. In the left sidebar, select **Wiki**, then **Create your first page**. +1. Go to your project or group and select **Wiki**. +1. Select **Create your first page**. 1. Select a **Format** for styling your text. 1. Add a welcome message in the **Content** section. You can always edit it later. 1. Add a **Commit message**. Git requires a commit message, so GitLab creates one @@ -46,8 +46,7 @@ users see when viewing the wiki: Users with Developer [permissions](../../permissions.md) can create new wiki pages: -1. Go to the page for your project or group. -1. In the left sidebar, select **Wiki**. +1. Go to your project or group and select **Wiki**. 1. Select **New page** on this page, or any other wiki page. 1. Select a content format. 1. Add a title for your new page. Page titles use @@ -111,8 +110,8 @@ may not be able to check out the wiki locally afterward. You need Developer [permissions](../../permissions.md) or higher to edit a wiki page: -1. Go to the page for your project or group. -1. In the left sidebar, select **Wiki**, and go to the page you want to edit. +1. Go to your project or group and select **Wiki**. +1. Go to the page you want to edit. 1. Select the edit icon (**{pencil}**). 1. Edit the content. 1. Select **Save changes**. @@ -124,10 +123,11 @@ For an example, read [Table of contents](../../markdown.md#table-of-contents). ## Delete a wiki page -You need Maintainer [permissions](../../permissions.md) or higher to delete a wiki page: +You need the [Maintainer role](../../permissions.md) or higher to delete a wiki page: -1. Go to the page for your project or group. -1. In the left sidebar, select **Wiki**, and go to the page you want to delete. +1. Go to your project or group and select **Wiki**. +1. Go to the page you want to delete. +1. Select the edit icon (**{pencil}**). 1. Select **Delete page**. 1. Confirm the deletion. @@ -135,8 +135,8 @@ You need Maintainer [permissions](../../permissions.md) or higher to delete a wi You need Developer [permissions](../../permissions.md) or higher to move a wiki page: -1. Go to the page for your project or group. -1. In the left sidebar, select **Wiki**, and go to the page you want to move. +1. Go to your project or group and select **Wiki**. +1. Go to the page you want to move. 1. Select the edit icon (**{pencil}**). 1. Add the new path to the **Title** field. For example, if you have a wiki page called `about` under `company` and you want to move it to the wiki's root, @@ -164,8 +164,8 @@ From the history page you can see: You can see the changes made in a version of a wiki page, similar to versioned diff file views: -1. Go to the page for your project or group. -1. In the left sidebar, select **Wiki**, and go to the wiki page you're interested in. +1. Go to your project or group and select **Wiki**. +1. Go to the wiki page you're interested in. 1. Select **Page history** to see all page versions. 1. Select the commit message in the **Changes** column for the version you're interested in. @@ -192,8 +192,7 @@ You need Developer [permissions](../../permissions.md) or higher to customize th navigation sidebar. This process creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation: -1. Go to the page for your project or group. -1. In the left sidebar, select **Wiki**. +1. Go to your project or group and select **Wiki**. 1. In the top right corner of the page, select **Edit sidebar**. 1. When complete, select **Save changes**. @@ -243,7 +242,7 @@ and above. Group wiki repositories can be moved using the To add a link to an external wiki from a project's left sidebar: -1. In your project, go to **Settings > Integrations**. +1. Go to your project and select **Settings > Integrations**. 1. Select **External wiki**. 1. Add the URL to your external wiki. 1. (Optional) Select **Test settings** to verify the connection. @@ -253,21 +252,21 @@ You can now see the **External wiki** option from your project's left sidebar. When you enable this integration, the link to the external -wiki won't replace the link to the internal wiki. +wiki doesn't replace the link to the internal wiki. To hide the internal wiki from the sidebar, [disable the project's wiki](#disable-the-projects-wiki). To hide the link to an external wiki: -1. In your project, go to **Settings > Integrations**. +1. Go to your project and select **Settings > Integrations**. 1. Select **External wiki**. -1. Unselect **Enable integration**. +1. In the **Enable integration** section, clear the **Active** checkbox. 1. Select **Save changes**. ## Disable the project's wiki To disable a project's internal wiki: -1. In your project, go to **Settings > General**. +1. Go to your project and select **Settings > General**. 1. Expand **Visibility, project features, permissions**. 1. Scroll down to find **Wiki** and toggle it off (in gray). 1. Select **Save changes**. @@ -282,6 +281,47 @@ Previously added wiki pages are preserved in case you want to re-enable the wiki. To re-enable it, repeat the process to disable the wiki but toggle it on (in blue). +## Content Editor **(FREE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5643) in GitLab 14.0. + +GitLab version 14.0 introduces a WYSIWYG editing experience for GitLab Flavored Markdown +in Wikis through the [Content Editor](../../../development/fe_guide/content_editor.md). +The Content Editor is under active development, and is not yet the default editing +experience in the Wiki. To opt in for the new editor: + +1. Create a new wiki page, or edit an existing one. +1. Ensure the wiki page uses the Markdown format. Other formats are not yet supported. +1. Below the **Format** select box, select **Use the new editor**: + +  + +### Use the Content Editor + +1. [Create](#create-a-new-wiki-page) a new wiki page, or [edit](#edit-a-wiki-page) an existing one. +1. Select **Markdown** as your format. +1. Below the **Format** select box, select **Use new editor**. +1. Customize your page's content using the various formatting options available in the content editor. +1. Select **Create page** for a new page, or **Save changes** for an existing page: + +  + +### Switch back to the old editor + +1. *If you're editing the page in the content editor,* scroll to **Content**. +1. Select **Switch me back to the classic editor**. +1. Select **Switch to classic editor** in the confirmation popup to confirm. + +When you switch back to the old editor, any unsaved changes are lost. + +### GitLab Flavored Markdown support + +Supporting all GitLab Flavored Markdown content types in the Content Editor is a work in progress. +For the status of the ongoing development for CommonMark and GitLab Flavored Markdown support, read: + +- [Basic Markdown formatting extensions](https://gitlab.com/groups/gitlab-org/-/epics/5404) epic. +- [GitLab Flavored Markdown extensions](https://gitlab.com/groups/gitlab-org/-/epics/5438) epic. + ## Resources - [Wiki settings for administrators](../../../administration/wikis/index.md) diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index ddca0b64f81..a0b20f5c86d 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -13,8 +13,8 @@ code are saved in projects, and most features are in the scope of projects. You can explore other popular projects available on GitLab. To explore projects: -1. Click **Projects** in the navigation bar. -1. Click **Explore Projects**. +1. On the top bar, select **Menu > Project**. +1. Select **Explore Projects**. GitLab displays a list of projects, sorted by last updated date. To view projects with the most [stars](#star-a-project), click **Most stars**. To view @@ -84,6 +84,7 @@ Built-in templates are project templates that are: - Developed and maintained in the [`project-templates`](https://gitlab.com/gitlab-org/project-templates) and [`pages`](https://gitlab.com/pages) groups. - Released with GitLab. +- Anyone can contribute a built-in template by following [these steps](https://about.gitlab.com/community/contribute/project-templates). To use a built-in template on the **New project** page: @@ -196,8 +197,8 @@ To star a project: To view your starred projects: -1. Click **Projects** in the navigation bar. -1. Click **Starred Projects**. +1. On the top bar, select **Menu > Project**. +1. Select **Starred Projects**. 1. GitLab displays information about your starred projects, including: - Project description, including name, description, and icon @@ -227,10 +228,16 @@ Read through the documentation on [project settings](settings/index.md). ## Project activity -To view the activity of a project, navigate to **Project overview > Activity**. -From there, you can click on the tabs to see **All** the activity, or see it -filtered by **Push events**, **Merge events**, **Issue events**, **Comments**, -**Team**, and **Wiki**. +To view the activity of a project: + +1. On the left sidebar, select **Project information > Activity**. +1. Select a tab to view **All** the activity, or to filter it by any of these criteria: + - **Push events** + - **Merge events** + - **Issue events** + - **Comments** + - **Team** + - **Wiki** ### Leave a project @@ -333,7 +340,7 @@ For public projects, and to members of internal and private projects with [permissions to view the project's code](../permissions.md#project-members-permissions): - The content of a - [`README` or an index file](repository/#repository-readme-and-index-files) + [`README` or an index file](repository/index.md#readme-and-index-files) is displayed (if any), followed by the list of directories in the project's repository. - If the project doesn't contain either of these files, the diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index 16ff8538630..bf9abcca640 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -10,7 +10,7 @@ Not all project & group names are allowed because they would conflict with existing routes used by GitLab. For a list of words that are not allowed to be used as group or project names, see the -[`path_regex.rb` file](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/path_regex.rb) +[`path_regex.rb` file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/path_regex.rb) under the `TOP_LEVEL_ROUTES`, `PROJECT_WILDCARD_ROUTES` and `GROUP_ROUTES` lists: - `TOP_LEVEL_ROUTES`: are names that are reserved as usernames or top level groups @@ -54,13 +54,11 @@ Currently the following names are reserved as top level groups: - `500.html` - `502.html` - `503.html` -- `abuse_reports` - `admin` - `api` - `apple-touch-icon-precomposed.png` - `apple-touch-icon.png` - `assets` -- `autocomplete` - `dashboard` - `deploy.html` - `explore` @@ -71,7 +69,6 @@ Currently the following names are reserved as top level groups: - `health_check` - `help` - `import` -- `invites` - `jwt` - `login` - `oauth` @@ -81,7 +78,6 @@ Currently the following names are reserved as top level groups: - `robots.txt` - `s` - `search` -- `sent_notifications` - `sitemap` - `sitemap.xml` - `sitemap.xml.gz` diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index 1c4423fb7b0..20a2a7263c3 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -57,13 +57,13 @@ Full details can be found in the [Elasticsearch documentation](https://www.elast here's a quick guide: - Searches look for all the words in a query, in any order - e.g.: searching - issues for [`display bug`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=issues&repository_ref=&search=display+bug&group_id=9970&project_id=278964) and [`bug display`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=issues&repository_ref=&search=bug+Display&group_id=9970&project_id=278964) will return the same results. -- To find the exact phrase (stemming still applies), use double quotes: [`"display bug"`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=issues&repository_ref=&search=%22display+bug%22&group_id=9970&project_id=278964) -- To find bugs not mentioning display, use `-`: [`bug -display`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=issues&repository_ref=&search=bug+-display&group_id=9970&project_id=278964) -- To find a bug in display or banner, use `|`: [`bug display | banner`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=issues&repository_ref=&search=bug+display+%7C+banner&group_id=9970&project_id=278964) -- To group terms together, use parentheses: [`bug | (display +banner)`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=issues&repository_ref=&search=bug+%7C+%28display+%2Bbanner%29&group_id=9970&project_id=278964) -- To match a partial word, use `*`. In this example, I want to find bugs with any 500 errors. : [`bug error 50*`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=issues&repository_ref=&search=bug+error+50*&group_id=9970&project_id=278964) -- To use one of symbols above literally, escape the symbol with a preceding `\`: [`argument \-last`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=argument+%5C-last&group_id=9970&project_id=278964) + issues for [`display bug`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=display+bug&group_id=9970&project_id=278964) and [`bug display`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+Display&group_id=9970&project_id=278964) will return the same results. +- To find the exact phrase (stemming still applies), use double quotes: [`"display bug"`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=%22display+bug%22&group_id=9970&project_id=278964) +- To find bugs not mentioning display, use `-`: [`bug -display`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+-display&group_id=9970&project_id=278964) +- To find a bug in display or banner, use `|`: [`bug display | banner`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+display+%7C+banner&group_id=9970&project_id=278964) +- To group terms together, use parentheses: [`bug | (display +banner)`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+%7C+%28display+%2Bbanner%29&group_id=9970&project_id=278964) +- To match a partial word, use `*`. In this example, I want to find bugs with any 500 errors. : [`bug error 50*`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+error+50*&group_id=9970&project_id=278964) +- To use one of symbols above literally, escape the symbol with a preceding `\`: [`argument \-last`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=argument+%5C-last&group_id=9970&project_id=278964) ## Syntax search filters @@ -79,15 +79,15 @@ any spaces between the colon (`:`) and the value. When no keyword is provided, a Examples: -- Finding a file with any content named `search_results.rb`: [`* filename:search_results.rb`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=*+filename%3Asearch_results.rb&group_id=9970&project_id=278964) +- Finding a file with any content named `search_results.rb`: [`* filename:search_results.rb`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=*+filename%3Asearch_results.rb&group_id=9970&project_id=278964) - The leading asterisk (`*`) can be ignored in the case above: [`filename:search_results.rb`](https://gitlab.com/search?group_id=9970&project_id=278964&scope=blobs&search=filename%3Asearch_results.rb) -- Finding a file named `found_blob_spec.rb` with the text `CHANGELOG` inside of it: [`CHANGELOG filename:found_blob_spec.rb`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=CHANGELOG+filename%3Afound_blob_spec.rb&group_id=9970&project_id=278964) -- Finding the text `EpicLinks` inside files with the `.rb` extension: [`EpicLinks extension:rb`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=EpicLinks+extension%3Arb&group_id=9970&project_id=278964) -- Finding any file with the `.yaml` extension: [`extension:yaml`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=extension%3Ayaml&group_id=9970&project_id=278964) -- Finding the text `Sidekiq` in a file, when that file is in a path that includes `elastic`: [`Sidekiq path:elastic`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=Sidekiq+path%3Aelastic&group_id=9970&project_id=278964) -- Finding any file in a path that includes `elasticsearch`: [`path:elasticsearch`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=path%3Aelasticsearch&group_id=9970&project_id=278964) -- Finding the files represented by the Git object ID `998707b421c89bd9a3063333f9f728ef3e43d101`: [`* blob:998707b421c89bd9a3063333f9f728ef3e43d101`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=false&scope=blobs&repository_ref=&search=*+blob%3A998707b421c89bd9a3063333f9f728ef3e43d101&group_id=9970) -- Syntax filters can be combined for complex filtering. Finding any file starting with `search` containing `eventHub` and with the `.js` extension: [`eventHub filename:search* extension:js`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=eventHub+filename%3Asearch*+extension%3Ajs&group_id=9970&project_id=278964) +- Finding a file named `found_blob_spec.rb` with the text `CHANGELOG` inside of it: [`CHANGELOG filename:found_blob_spec.rb`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=CHANGELOG+filename%3Afound_blob_spec.rb&group_id=9970&project_id=278964) +- Finding the text `EpicLinks` inside files with the `.rb` extension: [`EpicLinks extension:rb`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=EpicLinks+extension%3Arb&group_id=9970&project_id=278964) +- Finding any file with the `.yaml` extension: [`extension:yaml`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=extension%3Ayaml&group_id=9970&project_id=278964) +- Finding the text `Sidekiq` in a file, when that file is in a path that includes `elastic`: [`Sidekiq path:elastic`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=Sidekiq+path%3Aelastic&group_id=9970&project_id=278964) +- Finding any file in a path that includes `elasticsearch`: [`path:elasticsearch`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=path%3Aelasticsearch&group_id=9970&project_id=278964) +- Finding the files represented by the Git object ID `998707b421c89bd9a3063333f9f728ef3e43d101`: [`* blob:998707b421c89bd9a3063333f9f728ef3e43d101`](https://gitlab.com/search?snippets=false&scope=blobs&repository_ref=&search=*+blob%3A998707b421c89bd9a3063333f9f728ef3e43d101&group_id=9970) +- Syntax filters can be combined for complex filtering. Finding any file starting with `search` containing `eventHub` and with the `.js` extension: [`eventHub filename:search* extension:js`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=eventHub+filename%3Asearch*+extension%3Ajs&group_id=9970&project_id=278964) ### Excluding filters @@ -102,14 +102,14 @@ Filters can be inverted to **filter out** results from the result set, by prefix Examples: -- Finding `rails` in all files but `Gemfile.lock`: [`rails -filename:Gemfile.lock`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=rails+-filename%3AGemfile.lock&group_id=9970&project_id=278964) -- Finding `success` in all files excluding `.po|pot` files: [`success -filename:*.po*`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=success+-filename%3A*.po*&group_id=9970&project_id=278964) -- Finding `import` excluding minified JavaScript (`.min.js`) files: [`import -extension:min.js`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=import+-extension%3Amin.js&group_id=9970&project_id=278964) -- Finding `docs` for all files outside the `docs/` folder: [`docs -path:docs/`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=docs+-path%3Adocs%2F&group_id=9970&project_id=278964) +- Finding `rails` in all files but `Gemfile.lock`: [`rails -filename:Gemfile.lock`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=rails+-filename%3AGemfile.lock&group_id=9970&project_id=278964) +- Finding `success` in all files excluding `.po|pot` files: [`success -filename:*.po*`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=success+-filename%3A*.po*&group_id=9970&project_id=278964) +- Finding `import` excluding minified JavaScript (`.min.js`) files: [`import -extension:min.js`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=import+-extension%3Amin.js&group_id=9970&project_id=278964) +- Finding `docs` for all files outside the `docs/` folder: [`docs -path:docs/`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=docs+-path%3Adocs%2F&group_id=9970&project_id=278964) ## Search by issue or merge request ID You can search a specific issue or merge request by its ID with a special prefix. -- To search by issue ID, use prefix `#` followed by issue ID. For example, [#23456](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=issues&repository_ref=&search=%2323456&group_id=9970&project_id=278964) -- To search by merge request ID, use prefix `!` followed by merge request ID. For example [!23456](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=merge_requests&repository_ref=&search=%2123456&group_id=9970&project_id=278964) +- To search by issue ID, use prefix `#` followed by issue ID. For example, [#23456](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=%2323456&group_id=9970&project_id=278964) +- To search by merge request ID, use prefix `!` followed by merge request ID. For example [!23456](https://gitlab.com/search?snippets=&scope=merge_requests&repository_ref=&search=%2123456&group_id=9970&project_id=278964) diff --git a/doc/user/search/index.md b/doc/user/search/index.md index db89dddaf14..0cdaa3150c5 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -194,7 +194,7 @@ author, type, and action. Also, you can sort them by ## Projects -You can search through your projects from the left menu, by clicking the menu bar, then **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. @@ -252,7 +252,7 @@ You can also type in this search bar to see autocomplete suggestions for: - Recently viewed issues (try and type some word from the title of a recently viewed issue) - Recently viewed merge requests (try and type some word from the title of a recently viewed merge request) - Recently viewed epics (try and type some word from the title of a recently viewed epic) -- [GitLab Flavored Markdown](../markdown.md#special-gitlab-references) (GFM) for issues in a project (try and type a GFM reference for an issue) +- [GitLab Flavored Markdown](../markdown.md#gitlab-specific-references) (GFM) for issues in a project (try and type a GFM reference for an issue) ## Basic search diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index 6673611267d..6abbb128f49 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -79,9 +79,9 @@ relatively quickly to work, and they take you to another page in the project. | <kbd>g</kbd> + <kbd>b</kbd> | Go to the project issue boards list (**Issues > Boards**). | | <kbd>g</kbd> + <kbd>m</kbd> | Go to the project merge requests list (**Merge Requests**). | | <kbd>g</kbd> + <kbd>j</kbd> | Go to the CI/CD jobs list (**CI/CD > Jobs**). | -| <kbd>g</kbd> + <kbd>l</kbd> | Go to the project metrics (**Operations > Metrics**). | -| <kbd>g</kbd> + <kbd>e</kbd> | Go to the project environments (**Operations > Environments**). | -| <kbd>g</kbd> + <kbd>k</kbd> | Go to the project Kubernetes cluster integration page (**Operations > Kubernetes**). Note that you must have at least [`maintainer` permissions](permissions.md) to access this page. | +| <kbd>g</kbd> + <kbd>l</kbd> | Go to the project metrics (**Monitor > Metrics**). | +| <kbd>g</kbd> + <kbd>e</kbd> | Go to the project environments (**Deployments > Environments**). | +| <kbd>g</kbd> + <kbd>k</kbd> | Go to the project Kubernetes cluster integration page (**Infrastructure > Kubernetes**). Note that you must have at least [`maintainer` permissions](permissions.md) to access this page. | | <kbd>g</kbd> + <kbd>s</kbd> | Go to the project snippets list (**Snippets**). | | <kbd>g</kbd> + <kbd>w</kbd> | Go to the project wiki (**Wiki**), if enabled. | @@ -126,7 +126,7 @@ These shortcuts are available when editing a file with the [Web IDE](project/web ### Repository graph -These shortcuts are available when viewing the project [repository graph](project/repository/index.md#repository-graph) +These shortcuts are available when viewing the project [repository graph](project/repository/index.md#repository-history-graph) page (navigate to **Repository > Graph**): | Keyboard shortcut | Description | diff --git a/doc/user/snippets.md b/doc/user/snippets.md index 45751e14cb8..4b3f9e78c7b 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -57,11 +57,11 @@ In GitLab versions 13.0 and later, snippets are [versioned by default](#versione To discover all snippets visible to you in GitLab, you can: -- **View all snippets visible to you**: In the top navigation bar of your GitLab - instance, go to **More > Snippets** to view your snippets dashboard. +- **View all snippets visible to you**: On the top bar of your GitLab + instance, select **Menu > Snippets** to view your snippets dashboard. - **Visit [GitLab snippets](https://gitlab.com/dashboard/snippets)** for your snippets on GitLab.com. -- **Explore all public snippets**: In the top navigation bar of your GitLab - instance, go to **More > Snippets** and select **Explore snippets** to view +- **Explore all public snippets**: On the top bar of your GitLab + instance, select **Menu > Snippets** and select **Explore snippets** to view [all public snippets](https://gitlab.com/explore/snippets). - **View a project's snippets**: In your project, go to **Snippets**. diff --git a/doc/user/todos.md b/doc/user/todos.md index 695532abf9f..4227f46dfa8 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -112,6 +112,7 @@ Actions that dismiss to-do items include: - Changing the milestone - Adding/removing a label - Commenting on the issue +- Resolving a [design discussion thread](project/issues/design_management.md#resolve-design-threads) Your To-Do List is personal, and items are only marked as done if you take action. If you close the issue or merge request, your to-do item is marked as |
