diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-02-18 10:34:06 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-02-18 10:34:06 +0000 |
| commit | 859a6fb938bb9ee2a317c46dfa4fcc1af49608f0 (patch) | |
| tree | d7f2700abe6b4ffcb2dcfc80631b2d87d0609239 /doc/user | |
| parent | 446d496a6d000c73a304be52587cd9bbc7493136 (diff) | |
| download | gitlab-ce-859a6fb938bb9ee2a317c46dfa4fcc1af49608f0.tar.gz | |
Add latest changes from gitlab-org/gitlab@13-9-stable-eev13.9.0-rc42
Diffstat (limited to 'doc/user')
386 files changed, 4727 insertions, 4365 deletions
diff --git a/doc/user/account/security.md b/doc/user/account/security.md deleted file mode 100644 index d9db3a25c00..00000000000 --- a/doc/user/account/security.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../profile/account/index.md' ---- - -This document was moved to [profile](../profile/account/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/account/two_factor_authentication.md b/doc/user/account/two_factor_authentication.md deleted file mode 100644 index b085611f747..00000000000 --- a/doc/user/account/two_factor_authentication.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../profile/account/two_factor_authentication.md' ---- - -This document was moved to [profile/account/two_factor_authentication](../profile/account/two_factor_authentication.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/abuse_reports.md b/doc/user/admin_area/abuse_reports.md index 62f3bd3625c..653c67ed197 100644 --- a/doc/user/admin_area/abuse_reports.md +++ b/doc/user/admin_area/abuse_reports.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Abuse reports **(CORE ONLY)** +# Abuse reports **(FREE SELF)** View and resolve abuse reports from GitLab users. diff --git a/doc/user/admin_area/analytics/convdev.md b/doc/user/admin_area/analytics/convdev.md deleted file mode 100644 index d0f3a34e15e..00000000000 --- a/doc/user/admin_area/analytics/convdev.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'dev_ops_report.md' ---- - -This document was moved to [another location](dev_ops_report.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/analytics/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index 80108fba060..a8f6e8ec8fa 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -4,7 +4,7 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# DevOps Report **(CORE)** +# DevOps Report > - [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. @@ -15,7 +15,7 @@ from planning to monitoring. To see DevOps Report, go to **Admin Area > Analytics > DevOps Report**. -## DevOps Score **(CORE)** +## DevOps Score **(FREE)** NOTE: Your GitLab instance's [usage ping](../settings/usage_statistics.md#usage-ping) must be activated in order to use this feature. @@ -40,7 +40,7 @@ collected before this feature is available. [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). -The DevOps Adoption tab shows you which segments of your organization are using the most essential features of GitLab: +The DevOps Adoption tab shows you which groups within your organization are using the most essential features of GitLab: - Issues - Merge Requests @@ -50,9 +50,7 @@ The DevOps Adoption tab shows you which segments of your organization are using - Deploys - Scanning -Segments are arbitrary collections of GitLab groups that you define. You might define a segment to represent a small team, a large department, or a whole organization. -You are limited to creating a maximum of 20 segments, and each segment is limited to a maximum of 20 groups. -Buttons to manage your segments appear in the DevOps Adoption section of the page. +Buttons to manage your groups appear in the DevOps Adoption section of the page. DevOps Adoption allows you to: @@ -60,7 +58,7 @@ 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 diff --git a/doc/user/admin_area/analytics/img/cohorts_v13_4.png b/doc/user/admin_area/analytics/img/cohorts_v13_4.png Binary files differdeleted file mode 100644 index 6f7dd5101f2..00000000000 --- a/doc/user/admin_area/analytics/img/cohorts_v13_4.png +++ /dev/null diff --git a/doc/user/admin_area/analytics/img/cohorts_v13_9.png b/doc/user/admin_area/analytics/img/cohorts_v13_9.png Binary files differnew file mode 100644 index 00000000000..6a616b201c9 --- /dev/null +++ b/doc/user/admin_area/analytics/img/cohorts_v13_9.png diff --git a/doc/user/admin_area/analytics/img/dev_ops_adoption_v13_7.png b/doc/user/admin_area/analytics/img/dev_ops_adoption_v13_7.png Binary files differdeleted file mode 100644 index 0f1f16bead6..00000000000 --- a/doc/user/admin_area/analytics/img/dev_ops_adoption_v13_7.png +++ /dev/null diff --git a/doc/user/admin_area/analytics/img/dev_ops_adoption_v13_9.png b/doc/user/admin_area/analytics/img/dev_ops_adoption_v13_9.png Binary files differnew file mode 100644 index 00000000000..a295179dda3 --- /dev/null +++ b/doc/user/admin_area/analytics/img/dev_ops_adoption_v13_9.png diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md index 098d758e42a..5cf5e33f2d2 100644 --- a/doc/user/admin_area/analytics/index.md +++ b/doc/user/admin_area/analytics/index.md @@ -12,6 +12,6 @@ Administrators have access to instance-wide analytics, as shown in **Admin Area There are several kinds of statistics: -- [DevOps Report](dev_ops_report.md): Provides an overview of your entire instance's feature usage. **(CORE)** -- [Usage Trends](usage_trends.md): Shows how much data your instance contains, and how that is changing. **(CORE)** -- [User Cohorts](user_cohorts.md): Display the monthly cohorts of new users and their activities over time. **(CORE)** +- [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)** +- [User Cohorts](user_cohorts.md): Display the monthly cohorts of new users and their activities over time. **(FREE)** diff --git a/doc/user/admin_area/analytics/instance_statistics.md b/doc/user/admin_area/analytics/instance_statistics.md index 44fd04198b1..e44dd891029 100644 --- a/doc/user/admin_area/analytics/instance_statistics.md +++ b/doc/user/admin_area/analytics/instance_statistics.md @@ -3,3 +3,6 @@ redirect_to: 'usage_trends.md' --- This document was moved to [another location](usage_trends.md). + +<!-- This redirect file can be deleted after <2022-03-20>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/analytics/usage_trends.md b/doc/user/admin_area/analytics/usage_trends.md index aeb577b8183..0c0cae09c16 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 **(CORE)** +# Usage Trends **(FREE)** > - [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 7adc9ad59a5..a7c93160b69 100644 --- a/doc/user/admin_area/analytics/user_cohorts.md +++ b/doc/user/admin_area/analytics/user_cohorts.md @@ -4,19 +4,19 @@ 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 --- -# Cohorts **(CORE)** +# Cohorts **(FREE)** As a benefit of having the [usage ping active](../settings/usage_statistics.md), you can analyze your users' GitLab activities over time. -To see user cohorts, go to **Admin Area > Analytics > Cohorts**. +To see user cohorts, go to **Admin Area > Overview > Users**. ## Overview How do you interpret the user cohorts table? Let's review an example with the following user cohorts: - + For the cohort of March 2020, three users were added to this server and have been active since this month. One month later (April 2020), two users are still diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index b7f5afe7b70..e2e96f980f5 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -6,7 +6,7 @@ type: howto disqus_identifier: 'https://docs.gitlab.com/ee/customization/branded_login_page.html' --- -# GitLab Appearance **(CORE ONLY)** +# 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** @@ -20,7 +20,7 @@ used (less than 1MB) and it is automatically resized.  -Once you select and upload an image, click **Update appearance settings** at the bottom +After you select and upload an image, click **Update appearance settings** at the bottom of the page to activate it in the GitLab instance. NOTE: @@ -41,8 +41,7 @@ of the page to activate it in the GitLab instance. ## System header and footer messages -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5023) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.7. -> - [Added](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55057) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55057) to GitLab Free in 11.9. You can add a small header message, a small footer message, or both, to the interface of your GitLab instance. These messages appear on all projects and pages of the diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index c96c57a99eb..6f6aed68620 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Broadcast Messages **(CORE ONLY)** +# Broadcast Messages **(FREE SELF)** GitLab can display broadcast messages to all users of a GitLab instance. There are two types of broadcast messages: diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index 70bb070b13e..02659276b53 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Credentials inventory **(ULTIMATE ONLY)** +# Credentials inventory **(ULTIMATE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20912) in GitLab 12.6. diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index a9bc2ecf324..26551d828bf 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Custom instance-level project templates **(PREMIUM ONLY)** +# Custom instance-level project templates **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. diff --git a/doc/user/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md index b5fcab58535..83b1869c7f2 100644 --- a/doc/user/admin_area/diff_limits.md +++ b/doc/user/admin_area/diff_limits.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Diff limits administration **(CORE ONLY)** +# Diff limits administration **(FREE SELF)** You can set a maximum size for display of diff files (patches). @@ -13,25 +13,25 @@ For details about diff files, [View changes between files](../project/merge_requ ## Maximum diff patch size -Diff files which exceed this value will be presented as 'too large' and won't -be expandable. Instead of an expandable view, a link to the blob view will be +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. -Patches greater than 10% of this size will be automatically collapsed, and a -link to expand the diff will be presented. +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. -NOTE: -Merge requests and branch comparison views will be affected. - -WARNING: -This setting is experimental. An increased maximum will increase resource -consumption of your instance. Keep this in mind when adjusting the maximum. +To set the maximum diff patch size: 1. Go to **Admin Area > Settings > General**. 1. Expand **Diff limits**. 1. Enter a value for **Maximum diff patch size**, measured in bytes. 1. Click on **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 81e987d25d6..f41170da975 100644 --- a/doc/user/admin_area/geo_nodes.md +++ b/doc/user/admin_area/geo_nodes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Geo nodes Admin Area **(PREMIUM ONLY)** +# Geo nodes Admin Area **(PREMIUM SELF)** You can configure various settings for GitLab Geo nodes. For more information, see [Geo documentation](../../administration/geo/index.md). diff --git a/doc/user/admin_area/img/impersonate_user_button_v13_8.png b/doc/user/admin_area/img/impersonate_user_button_v13_8.png Binary files differnew file mode 100644 index 00000000000..475315a0c0f --- /dev/null +++ b/doc/user/admin_area/img/impersonate_user_button_v13_8.png diff --git a/doc/user/admin_area/img/license_details.png b/doc/user/admin_area/img/license_details.png Binary files differdeleted file mode 100644 index 3e980d9316d..00000000000 --- a/doc/user/admin_area/img/license_details.png +++ /dev/null diff --git a/doc/user/admin_area/img/license_details_v13_8.png b/doc/user/admin_area/img/license_details_v13_8.png Binary files differnew file mode 100644 index 00000000000..00421d8a41d --- /dev/null +++ b/doc/user/admin_area/img/license_details_v13_8.png diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 40cb6bd0853..b5e51e8d4c0 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# GitLab Admin Area **(CORE ONLY)** +# GitLab Admin Area **(FREE SELF)** The Admin Area provides a web UI for administering some features of GitLab self-managed instances. @@ -24,20 +24,20 @@ The Admin Area is made up of the following sections: | Section | Description | |:-----------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **{overview}** [Overview](#overview-section) | View your GitLab [Dashboard](#admin-dashboard), and administer [projects](#administering-projects), [users](#administering-users), [groups](#administering-groups), [jobs](#administering-jobs), [runners](#administering-runners), and [Gitaly servers](#administering-gitaly-servers). | -| **{monitor}** Monitoring | View GitLab [system information](#system-info), and information on [background jobs](#background-jobs), [logs](#logs), [health checks](monitoring/health_check.md), [requests profiles](#requests-profiles), and [audit events](#audit-events). | +| **{monitor}** Monitoring | View GitLab [system information](#system-information), and information on [background jobs](#background-jobs), [logs](#logs), [health checks](monitoring/health_check.md), [requests profiles](#requests-profiles), and [audit events](#audit-events). | | **{messages}** Messages | Send and manage [broadcast messages](broadcast_messages.md) for your users. | | **{hook}** System Hooks | Configure [system hooks](../../system_hooks/system_hooks.md) for many events. | | **{applications}** Applications | Create system [OAuth applications](../../integration/oauth_provider.md) for integrations with other services. | | **{slight-frown}** Abuse Reports | Manage [abuse reports](abuse_reports.md) submitted by your users. | | **{license}** License **(STARTER ONLY)** | Upload, display, and remove [licenses](license.md). | | **{cloud-gear}** Kubernetes | Create and manage instance-level [Kubernetes clusters](../instance/clusters/index.md). | -| **{push-rules}** Push Rules **(STARTER ONLY)** | Configure pre-defined Git [push rules](../../push_rules/push_rules.md) for projects. Also, configure [merge requests approvers rules](merge_requests_approvals.md). **(PREMIUM ONLY)** | -| **{location-dot}** Geo **(PREMIUM ONLY)** | Configure and maintain [Geo nodes](geo_nodes.md). | -| **{key}** Deploy Keys | Create instance-wide [SSH deploy keys](../../ssh/README.md#deploy-keys). | -| **{lock}** Credentials **(ULTIMATE ONLY)** | View [credentials](credentials_inventory.md) that can be used to access your instance. | +| **{push-rules}** Push rules **(STARTER ONLY)** | Configure pre-defined Git [push rules](../../push_rules/push_rules.md) for projects. Also, configure [merge requests approvers rules](merge_requests_approvals.md). **(PREMIUM SELF)** | +| **{location-dot}** Geo **(PREMIUM SELF)** | Configure and maintain [Geo nodes](geo_nodes.md). | +| **{key}** Deploy keys | Create instance-wide [SSH deploy keys](../../ssh/README.md#deploy-keys). | +| **{lock}** Credentials **(ULTIMATE SELF)** | 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. | | **{labels}** Labels | Create and maintain [labels](labels.md) for your GitLab instance. | -| **{appearance}** Appearance | Customize [GitLab appearance](appearance.md). | +| **{appearance}** Appearance | Customize [GitLab appearance](appearance.md). | | **{settings}** Settings | Modify the [settings](settings/index.md) for your GitLab instance. | ## Admin Dashboard @@ -144,6 +144,19 @@ To search for users, enter your criteria in the search field. The user search is insensitive, and applies partial matching to name and username. To search for an email address, you must provide the complete email address. +#### User impersonation + +An administrator can "impersonate" any other user, including other administrator users. +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**. +- 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). + + + #### Users statistics The **Users statistics** page provides an overview of user accounts by role. These statistics are @@ -242,7 +255,7 @@ For each runner, the following attributes are listed: | Projects | Projects to which the runner is assigned | | Jobs | Total of jobs run by the runner | | Tags | Tags associated with the runner | -| Last contact | Timestamp indicating when the GitLab instance last contacted the runner | +| Last contact | Timestamp indicating when the runner last contacted the GitLab instance | You can also edit, pause, or remove each runner. @@ -267,7 +280,7 @@ For each Gitaly server, the following details are listed: The following topics document the **Monitoring** section of the Admin Area. -### System Info +### System Information The **System Info** page provides the following statistics: @@ -300,7 +313,9 @@ The Sidekiq dashboard consists of the following elements: ### Logs -The **Logs** page provides access to the following log files: +Since GitLab 13.0, **Log** view has been removed from the admin dashboard since the logging does not work in multi-node setups and could cause confusion for administrators by displaying partial information. + +For multi-node systems we recommend ingesting the logs into services like Elasticsearch and Splunk. | Log file | Contents | | :---------------------- | :------- | @@ -312,7 +327,7 @@ The **Logs** page provides access to the following log files: | `integrations_json.log` | Activity between GitLab and integrated systems | | `kubernetes.log` | Kubernetes activity | -The contents of these log files can be useful when troubleshooting a problem. Access is available to GitLab admins, without requiring direct access to the log files. +The contents of these log files can be useful when troubleshooting a problem. For details of these log files and their contents, see [Log system](../../administration/logs.md). @@ -322,6 +337,6 @@ The content of each log file is listed in chronological order. To minimize perfo The **Requests Profiles** page contains the token required for profiling. For more details, see [Request Profiling](../../administration/monitoring/performance/request_profiling.md). -### Audit Events **(PREMIUM ONLY)** +### Audit Events **(PREMIUM SELF)** The **Audit Events** page lists changes made within the GitLab server. With this information you can control, analyze, and track every change. diff --git a/doc/user/admin_area/labels.md b/doc/user/admin_area/labels.md index cc9735df9d6..b5dbf835d70 100644 --- a/doc/user/admin_area/labels.md +++ b/doc/user/admin_area/labels.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Labels administration **(CORE ONLY)** +# Labels administration **(FREE SELF)** In the Admin Area, you can manage labels for the GitLab instance. For more details, see [Labels](../project/labels.md). diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index d06b0c844ec..505f54e9ae9 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -13,7 +13,7 @@ you are running. To verify, sign in to GitLab and browse to `/help`. The GitLab are listed at the top of the **Help** page. If you are running GitLab Community Edition (CE), upgrade your installation to -GitLab Enterprise Edition (EE). For more details, see [Upgrading between editions](../../update/README.md#upgrading-between-editions). +GitLab Enterprise Edition (EE). For more details, see [Upgrading between editions](../../update/index.md#upgrading-between-editions). If you have questions or need assistance upgrading from GitLab CE to EE please [contact GitLab Support](https://about.gitlab.com/support/#contact-support). The license is a base64-encoded ASCII text file with a `.gitlab-license` @@ -25,7 +25,7 @@ by **signing into your GitLab instance as an admin** or adding it at installation time. As of GitLab Enterprise Edition 9.4.0, a newly-installed instance without an -uploaded license only has the Core features active. A trial license +uploaded license only has the Free features active. A trial license activates all Ultimate features, but after [the trial expires](#what-happens-when-your-license-expires), some functionality is locked. @@ -86,13 +86,13 @@ These methods only add a license at the time of installation. Use the After the license is uploaded, all GitLab Enterprise Edition functionality is active until the end of the license period. When that period ends, the -instance will [fall back](#what-happens-when-your-license-expires) to Core-only +instance will [fall back](#what-happens-when-your-license-expires) to Free-only functionality. You can review the license details at any time in the **License** section of the **Admin Area**. - + ## Notification before the license expires @@ -106,7 +106,7 @@ In case your license expires, GitLab locks down some features like Git pushes, and issue creation, and displays a message to all administrators to inform of the expired license. To get back all the previous functionality, you must upload a new license. -To fall back to having only the Core features active, you must delete the +To fall back to having only the Free features active, you must delete the expired license(s). ### Remove a license @@ -133,7 +133,7 @@ The banner disappears after the new license becomes active. ### There is no License tab in the Admin Area If you originally installed Community Edition rather than Enterprise Edition you must -[upgrade to Enterprise Edition](../../update/README.md#community-to-enterprise-edition) +[upgrade to Enterprise Edition](../../update/index.md#community-to-enterprise-edition) before uploading your license. GitLab.com users can't upload and use a self-managed license. If you diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index 5264f3b770b..d6ffde7be95 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Merge request approval rules **(PREMIUM ONLY)** +# Merge request approval rules **(PREMIUM SELF)** > Introduced in [GitLab Premium](https://gitlab.com/gitlab-org/gitlab/-/issues/39060) 12.8. diff --git a/doc/user/admin_area/monitoring/convdev.md b/doc/user/admin_area/monitoring/convdev.md deleted file mode 100644 index d9c3950f2e4..00000000000 --- a/doc/user/admin_area/monitoring/convdev.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: '../analytics/dev_ops_report.md' ---- - -Conversational Development Index was renamed to [DevOps Report](../analytics/dev_ops_report.md) in GitLab 12.6. diff --git a/doc/user/admin_area/monitoring/dev_ops_report.md b/doc/user/admin_area/monitoring/dev_ops_report.md deleted file mode 100644 index 2cc9f153de3..00000000000 --- a/doc/user/admin_area/monitoring/dev_ops_report.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../analytics/dev_ops_report.md' ---- - -This document was moved to [another location](../analytics/dev_ops_report.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 3c08a330b13..2d4683911fb 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Health Check **(CORE ONLY)** +# Health Check **(FREE SELF)** > - Liveness and readiness probes were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10416) in GitLab 9.1. > - The `health_check` endpoint was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3888) in GitLab 8.8 and was @@ -15,7 +15,7 @@ type: concepts, howto GitLab provides liveness and readiness probes to indicate service health and reachability to required services. These probes report on the status of the -database connection, Redis connection, and access to the filesystem. These +database connection, Redis connection, and access to the file system. These endpoints [can be provided to schedulers like Kubernetes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/) to hold traffic until the system is ready or restart the container as needed. 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 028858c96f6..70416c224c7 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Account and limit settings **(CORE ONLY)** +# Account and limit settings **(FREE SELF)** ## Default projects limit @@ -13,7 +13,8 @@ You can change the default maximum number of projects that users can create in t Navigate to **Admin Area > Settings > General**, then expand **Account and Limit**. You can 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 within a group. +- 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 @@ -22,8 +23,8 @@ 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)`. NOTE: -If you choose a size larger than what is currently configured for the web server, -you will likely get errors. See the [troubleshooting section](#troubleshooting) for more +If you choose a size larger than the configured value for the web server, +you may receive errors. See the [troubleshooting section](#troubleshooting) for more details. ## Max push size @@ -39,8 +40,8 @@ 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)`. NOTE: -If you choose a size larger than what is currently configured for the web server, -you will likely get errors. See the [troubleshooting section](#troubleshooting) for more +If you choose a size larger than the configured value for the web server, +you may receive errors. See the [troubleshooting section](#troubleshooting) for more details. ## Personal Access Token prefix @@ -62,14 +63,11 @@ to any PAT generated in the system by any user: It is also possible to configure the prefix via the [settings API](../../../api/settings.md) using the `personal_access_token_prefix` field. -## Repository size limit **(STARTER ONLY)** +## Repository size limit **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/740) in [GitLab Enterprise Edition 8.12](https://about.gitlab.com/releases/2016/09/22/gitlab-8-12-released/#limit-project-size-ee). - -Repositories within your GitLab instance can grow quickly, especially if you are +Repositories in your GitLab instance can grow quickly, especially if you are using LFS. Their size can grow exponentially, rapidly consuming available storage. - -To avoid this from happening, you can set a hard limit for your repositories' size. +To prevent this from happening, you can set a hard limit for your repositories' size. This limit can be set globally, per group, or per project, with per project limits taking the highest priority. @@ -88,7 +86,7 @@ For instance, consider the following workflow: Only a GitLab administrator can set those limits. Setting the limit to `0` means there are no restrictions. -These settings can be found within: +These settings can be found in: - Each project's settings: 1. From the Project's homepage, navigate to **Settings > General**. @@ -104,9 +102,9 @@ These settings can be found within: 1. Fill in the **Size limit per repository (MB)** field. 1. Click **Save changes**. -The first push of a new project, including LFS objects, will be checked for size -and **will** be rejected if the sum of their sizes exceeds the maximum allowed -repository size. +The first push of a new project, including LFS objects, is checked for size. +If the sum of their sizes exceeds the maximum allowed repository size, the push +is rejected. NOTE: The repository size limit includes repository files and LFS, but does not include artifacts, uploads, @@ -121,29 +119,46 @@ For GitLab.com repository size limits, see [accounts and limit settings](../../g ### 413 Request Entity Too Large -If you are attaching a file to a comment or reply in GitLab and receive the `413 Request Entity Too Large` -error, it is likely caused by having a [max attachment size](#max-attachment-size) -larger than what the web server is configured to allow. +When attaching a file to a comment or reply in GitLab displays a `413 Request Entity Too Large` +error, the [max attachment size](#max-attachment-size) +is probably larger than the web server's allowed value. -If you wanted to increase the max attachment size to 200m in a GitLab -[Omnibus](https://docs.gitlab.com/omnibus/) install, for example, you might need to +To increase the max attachment size to 200 MB in a +[Omnibus GitLab](https://docs.gitlab.com/omnibus/) install, you may need to add the line below to `/etc/gitlab/gitlab.rb` before increasing the max attachment size: ```ruby nginx['client_max_body_size'] = "200m" ``` -## Limiting lifetime of personal access tokens **(ULTIMATE ONLY)** +## Customize session duration for Git Operations when 2FA is enabled **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296669) in GitLab 13.9. +> - It's deployed behind a feature flag, 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](../../../security/two_factor_authentication.md#enable-or-disable-two-factor-authentication-2fa-for-git-operations) -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. +GitLab administrators can choose to customize the session duration (in minutes) for Git operations when 2FA is enabled. The default is 15 and this can be set to a value between 1 and 10080. + +To set a limit on how long these sessions are valid: + +1. Navigate to **Admin Area > 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**. + +## Limiting lifetime of personal access tokens **(ULTIMATE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3649) in GitLab Ultimate 12.6. Users can optionally specify an expiration date for [personal access tokens](../../profile/personal_access_tokens.md). This expiration date is not a requirement, and can be set to any arbitrary date. -Since personal access tokens are the only token needed for programmatic access to GitLab, -organizations with security requirements may want to enforce more protection to require -regular rotation of these tokens. +Personal access tokens are the only tokens needed for programmatic access to GitLab. +However, organizations with security requirements may want to enforce more protection by +requiring the regular rotation of these tokens. ### Setting a limit @@ -157,48 +172,40 @@ To set a limit on how long personal access tokens are valid: 1. Fill in the **Maximum allowable lifetime for personal access tokens (days)** field. 1. Click **Save changes**. -Once a lifetime for personal access tokens is set, GitLab will: +Once a lifetime for personal access tokens is set, GitLab: -- Apply the lifetime for new personal access tokens, and require users to set an expiration date +- Applies the lifetime for new personal access tokens, and require users to set an expiration date and a date no later than the allowed lifetime. - After three hours, revoke old tokens with no expiration date or with a lifetime longer than the allowed lifetime. Three hours is given to allow administrators to change the allowed lifetime, or remove it, before revocation takes place. -## Optional enforcement of Personal Access Token expiry **(ULTIMATE ONLY)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214723) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. -> - It is deployed behind a feature flag, disabled by default. -> - It is disabled on GitLab.com. -> - It is not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-optional-enforcement-of-personal-access-token-expiry-feature). **(CORE ONLY)** +## Enforcement of SSH key expiration **(ULTIMATE SELF)** -GitLab administrators can choose to prevent personal access tokens from expiring automatically. The tokens will be usable after the expiry date, unless they are revoked explicitly. +GitLab administrators can choose to enforce the expiration of SSH keys after their expiration dates. +If you enable this feature, this disables all _expired_ SSH keys. To do this: 1. Navigate to **Admin Area > Settings > General**. 1. Expand the **Account and limit** section. -1. Uncheck the **Enforce personal access token expiration** checkbox. +1. Select the **Enforce SSH key expiration** checkbox. -### Enable or disable optional enforcement of Personal Access Token expiry Feature **(CORE ONLY)** +## Optional enforcement of Personal Access Token expiry **(ULTIMATE SELF)** -Optional Enforcement of Personal Access Token Expiry is deployed behind a feature flag and is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) can enable it for your instance from the [rails console](../../../administration/feature_flags.md#start-the-gitlab-rails-console). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214723) in GitLab Ultimate 13.1. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/296881) in GitLab 13.9. -To enable it: +GitLab administrators can choose to prevent personal access tokens from expiring +automatically. The tokens are usable after the expiry date, unless they are revoked explicitly. -```ruby -Feature.enable(:enforce_pat_expiration) -``` - -To disable it: +To do this: -```ruby -Feature.disable(:enforce_pat_expiration) -``` +1. Navigate to **Admin Area > Settings > General**. +1. Expand the **Account and limit** section. +1. Uncheck the **Enforce personal access token expiration** checkbox. -## Disabling user profile name changes **(PREMIUM ONLY)** +## Disabling user profile name changes **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24605) in GitLab 12.7. @@ -210,4 +217,6 @@ To do this: 1. Check the **Prevent users from changing their profile name** checkbox. NOTE: -When this ability is disabled, GitLab administrators will still be able to update the name of any user in their instance via the [Admin UI](../index.md#administering-users) or the [API](../../../api/users.md#user-modification) +When this ability is disabled, GitLab administrators can still use the +[Admin UI](../index.md#administering-users) or the +[API](../../../api/users.md#user-modification) to update usernames. diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 6418be13ee9..761fc6477d6 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -5,14 +5,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Continuous Integration and Deployment Admin settings **(CORE ONLY)** +# Continuous Integration and Deployment Admin 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 > Settings > CI/CD**.  -## Auto DevOps **(CORE ONLY)** +## Auto DevOps **(FREE SELF)** To enable (or disable) [Auto DevOps](../../../topics/autodevops/index.md) for all projects: @@ -29,7 +29,7 @@ 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#enablingdisabling-auto-devops). -## Maximum artifacts size **(CORE ONLY)** +## Maximum artifacts size **(FREE SELF)** The maximum size of the [job artifacts](../../../administration/job_artifacts.md) can be set at: @@ -65,7 +65,7 @@ To change it at the: NOTE: The setting at all levels is only available to GitLab administrators. -## Default artifacts expiration **(CORE ONLY)** +## Default artifacts expiration **(FREE SELF)** 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 @@ -86,9 +86,28 @@ 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). -## Shared runners pipeline minutes quota **(STARTER ONLY)** +## Keep the latest artifacts for all jobs in the latest successful pipelines **(CORE ONLY)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1078) in GitLab Starter 8.16. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50889) in GitLab Core 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 disabled, the latest artifacts for any **new** successful or fixed pipelines +are allowed to expire. + +This setting takes precedence over the [project level setting](../../../ci/pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). +If disabled at the instance level, you cannot enable this per-project. + +When you disable the feature, the latest artifacts do not immediately expire. +A new pipeline must run before the latest artifacts can expire and be deleted. + +NOTE: +All application settings have a [customizable cache expiry interval](../../../administration/application_settings_cache.md) which can delay the settings affect. + +## Shared runners pipeline minutes quota **(PREMIUM SELF)** + +> [Moved](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) to GitLab Premium in 13.9. If you have enabled shared runners for your GitLab instance, you can limit their usage by setting a maximum number of pipeline minutes that a group can use on @@ -126,7 +145,7 @@ a group in the **Usage Quotas** page available to the group page settings list.  -## Archive jobs **(CORE ONLY)** +## Archive jobs **(FREE SELF)** 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), @@ -156,21 +175,9 @@ Area of your GitLab instance (`.gitlab-ci.yml` if not set): 1. Input the new path in the **Default CI configuration path** field. 1. Hit **Save changes** for the changes to take effect. -It is also possible to specify a [custom CI configuration path for a specific project](../../../ci/pipelines/settings.md#custom-ci-configuration-path). +It is also possible to specify a [custom CI/CD configuration path for a specific project](../../../ci/pipelines/settings.md#custom-cicd-configuration-path). -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> - -## Required pipeline configuration **(PREMIUM ONLY)** +## Required pipeline configuration **(PREMIUM SELF)** WARNING: This feature is being re-evaluated in favor of a different @@ -204,18 +211,18 @@ To set required pipeline configuration: ## Package Registry configuration -### NPM Forwarding **(PREMIUM ONLY)** +### npm Forwarding **(PREMIUM SELF)** -GitLab administrators can disable the forwarding of NPM requests to [npmjs.com](https://www.npmjs.com/). +GitLab administrators can disable the forwarding of npm requests to [npmjs.com](https://www.npmjs.com/). To disable it: 1. Go to **Admin Area > Settings > CI/CD**. 1. Expand the **Package Registry** section. -1. Uncheck **Enable forwarding of NPM package requests to npmjs.org**. +1. Uncheck **Enable forwarding of npm package requests to npmjs.org**. 1. Click **Save changes**. - + ### Package file size limits @@ -228,3 +235,14 @@ To set the maximum file size: 1. Find the package type you would like to adjust. 1. Enter the maximum file size, in bytes. 1. Click **Save size limits**. + +## Troubleshooting + +### 413 Request Entity Too Large + +When build jobs fail with the following error, +increase the [maximum artifacts size](#maximum-artifacts-size). + +```plaintext +Uploading artifacts as "archive" to coordinator... too large archive <job-id> responseStatus=413 Request Entity Too Large status=413" at end of a build job on pipeline when trying to store artifacts to <object-storage>. +``` diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index 4ebfac57715..2eaff417ba3 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -5,7 +5,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Email **(CORE ONLY)** +# Email **(FREE SELF)** You can customize some of the content in emails sent from your GitLab instance. @@ -13,7 +13,7 @@ You can customize some of the content in emails sent from your GitLab instance. The logo in the header of some emails can be customized, see the [logo customization section](../appearance.md#navigation-bar). -## Custom additional text **(PREMIUM ONLY)** +## Custom additional text **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5031) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.7. @@ -40,7 +40,7 @@ In order to change this option: 1. Select **Save changes**. NOTE: -Once the hostname gets configured, every private commit email using the previous hostname, will not get +After the hostname gets configured, every private commit email using the previous hostname is not recognized by GitLab. This can directly conflict with certain [Push rules](../../../push_rules/push_rules.md) such as `Check whether author is a GitLab user` and `Check whether committer is the current authenticated user`. diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 18ae7e6f05a..0975b93f98f 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -5,10 +5,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# External authorization control **(CORE ONLY)** +# External authorization control **(FREE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4216) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27056) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27056) to GitLab Free in 11.10. In highly controlled environments, it may be necessary for access policy to be controlled by an external service that permits access based on project diff --git a/doc/user/admin_area/settings/gitaly_timeouts.md b/doc/user/admin_area/settings/gitaly_timeouts.md index d196dc1730e..3570634b9ba 100644 --- a/doc/user/admin_area/settings/gitaly_timeouts.md +++ b/doc/user/admin_area/settings/gitaly_timeouts.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Gitaly timeouts **(CORE ONLY)** +# Gitaly timeouts **(FREE SELF)** [Gitaly](../../../administration/gitaly/index.md) timeouts are configurable. The timeouts can be configured to make sure that long running Gitaly calls don't needlessly take up resources. diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 9a661fa9716..3377b1674db 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index --- -# Admin Area settings **(CORE ONLY)** +# Admin Area settings **(FREE SELF)** As an administrator of a GitLab self-managed instance, you can manage the behavior of your deployment. To do so, select **Admin Area > Settings**. @@ -36,7 +36,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | [Elasticsearch](../../../integration/elasticsearch.md#enabling-advanced-search) | Elasticsearch integration. Elasticsearch AWS IAM. | | [Kroki](../../../administration/integration/kroki.md#enable-kroki-in-gitlab) | Allow rendering of diagrams in AsciiDoc and Markdown documents using [kroki.io](https://kroki.io). | | [PlantUML](../../../administration/integration/plantuml.md#gitlab) | Allow rendering of PlantUML diagrams in AsciiDoc and Markdown documents. | -| [Slack application](../../../user/project/integrations/gitlab_slack_application.md#configuration) **(FREE ONLY)** | Slack integration allows you to interact with GitLab via slash commands in a chat window. This option is only available on GitLab.com, though it may be [available for self-managed instances in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). | +| [Slack application](../../../user/project/integrations/gitlab_slack_application.md#configuration) **(FREE SAAS)** | Slack integration allows you to interact with GitLab via slash commands in a chat window. This option is only available on GitLab.com, though it may be [available for self-managed instances in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). | | [Third party offers](third_party_offers.md) | Control the display of third party offers. | | [Snowplow](../../../development/snowplow.md) | Configure the Snowplow integration. | | [Google GKE](../../project/clusters/add_gke_clusters.md) | Google GKE integration allows you to provision GKE clusters from GitLab. | @@ -52,7 +52,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | Repository maintenance | ([Repository checks](../../../administration/repository_checks.md) and [Housekeeping](../../../administration/housekeeping.md)). Configure automatic Git checks and housekeeping on repositories. | | [Repository static objects](../../../administration/static_objects_external_storage.md) | Serve repository static objects (for example, archives, blobs, ...) from an external storage (for example, a CDN). | -## Templates **(PREMIUM ONLY)** +## Templates **(PREMIUM SELF)** | Option | Description | | ------ | ----------- | @@ -64,7 +64,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | Option | Description | | ------ | ----------- | | [Continuous Integration and Deployment](continuous_integration.md) | Auto DevOps, runners and job artifacts. | -| [Required pipeline configuration](continuous_integration.md#required-pipeline-configuration) **(PREMIUM ONLY)** | Set an instance-wide auto included [pipeline configuration](../../../ci/yaml/README.md). This pipeline configuration is run after the project's own configuration. | +| [Required pipeline configuration](continuous_integration.md#required-pipeline-configuration) **(PREMIUM SELF)** | Set an instance-wide auto included [pipeline configuration](../../../ci/yaml/README.md). This pipeline configuration is run after the project's own configuration. | | [Package Registry](continuous_integration.md#package-registry-configuration) | Settings related to the use and experience of using the GitLab Package Registry. Note there are [risks involved](../../packages/container_registry/index.md#use-with-external-container-registries) in enabling some of these settings. | ## Reporting @@ -80,7 +80,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | ------ | ----------- | | [Metrics - Prometheus](../../../administration/monitoring/prometheus/gitlab_metrics.md) | Enable and configure Prometheus metrics. | | [Metrics - Grafana](../../../administration/monitoring/performance/grafana_configuration.md#integration-with-gitlab-ui) | Enable and configure Grafana. | -| [Profiling - Performance bar](../../../administration/monitoring/performance/performance_bar.md#enable-the-performance-bar-via-the-admin-panel) | Enable access to the Performance Bar for a given group. | +| [Profiling - Performance bar](../../../administration/monitoring/performance/performance_bar.md#enable-the-performance-bar-via-the-admin-area) | Enable access to the Performance Bar for a given group. | | [Self monitoring](../../../administration/monitoring/gitlab_self_monitoring_project/index.md#creating-the-self-monitoring-project) | Enable or disable instance self monitoring. | | [Usage statistics](usage_statistics.md) | Enable or disable version check and usage ping. | | [Pseudonymizer data collection](../../../administration/pseudonymizer.md) **(ULTIMATE)** | Enable or disable the Pseudonymizer data collection. | @@ -94,6 +94,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | [Outbound requests](../../../security/webhooks.md) | Allow requests to the local network from hooks and services. | | [Protected Paths](protected_paths.md) | Configure paths to be protected by Rack Attack. | | [Incident Management](../../../operations/incident_management/index.md) Limits | Configure limits on the number of inbound alerts able to be sent to a project. | +| [Notes creation limit](rate_limit_on_notes_creation.md)| Set a rate limit on the note creation requests. | ## Geo diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index 42fa7fe6f54..7630f0c2fbd 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Instance template repository **(PREMIUM ONLY)** +# Instance template repository **(PREMIUM SELF)** **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5986) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. @@ -22,10 +22,9 @@ select the project to serve as the custom template repository.  -Once a project has been selected, you can add custom templates to the repository, -and they will appear in the appropriate places in the -[frontend](../../project/repository/web_editor.md#template-dropdowns) and -[API](../../../api/settings.md). +After that, you can add custom templates to the selected repository and use them for the entire instance. +They will be available on the [Web Editor's dropdown](../../project/repository/web_editor.md#template-dropdowns) +and through the [API settings](../../../api/settings.md). Templates must be added to a specific subdirectory in the repository, corresponding to the kind of template. The following types of custom templates @@ -61,9 +60,7 @@ extension and not be empty. So, the hierarchy should look like this: |-- another_metrics-dashboard.yml ``` -Once this is established, the list of custom templates will be included when -creating a new file and the template type is selected. These will appear at the -top of the list. +Your custom templates will be displayed on the dropdown menu when a new file is added through the GitLab UI:  diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index adb192f5b4a..18491f92650 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -17,7 +17,7 @@ for all projects that didn't have it already enabled. Only the complete settings for an integration can be inherited. Per-field inheritance is [planned](https://gitlab.com/groups/gitlab-org/-/epics/2137). -## Manage instance-level default settings for a project integration **(CORE ONLY)** +## Manage instance-level default settings for a project integration **(FREE SELF)** > - [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. diff --git a/doc/user/admin_area/settings/protected_paths.md b/doc/user/admin_area/settings/protected_paths.md index a03156511e2..061e9fa05d3 100644 --- a/doc/user/admin_area/settings/protected_paths.md +++ b/doc/user/admin_area/settings/protected_paths.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Protected paths **(CORE ONLY)** +# Protected paths **(FREE SELF)** Rate limiting is a common technique used to improve the security and durability of a web application. For more details, see 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 484bb7b0a14..1d6424face0 100644 --- a/doc/user/admin_area/settings/push_event_activities_limit.md +++ b/doc/user/admin_area/settings/push_event_activities_limit.md @@ -5,21 +5,21 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Push event activities limit and bulk push events +# Push event activities limit and bulk push events **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31007) in GitLab 12.4. -This allows you to set the number of changes (branches or tags) in a single push -to determine whether individual push events or bulk push event will be created. -Bulk push events will be created if it surpasses that value. +Set the number of branches or tags to limit the number of single push events +allowed at once. If the number of events is greater than this, GitLab creates +bulk push event instead. For example, if 4 branches are pushed and the limit is currently set to 3, you'll see the following in the activity feed:  -With this feature, when a single push includes a lot of changes (e.g. 1,000 -branches), only 1 bulk push event will be created instead of creating 1,000 push +With this feature, when a single push includes a lot of changes (for example, 1,000 +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. 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 new file mode 100644 index 00000000000..54b5da35dac --- /dev/null +++ b/doc/user/admin_area/settings/rate_limit_on_notes_creation.md @@ -0,0 +1,32 @@ +--- +type: reference +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Rate limits on note creation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53637) in GitLab 13.9. + +This setting allows you to rate limit the requests to the note creation endpoint. + +To change the note creation rate limit: + +1. Go to **Admin Area > Settings > Network**. +1. Expand the **Notes Rate Limits** section. +1. Enter the new value. +1. Select **Save changes**. + +This limit is: + +- Applied independently per user. +- Not applied per IP address. + +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) +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 9ffd46e9ba6..a9b23b3dc50 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 @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Rate limits on raw endpoints **(CORE ONLY)** +# Rate limits on raw endpoints **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30829) in GitLab 12.2. diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 92ad8eced95..a34a63f4543 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Sign-in restrictions **(CORE ONLY)** +# Sign-in restrictions **(FREE SELF)** You can use **Sign-in restrictions** to customize authentication restrictions for web interfaces as well as Git over HTTP(S). @@ -27,7 +27,7 @@ You can restrict the password authentication for web interface and Git over HTTP When this feature enabled, all users must use the [two-factor authentication](../../profile/account/two_factor_authentication.md). -Once the two-factor authentication is configured as mandatory, the users are allowed +After the two-factor authentication is configured as mandatory, users are allowed to skip forced configuration of two-factor authentication for the configurable grace period in hours. diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index ddd3dbda9cc..0945471b11b 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Sign-up restrictions **(CORE ONLY)** +# Sign-up restrictions **(FREE SELF)** You can enforce the following restrictions on sign ups: @@ -50,12 +50,10 @@ 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. Select the **Enable email restrictions for sign ups** checkbox, then select **Save changes**. -## User cap **(CORE ONLY)** +## User cap **(FREE SELF)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4315) in GitLab 13.7. -> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-user-cap). **(CORE ONLY)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292600) in GitLab 13.9. When the number of billable users reaches the user cap, any user who is added or requests access must be [approved](../approving_users.md#approving-a-user) by an administrator before they can start using @@ -64,29 +62,10 @@ their account. If an administrator increases or removes the user cap, the users in pending approval state are automatically approved in a background job. -### Enable or disable User cap **(CORE ONLY)** - -User cap 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 disable it: - -```ruby -Feature.disable(:admin_new_user_signups_cap) -``` - -To enable it: - -```ruby -Feature.enable(:admin_new_user_signups_cap) -``` - ## Soft email confirmation > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47003) in GitLab 12.2. -> - It's [deployed behind a feature flag](../../..//user/feature_flags.md), disabled by default. +> - It's [deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. > - It's enabled on GitLab.com. > - It's recommended for production use. > - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-soft-email-confirmation). @@ -94,7 +73,7 @@ Feature.enable(:admin_new_user_signups_cap) WARNING: This feature might not be available to you. Check the **version history** note above for details. -The soft email confirmation improves the signup experience for new users by allowing +The soft email confirmation improves the sign-up experience for new users by allowing them to sign in without an immediate confirmation when an email confirmation is required. GitLab shows the user a reminder to confirm their email address, and the user can't create or update pipelines until their email address is confirmed. diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index b6826035116..3e0636ef7ac 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -5,9 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Enforce accepting Terms of Service **(CORE ONLY)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18570) in [GitLab Core](https://about.gitlab.com/pricing/) 10.8. +# 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. diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index 84511339842..59845a8d0d8 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.md @@ -5,9 +5,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Third party offers **(CORE ONLY)** +# Third party offers **(FREE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20379) in [GitLab Core](https://about.gitlab.com/pricing/) 11.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20379) in GitLab Free 11.1. Within GitLab, we inform users of available third-party offers they might find valuable in order to enhance the development of their projects. An example is the Google Cloud Platform free credit diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 06b39d67228..2bb6adbc32b 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Usage statistics **(CORE ONLY)** +# Usage statistics **(FREE SELF)** GitLab Inc. periodically collects information about your instance in order to perform various actions. @@ -20,7 +20,7 @@ usage statistics to GitLab Inc. If your GitLab instance is behind a proxy, set the appropriate [proxy configuration variables](https://docs.gitlab.com/omnibus/settings/environment-variables.html). -## Version Check **(CORE ONLY)** +## Version Check **(FREE SELF)** If enabled, version check informs you if a new version is available and the importance of it through a status. This is shown on the help page (i.e. `/help`) @@ -59,7 +59,7 @@ sequenceDiagram Version Application->>GitLab instance: Response (PNG/SVG) ``` -## Usage Ping **(CORE ONLY)** +## Usage Ping **(FREE SELF)** See [Usage Ping guide](../../../development/usage_ping.md). diff --git a/doc/user/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md index e2040ef19d6..ba4ef890caa 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 @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# User and IP rate limits **(CORE ONLY)** +# User and IP rate limits **(FREE SELF)** Rate limiting is a common technique used to improve the security and durability of a web application. For more details, see 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 fe1841e7020..0fcdbf3ca90 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -5,22 +5,22 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Visibility and access controls **(CORE ONLY)** +# Visibility and access controls **(FREE SELF)** GitLab allows administrators to enforce specific controls. To access the visibility and access control options: -1. Log in to GitLab as an admin. +1. Sign in to GitLab as a user with Administrator [permissions](../../permissions.md). 1. Go to **Admin Area > 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_. +branches. In this case _Default_ refers to a repository's default branch, which in most cases is `master`. -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). +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). To change the default branch protection: @@ -31,7 +31,7 @@ For more details, see [Protected branches](../../project/protected_branches.md). To change this setting for a specific group, see [Default branch protection for groups](../../group/index.md#changing-the-default-branch-protection-of-a-group) -### Disable group owners from updating default branch protection **(PREMIUM ONLY)** +### Disable group owners from updating default branch protection **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211944) in GitLab 13.0. @@ -57,30 +57,30 @@ To change the default project creation protection: For more details, see [Default project-creation level](../../group/index.md#default-project-creation-level). -## Default project deletion protection **(PREMIUM ONLY)** +## Default project deletion protection **(PREMIUM SELF)** By default, a project can be deleted by anyone with the **Owner** role, either at the project or group level. -To ensure only admin users can delete projects: +To ensure only Administrator users can delete projects: 1. Check the **Default project deletion protection** checkbox. 1. Click **Save changes**. -## Default deletion delay **(PREMIUM ONLY)** +## Default deletion delay **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6. -By default, a project marked for deletion will be permanently removed with immediate effect. -By default, a group marked for deletion will be permanently removed after 7 days. +By default, a project marked for deletion is permanently removed with immediate effect. +By default, a group marked for deletion is permanently removed after seven days. WARNING: The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to [Immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. -Projects within a group (but not a personal namespace) can be deleted after a delayed period, by [configuring in Group Settings](../../group/index.md#enabling-delayed-project-removal). - -The default period is 7 days, and can be changed. Setting this period to 0 will enable immediate removal +Projects in a group (but not a personal namespace) can be deleted after a delayed period, by +[configuring in Group Settings](../../group/index.md#enabling-delayed-project-removal). +The default period is seven days, and can be changed. Setting this period to `0` enables immediate removal of projects or groups. To change this period: @@ -124,10 +124,10 @@ For more details on group visibility, see [Public access](../../../public_access ## Restricted visibility levels -To set the available visibility levels for projects, snippets, and selected pages: +To set the restricted visibility levels for projects, snippets, and selected pages: -1. Check the desired visibility levels. -1. Click **Save changes**. +1. Select the desired visibility levels to restrict. +1. Select **Save changes**. For more details on project visibility, see [Public access](../../../public_access/public_access.md). @@ -149,13 +149,11 @@ For more details, see [Exporting a project and its data](../../../user/project/s ## Enabled Git access protocols -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4696) in GitLab 8.10. - With GitLab access restrictions, you can select with which protocols users can communicate with GitLab. -Disabling an access protocol does not block access to the server itself via those ports. The ports -used for the protocol, SSH or HTTP(S), will still be accessible. The GitLab restrictions apply at the +Disabling an access protocol does not block access to the server itself by using those ports. The ports +used for the protocol, SSH or HTTP(S), are still accessible. The GitLab restrictions apply at the application level. To specify the enabled Git access protocols: @@ -170,26 +168,26 @@ When both SSH and HTTP(S) are enabled, users can choose either protocol. When only one protocol is enabled: -- The project page will only show the allowed protocol's URL, with no option to +- The project page shows only the allowed protocol's URL, with no option to change it. -- A tooltip will be shown when you hover over the URL's protocol, if an action - on the user's part is required, e.g. adding an SSH key, or setting a password. +- A tooltip is shown when you hover over the URL's protocol, if an action + on the user's part is required. For example, adding an SSH key or setting a password.  -On top of these UI restrictions, GitLab will deny all Git actions on the protocol +On top of these UI restrictions, GitLab denies all Git actions on the protocol not selected. WARNING: -Starting with [GitLab 10.7](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18021), -HTTP(S) protocol will be allowed for Git clone or fetch requests done by GitLab Runner -from CI/CD jobs, even if _Only SSH_ was selected. +GitLab versions [10.7 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18021), +allow the HTTP(S) protocol for Git clone or fetch requests done by GitLab Runner +from CI/CD jobs, even if **Only SSH** was selected. ## Custom Git clone URL for HTTP(S) > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18422) in GitLab 12.4. -You can customize project Git clone URLs for HTTP(S). This will affect the clone +You can customize project Git clone URLs for HTTP(S), which affects the clone panel:  @@ -225,10 +223,9 @@ For more details, see [SSH key restrictions](../../../security/ssh_keys_restrict ## Allow mirrors to be set up for projects -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3586) in GitLab 10.3. - -This option is enabled by default. By disabling it, both [pull and push mirroring](../../project/repository/repository_mirroring.md) will no longer -work in every repository and can only be re-enabled by an admin on a per-project basis. +This option is enabled by default. By disabling it, both +[pull and push mirroring](../../project/repository/repository_mirroring.md) no longer +work in every repository. They can only be re-enabled by an administrator user on a per-project basis.  diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md deleted file mode 100644 index a95501c0bde..00000000000 --- a/doc/user/admin_area/user_cohorts.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'analytics/user_cohorts.md' ---- - -This document was moved to [another location](analytics/user_cohorts.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index beb2cbfdc58..0f19998749d 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # CI/CD Analytics -## Pipeline success and duration charts **(CORE)** +## Pipeline success and duration charts **(FREE)** > - 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. @@ -22,6 +22,29 @@ View pipeline duration history:  +## DORA4 Metrics + +Customer experience is a key metric. Users want to measure platform stability and other +post-deployment performance KPIs, and set targets for customer behavior, experience, and financial +impact. Tracking and measuring these indicators solves an important pain point. Similarly, creating +views that manage products, not projects or repositories, provides users with a more relevant data set. +Since GitLab is a tool for the entire DevOps life-cycle, information from different workflows is +integrated and can be used to measure the success of the teams. + +The DevOps Research and Assessment ([DORA](https://cloud.google.com/blog/products/devops-sre/the-2019-accelerate-state-of-devops-elite-performance-productivity-and-scaling)) +team developed four key metrics that the industry has widely adopted. You can use these metrics as +performance indicators for software development teams: + +- Deployment frequency: How often an organization successfully releases to production. +- Lead time for changes: The amount of time it takes for code to reach production. +- Change failure rate: The percentage of deployments that cause a failure in production. +- Time to restore service: How long it takes an organization to recover from a failure in + production. + +GitLab plans to add support for all the DORA4 metrics at the project and group levels. GitLab added +the first metric, deployment frequency, at the project and group scopes for [CI/CD charts](ci_cd_analytics.md#deployment-frequency-charts), +the [Project API]( ../../api/dora4_project_analytics.md), and the [Group API]( ../../api/dora4_group_analytics.md). + ## Deployment frequency charts **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.8. diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index 745774480b0..19016c3aa26 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -6,22 +6,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w --- -# Code Review Analytics **(STARTER)** +# Code Review Analytics **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38062) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38062) in GitLab 12.7. +> - Moved to GitLab Premium in 13.9. -Code Review Analytics makes it easy to view the longest-running reviews among open merge requests and -enables you to: +Use Code Review Analytics to view the longest-running reviews among open merge +requests, and: -1. Take action on individual merge requests. -1. Reduce overall cycle time. +- Take action on individual merge requests. +- Reduce overall cycle time. NOTE: Initially, no data appears. Data is populated as users comment on open merge requests. ## Overview -Code Review Analytics displays a table of open merge requests that have at least one non-author comment. The review time is measured from the time the first non-author comment was submitted. +Code Review Analytics is available to users with Reporter access and above, and displays a table of open merge requests that have at least one non-author comment. The review time is measured from the time the first non-author comment was submitted. To access Code Review Analytics, from your project's menu, go to **Project Analytics > Code Review**. @@ -53,8 +54,3 @@ For example: - Lots of comments or commits? Maybe the code is too complex. - A particular author is involved? Maybe more training is required. - Few comments and approvers? Maybe your team is understaffed. - -## Permissions - -- On [Starter or Bronze tier](https://about.gitlab.com/pricing/) and above. -- By users with Reporter access and above. diff --git a/doc/user/analytics/cycle_analytics.md b/doc/user/analytics/cycle_analytics.md deleted file mode 100644 index 5c235f6708b..00000000000 --- a/doc/user/analytics/cycle_analytics.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../analytics/value_stream_analytics.md' ---- - -This document was moved to [another location](../analytics/value_stream_analytics.md) - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index caa8972b220..f5da373ee6d 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -6,6 +6,28 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Analytics +## Definitions + +When we describe GitLab analytics, we use the following terms: + +- Cycle time: The duration of your value stream, from start to finish. Often displayed in combination with "lead time." GitLab measures cycle time from issue creation to issue close. GitLab displays cycle time in [Value Stream Analytics](value_stream_analytics.md). +- DORA (DevOps Research and Assessment) ["Four Keys"](https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance): + - Speed + - Deployment Frequency: How often an organization successfully releases to production. + - Lead Time for Changes: The time it takes for a commit to get into production. This differs from ordinary "lead time" as it "focuses on measuring only the time to deliver a feature once it has been developed", +as described in ([Measuring DevOps Performance](https://devops.com/measuring-devops-performance/)). + - Stability + - Change Failure Rate: The percentage of deployments causing a failure in production. + - Time to Restore Service: How long it takes an organization to recover from a failure in production. +- MTTC (Mean Time to Change): The average duration between idea and delivery. GitLab measures MTTC from issue creation to the issue's latest related merge request's deployment to production. +- MTTD (Mean Time to Detect): The average duration that a bug goes undetected in production. GitLab measures MTTD from deployment of bug to issue creation. +- MTTM (Mean Time To Merge): The average lifespan of a merge request. GitLab measures MTTM from merge request creation to merge request merge (and closed/un-merged merge requests are excluded). For more information, see [Merge Request Analytics](merge_request_analytics.md). +- MTTR (Mean Time to Recover/Repair/Resolution/Resolve/Restore): The average duration that a bug is not fixed in production. GitLab measures MTTR from deployment of bug to deployment of fix. +- Lead time: The duration of the work itself. Often displayed in combination with "cycle time." GitLab measures from issue first merge request creation to issue close. Note: Obviously work started before the creation of the first merge request. We plan to start measuring from "issue first commit" as a better proxy, although still imperfect. GitLab displays lead time in [Value Stream Analytics](value_stream_analytics.md). +- Throughput: The number of issues closed or merge requests merged (not closed) in some period of time. Often measured per sprint. GitLab displays merge request throughput in [Merge Request Analytics](merge_request_analytics.md). +- Value Stream: The entire work process that is followed to deliver value to customers. For example, the [DevOps lifecycle](https://about.gitlab.com/stages-devops-lifecycle/) is a value stream that starts with "plan" and ends with "monitor". GitLab helps you track your value stream using [Value Stream Analytics](value_stream_analytics.md). +- Velocity: The total issue burden completed in some period of time. The burden is usually measured in points or weight, often per sprint. For example, your velocity may be "30 points per sprint". GitLab measures velocity as the total points/weight of issues closed in a given period of time. + ## Instance-level analytics > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12077) in GitLab 12.2. @@ -18,26 +40,27 @@ in one place. ## Group-level analytics -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195979) in GitLab 12.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195979) in GitLab 12.8. +> - Moved to [GitLab Premium](https://about.gitlab.com/pricing/) due to Starter/Bronze being [discontinued](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) in 13.9. The following analytics features are available at the group level: -- [Contribution](../group/contribution_analytics/index.md). **(STARTER)** +- [Contribution](../group/contribution_analytics/index.md). **(PREMIUM)** - [Insights](../group/insights/index.md). **(ULTIMATE)** - [Issue](../group/issues_analytics/index.md). **(PREMIUM)** - [Productivity](productivity_analytics.md) **(PREMIUM)** - [Repositories](../group/repositories_analytics/index.md) **(PREMIUM)** -- [Value Stream](value_stream_analytics.md). **(PREMIUM)** +- [Value Stream](../group/value_stream_analytics/index.md). **(PREMIUM)** ## Project-level analytics The following analytics features are available at the project level: -- [CI/CD](ci_cd_analytics.md). **(CORE)** -- [Code Review](code_review_analytics.md). **(STARTER)** +- [CI/CD](ci_cd_analytics.md). **(FREE)** +- [Code Review](code_review_analytics.md). **(PREMIUM)** - [Insights](../project/insights/index.md). **(ULTIMATE)** - [Issue](../group/issues_analytics/index.md). **(PREMIUM)** - [Merge Request](merge_request_analytics.md), enabled with the `project_merge_request_analytics` - [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-locally-in-development). **(STARTER)** -- [Repository](repository_analytics.md). **(CORE)** -- [Value Stream](value_stream_analytics.md). **(CORE)** + [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-locally-in-development). **(PREMIUM)** +- [Repository](repository_analytics.md). **(FREE)** +- [Value Stream](value_stream_analytics.md). **(FREE)** diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md index 0aa135ab88d..6c6911ff4f4 100644 --- a/doc/user/analytics/issue_analytics.md +++ b/doc/user/analytics/issue_analytics.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9. Issue Analytics is a bar graph which illustrates the number of issues created each month. -The default timespan is 13 months, which includes the current month, and the 12 months +The default time span is 13 months, which includes the current month, and the 12 months prior. To access the chart, navigate to your project sidebar and select **{chart}** **Analytics > Issue Analytics**. diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index c0fe19f1f16..3edbe3e8aa4 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -5,9 +5,10 @@ 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 --- -# Merge Request Analytics **(STARTER)** +# Merge Request Analytics **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229045) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229045) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.3. +> - Moved to [GitLab Premium](https://about.gitlab.com/pricing/) due to Starter/Bronze being [discontinued](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) in 13.9. Merge Request Analytics helps you understand the efficiency of your code review process, and the productivity of your team. @@ -102,5 +103,5 @@ bookmark for those preferred settings in your browser. The **Merge Request Analytics** feature can be accessed only: -- On [Starter](https://about.gitlab.com/pricing/) and above. +- On [Premium](https://about.gitlab.com/pricing/) and above. - By users with [Reporter access](../permissions.md) and above. diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index 633d7b35087..a06d94caf69 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -16,7 +16,7 @@ long, on average, it takes to deliver features is an enormous endeavor. While [Value Stream Analytics](../analytics/value_stream_analytics.md) focuses on the entire Software Development Life Cycle (SDLC) process, Productivity Analytics provides a way for Engineering Management to drill down in a systematic way to uncover patterns and causes for success or failure at an individual, project, or group level. -Productivity can slow down for many reasons ranging from degrading code base to quickly growing teams. In order to investigate, department or team leaders can start by visualizing the time it takes for merge requests to be merged. +Productivity can slow down for many reasons ranging from degrading codebase to quickly growing teams. In order to investigate, department or team leaders can start by visualizing the time it takes for merge requests to be merged. ## Supported features @@ -60,5 +60,5 @@ GitLab has the ability to filter analytics based on a date range. To filter resu The **Productivity Analytics** dashboard can be accessed only: -- On [Premium or Silver tier](https://about.gitlab.com/pricing/) and above. +- On the [Premium tier](https://about.gitlab.com/pricing/) and above. - By users with [Reporter access](../permissions.md) and above. diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index b5aecff5180..6c41d93d51f 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.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 --- -# Value Stream Analytics **(CORE)** +# 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. diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 674afcb29ee..49311ccc7cd 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -69,7 +69,7 @@ Examples of both configurations can be found here: The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an API description format for REST APIs. This section shows you how to configure API fuzzing by using an OpenAPI specification to provide information about the target API to test. OpenAPI specifications -are provided as a filesystem resource or URL. +are provided as a file system resource or URL. Follow these steps to configure API fuzzing in GitLab with an OpenAPI specification: @@ -89,7 +89,7 @@ Follow these steps to configure API fuzzing in GitLab with an OpenAPI specificat amounts of fuzzing. We recommend that you start with the `Quick-10` profile. Testing with this profile completes quickly, allowing for easier configuration validation. - Provide the profile by adding the `FUZZAPI_PROFILE` variable to your `.gitlab-ci.yml` file, + Provide the profile by adding the `FUZZAPI_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, substituting `Quick-10` for the profile you choose: ```yaml @@ -182,7 +182,7 @@ target API to test: amounts of fuzzing. We recommend that you start with the `Quick-10` profile. Testing with this profile completes quickly, allowing for easier configuration validation. - Provide the profile by adding the `FUZZAPI_PROFILE` variable to your `.gitlab-ci.yml` file, + Provide the profile by adding the `FUZZAPI_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, substituting `Quick-10` for the profile you choose: ```yaml @@ -273,7 +273,7 @@ information about the target API to test: amounts of fuzzing. We recommend that you start with the `Quick-10` profile. Testing with this profile completes quickly, allowing for easier configuration validation. - Provide the profile by adding the `FUZZAPI_PROFILE` variable to your `.gitlab-ci.yml` file, + Provide the profile by adding the `FUZZAPI_PROFILE` CI/CD variable to your `.gitlab-ci.yml` file, substituting `Quick-10` for the profile you choose: ```yaml @@ -335,16 +335,17 @@ provide a script that performs an authentication flow or calculates the token. #### HTTP Basic Authentication [HTTP basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) -is an authentication method built into the HTTP protocol and used in-conjunction with +is an authentication method built in to the HTTP protocol and used in conjunction with [transport layer security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security). -To use HTTP basic authentication, two variables are added to your `.gitlab-ci.yml` file: +To use HTTP basic authentication, two CI/CD variables are added to your `.gitlab-ci.yml` file: - `FUZZAPI_HTTP_USERNAME`: The username for authentication. - `FUZZAPI_HTTP_PASSWORD`: The password for authentication. For the password, we recommended that you [create a CI/CD variable](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui) (for example, `TEST_API_PASSWORD`) set to the password. You can create CI/CD variables from the -GitLab projects page at **Settings > CI/CD**, in the **Variables** section. +GitLab projects page at **Settings > CI/CD**, in the **Variables** section. Use that variable +as the value for `FUZZAPI_HTTP_PASSWORD`: ```yaml include: @@ -356,7 +357,6 @@ variables: FUZZAPI_TARGET_URL: http://test-deployment/ FUZZAPI_HTTP_USERNAME: testuser FUZZAPI_HTTP_PASSWORD: $TEST_API_PASSWORD - ``` #### Bearer Tokens @@ -371,36 +371,39 @@ tokens with API fuzzing, you need one of the following: ##### Token doesn't expire -If the bearer token doesn't expire, you can provide it using the `FUZZAPI_OVERRIDES_ENV` variable. -The `FUZZAPI_OVERRIDES_ENV` content is a JSON snippet that provides headers and cookies that should -be added to outgoing HTTP requests made by API fuzzing. +If the bearer token doesn't expire, use the `FUZZAPI_OVERRIDES_ENV` variable to provide it. This +variable's content is a JSON snippet that provides headers and cookies to add to API fuzzing's +outgoing HTTP requests. -Create a CI/CD variable, for example `TEST_API_BEARERAUTH`, with the value -`{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}` (substitute your token). You can -create CI/CD variables from the GitLab projects page at **Settings > CI/CD** in the **Variables** -section. +Follow these steps to provide the bearer token with `FUZZAPI_OVERRIDES_ENV`: -Set `FUZZAPI_OVERRIDES_ENV` in your `.gitlab-ci.yml` file: +1. [Create a CI/CD variable](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), + for example `TEST_API_BEARERAUTH`, with the value + `{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}` (substitute your token). You + can create CI/CD variables from the GitLab projects page at **Settings > CI/CD**, in the + **Variables** section. -```yaml -include: - - template: API-Fuzzing.gitlab-ci.yml +1. In your `.gitlab-ci.yml` file, set `FUZZAPI_OVERRIDES_ENV` to the variable you just created: -variables: - FUZZAPI_PROFILE: Quick-10 - FUZZAPI_OPENAPI: test-api-specification.json - FUZZAPI_TARGET_URL: http://test-deployment/ - FUZZAPI_OVERRIDES_ENV: $TEST_API_BEARERAUTH -``` + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml -To validate that authentication is working, run an API fuzzing test and review the fuzzing logs and -the test API's application logs. + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OVERRIDES_ENV: $TEST_API_BEARERAUTH + ``` + +1. To validate that authentication is working, run an API fuzzing test and review the fuzzing logs + and the test API's application logs. -##### Token generated at test-runtime +##### Token generated at test runtime -If the bearer token must be generated, and the resulting token doesn't expire during testing, you -can provide to API fuzzing a file containing the token. This file can be generated by a prior stage -and job, or as part of the API fuzzing job. +If the bearer token must be generated and doesn't expire during testing, you can provide to API +fuzzing a file containing the token. A prior stage and job, or part of the API fuzzing job, can +generate this file. API fuzzing expects to receive a JSON file with the following structure: @@ -413,7 +416,7 @@ API fuzzing expects to receive a JSON file with the following structure: ``` This file can be generated by a prior stage and provided to API fuzzing through the -`FUZZAPI_OVERRIDES_FILE` variable. +`FUZZAPI_OVERRIDES_FILE` CI/CD variable. Set `FUZZAPI_OVERRIDES_FILE` in your `.gitlab-ci.yml` file: @@ -448,11 +451,13 @@ The script must create a JSON file containing the bearer token in a specific for } ``` -You must provide three variables, each set for correct operation: +You must provide three CI/CD variables, each set for correct operation: -- `FUZZAPI_OVERRIDES_FILE`: File generated by the provided command. -- `FUZZAPI_OVERRIDES_CMD`: Command to generate JSON file. -- `FUZZAPI_OVERRIDES_INTERVAL`: Interval in seconds to run command. +- `FUZZAPI_OVERRIDES_FILE`: JSON file the provided command generates. +- `FUZZAPI_OVERRIDES_CMD`: Command that generates the JSON file. +- `FUZZAPI_OVERRIDES_INTERVAL`: Interval (in seconds) to run command. + +For example: ```yaml include: @@ -472,35 +477,35 @@ the test API's application logs. ### Configuration files -To get started quickly, GitLab provides you with the configuration file +To get you started quickly, GitLab provides the configuration file [`gitlab-api-fuzzing-config.yml`](https://gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing/-/blob/master/gitlab-api-fuzzing-config.yml). -This file has several testing profiles that perform various amounts of testing. The run time of each -increases as the numbers go up. To use a configuration file, add it to your repository's root as -`.gitlab-api-fuzzing.yml`. +This file has several testing profiles that perform various numbers of tests. The run time of each +profile increases as the test numbers go up. To use a configuration file, add it to your +repository's root as `.gitlab-api-fuzzing.yml`. -| Profile | Scan Type | +| Profile | Fuzz Tests (per parameter) | |:---------|:-----------| -|Quick-10 |Fuzzing 10 times per parameter | -|Medium-20 |Fuzzing 20 times per parameter | -|Medium-50 |Fuzzing 50 times per parameter | -|Long-100 |Fuzzing 100 times per parameter | - -### Available variables - -| Environment variable | Description | -|-----------------------------|--------------------| -| `FUZZAPI_VERSION` | Specify API Fuzzing container version. Defaults to `latest`. | -| `FUZZAPI_TARGET_URL` | Base URL of API testing target. | -|[`FUZZAPI_CONFIG`](#configuration-files) | API Fuzzing configuration file. Defaults to `.gitlab-apifuzzer.yml`. | -|[`FUZZAPI_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | -| `FUZZAPI_REPORT` | Scan report filename. Defaults to `gl-api_fuzzing-report.xml`. | -|[`FUZZAPI_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | -|[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | -|[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | -|[`FUZZAPI_OVERRIDES_FILE`](#overrides) | Path to a JSON file containing overrides. | -|[`FUZZAPI_OVERRIDES_ENV`](#overrides) | JSON string containing headers to override. | -|[`FUZZAPI_OVERRIDES_CMD`](#overrides) | Overrides command. | -|[`FUZZAPI_OVERRIDES_INTERVAL`](#overrides) | How often to run overrides command in seconds. Defaults to `0` (once). | +| Quick-10 | 10 | +| Medium-20 | 20 | +| Medium-50 | 50 | +| Long-100 | 100 | + +### Available CI/CD variables + +| CI/CD variable | Description | +|------------------------------------------------------|--------------------| +| `FUZZAPI_VERSION` | Specify API Fuzzing container version. Defaults to `latest`. | +| `FUZZAPI_TARGET_URL` | Base URL of API testing target. | +|[`FUZZAPI_CONFIG`](#configuration-files) | API Fuzzing configuration file. Defaults to `.gitlab-apifuzzer.yml`. | +|[`FUZZAPI_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | +| `FUZZAPI_REPORT` | Scan report filename. Defaults to `gl-api_fuzzing-report.xml`. | +|[`FUZZAPI_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | +|[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | +|[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | +|[`FUZZAPI_OVERRIDES_FILE`](#overrides) | Path to a JSON file containing overrides. | +|[`FUZZAPI_OVERRIDES_ENV`](#overrides) | JSON string containing headers to override. | +|[`FUZZAPI_OVERRIDES_CMD`](#overrides) | Overrides command. | +|[`FUZZAPI_OVERRIDES_INTERVAL`](#overrides) | How often to run overrides command in seconds. Defaults to `0` (once). | |[`FUZZAPI_HTTP_USERNAME`](#http-basic-authentication) | Username for HTTP authentication. | |[`FUZZAPI_HTTP_PASSWORD`](#http-basic-authentication) | Password for HTTP authentication. | @@ -518,11 +523,11 @@ increases as the numbers go up. To use a configuration file, add it to your repo ### Overrides -API Fuzzing provides a method to add or override headers and cookies for all outbound HTTP requests -made. You can use this to inject semver headers, authentication, and so on. The +API Fuzzing provides a method to add or override headers and cookies for all outbound HTTP requests. +You can use this to inject semantic version headers, authentication, and so on. The [authentication section](#authentication) includes examples of using overrides for that purpose. -Overrides uses a JSON document to define the headers and cookies: +Overrides use a JSON document to define the headers and cookies: ```json { @@ -537,7 +542,7 @@ Overrides uses a JSON document to define the headers and cookies: } ``` -Example usage for setting a single header: +Example of setting a single header: ```json { @@ -547,7 +552,7 @@ Example usage for setting a single header: } ``` -Example usage for setting both a header and cookie: +Example of setting both a header and cookie: ```json { @@ -560,14 +565,14 @@ Example usage for setting both a header and cookie: } ``` -You can provide this JSON document as a file or environment variable. You may also provide a command +You can provide this JSON document as a file or CI/CD variable. You may also provide a command to generate the JSON document. The command can run at intervals to support values that expire. #### Using a file -To provide the overrides JSON as a file, the `FUZZAPI_OVERRIDES_FILE` environment variable is set. The path is relative to the job current working directory. +To provide the overrides JSON as a file, the `FUZZAPI_OVERRIDES_FILE` CI/CD variable is set. The path is relative to the job current working directory. -Example `.gitlab-ci.yml`: +Here's an example `.gitlab-ci.yml`: ```yaml include: @@ -580,12 +585,12 @@ variables: FUZZAPI_OVERRIDES_FILE: output/api-fuzzing-overrides.json ``` -#### Using an environment variable +#### Using a CI/CD variable -To provide the overrides JSON as an environment variable, use the `FUZZAPI_OVERRIDES_ENV` variable. -This allows you to place the JSON as CI/CD variables that can be masked and protected. +To provide the overrides JSON as a CI/CD variable, use the `FUZZAPI_OVERRIDES_ENV` variable. +This allows you to place the JSON as variables that can be masked and protected. -In this example `.gitlab-ci.yml`, the JSON is provided directly: +In this example `.gitlab-ci.yml`, the `FUZZAPI_OVERRIDES_ENV` variable is set directly to the JSON: ```yaml include: @@ -598,8 +603,8 @@ variables: FUZZAPI_OVERRIDES_ENV: '{"headers":{"X-API-Version":"2"}}' ``` -In this example `.gitlab-ci.yml`, the CI/CD variable `SECRET_OVERRIDES` provides the JSON. This is a -[group or instance level environment variable defined in the UI](../../../ci/variables/README.md#instance-level-cicd-environment-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-level-cicd-variables): ```yaml include: @@ -620,7 +625,7 @@ container that has Python 3 and Bash installed. If the Python script requires ad it must detect this and install the packages at runtime. The script creates the overrides JSON file as defined above. -You must provide three variables, each set for correct operation: +You must provide three CI/CD variables, each set for correct operation: - `FUZZAPI_OVERRIDES_FILE`: File generated by the provided command. - `FUZZAPI_OVERRIDES_CMD`: Command to generate JSON file. @@ -689,9 +694,9 @@ for off. To turn header fuzzing on, change this setting to `true`: Headers: ``` -`Headers` is a list of headers to fuzz. Only headers listed are fuzzed. For example, to fuzz a -custom header `X-Custom` used by your APIs, add an entry for it using the syntax -`- Name: HeaderName`, substituting `HeaderName` with the header to fuzz: +`Headers` is a list of headers to fuzz. Only headers listed are fuzzed. To fuzz a header used by +your APIs, add an entry for it using the syntax `- Name: HeaderName`. For example, to fuzz a +custom header `X-Custom`, add `- Name: X-Custom`: ```yaml - Name: GeneralFuzzingCheck diff --git a/doc/user/application_security/compliance_dashboard/index.md b/doc/user/application_security/compliance_dashboard/index.md deleted file mode 100644 index 383d2bf2df7..00000000000 --- a/doc/user/application_security/compliance_dashboard/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../compliance/compliance_dashboard/index.md' ---- - -This document was moved to [another location](../../compliance/compliance_dashboard/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 9bde2c28972..6eec1418ef0 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -9,6 +9,15 @@ 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. This is not a hard +breaking change, as customers who wish to continue to use Clair can do so by setting the +`CS_MAJOR_VERSION` CI/CD variable to version 3 (or earlier) in their `gitlab-ci.yaml` file. Since Clair is +deprecated, however, note that GitLab will no longer update or maintain that scanning engine +beginning in the 14.0 release. We advise customers to use the new default of Trivy beginning in +GitLab 14.0 for regular updates and the latest features. + 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. @@ -46,7 +55,7 @@ To enable container scanning in your pipeline, you need the following: - An image matching [Clair's list of supported distributions](https://quay.github.io/claircore/). - [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 environment variables](../../../ci/variables/predefined_variables.md): + the following [predefined CI/CD variables](../../../ci/variables/predefined_variables.md): ```plaintext $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA @@ -131,12 +140,12 @@ 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 from Clair or Klar, 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 [environment variables](#available-variables). -The environment variables you set in your `.gitlab-ci.yml` overwrite those in +parameter in your `.gitlab-ci.yml` to set [CI/CD variables](#available-variables). +The variables you set in your `.gitlab-ci.yml` overwrite those in `Container-Scanning.gitlab-ci.yml`. This example [includes](../../../ci/yaml/README.md#include) the container scanning template and -enables verbose output from Clair by setting the `CLAIR_OUTPUT` environment variable to `High`: +enables verbose output from Clair by setting the `CLAIR_OUTPUT` variable to `High`: ```yaml include: @@ -173,26 +182,26 @@ variables: #### Available variables You can [configure](#customizing-the-container-scanning-settings) container -scanning by using the following environment variables: +scanning by using the following CI/CD variables: -| Environment Variable | Default | Description | +| CI/CD Variable | Default | Description | | ------------------------------ | ------------- | ----------- | -| `ADDITIONAL_CA_CERT_BUNDLE` | `""` | Bundle of CA certs that you want to trust. | +| `ADDITIONAL_CA_CERT_BUNDLE` | `""` | Bundle of CA certs that you want to trust. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. | | `CLAIR_DB_CONNECTION_STRING` | `postgresql://postgres:password@clair-vulnerabilities-db:5432/postgres?sslmode=disable&statement_timeout=60000` | This variable represents the [connection string](https://www.postgresql.org/docs/9.3/libpq-connect.html#AEN39692) to the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) database and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone container scanning tool](#running-the-standalone-container-scanning-tool) section. The host value for the connection string must match the [alias](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) value of the `Container-Scanning.gitlab-ci.yml` template file, which defaults to `clair-vulnerabilities-db`. | | `CLAIR_DB_IMAGE` | `arminc/clair-db:latest` | The Docker image name and tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes, or to refer to a locally hosted vulnerabilities database for an on-premise offline installation. | | `CLAIR_DB_IMAGE_TAG` | `latest` | (**DEPRECATED - use `CLAIR_DB_IMAGE` instead**) The Docker image tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes. | | `CLAIR_OUTPUT` | `Unknown` | Severity level threshold. Vulnerabilities with severity level higher than or equal to this threshold are outputted. Supported levels are `Unknown`, `Negligible`, `Low`, `Medium`, `High`, `Critical` and `Defcon1`. | -| `CLAIR_TRACE` | `"false"` | Set to true to enable more verbose output from the clair server process. | +| `CLAIR_TRACE` | `"false"` | Set to true to enable more verbose output from the Clair server process. | | `CLAIR_VULNERABILITIES_DB_URL` | `clair-vulnerabilities-db` | (**DEPRECATED - use `CLAIR_DB_CONNECTION_STRING` instead**) This variable is explicitly set in the [services section](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) of the `Container-Scanning.gitlab-ci.yml` file and defaults to `clair-vulnerabilities-db`. This value represents the address that the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) is running on and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone container scanning tool](#running-the-standalone-container-scanning-tool) section. | | `CI_APPLICATION_REPOSITORY` | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | Docker repository URL for the image to be scanned. | | `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | -| `CS_MAJOR_VERSION` | `3` | The major version of the Docker image tag. | +| `CS_MAJOR_VERSION` | `3` | The major version of the Docker image tag. | | `DOCKER_IMAGE` | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | The Docker image to be scanned. If set, this variable overrides the `$CI_APPLICATION_REPOSITORY` and `$CI_APPLICATION_TAG` variables. | | `DOCKER_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access secure Docker registries using HTTPS with bad (or self-signed) SSL certificates. | | `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. | | `DOCKER_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. | | `DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to be used for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project, so this variable should only be configured if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | -| `KLAR_TRACE` | `"false"` | Set to true to enable more verbose output from klar. | +| `KLAR_TRACE` | `"false"` | Set to true to enable more verbose output from Klar. | | `REGISTRY_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | | `SECURE_ANALYZERS_PREFIX` | `"registry.gitlab.com/gitlab-org/security-products/analyzers"` | Set the Docker registry base address from which to download the analyzer. | | `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. | @@ -217,6 +226,23 @@ GitLab 13.0 and later doesn't support [`only` and `except`](../../../ci/yaml/REA When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. +### Using a custom SSL CA certificate authority + +You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority, which is used to verify the peer when fetching Docker images from a registry which uses HTTPS. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following: + +```yaml +container_scanning: + variables: + ADDITIONAL_CA_CERT_BUNDLE: | + -----BEGIN CERTIFICATE----- + MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB + ... + jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs= + -----END CERTIFICATE----- +``` + +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. + ### Vulnerability allowlisting To allowlist specific vulnerabilities, follow these steps: @@ -277,7 +303,7 @@ For details on saving and transporting Docker images as a file, see Docker's doc [`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/), [`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/). -#### Set container scanning CI job variables to use local container scanner analyzers +#### Set container scanning CI/CD variables to use local container scanner analyzers 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: @@ -334,13 +360,13 @@ image directly, follow these steps: docker run -p 5432:5432 -d --name clair-db arminc/clair-db:latest ``` -1. Configure an environment 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): +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` environment variables: +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 \ @@ -437,7 +463,7 @@ Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. To enable remediation support, the scanning tool _must_ have access to the `Dockerfile` specified by -the [`DOCKERFILE_PATH`](#available-variables) environment variable. To ensure that the scanning tool +the [`DOCKERFILE_PATH`](#available-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 your `.gitlab-ci.yml` file by following the instructions described in this document's diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 469945246c1..9e42b3e403a 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -27,12 +27,13 @@ Docker image with the fuzz engine to run your app. |----------|----------------|---------| | C/C++ | [libFuzzer](https://llvm.org/docs/LibFuzzer.html) | [c-cpp-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/c-cpp-fuzzing-example) | | GoLang | [go-fuzz (libFuzzer support)](https://github.com/dvyukov/go-fuzz) | [go-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example) | -| Swift | [libfuzzer](https://github.com/apple/swift/blob/master/docs/libFuzzerIntegration.md) | [swift-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/swift-fuzzing-example) | +| Swift | [libFuzzer](https://github.com/apple/swift/blob/master/docs/libFuzzerIntegration.md) | [swift-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/swift-fuzzing-example) | | Rust | [cargo-fuzz (libFuzzer support)](https://github.com/rust-fuzz/cargo-fuzz) | [rust-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/rust-fuzzing-example) | -| Java | [javafuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/javafuzz) (recommended) | [javafuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/javafuzz-fuzzing-example) | +| Java | [Javafuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/javafuzz) (recommended) | [javafuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/javafuzz-fuzzing-example) | | Java | [JQF](https://github.com/rohanpadhye/JQF) (not preferred) | [jqf-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/java-fuzzing-example) | -| JavaScript | [jsfuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/jsfuzz)| [jsfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/jsfuzz-fuzzing-example) | -| Python | [pythonfuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/pythonfuzz)| [pythonfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/pythonfuzz-fuzzing-example) | +| JavaScript | [`jsfuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/jsfuzz)| [jsfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/jsfuzz-fuzzing-example) | +| Python | [`pythonfuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/pythonfuzz)| [pythonfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/pythonfuzz-fuzzing-example) | +| AFL (any language that works on top of AFL) | [AFL](https://lcamtuf.coredump.cx/afl/)| [afl-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/afl-fuzzing-example) | ## Configuration @@ -44,8 +45,18 @@ provided as part of your GitLab installation. To do so, add the following to your `.gitlab-ci.yml` file: ```yaml +stages: + - fuzz + include: - template: Coverage-Fuzzing.gitlab-ci.yml + +my_fuzz_target: + extends: .fuzz_base + script: + # Build your fuzz target binary in these steps, then run it with gitlab-cov-fuzz> + # See our example repos for how you could do this with any of our supported languages + - ./gitlab-cov-fuzz run --regression=$REGRESSION -- <your fuzz target> ``` The included template makes available the [hidden job](../../../ci/yaml/README.md#hide-jobs) @@ -97,7 +108,7 @@ There are two types of jobs: Here's our current suggestion for configuring your fuzz target's timeout: -- Set `COVFUZZ_BRANCH` to the branch where you want to run long-running (async) fuzzing +- Set `COVFUZZ_BRANCH` to the branch where you want to run long-running (asynchronous) fuzzing jobs. This is `master` by default. - Use regression or short-running fuzzing jobs for other branches or merge requests. @@ -108,13 +119,13 @@ You can configure this by passing `--regression=false/true` to `gitlab-cov-fuzz` shows. Also note that `gitlab-cov-fuzz` is a wrapper, so you can pass those arguments to configure any option available in the underlying fuzzing engine. -### Available variables +### Available CI/CD variables -| Environment variable | Description | -|---------------------------|--------------------------------------------------------------------| -| `COVFUZZ_BRANCH` | The branch for long-running fuzzing jobs. The default is `master`. | -| `COVFUZZ_SEED_CORPUS` | Path to a seed corpus directory. The default is empty. | -| `COVFUZZ_URL_PREFIX` | Path to the `gitlab-cov-fuzz` repository cloned for use with an offline environment. You should only change this when using an offline environment. The default value is `https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz/-/raw`. | +| CI/CD variable | Description | +|-----------------------|--------------------------------------------------------------------| +| `COVFUZZ_BRANCH` | The branch for long-running fuzzing jobs. The default is `master`. | +| `COVFUZZ_SEED_CORPUS` | Path to a seed corpus directory. The default is empty. | +| `COVFUZZ_URL_PREFIX` | Path to the `gitlab-cov-fuzz` repository cloned for use with an offline environment. You should only change this when using an offline environment. The default value is `https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz/-/raw`. | The files in the seed corpus (`COVFUZZ_SEED_CORPUS`), if provided, aren't updated unless you commit new files to your Git repository. There's usually no need to frequently update the seed corpus. As part @@ -178,20 +189,20 @@ To use coverage fuzzing in an offline environment, follow these steps: `NEW_URL_GITLAB_COV_FUZ` is the URL of the private `gitlab-cov-fuzz` clone that you set up in the first step. -### Continuous fuzzing (long-running async fuzzing jobs) +### Continuous fuzzing (long-running asynchronous fuzzing jobs) It's also possible to run the fuzzing jobs longer and without blocking your main pipeline. This configuration uses the GitLab [parent-child pipelines](../../../ci/parent_child_pipelines.md). The full example is available in the [repository](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/tree/continuous_fuzzing#running-go-fuzz-from-ci). This example uses Go, but is applicable for any other supported languages. -The suggested workflow in this scenario is to have long-running, async fuzzing jobs on a +The suggested workflow in this scenario is to have long-running, asynchronous fuzzing jobs on a main/development branch, and short, blocking sync fuzzing jobs on all other branches and MRs. This is a good way to balance the needs of letting a developer's per-commit pipeline complete quickly, and also giving the fuzzer a large amount of time to fully explore and test the app. Long-running fuzzing jobs are usually necessary for the coverage guided fuzzer to find deeper bugs -in your latest code base. THe following is an example of what `.gitlab-ci.yml` looks like in this +in your latest codebase. THe following is an example of what `.gitlab-ci.yml` looks like in this workflow (for the full example, see the [repository](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/tree/continuous_fuzzing)): ```yaml @@ -207,7 +218,7 @@ sync_fuzzing: async_fuzzing: variables: - COVFUZZ_ADDITIONAL_ARGS: '-max_total_time=3600' + COVFUZZ_ADDITIONAL_ARGS: '-max_total_time=3600' trigger: include: .covfuzz-ci.yml rules: @@ -242,9 +253,9 @@ vulnerability: vulnerability can be Detected, Confirmed, Dismissed, or Resolved. - Project: The project in which the vulnerability exists. - Crash type: The type of crash or weakness in the code. This typically maps to a [CWE](https://cwe.mitre.org/). -- Crash state: A normalized version of the stacktrace, containing the last three functions of the +- Crash state: A normalized version of the stack trace, containing the last three functions of the crash (without random addresses). -- Stacktrace snippet: The last few lines of the stacktrace, which shows details about the crash. +- Stack trace snippet: The last few lines of the stack trace, which shows details about the crash. - Identifier: The vulnerability's identifier. This maps to either a [CVE](https://cve.mitre.org/) or [CWE](https://cwe.mitre.org/). - Severity: The vulnerability's severity. This can be Critical, High, Medium, Low, Info, or Unknown. diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 395a8702d1b..3950c856b40 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -92,7 +92,7 @@ variables: To use the latest version of the DAST template, include `DAST.latest.gitlab-ci.yml` instead of `DAST.gitlab-ci.yml`. -See the CI [docs](../../../development/cicd/templates.md#latest-version) +See the CI/CD [documentation](../../../development/cicd/templates.md#latest-version) on template versioning for more information. Please note that the latest version may include breaking changes. Check the @@ -102,7 +102,7 @@ Please note that the latest version may include breaking changes. Check the There are two ways to define the URL to be scanned by DAST: -1. Set the `DAST_WEBSITE` [variable](../../../ci/yaml/README.md#variables). +1. Set the `DAST_WEBSITE` [CI/CD variable](../../../ci/yaml/README.md#variables). 1. Add it in an `environment_url.txt` file at the root of your project. This is useful for testing in dynamic environments. To run DAST against an application @@ -177,7 +177,7 @@ authorization credentials. By default, the following headers are masked: - `Set-Cookie` (values only). - `Cookie` (values only). -Using the [`DAST_MASK_HTTP_HEADERS` variable](#available-variables), you can list the +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). @@ -192,7 +192,7 @@ of your application is likely not accessible without authentication. It is also 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 variables to pass the credentials that DAST uses. +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#create-a-custom-variable-in-the-ui). Note that the key of the username variable must be `DAST_USERNAME` and the key of the password variable must be `DAST_PASSWORD`. @@ -252,7 +252,7 @@ and potentially damage them. You could even take down your production environmen For that reason, you should use domain validation. Domain validation is not required by default. It can be required by setting the -[environment variable](#available-variables) `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` to `"true"`. +[CI/CD variable](#available-variables) `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` to `"true"`. ```yaml include: @@ -406,14 +406,14 @@ dast: #### Full API scan API scans support full scanning, which can be enabled by using the `DAST_FULL_SCAN_ENABLED` -environment variable. Domain validation is not supported for full API scans. +CI/CD variable. Domain validation is not supported for full API scans. #### Host override Specifications often define a host, which contains a domain name and a port. The host referenced may be different than the host of the API's review instance. This can cause incorrect URLs to be imported, or a scan on an incorrect host. -Use the `DAST_API_HOST_OVERRIDE` environment variable to override these values. +Use the `DAST_API_HOST_OVERRIDE` CI/CD variable to override these values. For example, with a OpenAPI V3 specification containing: @@ -441,7 +441,7 @@ limitation in the ZAP OpenAPI extension. #### Authentication using headers Tokens in request headers are often used as a way to authenticate API requests. -You can achieve this by using the `DAST_REQUEST_HEADERS` environment variable. +You can achieve this by using the `DAST_REQUEST_HEADERS` CI/CD variable. Headers are applied to every request DAST makes. ```yaml @@ -463,10 +463,10 @@ A URL scan allows you to specify which parts of a website are scanned by DAST. URLs to scan can be specified by either of the following methods: -- Use `DAST_PATHS_FILE` environment variable to specify the name of a file containing the paths. -- Use `DAST_PATHS` environment variable to list the paths. +- Use `DAST_PATHS_FILE` CI/CD variable to specify the name of a file containing the paths. +- Use `DAST_PATHS` variable to list the paths. -##### Use DAST_PATHS_FILE environment variable +##### Use `DAST_PATHS_FILE` CI/CD variable > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. @@ -478,7 +478,7 @@ page1.html category/shoes/page1.html ``` -To scan the URLs in that file, set the environment variable `DAST_PATHS_FILE` to the path of that file. +To scan the URLs in that file, set the CI/CD variable `DAST_PATHS_FILE` to the path of that file. ```yaml include: @@ -501,12 +501,12 @@ dast: DAST_PATHS_FILE: url_file.txt ``` -##### Use DAST_PATHS environment variable +##### Use `DAST_PATHS` CI/CD variable > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. -To specify the paths to scan in an environment variable, add a comma-separated list of the paths to the `DAST_PATHS` -environment variable. Note that you can only scan paths of a single host. +To specify the paths to scan in a CI/CD variable, add a comma-separated list of the paths to the `DAST_PATHS` +variable. Note that you can only scan paths of a single host. ```yaml include: @@ -521,12 +521,12 @@ When using `DAST_PATHS` and `DAST_PATHS_FILE`, note the following: - `DAST_WEBSITE` must be defined when using either `DAST_PATHS_FILE` or `DAST_PATHS`. The paths listed in either use `DAST_WEBSITE` to build the URLs to scan - Spidering is disabled when `DAST_PATHS` or `DAST_PATHS_FILE` are defined - `DAST_PATHS_FILE` and `DAST_PATHS` can not be used together -- The `DAST_PATHS` environment variable has a limit of about 130kb. If you have a list or paths +- The `DAST_PATHS` variable has a limit of about 130kb. If you have a list or paths greater than this, use `DAST_PATHS_FILE`. #### Full Scan -To perform a [full scan](#full-scan) on the listed paths, use the `DAST_FULL_SCAN_ENABLED` environment variable. +To perform a [full scan](#full-scan) on the listed paths, use the `DAST_FULL_SCAN_ENABLED` CI/CD variable. ### Customizing the DAST settings @@ -534,7 +534,7 @@ WARNING: Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. -The DAST settings can be changed through environment variables by using the +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). @@ -554,46 +554,47 @@ configuration, the last mention of the variable takes precedence. ### Available variables -DAST can be [configured](#customizing-the-dast-settings) using environment variables. +DAST can be [configured](#customizing-the-dast-settings) using CI/CD variables. -| Environment variable | Type | Description | -|-----------------------------| -----------|--------------------------------------------------------------------------------| -| `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | -| `DAST_WEBSITE` | URL | The URL of the website to scan. `DAST_API_SPECIFICATION` must be specified if this is omitted. | -| `DAST_API_SPECIFICATION` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | +| CI/CD variable | Type | Description | +|------------------------------| --------|-------------| +| `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | +| `DAST_WEBSITE` | URL | The URL of the website to scan. `DAST_API_SPECIFICATION` must be specified if this is omitted. | +| `DAST_API_SPECIFICATION` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | | `DAST_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_VALIDATION_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. In [GitLab 13.7 and earlier](https://gitlab.com/gitlab-org/security-products/dast/-/merge_requests/367), was `DAST_AUTH_EXCLUDE_URLS` (which we plan to support until GitLab 14.0). | -| `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_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_VALIDATION_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 | 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_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_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_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 and be in `/zap/wrk`. [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_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 and be in `/zap/wrk`. [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. | ### DAST command-line options -Not all DAST configuration is available via environment variables. To find out all +Not all DAST configuration is available via CI/CD variables. To find out all possible options, run the following configuration. Available command-line options are printed to the job log: @@ -648,11 +649,11 @@ A DAST job has two executing processes: - The ZAP server. - A series of scripts that start, control and stop the ZAP server. -Debug mode of the scripts can be enabled by using the `DAST_DEBUG` environment variable. This can help when troubleshooting the job, +Debug mode of the scripts can be enabled by using the `DAST_DEBUG` CI/CD variable. This can help when troubleshooting the job, and outputs statements indicating what percentage of the scan is complete. For details on using variables, see [Overriding the DAST template](#customizing-the-dast-settings). -Debug mode of the ZAP server can be enabled using the `DAST_ZAP_LOG_CONFIGURATION` environment variable. +Debug mode of the ZAP server can be enabled using the `DAST_ZAP_LOG_CONFIGURATION` variable. The following table outlines examples of values that can be set and the effect that they have on the output that is logged. Multiple values can be specified, separated by semicolons. @@ -705,7 +706,7 @@ For details on saving and transporting Docker images as a file, see Docker's doc [`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/). -### Set DAST CI job variables to use local DAST analyzers +### Set DAST CI/CD job variables to use local DAST analyzers Add the following configuration to your `.gitlab-ci.yml` file. You must replace `image` to refer to the DAST Docker image hosted on your local Docker container registry: @@ -720,21 +721,24 @@ dast: The DAST job should now use local copies of the DAST analyzers to scan your code and generate security reports without requiring internet access. -Alternatively, you can use the variable `SECURE_ANALYZERS_PREFIX` to override the base registry address of the `dast` image. +Alternatively, you can use the CI/CD variable `SECURE_ANALYZERS_PREFIX` to override the base registry address of the `dast` image. ## On-demand scans > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.2. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.3. +> - The saved scans feature was [added](https://gitlab.com/groups/gitlab-org/-/epics/5100) in +> GitLab 13.9. An on-demand DAST scan runs outside the DevOps life cycle. Changes in your repository don't trigger the scan. You must start it manually. An on-demand DAST scan: -- Uses settings in the site profile and scanner profile you select when you run the scan, - instead of those in the `.gitlab-ci.yml` file. +- Can run a specific combination of a [site profile](#site-profile) and a + [scanner profile](#scanner-profile). - Is associated with your project's default branch. +- Is saved on creation so it can be run later. ### On-demand scan modes @@ -742,8 +746,8 @@ An on-demand scan can be run in active or passive mode: - _Passive mode_ is the default and runs a ZAP Baseline Scan. - _Active mode_ runs a ZAP Full Scan which is potentially harmful to the site being scanned. To - minimize the risk of accidental damage, running an active scan requires a [validated site - profile](#site-profile-validation). + minimize the risk of accidental damage, running an active scan requires a [validated site + profile](#site-profile-validation). ### Run an on-demand DAST scan @@ -752,19 +756,81 @@ You must have permission to run an on-demand DAST scan against a protected branc The default branch is automatically protected. For more information, see [Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). -To run an on-demand DAST scan, you need: +Prerequisites: - A [scanner profile](#create-a-scanner-profile). - A [site profile](#create-a-site-profile). - If you are running an active scan the site profile must be [validated](#validate-a-site-profile). -1. From your project's home page, go to **Security & Compliance > On-demand Scans** in the left sidebar. +To run an on-demand scan, either: + +- [Create and run an on-demand scan](#create-and-run-an-on-demand-scan). +- [Run a previously saved on-demand scan](#run-a-saved-on-demand-scan). + +#### Create and run an on-demand scan + +1. From your project's home page, go to **Security & Compliance > On-demand Scans** in the left + sidebar. +1. Complete the **Scan name** and **Description** fields. 1. In **Scanner profile**, select a scanner profile from the dropdown. 1. In **Site profile**, select a site profile from the dropdown. -1. Click **Run scan**. +1. To run the on-demand scan now, select **Save and run scan**. Otherwise select **Save scan** to + [run](#run-a-saved-on-demand-scan) it later. The on-demand DAST scan runs and the project's dashboard shows the results. +### List saved on-demand scans + +To list saved on-demand scans: + +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Select the **Saved Scans** tab. + +### View details of an on-demand scan + +To view details of an on-demand scan: + +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Select **Manage DAST scans**. +1. Select **Manage** in the **DAST Profiles** row. +1. Select the **Saved Scans** tab. +1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. + +### Run a saved on-demand scan + +To run a saved on-demand scan: + +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Select **Manage DAST scans**. +1. Select **Manage** in the **DAST Profiles** row. +1. Select the **Saved Scans** tab. +1. In the scan's row select **Run scan**. + +The on-demand DAST scan runs and the project's dashboard shows the results. + +### Edit an on-demand scan + +To edit an on-demand scan: + +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Select **Manage DAST scans**. +1. Select **Manage** in the **DAST Profiles** row. +1. Select the **Saved Scans** tab. +1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. +1. Edit the form. +1. Select **Save scan**. + +### Delete an on-demand scan + +To delete an on-demand scan: + +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. Select **Manage DAST scans**. +1. Select **Manage** in the **DAST Profiles** row. +1. Select the **Saved Scans** tab. +1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Delete**. +1. Select **Delete** to confirm the deletion. + ## Site profile A site profile describes the attributes of a web site to scan on demand with DAST. A site profile is @@ -775,7 +841,7 @@ A site profile contains the following: - **Profile name**: A name you assign to the site to be scanned. - **Target URL**: The URL that DAST runs against. -## Site profile validation +### Site profile validation > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233020) in GitLab 13.8. @@ -798,37 +864,51 @@ To create a site profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. 1. Select **Manage** in the **DAST Profiles** row. -1. Select **New Profile > Site Profile**. -1. Type in a unique **Profile name** and **Target URL** then select **Save profile**. +1. Select **New > Site Profile**. +1. Complete the fields then select **Save profile**. + +The site profile is created. ### Edit a site profile To edit an existing site profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select **Manage** in the **DAST Profiles** row. -1. Select **Edit** in the row of the profile to edit. -1. Edit the **Profile name** and **Target URL**, then select **Save profile**. +1. In the **DAST Profiles** row select **Manage**. +1. Select the **Site Profiles** tab. +1. In the profile's row select the **More actions** (**{ellipsis_v}**) menu, then select **Edit**. +1. Edit the fields then select **Save profile**. + +The site profile is updated with the edited details. ### Delete a site profile To delete an existing site profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select **Manage** in the **DAST Profiles** row. -1. Select **{remove}** (Delete profile) in the row of the profile to delete. +1. In the **DAST Profiles** row select **Manage**. +1. Select the **Site Profiles** tab. +1. In the profile's row select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**. +1. Select **Delete** to confirm the deletion. + +The site profile is deleted. ### Validate a site profile +Prerequisites: + +- A site profile. + To validate a site profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select **Manage** in the **DAST Profiles** row. -1. Select **Validate target site** beside the profile to validate. +1. In the **DAST Profiles** row select **Manage**. +1. Select the **Site Profiles** tab. +1. In the profile's row select **Validate** or **Retry validation**. 1. Select the validation method. 1. For **Text file validation**: 1. Download the validation file listed in **Step 2**. - 1. Upload the validation file to the host. You can upload the file to the location in + 1. Upload the validation file to the host. Upload the file to the location in **Step 3** or any location you prefer. 1. Select **Validate**. 1. For **Header validation**: @@ -839,11 +919,23 @@ To validate a site profile: The site is validated and an active scan can run against it. -If a validated site profile's target URL is edited, the site is no longer validated. +If a validated site profile's target URL is edited, the site's validation status is revoked. + +### Revoke a site profile's validation status + +Note that all site profiles with the same URL have their validation status revoked. + +To revoke a site profile's validation status: + +1. From your project's home page, go to **Security & Compliance > Configuration**. +1. In the **DAST Profiles** row select **Manage**. +1. Select **Revoke validation** beside the validated profile. + +The site profile's validation status is revoked. #### Validated site profile headers -The following are code samples of how you could provide the required site profile header in your +The following are code samples of how you can provide the required site profile header in your application. ##### Ruby on Rails example for on-demand scan @@ -888,27 +980,26 @@ app.get('/dast-website-target', function(req, res) { ## Scanner profile > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222767) in GitLab 13.4. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/225804) in GitLab 13.5: scan mode, AJAX spider, debug messages. A scanner profile defines the scanner settings used to run an on-demand scan: - **Profile name:** A name you give the scanner profile. For example, "Spider_15". +- **Scan mode:** A passive scan monitors all HTTP messages (requests and responses) sent to the target. An active scan attacks the target to find potential vulnerabilities. - **Spider timeout:** The maximum number of minutes allowed for the spider to traverse the site. - **Target timeout:** The maximum number of seconds DAST waits for the site to be available before starting the scan. -- **Scan mode:** A passive scan monitors all HTTP messages (requests and responses) sent to the target. An active scan attacks the target to find potential vulnerabilities. - **AJAX spider:** Run the AJAX spider, in addition to the traditional spider, to crawl the target site. - **Debug messages:** Include debug messages in the DAST console output. -Scan mode, AJAX spider, Debug messages are [added in GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/225804) - ### Create a scanner profile To create a scanner profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Click **Manage** in the **DAST Profiles** row. -1. Click **New Profile > Scanner Profile**. -1. Enter a unique **Profile name**, the desired **Spider timeout**, and the **Target timeout**. +1. In the **DAST Profiles** row select **Manage**. +1. Select **New > Scanner Profile**. +1. Complete the form. For details of each field, see [Scanner profile](#scanner-profile). 1. Click **Save profile**. ### Edit a scanner profile @@ -917,7 +1008,12 @@ To edit a scanner profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. 1. Click **Manage** in the **DAST Profiles** row. -1. Click **Edit** in the scanner profile's row. +1. Select the **Scanner Profiles** tab. +1. In the scanner's row select the **More actions** (**{ellipsis_v}**) menu, then select **Edit**. +1. Edit the form. +1. Select **Save profile**. + +The scanner profile is updated with the edited details. ### Delete a scanner profile @@ -925,7 +1021,11 @@ To delete a scanner profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. 1. Click **Manage** in the **DAST Profiles** row. -1. Click **{remove}** (Delete profile) in the scanner profile's row. +1. Select the **Scanner Profiles** tab. +1. In the scanner's row select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**. +1. Select **Delete**. + +The scanner profile is deleted. ## Reports @@ -985,7 +1085,7 @@ vulnerabilities in your groups, projects and pipelines. Read more about the ZAP first creates rules in the `alpha` class. After a testing period with the community, they are promoted to `beta`. DAST uses `beta` definitions by default. To request `alpha` definitions, use the -`DAST_INCLUDE_ALPHA_VULNERABILITIES` environment variable as shown in the +`DAST_INCLUDE_ALPHA_VULNERABILITIES` CI/CD variable as shown in the following configuration: ```yaml @@ -1033,7 +1133,7 @@ This results in the following error: ``` Fortunately, it's straightforward to increase the amount of memory available -for DAST by using the `DAST_ZAP_CLI_OPTIONS` environment variable: +for DAST by using the `DAST_ZAP_CLI_OPTIONS` CI/CD variable: ```yaml include: diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index 1079a75e32f..53d91bfcd78 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -34,8 +34,8 @@ maintained by GitLab, but users can also integrate their own **custom images**. ## Official default analyzers -Any custom change to the official analyzers can be achieved by using an -[environment variable in your `.gitlab-ci.yml`](index.md#customizing-the-dependency-scanning-settings). +Any custom change to the official analyzers can be achieved by using a +[CI/CD variable in your `.gitlab-ci.yml`](index.md#customizing-the-dependency-scanning-settings). ### Using a custom Docker mirror diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index cecf818edfc..11d27140e42 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -65,20 +65,19 @@ The following languages and dependency managers are supported: | [Golang](https://golang.org/) | Go | `go.sum` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | Java | `build.gradle`, `build.gradle.kts`, `pom.xml` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | [npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/) 1.x | JavaScript | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| [npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/) 1.x | JavaScript | `package.json` | [Retire.js](https://retirejs.github.io/retire.js/) | +| [npm](https://www.npmjs.com/) (7 and earlier), [yarn](https://classic.yarnpkg.com/en/) 1.x | JavaScript | `package.json` | [Retire.js](https://retirejs.github.io/retire.js/) | | [NuGet](https://www.nuget.org/) 4.9+ | .NET, C# | [`packages.lock.json`](https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| [setuptools](https://setuptools.readthedocs.io/en/latest/), [pip](https://pip.pypa.io/en/stable/), [Pipenv](https://pipenv.pypa.io/en/latest/) (*1*) | Python | `setup.py`, `requirements.txt`, `requirements.pip`, `requires.txt`, `Pipfile`, `Pipfile.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| [sbt](https://www.scala-sbt.org/) 1.2 and below ([Ivy](http://ant.apache.org/ivy/)) | Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| [`setuptools`](https://setuptools.readthedocs.io/en/latest/), [pip](https://pip.pypa.io/en/stable/), [Pipenv](https://pipenv.pypa.io/en/latest/) (*1*) | Python | `setup.py`, `requirements.txt`, `requirements.pip`, `requires.txt`, `Pipfile`, `Pipfile.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| [sbt](https://www.scala-sbt.org/) (*2*) | Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | 1. [Pipenv](https://pipenv.pypa.io/en/latest/) projects are scanned when a `Pipfile` is present. - Gemnasium scans the exact package versions listed in `Pipfile.lock` when this file is also present. +1. Support for [sbt](https://www.scala-sbt.org/) 1.3 and above was added in GitLab 13.9. Plans are underway for supporting the following languages, dependency managers, and dependency files. For details, see the issue link for each. | Package Managers | Languages | Supported files | Scan tools | Issue | | ------------------- | --------- | --------------- | ---------- | ----- | | [Poetry](https://python-poetry.org/) | Python | `poetry.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#7006](https://gitlab.com/gitlab-org/gitlab/-/issues/7006) | -| [sbt](https://www.scala-sbt.org/) 1.3+ ([Coursier](https://get-coursier.io/))| Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#271345](https://gitlab.com/gitlab-org/gitlab/-/issues/271345) | ## Contribute your scanner @@ -109,7 +108,7 @@ always take the latest dependency scanning artifact available. ### Customizing the dependency scanning settings -The dependency scanning settings can be changed through [environment variables](#available-variables) by using the +The dependency scanning settings can be changed through [CI/CD variables](#available-variables) by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. For example: @@ -163,47 +162,63 @@ using environment variables. The following variables allow configuration of global dependency scanning settings. -| Environment variable | Description | -| --------------------------------------- |------------ | -| `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). | -| `DS_DEFAULT_ANALYZERS` | Override the names of the official default images. Read more about [customizing analyzers](analyzers.md). | -| `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. The bundle of certificates provided here is also used by other tools during the scanning process, such as `git`, `yarn`, or `npm`. | -| `DS_EXCLUDED_PATHS` | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"` | -| `SECURE_LOG_LEVEL` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. Default: `info` | +| CI/CD variables | Description | +| ----------------------------|------------ | +| `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. The bundle of certificates provided here is also used by other tools during the scanning process, such as `git`, `yarn`, or `npm`. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. | +| `DS_DEFAULT_ANALYZERS` | Override the names of the official default images. Read more about [customizing analyzers](analyzers.md). | +| `DS_EXCLUDED_PATHS` | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"`. | +| `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). | +| `SECURE_LOG_LEVEL` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. Default: `info`. | #### Configuring specific analyzers used by dependency scanning The following variables are used for configuring specific analyzers (used for a specific language/framework). -| Environment variable | Analyzer | Default | Description | -| --------------------------------------- | ------------------ | ---------------------------- |------------ | -| `GEMNASIUM_DB_LOCAL_PATH` | `gemnasium` | `/gemnasium-db` | Path to local Gemnasium database. | -| `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. | -| `PIP_INDEX_URL` | `gemnasium-python` | `https://pypi.org/simple` | Base URL of Python Package Index. | -| `PIP_EXTRA_INDEX_URL` | `gemnasium-python` | | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma-separated. | -| `PIP_REQUIREMENTS_FILE` | `gemnasium-python` | | Pip requirements file to be scanned. | -| `DS_PIP_VERSION` | `gemnasium-python` | | Force the install of a specific pip version (example: `"19.3"`), otherwise the pip installed in the Docker image is used. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12811) in GitLab 12.7) | -| `DS_PIP_DEPENDENCY_PATH` | `gemnasium-python` | | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12412) in GitLab 12.2) | -| `DS_PYTHON_VERSION` | `retire.js` | | Version of Python. If set to 2, dependencies are installed using Python 2.7 instead of Python 3.6. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12296) in GitLab 12.1, [removed](https://www.python.org/doc/sunset-python-2/) in GitLab 13.7)| -| `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`. Maven and Gradle use the Java version specified by this value. | -| `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-repos). | -| `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`. | -| `BUNDLER_AUDIT_UPDATE_DISABLED` | `bundler-audit` | `"false"` | Disable automatic updates for the `bundler-audit` analyzer. Useful if you're running dependency scanning in an offline, air-gapped environment.| -| `BUNDLER_AUDIT_ADVISORY_DB_URL` | `bundler-audit` | `https://github.com/rubysec/ruby-advisory-db` | URL of the advisory database used by bundler-audit. | -| `BUNDLER_AUDIT_ADVISORY_DB_REF_NAME` | `bundler-audit` | `master` | Git ref for the advisory database specified by `BUNDLER_AUDIT_ADVISORY_DB_URL`. | -| `RETIREJS_JS_ADVISORY_DB` | `retire.js` | `https://raw.githubusercontent.com/RetireJS/retire.js/master/repository/jsrepository.json` | Path or URL to `retire.js` JS vulnerability data file. Note that if the URL hosting the data file uses a custom SSL certificate, for example in an offline installation, you can pass the certificate in the `ADDITIONAL_CA_CERT_BUNDLE` environment variable. | -| `RETIREJS_NODE_ADVISORY_DB` | `retire.js` | `https://raw.githubusercontent.com/RetireJS/retire.js/master/repository/npmrepository.json` | Path or URL to `retire.js` node vulnerability data file. Note that if the URL hosting the data file uses a custom SSL certificate, for example in an offline installation, you can pass the certificate in the `ADDITIONAL_CA_CERT_BUNDLE` environment variable. | -| `RETIREJS_ADVISORY_DB_INSECURE` | `retire.js` | `false` | Enable fetching remote JS and Node vulnerability data files (defined by the `RETIREJS_JS_ADVISORY_DB` and `RETIREJS_NODE_ADVISORY_DB` variables) from hosts using an insecure or self-signed SSL (TLS) certificate. | - -### Using private Maven repos +| CI/CD variable | Analyzer | Default | Description | +| ------------------------------------ | ------------------ | ---------------------------- |------------ | +| `BUNDLER_AUDIT_UPDATE_DISABLED` | `bundler-audit` | `"false"` | Disable automatic updates for the `bundler-audit` analyzer. Use if you're running dependency scanning in an offline, air-gapped environment.| +| `BUNDLER_AUDIT_ADVISORY_DB_URL` | `bundler-audit` | `https://github.com/rubysec/ruby-advisory-db` | URL of the advisory database used by bundler-audit. | +| `BUNDLER_AUDIT_ADVISORY_DB_REF_NAME` | `bundler-audit` | `master` | Git ref for the advisory database specified by `BUNDLER_AUDIT_ADVISORY_DB_URL`. | +| `GEMNASIUM_DB_LOCAL_PATH` | `gemnasium` | `/gemnasium-db` | Path to local Gemnasium database. | +| `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`. Maven and Gradle use the Java version specified by this value. | +| `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`. | +| `PIP_INDEX_URL` | `gemnasium-python` | `https://pypi.org/simple` | Base URL of Python Package Index. | +| `PIP_EXTRA_INDEX_URL` | `gemnasium-python` | | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma-separated. | +| `PIP_REQUIREMENTS_FILE` | `gemnasium-python` | | Pip requirements file to be scanned. | +| `DS_PIP_VERSION` | `gemnasium-python` | | Force the install of a specific pip version (example: `"19.3"`), otherwise the pip installed in the Docker image is used. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12811) in GitLab 12.7) | +| `DS_PIP_DEPENDENCY_PATH` | `gemnasium-python` | | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12412) in GitLab 12.2) | +| `DS_PYTHON_VERSION` | `retire.js` | | Version of Python. If set to 2, dependencies are installed using Python 2.7 instead of Python 3.6. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12296) in GitLab 12.1, [removed](https://www.python.org/doc/sunset-python-2/) in GitLab 13.7). | +| `RETIREJS_JS_ADVISORY_DB` | `retire.js` | `https://raw.githubusercontent.com/RetireJS/retire.js/master/repository/jsrepository.json` | Path or URL to `retire.js` JS vulnerability data file. Note that if the URL hosting the data file uses a custom SSL certificate, for example in an offline installation, you can pass the certificate in the `ADDITIONAL_CA_CERT_BUNDLE` variable. | +| `RETIREJS_NODE_ADVISORY_DB` | `retire.js` | `https://raw.githubusercontent.com/RetireJS/retire.js/master/repository/npmrepository.json` | Path or URL to `retire.js` node vulnerability data file. Note that if the URL hosting the data file uses a custom SSL certificate, for example in an offline installation, you can pass the certificate in the `ADDITIONAL_CA_CERT_BUNDLE` variable. | +| `RETIREJS_ADVISORY_DB_INSECURE` | `retire.js` | `false` | Enable fetching remote JS and Node vulnerability data files (defined by the `RETIREJS_JS_ADVISORY_DB` and `RETIREJS_NODE_ADVISORY_DB` variables) from hosts using an insecure or self-signed SSL (TLS) certificate. | + +### 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. 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 +variables: + ADDITIONAL_CA_CERT_BUNDLE: | + -----BEGIN CERTIFICATE----- + MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB + ... + jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs= + -----END CERTIFICATE----- +``` + +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. + +### Using private Maven repositories If your private Maven repository requires login credentials, -you can use the `MAVEN_CLI_OPTS` environment variable. +you can use the `MAVEN_CLI_OPTS` CI/CD variable. -Read more on [how to use private Maven repositories](../index.md#using-private-maven-repos). +Read more on [how to use private Maven repositories](../index.md#using-private-maven-repositories). ## Interacting with the vulnerabilities @@ -370,12 +385,12 @@ Here are the requirements for using dependency scanning in an offline environmen - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). - Docker Container Registry with locally available copies of dependency scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. - If you have a limited access environment you need to allow access, such as using a proxy, to the advisory database: `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git`. - If you are unable to permit access to `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` you must host an offline copy of this `git` repository and set the `GEMNASIUM_DB_REMOTE_URL` variable to the URL of this repository. For more information on configuration variables, see [Dependency Scanning](#configuring-dependency-scanning). + If you are unable to permit access to `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` you must host an offline copy of this `git` repository and set the `GEMNASIUM_DB_REMOTE_URL` CI/CD variable to the URL of this repository. For more information on configuration variables, see [Dependency Scanning](#configuring-dependency-scanning). This advisory database is constantly being updated, so you must periodically sync your local copy with GitLab. - _Only if scanning Ruby projects_: Host an offline Git copy of the [advisory database](https://github.com/rubysec/ruby-advisory-db). -- _Only if scanning npm/yarn projects_: Host an offline copy of the [retire.js](https://github.com/RetireJS/retire.js/) [node](https://github.com/RetireJS/retire.js/blob/master/repository/npmrepository.json) and [js](https://github.com/RetireJS/retire.js/blob/master/repository/jsrepository.json) advisory databases. +- _Only if scanning npm/yarn projects_: Host an offline copy of the [`retire.js`](https://github.com/RetireJS/retire.js/) [node](https://github.com/RetireJS/retire.js/blob/master/repository/npmrepository.json) and [`js`](https://github.com/RetireJS/retire.js/blob/master/repository/jsrepository.json) advisory databases. 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 @@ -420,7 +435,7 @@ Support for custom certificate authorities was introduced in the following versi | `retire.js` | [v2.4.0](https://gitlab.com/gitlab-org/security-products/analyzers/retire.js/-/releases/v2.4.0) | | `bundler-audit` | [v2.4.0](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit/-/releases/v2.4.0) | -### Set dependency scanning CI job variables to use local dependency scanning analyzers +### Set dependency scanning CI/CD job variables to use local dependency scanning analyzers Add the following configuration to your `.gitlab-ci.yml` file. You must change the value of `SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry. You must also change the @@ -460,7 +475,7 @@ BUNDLER_AUDIT_ADVISORY_DB_REF_NAME: "master" BUNDLER_AUDIT_ADVISORY_DB_URL: "gitlab.example.com/ruby-advisory-db.git" ``` -#### Python (setuptools) +#### Python (setup tools) When using self-signed certificates for your private PyPi repository, no extra job configuration (aside from the template `.gitlab-ci.yml` above) is needed. However, you must update your `setup.py` to @@ -526,5 +541,9 @@ scanning job might be triggered even if the scanner doesn't support your project ### Issues building projects with npm or yarn packages relying on Python 2 -Python 2 was removed (see: [Python 2 sunsetting](https://www.python.org/doc/sunset-python-2/)) from the `retire.js` analyzer in GitLab 13.7 (analyzer version 2.10.1). Projects using packages +[Python 2 was removed](https://www.python.org/doc/sunset-python-2/) from the `retire.js` analyzer in GitLab 13.7 (analyzer version 2.10.1). Projects using packages with a dependency on this version of Python should use `retire.js` version 2.10.0 or lower (for example, `registry.gitlab.com/gitlab-org/security-products/analyzers/retire.js:2.10.0`). + +### Error: `dependency_scanning is used for configuration only, and its script should not be executed` + +For information on this, see the [GitLab Secure troubleshooting section](../index.md#error-job-is-used-for-configuration-only-and-its-script-should-not-be-executed). diff --git a/doc/user/application_security/img/create_issue_from_vulnerability_v13_3.png b/doc/user/application_security/img/create_issue_from_vulnerability_v13_3.png Binary files differdeleted file mode 100644 index b792fbc9af1..00000000000 --- a/doc/user/application_security/img/create_issue_from_vulnerability_v13_3.png +++ /dev/null diff --git a/doc/user/application_security/img/issue.png b/doc/user/application_security/img/issue.png Binary files differdeleted file mode 100644 index 6467201df3f..00000000000 --- a/doc/user/application_security/img/issue.png +++ /dev/null diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 417ce70665c..4a23cd874be 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -57,7 +57,7 @@ see [configure SAST in the UI](sast/index.md#configure-sast-in-the-ui). ### Override the default registry base address By default, GitLab security scanners use `registry.gitlab.com/gitlab-org/security-products/analyzers` as the -base address for Docker images. You can override this globally by setting the variable +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. ## Security scanning tools @@ -110,7 +110,7 @@ The scanning tools and vulnerabilities database are updated regularly. | Secure scanning tool | Vulnerabilities database updates | |:-------------------------------------------------------------|-------------------------------------------| | [Container Scanning](container_scanning/index.md) | Uses `clair`. The latest `clair-db` version is used for each job by running the [`latest` Docker image tag](https://gitlab.com/gitlab-org/gitlab/blob/438a0a56dc0882f22bdd82e700554525f552d91b/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L37). The `clair-db` database [is updated daily according to the author](https://github.com/arminc/clair-local-scan#clair-server-or-local). | -| [Dependency Scanning](dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for NPM packages), and `gemnasium` (the GitLab tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated at least once a week. See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | +| [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. | @@ -123,19 +123,12 @@ latest versions of the scanning tools without having to do anything. There are s with this approach, however, and there is a [plan to resolve them](https://gitlab.com/gitlab-org/gitlab/-/issues/9725). -## Viewing security scan information in merge requests **(CORE)** +## Viewing security scan information in merge requests **(FREE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4393) in GitLab Core 13.5. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4393) in GitLab Free 13.5. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/273205) in 13.6. > - Report download dropdown [added](https://gitlab.com/gitlab-org/gitlab/-/issues/273418) in 13.7. -> - It's [deployed behind a feature flag](../feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It can be enabled or disabled for a single project. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-the-basic-security-widget). **(CORE ONLY)** - -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/249550) in GitLab 13.9. Merge requests which have run security scans let you know that the generated reports are available to download. To download a report, click on the @@ -148,12 +141,12 @@ reports are available to download. To download a report, click on the > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.8. Each security vulnerability in the merge request report or the -[Security Dashboard](security_dashboard/index.md) is actionable. Click an entry to view detailed +[Vulnerability Report](vulnerability_report/index.md) is actionable. Click an entry to view detailed information with several options: - [Dismiss vulnerability](#dismissing-a-vulnerability): Dismissing a vulnerability styles it in strikethrough. -- [Create issue](#creating-an-issue-for-a-vulnerability): Create a new issue with the title and +- [Create issue](vulnerabilities/index.md#create-a-gitlab-issue-for-a-vulnerability): Create a new issue with the title and description pre-populated with information from the vulnerability report. By default, such issues are [confidential](../project/issues/confidential_issues.md). - [Automatic Remediation](#automatic-remediation-for-vulnerabilities): For some vulnerabilities, @@ -261,40 +254,29 @@ vulnerability as you learn more over time. #### Dismissing multiple vulnerabilities -> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35816) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. You can dismiss multiple vulnerabilities at once, providing an optional reason. Selecting the checkboxes on the side of each vulnerability in the list selects that individual vulnerability. Alternatively, you can select all the vulnerabilities in the list by selecting the checkbox in the table header. Deselecting the checkbox in the header deselects all the vulnerabilities in the list. -Once you have selected some vulnerabilities, a menu appears at the top of the table that allows you to select a dismissal reason. +After you have selected some vulnerabilities, a menu appears at the top of the table that allows you to select a dismissal reason. Pressing the "Dismiss Selected" button dismisses all the selected vulnerabilities at once, with the reason you chose.  -### Creating an issue for a vulnerability - -You can create an issue for a vulnerability by visiting the vulnerability's page and clicking -**Create issue**, which you can find in the **Related issues** section. - - - -This creates a [confidential issue](../project/issues/confidential_issues.md) in the project the -vulnerability came from, and pre-populates it with some useful information taken from the vulnerability -report. Once the issue is created, you are redirected to it so you can edit, assign, or comment on -it. +### Create an issue for a vulnerability -Upon returning to the group security dashboard, the vulnerability now has an associated issue next -to the name. - - +You can create a GitLab issue, or a Jira issue (if it's enabled) for a vulnerability. For more +details, see [Vulnerability Pages](vulnerabilities/index.md). ### Automatic remediation for vulnerabilities > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5656) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.7. -Some vulnerabilities can be fixed by applying the solution that GitLab -automatically generates. Although the feature name is Automatic Remediation, this feature is also commonly called Auto-Remediation, Auto Remediation, or Suggested Solutions. The following scanners are supported: +Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. +Although the feature name is Automatic Remediation, this feature is also commonly called +Auto-Remediation, Auto Remediation, or Suggested Solutions. The following scanners are supported: - [Dependency Scanning](dependency_scanning/index.md): Automatic Patch creation is only available for Node.js projects managed with @@ -395,11 +377,11 @@ must be created. A [security scanner job](#security-scanning-tools) must be enab job must be enabled for `License-Check`. When the proper jobs aren't configured, the following appears: - + 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. - + 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) @@ -446,10 +428,10 @@ environment. Read how to [operate the Secure scanners in an offline environment](offline_deployments/index.md). -## Using private Maven repos +## Using private Maven repositories If you have a private Apache Maven repository that requires login credentials, -you can use the `MAVEN_CLI_OPTS` environment variable +you can use the `MAVEN_CLI_OPTS` CI/CD variable to pass a username and password. You can set it under your project's settings so that your credentials aren't exposed in `.gitlab-ci.yml`. @@ -457,8 +439,8 @@ If the username is `myuser` and the password is `verysecret` then you would [set the following variable](../../ci/variables/README.md#create-a-custom-variable-in-the-ui) under your project's settings: -| Type | Key | Value | -| ---- | --- | ----- | +| Type | Key | Value | +| -------- | ---------------- | ----- | | Variable | `MAVEN_CLI_OPTS` | `--settings mysettings.xml -Drepository.password=verysecret -Drepository.user=myuser` | ```xml @@ -522,13 +504,28 @@ This error appears when the included job's stage (named `test`) isn't declared i To fix this issue, you can either: - Add a `test` stage in your `.gitlab-ci.yml`. -- Change the default stage of the included security jobs. For example, with SpotBugs (SAST): +- Override the default stage of each security job. For example, to use a pre-defined stage name `unit-tests`: ```yaml include: - template: Security/SAST.gitlab-ci.yml + - template: Security/Dependency-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml + - template: Security/Secret-Detection.gitlab-ci.yml + + stages: + - unit-tests + + dependency_scanning: + stage: unit-tests - spotbugs-sast: + license_scanning: + stage: unit-tests + + sast: + stage: unit-tests + + .secret-analyzer: stage: unit-tests ``` @@ -541,7 +538,7 @@ This is often followed by the [error `No files to upload`](../../ci/pipelines/jo and preceded by other errors or warnings that indicate why the JSON report wasn't generated. Please check the entire job log for such messages. If you don't find these messages, retry the failed job after setting `SECURE_LOG_LEVEL: "debug"` as a -[custom environment variable](../../ci/variables/README.md#custom-environment-variables). +[custom CI/CD variable](../../ci/variables/README.md#custom-cicd-variables). This provides useful information to investigate further. ### Getting error message `sast job: config key may not be used with 'rules': only/except` @@ -652,27 +649,16 @@ Analyzer results are displayed in the [job logs](../../ci/jobs/index.md#expand-a or [Security Dashboard](security_dashboard/index.md). There is [an open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/235772) in which changes to this behavior are being discussed. -### Enable or disable the basic security widget **(CORE ONLY)** +### Error: job `is used for configuration only, and its script should not be executed` -The basic security widget 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](../feature_flags.md) -can opt to disable it. +[Changes made in GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41260) +to the `Security/Dependency-Scanning.gitlab-ci.yml` and `Security/SAST.gitlab-ci.yml` +templates mean that if you enable the `sast` or `dependency_scanning` jobs by setting the `rules` attribute, +they will fail with the error `(job) is used for configuration only, and its script should not be executed`. -To enable it: +The `sast` or `dependency_scanning` stanzas can be used to make changes to all SAST or Dependency Scanning, +such as changing `variables` or the `stage`, but they cannot be used to define shared `rules`. -```ruby -# For the instance -Feature.enable(:core_security_mr_widget) -# For a single project -Feature.enable(:core_security_mr_widget, Project.find(<project id>)) -``` - -To disable it: - -```ruby -# For the instance -Feature.disable(:core_security_mr_widget) -# For a single project -Feature.disable(:core_security_mr_widget, Project.find(<project id>)) -``` +There [is an issue open to improve extendability](https://gitlab.com/gitlab-org/gitlab/-/issues/218444). +Please upvote the issue to help with prioritization, and +[contributions are welcomed](https://about.gitlab.com/community/contribute/). diff --git a/doc/user/application_security/license_compliance/index.md b/doc/user/application_security/license_compliance/index.md deleted file mode 100644 index 4c598d851a9..00000000000 --- a/doc/user/application_security/license_compliance/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../compliance/license_compliance/index.md' ---- - -This document was moved to [another location](../../compliance/license_compliance/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/application_security/license_management/index.md b/doc/user/application_security/license_management/index.md deleted file mode 100644 index bd67fca529f..00000000000 --- a/doc/user/application_security/license_management/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: ../../compliance/license_compliance/index.md ---- - -This document was moved to [another location](../../compliance/license_compliance/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 14ca27cdabe..9d16fb75410 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -53,7 +53,7 @@ internally-hosted registry or provide access to the individual scanner images. You must also ensure that your app has access to common package repositories that are not hosted on GitLab.com, such as npm, yarn, or Ruby gems. Packages -from these repos can be obtained by temporarily connecting to a network or by +from these repositories can be obtained by temporarily connecting to a network or by mirroring the packages inside your own offline network. ### Interacting with the vulnerabilities @@ -132,7 +132,7 @@ a bastion, and used only for this specific project. #### Scheduling the updates By default, this project's pipeline runs only once, when the `.gitlab-ci.yml` is added to the -repo. To update the GitLab security scanners and signatures, it's necessary to run this pipeline +repository. To update the GitLab security scanners and signatures, it's necessary to run this pipeline 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. @@ -148,19 +148,19 @@ The project using the `Secure-Binaries.gitlab-ci.yml` template should now host a images and resources needed to run GitLab Security features. Next, you must tell the offline instance to use these resources instead of the default ones on -GitLab.com. To do so, set the environment variable `SECURE_ANALYZERS_PREFIX` with the URL of the +GitLab.com. To do so, set the CI/CD variable `SECURE_ANALYZERS_PREFIX` with the URL of the project [container registry](../../packages/container_registry/index.md). You can set this variable in the projects' `.gitlab-ci.yml`, or -in the GitLab UI at the project or group level. See the [GitLab CI/CD environment variables page](../../../ci/variables/README.md#custom-environment-variables) +in the GitLab UI at the project or group level. See the [GitLab CI/CD variables page](../../../ci/variables/README.md#custom-cicd-variables) for more information. #### Variables -The following table shows which variables you can use with the `Secure-Binaries.gitlab-ci.yml` +The following table shows which CI/CD variables you can use with the `Secure-Binaries.gitlab-ci.yml` template: -| VARIABLE | Description | Default value | +| CI/CD variable | Description | Default value | |-------------------------------------------|-----------------------------------------------|-----------------------------------| | `SECURE_BINARIES_ANALYZERS` | Comma-separated list of analyzers to download | `"bandit, brakeman, gosec, and so on..."` | | `SECURE_BINARIES_DOWNLOAD_IMAGES` | Used to disable jobs | `"true"` | @@ -224,11 +224,11 @@ these steps: Before running AutoDevOps, follow the [above steps](#using-the-official-gitlab-template) to load those container images into the local container registry. -1. Set the pipeline variable to ensure that AutoDevOps looks in the right place for those images. +1. Set the CI/CD variable to ensure that AutoDevOps looks in the right place for those images. The AutoDevOps templates leverage the `SECURE_ANALYZERS_PREFIX` variable to identify the location of analyzer images. This variable is discussed above in [Using the secure bundle created](#using-the-secure-bundle-created). Ensure that you set this variable to the correct value for where you loaded the analyzer images. - You could consider doing this with a pipeline variable or by [modifying](../../../topics/autodevops/customize.md#customizing-gitlab-ciyml) + You could consider doing this with a project CI/CD variable or by [modifying](../../../topics/autodevops/customize.md#customizing-gitlab-ciyml) the `.gitlab-ci.yml` file directly. Once these steps are complete, GitLab has local copies of the Secure analyzers and is set up to use diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 1f0b461c91b..83f85951388 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -4,10 +4,10 @@ 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 --- -# SAST Analyzers **(CORE)** +# SAST Analyzers **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. -> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to GitLab Free in 13.3. SAST relies on underlying third party tools that are wrapped into what we call "Analyzers". An analyzer is a @@ -33,6 +33,7 @@ SAST supports the following official analyzers: - [`phpcs-security-audit`](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit) (PHP CS security-audit) - [`pmd-apex`](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) (PMD (Apex only)) - [`security-code-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) (Security Code Scan (.NET)) +- [`semgrep`](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) (Semgrep) - [`sobelow`](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) (Sobelow (Elixir Phoenix)) - [`spotbugs`](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) (SpotBugs with the Find Sec Bugs plugin (Ant, Gradle and wrapper, Grails, Maven and wrapper, SBT)) @@ -44,8 +45,8 @@ GitLab, but users can also integrate their own **custom images**. ## Official default analyzers -Any custom change to the official analyzers can be achieved by using an -[environment variable in your `.gitlab-ci.yml`](index.md#customizing-the-sast-settings). +Any custom change to the official analyzers can be achieved by using a +[CI/CD variable in your `.gitlab-ci.yml`](index.md#customizing-the-sast-settings). ### Using a custom Docker mirror @@ -116,6 +117,19 @@ variables: SAST_EXCLUDED_ANALYZERS: "eslint" ``` +## Post Analyzers **(ULTIMATE)** + +While analyzers are thin wrappers for executing scanners, post analyzers work to +enrich the data generated within our reports. + +GitLab SAST post analyzers never modify report contents directly but work by +augmenting results with additional properties (such as CWEs), location tracking fields, +and a means of identifying false positives or insignificant findings. + +The implementation of post analyzers is determined by feature availability tiers, where +simple data enrichment may occur within our free tier and most advanced processing is split +into separate binaries or pipeline jobs. + ## Custom Analyzers You can provide your own analyzers by @@ -140,28 +154,28 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) ## Analyzers Data -| Property / Tool | Apex | Bandit | Brakeman | ESLint security | SpotBugs | Flawfinder | Gosec | Kubesec Scanner | MobSF | NodeJsScan | PHP CS Security Audit | Security code Scan (.NET) | Sobelow | -| --------------------------------------- | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :---------------------: | :-------------------------: | :----------------: | -| Severity | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | -| Title | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Description | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | -| File | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Start line | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | ✓ | ✓ | ✓ | -| End line | ✓ | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Start column | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | -| End column | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| External ID (for example, CVE) | 𐄂 | 𐄂 | ⚠ | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| URLs | ✓ | 𐄂 | ✓ | 𐄂 | ⚠ | 𐄂 | ⚠ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Internal doc/explanation | ✓ | ⚠ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | -| Solution | ✓ | 𐄂 | 𐄂 | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Affected item (for example, class or package) | ✓ | 𐄂 | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Confidence | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | x | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | -| Source code extract | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Internal ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | +| Property / Tool | Apex | Bandit | Brakeman | ESLint security | SpotBugs | Flawfinder | Gosec | Kubesec Scanner | MobSF | NodeJsScan | PHP CS Security Audit | Security code Scan (.NET) | Semgrep | Sobelow | +|--------------------------------|------|--------|----------|-----------------|----------|------------|-------|-----------------|-------|------------|-----------------------|---------------------------|---------|---------| +| Affected item (for example, class or package) | ✓ | ✗ | ✓ | ✗ | ✓ | ✓ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | +| Confidence | ✗ | ✓ | ✓ | ✗ | ✓ | x | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ⚠ | ✓ | +| Description | ✓ | ✗ | ✗ | ✓ | ✓ | ✗ | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✓ | ✓ | +| End column | ✓ | ✗ | ✗ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | +| End line | ✓ | ✓ | ✗ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | +| External ID (for example, CVE) | ✗ | ✗ | ⚠ | ✗ | ⚠ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ⚠ | ✗ | +| File | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Internal doc/explanation | ✓ | ⚠ | ✓ | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ | +| Internal ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ | +| Severity | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ⚠ | ✗ | +| Solution | ✓ | ✗ | ✗ | ✗ | ⚠ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ⚠ | ✗ | +| Source code extract | ✗ | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | +| Start column | ✓ | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✓ | ✓ | ✓ | ✗ | +| Start line | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Title | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| URLs | ✓ | ✗ | ✓ | ✗ | ⚠ | ✗ | ⚠ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | - ✓ => we have that data - ⚠ => we have that data but it's partially reliable, or we need to extract it from unstructured content -- 𐄂 => we don't have that data or it would need to develop specific or inefficient/unreliable logic to obtain it. +- ✗ => we don't have that data or it would need to develop specific or inefficient/unreliable logic to obtain it. The values provided by these tools are heterogeneous so they are sometimes normalized into common values (for example, `severity`, `confidence`, and so on). diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 59887c95c67..880edebfeda 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -8,7 +8,7 @@ type: reference, howto # Static Application Security Testing (SAST) > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. -> - All open source (OSS) analyzers were moved to GitLab Core in GitLab 13.3. +> - All open source (OSS) analyzers were moved to GitLab Free in GitLab 13.3. NOTE: The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) @@ -83,6 +83,7 @@ You can also [view our language roadmap](https://about.gitlab.com/direction/secu | Objective-C (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | | PHP | [phpcs-security-audit](https://github.com/FloeDesignTechnologies/phpcs-security-audit) | 10.8 | | Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/PyCQA/bandit) | 10.3 | +| Python | [semgrep](https://semgrep.dev) | 13.9 | | React | [ESLint react plugin](https://github.com/yannickcr/eslint-plugin-react) | 12.5 | | Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3 | | Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) | @@ -111,24 +112,25 @@ The following analyzers have multi-project support: - MobSF - PMD - Security Code Scan +- Semgrep - SpotBugs - Sobelow #### Enable multi-project support for Security Code Scan Multi-project support in the Security Code Scan requires a Solution (`.sln`) file in the root of -the repository. For details on the Solution format, see the Microsoft reference [Solution (.sln) file](https://docs.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file?view=vs-2019). +the repository. For details on the Solution format, see the Microsoft reference [Solution (`.sln`) file](https://docs.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file?view=vs-2019). ### Making SAST analyzers available to all GitLab tiers -All open source (OSS) analyzers have been moved to the GitLab Core tier as of GitLab 13.3. +All open source (OSS) analyzers have been moved to the GitLab Free tier as of GitLab 13.3. #### Summary of features per tier Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Capability | In Core | In Ultimate | +| Capability | In Free | In Ultimate | |:-----------------------------------------------------------------------------------|:--------------------|:-------------------| | [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | | [Customize SAST Settings](#customizing-the-sast-settings) | **{check-circle}** | **{check-circle}** | @@ -188,14 +190,15 @@ page: 1. If the project does not have a `.gitlab-ci.yml` file, click **Enable** in the Static Application Security Testing (SAST) row, otherwise click **Configure**. 1. Enter the custom SAST values. - Custom values are stored in the `.gitlab-ci.yml` file. For variables not in the SAST Configuration page, their values are left unchanged. Default values are inherited from the GitLab SAST template. + Custom values are stored in the `.gitlab-ci.yml` file. For CI/CD variables not in the SAST Configuration page, their values are left unchanged. Default values are inherited from the GitLab SAST template. + 1. Optionally, expand the **SAST analyzers** section, select individual [SAST analyzers](analyzers.md) and enter custom analyzer values. 1. Click **Create Merge Request**. 1. Review and merge the merge request. ### Customizing the SAST settings -The SAST settings can be changed through [environment variables](#available-variables) +The SAST settings can be changed through [CI/CD variables](#available-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 @@ -254,8 +257,8 @@ To create a custom ruleset: 1. Create a custom ruleset file named `sast-ruleset.toml` in the `.gitlab` directory. 1. In the `sast-ruleset.toml` file, do one of the following: - - Disable predefined rules belonging to SAST analyzers. In this example, the disabled rules - belong to `eslint` and `sobelow` and have the corresponding identifiers `type` and `value`: + - Disable predefined rules belonging to SAST analyzers. In this example, the three disabled rules + belong to `eslint` and `sobelow` by matching the corresponding identifiers' `type` and `value`: ```toml [eslint] @@ -265,6 +268,12 @@ To create a custom ruleset: type = "eslint_rule_id" value = "security/detect-object-injection" + [[eslint.ruleset]] + disable = true + [eslint.ruleset.identifier] + type = "cwe" + value = "185" + [sobelow] [[sobelow.ruleset]] disable = true @@ -322,20 +331,20 @@ To create a custom ruleset: value = "gosec-config.json" ``` -### Using environment variables to pass credentials for private repositories +### Using CI/CD variables to pass credentials for private repositories Some analyzers require downloading the project's dependencies in order to perform the analysis. In turn, such dependencies may live in private Git repositories and thus require credentials like username and password to download them. Depending on the analyzer, such credentials can be provided to -it via [custom environment variables](#custom-environment-variables). +it via [custom CI/CD variables](#custom-cicd-variables). -#### Using a variable to pass username and password to a private Maven repository +#### Using a CI/CD variable to pass username and password to a private Maven repository If your private Maven repository requires login credentials, -you can use the `MAVEN_CLI_OPTS` environment variable. +you can use the `MAVEN_CLI_OPTS` CI/CD variable. -Read more on [how to use private Maven repositories](../index.md#using-private-maven-repos). +Read more on [how to use private Maven repositories](../index.md#using-private-maven-repositories). ### Enabling Kubesec analyzer @@ -361,7 +370,7 @@ a `before_script` execution to prepare your scan job. To pass your project's dependencies as artifacts, the dependencies must be included in the project's working directory and specified using the `artifacts:path` configuration. -If all dependencies are present, the `COMPILE=false` variable can be provided to the +If all dependencies are present, the `COMPILE=false` CI/CD variable can be provided to the analyzer and compilation is skipped: ```yaml @@ -401,7 +410,7 @@ can use `MAVEN_REPO_PATH`. See ### Available variables -SAST can be [configured](#customizing-the-sast-settings) using environment variables. +SAST can be [configured](#customizing-the-sast-settings) using CI/CD variables. #### Logging level @@ -421,63 +430,75 @@ From highest to lowest severity, the logging levels are: #### Custom Certificate Authority To trust a custom Certificate Authority, set the `ADDITIONAL_CA_CERT_BUNDLE` variable to the bundle -of CA certs that you want to trust in the SAST environment. +of CA certs that you want to trust in the SAST environment. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following: + +```yaml +variables: + ADDITIONAL_CA_CERT_BUNDLE: | + -----BEGIN CERTIFICATE----- + MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB + ... + jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs= + -----END CERTIFICATE----- +``` + +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. #### Docker images -The following are Docker image-related variables. +The following are Docker image-related CI/CD variables. -| Environment variable | Description | +| 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_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). | #### Vulnerability filters Some analyzers make it possible to filter out vulnerabilities under a given threshold. -| Environment variable | Default value | Description | -|-------------------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. You might need to exclude temporary directories used by your build tool as these can generate false positives. | -| `SEARCH_MAX_DEPTH` | 4 | SAST searches the repository to detect the programming languages used, and selects the matching analyzers. Set the value of `SEARCH_MAX_DEPTH` to specify how many directory levels the search phase should span. After the analyzers have been selected, the _entire_ repository is analyzed. | -| `SAST_BANDIT_EXCLUDED_PATHS` | | Comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html); For example: `'*/tests/*, */venv/*'` | -| `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | -| `SAST_FLAWFINDER_LEVEL` | 1 | Ignore Flawfinder vulnerabilities under given risk level. Integer, 0=No risk, 5=High risk. | -| `SAST_GOSEC_LEVEL` | 0 | Ignore Gosec vulnerabilities under given confidence level. Integer, 0=Undefined, 1=Low, 2=Medium, 3=High. | +| CI/CD variable | Default value | Description | +|------------------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. You might need to exclude temporary directories used by your build tool as these can generate false positives. | +| `SEARCH_MAX_DEPTH` | 4 | SAST searches the repository to detect the programming languages used, and selects the matching analyzers. Set the value of `SEARCH_MAX_DEPTH` to specify how many directory levels the search phase should span. After the analyzers have been selected, the _entire_ repository is analyzed. | +| `SAST_BANDIT_EXCLUDED_PATHS` | | Comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html); For example: `'*/tests/*, */venv/*'` | +| `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | +| `SAST_FLAWFINDER_LEVEL` | 1 | Ignore Flawfinder vulnerabilities under given risk level. Integer, 0=No risk, 5=High risk. | +| `SAST_GOSEC_LEVEL` | 0 | Ignore Gosec vulnerabilities under given confidence level. Integer, 0=Undefined, 1=Low, 2=Medium, 3=High. | #### Analyzer settings -Some analyzers can be customized with environment variables. - -| Environment variable | Analyzer | Description | -|---------------------------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `SCAN_KUBERNETES_MANIFESTS` | Kubesec | Set to `"true"` to scan Kubernetes manifests. | -| `KUBESEC_HELM_CHARTS_PATH` | Kubesec | Optional path to Helm charts that `helm` uses to generate a Kubernetes manifest that `kubesec` scans. If dependencies are defined, `helm dependency build` should be ran in a `before_script` to fetch the necessary dependencies. | -| `KUBESEC_HELM_OPTIONS` | Kubesec | Additional arguments for the `helm` executable. | -| `COMPILE` | SpotBugs | Set to `false` to disable project compilation and dependency fetching. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195252) in GitLab 13.1. | -| `ANT_HOME` | SpotBugs | The `ANT_HOME` environment variable. | -| `ANT_PATH` | SpotBugs | Path to the `ant` executable. | -| `GRADLE_PATH` | SpotBugs | Path to the `gradle` executable. | -| `JAVA_OPTS` | SpotBugs | Additional arguments for the `java` executable. | -| `JAVA_PATH` | SpotBugs | Path to the `java` executable. | -| `SAST_JAVA_VERSION` | SpotBugs | Which Java version to use. Supported versions are `8` and `11`. Defaults to `8`. | -| `MAVEN_CLI_OPTS` | SpotBugs | Additional arguments for the `mvn` or `mvnw` executable. | -| `MAVEN_PATH` | SpotBugs | Path to the `mvn` executable. | -| `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). | -| `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. | - -#### Custom environment variables +Some analyzers can be customized with CI/CD variables. + +| CI/CD variable | Analyzer | Description | +|-----------------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `SCAN_KUBERNETES_MANIFESTS` | Kubesec | Set to `"true"` to scan Kubernetes manifests. | +| `KUBESEC_HELM_CHARTS_PATH` | Kubesec | Optional path to Helm charts that `helm` uses to generate a Kubernetes manifest that `kubesec` scans. If dependencies are defined, `helm dependency build` should be ran in a `before_script` to fetch the necessary dependencies. | +| `KUBESEC_HELM_OPTIONS` | Kubesec | Additional arguments for the `helm` executable. | +| `COMPILE` | SpotBugs | Set to `false` to disable project compilation and dependency fetching. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195252) in GitLab 13.1. | +| `ANT_HOME` | SpotBugs | The `ANT_HOME` variable. | +| `ANT_PATH` | SpotBugs | Path to the `ant` executable. | +| `GRADLE_PATH` | SpotBugs | Path to the `gradle` executable. | +| `JAVA_OPTS` | SpotBugs | Additional arguments for the `java` executable. | +| `JAVA_PATH` | SpotBugs | Path to the `java` executable. | +| `SAST_JAVA_VERSION` | SpotBugs | Which Java version to use. Supported versions are `8` and `11`. Defaults to `8`. | +| `MAVEN_CLI_OPTS` | SpotBugs | Additional arguments for the `mvn` or `mvnw` executable. | +| `MAVEN_PATH` | SpotBugs | Path to the `mvn` executable. | +| `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). | +| `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. | + +#### Custom CI/CD variables > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18193) in GitLab Ultimate 12.5. -In addition to the aforementioned SAST configuration variables, -all [custom environment variables](../../../ci/variables/README.md#custom-environment-variables) are propagated +In addition to the aforementioned SAST configuration CI/CD variables, +all [custom variables](../../../ci/variables/README.md#custom-cicd-variables) are propagated to the underlying SAST analyzer images if [the SAST vendored template](#configuration) is used. @@ -669,22 +690,23 @@ For details on saving and transporting Docker images as a file, see Docker's doc Support for custom certificate authorities was introduced in the following versions. -| Analyzer | Version | -| -------- | ------- | -| `bandit` | [v2.3.0](https://gitlab.com/gitlab-org/security-products/analyzers/bandit/-/releases/v2.3.0) | -| `brakeman` | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman/-/releases/v2.1.0) | -| `eslint` | [v2.9.2](https://gitlab.com/gitlab-org/security-products/analyzers/eslint/-/releases/v2.9.2) | -| `flawfinder` | [v2.3.0](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder/-/releases/v2.3.0) | -| `gosec` | [v2.5.0](https://gitlab.com/gitlab-org/security-products/analyzers/gosec/-/releases/v2.5.0) | -| `kubesec` | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec/-/releases/v2.1.0) | -| `nodejs-scan` | [v2.9.5](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan/-/releases/v2.9.5) | +| Analyzer | Version | +| -------- | ------- | +| `bandit` | [v2.3.0](https://gitlab.com/gitlab-org/security-products/analyzers/bandit/-/releases/v2.3.0) | +| `brakeman` | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman/-/releases/v2.1.0) | +| `eslint` | [v2.9.2](https://gitlab.com/gitlab-org/security-products/analyzers/eslint/-/releases/v2.9.2) | +| `flawfinder` | [v2.3.0](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder/-/releases/v2.3.0) | +| `gosec` | [v2.5.0](https://gitlab.com/gitlab-org/security-products/analyzers/gosec/-/releases/v2.5.0) | +| `kubesec` | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec/-/releases/v2.1.0) | +| `nodejs-scan` | [v2.9.5](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan/-/releases/v2.9.5) | | `phpcs-security-audit` | [v2.8.2](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit/-/releases/v2.8.2) | -| `pmd-apex` | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex/-/releases/v2.1.0) | -| `security-code-scan` | [v2.7.3](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan/-/releases/v2.7.3) | -| `sobelow` | [v2.2.0](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow/-/releases/v2.2.0) | -| `spotbugs` | [v2.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs/-/releases/v2.7.1) | +| `pmd-apex` | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex/-/releases/v2.1.0) | +| `security-code-scan` | [v2.7.3](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan/-/releases/v2.7.3) | +| `semgrep` | [v0.0.1](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan/-/releases/v0.0.1) | +| `sobelow` | [v2.2.0](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow/-/releases/v2.2.0) | +| `spotbugs` | [v2.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs/-/releases/v2.7.1) | -### Set SAST CI job variables to use local SAST analyzers +### Set SAST CI/CD variables to use local SAST analyzers Add the following configuration to your `.gitlab-ci.yml` file. You must replace `SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry: @@ -720,6 +742,10 @@ affected. Read more in For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). +### Error: `sast is used for configuration only, and its script should not be executed` + +For information on this, see the [GitLab Secure troubleshooting section](../index.md#error-job-is-used-for-configuration-only-and-its-script-should-not-be-executed). + ### Limitation when using rules:exists The [SAST CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) @@ -750,3 +776,7 @@ For Maven builds, add the following to your `pom.xml` file: <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> ``` + +### 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. diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 0ae038924ec..98177e804f3 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -86,14 +86,14 @@ However not all features are available on every tier. See the breakdown below fo Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Capability | In Core | In Ultimate | -|:--------------------------------------------------------------------------|:--------------------|:-------------------| -| [Configure Secret Detection Scanners](#configuration) | **{check-circle}** | **{check-circle}** | -| [Customize Secret Detection Settings](#customizing-settings) | **{check-circle}** | **{check-circle}** | -| View [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** | **{check-circle}** | -| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | +| Capability | In Free | In Ultimate | +|:----------------------------------------------------------------|:--------------------|:-------------------| +| [Configure Secret Detection Scanners](#configuration) | **{check-circle}** | **{check-circle}** | +| [Customize Secret Detection Settings](#customizing-settings) | **{check-circle}** | **{check-circle}** | +| View [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** | **{check-circle}** | +| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | | [Interaction with Vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | -| [Access to Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Access to Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | ## Configuration @@ -148,7 +148,7 @@ Third party cloud and SaaS providers can [express integration interest by fillin ### Customizing settings -The Secret Detection scan settings can be changed through [environment variables](#available-variables) +The Secret Detection scan settings can be changed through [CI/CD variables](#available-variables) by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. @@ -156,8 +156,21 @@ To override a job definition, (for example, change properties like `variables` o declare a job with the same name as the SAST job to override. Place this new job after the template inclusion and specify any additional keys under it. +WARNING: +Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) +is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. + +#### GIT_DEPTH + +The [`GIT_DEPTH` CI/CD variable](../../../ci/runners/README.md#shallow-cloning) affects Secret Detection. +The Secret Detection analyzer relies on generating patches between commits to scan content for +secrets. If you override the default, ensure the value is greater than 1. If the number of commits +in an MR is greater than the GIT_DEPTH value, Secret Detection will [fail to detect secrets](#error-couldnt-run-the-gitleaks-command-exit-status-2). + +#### Custom settings example + In the following example, we include the Secret Detection template and at the same time we -override the `secret_detection` job with the `SECRET_DETECTION_HISTORIC_SCAN` variable to `true`: +override the `secret_detection` job with the `SECRET_DETECTION_HISTORIC_SCAN` CI/CD variable to `true`: ```yaml include: @@ -171,20 +184,16 @@ secret_detection: Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable takes precedence. -WARNING: -Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) -is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. - #### Available variables -Secret Detection can be customized by defining available variables: +Secret Detection can be customized by defining available CI/CD variables: -| Environment variable | Default value | Description | -|-------------------------|---------------|-------------| -| `SECRET_DETECTION_COMMIT_FROM` | - | The commit a Gitleaks scan starts at. | -| `SECRET_DETECTION_COMMIT_TO` | - | The commit a Gitleaks scan ends at. | -| `SECRET_DETECTION_EXCLUDED_PATHS` | "" | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225273) in GitLab 13.3. | -| `SECRET_DETECTION_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. | +| CI/CD variable | Default value | Description | +|-----------------------------------|---------------|-------------| +| `SECRET_DETECTION_COMMIT_FROM` | - | The commit a Gitleaks scan starts at. | +| `SECRET_DETECTION_COMMIT_TO` | - | The commit a Gitleaks scan ends at. | +| `SECRET_DETECTION_EXCLUDED_PATHS` | "" | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225273) in GitLab 13.3. | +| `SECRET_DETECTION_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. | ### Custom rulesets **(ULTIMATE)** @@ -231,7 +240,7 @@ To create a custom ruleset: ### Logging level -To control the verbosity of logs set the `SECURE_LOG_LEVEL` environment variable. Messages of this logging level or higher are output. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. +To control the verbosity of logs set the `SECURE_LOG_LEVEL` CI/CD variable. Messages of this logging level or higher are output. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. From highest to lowest severity, the logging levels are: @@ -246,7 +255,7 @@ From highest to lowest severity, the logging levels are: GitLab 12.11 introduced support for scanning the full history of a repository. This new functionality is particularly useful when you are enabling Secret Detection in a repository for the first time and you want to perform a full secret scan. Running a secret scan on the full history can take a long time, -especially for larger repositories with lengthy Git histories. We recommend not setting this variable +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`](../sast/#vulnerability-filters)) @@ -307,7 +316,7 @@ Support for custom certificate authorities was introduced in the following versi | -------- | ------- | | secrets | [v3.0.0](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/releases/v3.0.0) | -### Set Secret Detection CI job variables to use local Secret Detection analyzer +### Set Secret Detection CI/CD variables to use local Secret Detection analyzer Add the following configuration to your `.gitlab-ci.yml` file. You must replace `SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry: @@ -331,11 +340,15 @@ For information on this, see the [general Application Security troubleshooting s ### Error: `Couldn't run the gitleaks command: exit status 2` -This error is usually caused by the `GIT_DEPTH` value of 50 that is set for all [projects by default](../../../ci/pipelines/settings.md#git-shallow-clone). - -For example, if a pipeline is triggered from a Merge Request containing 60 commits while the `GIT_DEPTH` is set to 50, the Secret Detection job fails as the clone is not deep enough to contain all of the relevant commits. +If a pipeline is triggered from a Merge Request containing 60 commits while the `GIT_DEPTH` variable +is set to 50 (a [project default](../../../ci/pipelines/settings.md#git-shallow-clone)), +the Secret Detection job fails as the clone is not deep enough to contain all of the +relevant commits. -You can confirm this to be the cause of the error by implementing a [logging level](../../application_security/secret_detection/index.md#logging-level) of `debug`. Once implemented, the logs should look similar to the following example, wherein an "object not found" error can be seen: +To confirm this as the cause of the error, set the +[logging level](../../application_security/secret_detection/index.md#logging-level) to `debug`, then +rerun the pipeline. The logs should look similar to the following example. The text "object not +found" is a symptom of this error. ```plaintext ERRO[2020-11-18T18:05:52Z] object not found @@ -343,7 +356,9 @@ ERRO[2020-11-18T18:05:52Z] object not found [ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ Gitleaks analysis failed: exit status 2 ``` -If this is the case, we can resolve the issue by setting the [`GIT_DEPTH` variable](../../../ci/runners/README.md#shallow-cloning) to a higher value. In order to apply this only to the Secret Detection job, the following can be added to your `.gitlab-ci.yml`: +To resolve the issue, set the [`GIT_DEPTH` CI/CD variable](../../../ci/runners/README.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: ```yaml secret_detection: diff --git a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_7.png b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_7.png Binary files differdeleted file mode 100644 index cd8dbed48fc..00000000000 --- a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_7.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_4.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_4.png Binary files differdeleted file mode 100644 index 9ade24be16f..00000000000 --- a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_export_csv_v13_4.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_dismissal_v13_4.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_dismissal_v13_4.png Binary files differdeleted file mode 100644 index eb1dfe6c6f4..00000000000 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard_dismissal_v13_4.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_5.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_5.png Binary files differdeleted file mode 100644 index c46a8295a53..00000000000 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_5.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_empty_v13_4.png b/doc/user/application_security/security_dashboard/img/security_center_dashboard_empty_v13_4.png Binary files differindex 5edceb32e5c..5edceb32e5c 100644 --- a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_empty_v13_4.png +++ b/doc/user/application_security/security_dashboard/img/security_center_dashboard_empty_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_link_v12_4.png b/doc/user/application_security/security_dashboard/img/security_center_dashboard_link_v12_4.png Binary files differindex e0e80810b08..e0e80810b08 100644 --- a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_link_v12_4.png +++ b/doc/user/application_security/security_dashboard/img/security_center_dashboard_link_v12_4.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_v13_4.png b/doc/user/application_security/security_dashboard/img/security_center_dashboard_v13_4.png Binary files differindex 5379b5c6e5d..5379b5c6e5d 100644 --- a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_v13_4.png +++ b/doc/user/application_security/security_dashboard/img/security_center_dashboard_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_center_settings_v13_4.png b/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png Binary files differindex 4223494c294..4223494c294 100644 --- a/doc/user/application_security/security_dashboard/img/instance_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/img/vulnerability_list_table_v13_4.png b/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png Binary files differdeleted file mode 100644 index 760942c3239..00000000000 --- a/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 10bf6202a92..b08c19bee47 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -5,15 +5,15 @@ 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 --- -# GitLab Security Dashboard, Security Center, and Vulnerability Reports **(ULTIMATE)** +# GitLab Security Dashboards and Security Center **(ULTIMATE)** GitLab provides a comprehensive set of features for viewing and managing vulnerabilities: -- Security dashboards: An overview of the security status in your instance, [groups](#group-security-dashboard), and +- Security dashboards: An overview of the security status in your personal [Security Center](#security-center), [groups](#group-security-dashboard), and [projects](#project-security-dashboard). -- [Vulnerability reports](#vulnerability-report): Detailed lists of all vulnerabilities for the instance, group, project, or +- [Vulnerability reports](../vulnerability_report/index.md): Detailed lists of all vulnerabilities for the Security Center, group, project, or pipeline. This is where you triage and manage vulnerabilities. -- [Security Center](#instance-security-center): A dedicated area for vulnerability management at the instance level. This +- [Security Center](#security-center): A dedicated area for personalized vulnerability management. This includes a security dashboard, vulnerability report, and settings. You can also drill down into a vulnerability and get extra information on the @@ -27,7 +27,7 @@ To benefit from these features, you must first configure one of the ## Supported reports -The vulnerability report displays vulnerabilities detected by scanners such as: +The security dashboard and vulnerability report displays information about vulnerabilities detected by scanners such as: - [Container Scanning](../container_scanning/index.md) - [Dynamic Application Security Testing](../dast/index.md) @@ -68,7 +68,7 @@ the analyzer outputs an > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235558) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. At the project level, the Security Dashboard displays a chart with the number of vulnerabilities over time. -Access it by navigating to **Security & Compliance > Security Dashboard**. Currently, we display historical +Access it by navigating to **Security & Compliance > Security Dashboard**. We display historical data up to 365 days.  @@ -76,43 +76,6 @@ data up to 365 days. Filter the historical data by clicking on the corresponding legend name. The image above, for example, shows only the graph for vulnerabilities with **high** severity. -### Vulnerability Report - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6165) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.1. - -The vulnerabilities that exist in your project's -[default branch](../../project/repository/branches/index.md#default-branch) are accessed by navigating to -**Security & Compliance > Vulnerability Report**. By default, the Vulnerability Report is filtered to -display all detected and confirmed vulnerabilities. - -The Vulnerability Report first displays the time at which the last pipeline completed on the project's -default branch. There's also a link to view this in more detail. In the case of any pipeline failures, -the number of failures is indicated. The failure notification takes you directly to -the **Failed jobs** tab of the pipeline page. - -The Vulnerability Report next displays the total number of vulnerabilities by severity (for example, -Critical, High, Medium, Low, Info, Unknown). Below this, a table shows each vulnerability's status, severity, -description and if there is a Merge Request related to it. Clicking a vulnerability takes you to its -[Vulnerability Details](../vulnerabilities) -page to view more information about that vulnerability. - - - -You can filter the vulnerabilities by one or more of the following: - -| Filter | Available Options | -| --- | --- | -| Status | Detected, Confirmed, Dismissed, Resolved | -| Severity | Critical, High, Medium, Low, Info, Unknown | -| Scanner | [Available Scanners](../index.md#security-scanning-tools) | - -You can also dismiss vulnerabilities in the table: - -1. Select the checkbox for each vulnerability you want to dismiss. -1. In the menu that appears, select the reason for dismissal and click **Dismiss Selected**. - - - ## Group Security Dashboard > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6709) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. @@ -146,30 +109,30 @@ Next to the timeline chart is a list of projects, grouped and sorted by the seve Projects with no vulnerability tests configured don't appear in the list. Additionally, dismissed vulnerabilities are excluded. -Navigate to the group's [vulnerability report](#vulnerability-report-1) to view the vulnerabilities found. +Navigate to the group's [vulnerability report](../vulnerability_report/index.md) to view the vulnerabilities found. -## Instance Security Center +## Security Center > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. -The Security Center is where you manage vulnerabilities for your instance. It displays the -vulnerabilities present in the default branches of all the projects you configure. It includes the -following: +The Security Center is personal space where you manage vulnerabilities across all your projects. It +displays the vulnerabilities present in the default branches of all the projects you configure. It includes +the following: - The [group security dashboard's](#group-security-dashboard) features. -- A [vulnerability report](#vulnerability-report). +- A [vulnerability report](../vulnerability_report/index.md). - A dedicated settings area to configure which projects to display. - + -You can access the Instance Security Center from the menu +You can access the Security Center from the menu bar at the top of the page. Under **More**, select **Security**. - + The dashboard and vulnerability report are empty before you add projects. - + ### Adding projects to the Security Center @@ -179,41 +142,11 @@ To add projects to the Security Center: 1. Search for and add one or more projects using the **Search your projects** field. 1. Click the **Add projects** button. - + After you add projects, the security dashboard and vulnerability report display the vulnerabilities found in those projects' default branches. -## Export vulnerabilities - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213014) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. - -You can export all your vulnerabilities in CSV (comma separated values) format by clicking the -**{upload}** **Export** button located at top right of the Security Dashboard. When the report is -ready, the CSV report downloads to your local machine. The report contains all vulnerabilities for -the projects defined in the Security Dashboard, as filters don't apply to the export function. - -NOTE: -It may take several minutes for the download to start if your project contains -thousands of vulnerabilities. Don't close the page until the download finishes. - -The fields in the export include: - -- Group Name -- Project Name -- Scanner Type -- Scanner Name -- Status -- Vulnerability -- Details -- Additional Info -- Severity -- [CVE](https://cve.mitre.org/) (Common Vulnerabilities and Exposures) -- [CWE](https://cwe.mitre.org/) (Common Weakness Enumeration) -- Other Identifiers - - - ## Keeping the dashboards up to date The Security Dashboard displays information from the results of the most recent @@ -245,35 +178,6 @@ When using [Auto DevOps](../../../topics/autodevops/index.md), use [special environment variables](../../../topics/autodevops/customize.md#environment-variables) to configure daily security scans. -## Vulnerability report - -Each vulnerability report contains vulnerabilities from the latest scans that were merged -into the default branch. - - - -You can filter which vulnerabilities the vulnerability report displays by: - -| Filter | Available Options | -| --- | --- | -| Status | Detected, Confirmed, Dismissed, Resolved | -| Severity | Critical, High, Medium, Low, Info, Unknown | -| Scanner | [Available Scanners](../index.md#security-scanning-tools) | -| Project | Projects configured in the Security Center settings | - -Clicking any vulnerability in the table takes you to its -[Vulnerability Details](../vulnerabilities) page to see more information on that vulnerability. -To create an issue associated with the vulnerability, click the **Create Issue** button. - - - -Once you create the issue, the linked issue icon in the vulnerability list: - -- Indicates that an issue has been created for that vulnerability. -- Shows a tooltip that contains a link to the issue. - - - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_9.png b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_9.png Binary files differnew file mode 100644 index 00000000000..a668ce1a3b8 --- /dev/null +++ b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_9.png diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index f7bd201aba9..13bde2ed38b 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -126,14 +126,13 @@ any pods. The policy itself is still deployed to the corresponding deployment na > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3403) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. -The policy editor allows you to create, edit, and delete policies. To -create a new policy click the **New policy** button located in the -**Policy** tab's header. To edit an existing policy, click**Edit -policy** in the selected policy drawer. - -Note that the policy editor only supports the -[CiliumNetworkPolicy](https://docs.cilium.io/en/v1.8/policy/)specification. Regular Kubernetes -[NetworkPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#networkpolicy-v1-networking-k8s-io) +You can use the policy editor to create, edit, and delete policies. + +- To create a new policy, click the **New policy** button located in the **Policy** tab's header. +- To edit an existing policy, click **Edit policy** in the selected policy drawer. + +The policy editor only supports the [CiliumNetworkPolicy](https://docs.cilium.io/en/v1.8/policy/) +specification. Regular Kubernetes [NetworkPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#networkpolicy-v1-networking-k8s-io) resources aren't supported. The policy editor has two modes: @@ -163,3 +162,65 @@ Once your policy is complete, save it by pressing the **Save policy** button at the bottom of the editor. Existing policies can also be removed from the editor interface by clicking the **Delete policy** 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. + +You can use policy alerts to track your policy's impact. Alerts are only available if you've +[installed](../../clusters/agent/repository.md) +and [configured](../../clusters/agent/index.md#create-an-agent-record-in-gitlab) +a Kubernetes Agent for this project. + +There are two ways to create policy alerts: + +- In the [policy editor UI](#container-network-policy-editor), + by clicking **Add alert**. +- In the policy editor's YAML mode, through the `metadata.annotations` property: + + ```yaml + metadata: + annotations: + app.gitlab.com/alert: 'true' + ``` + +Once added, the UI updates and displays a warning about the dangers of too many alerts. + +#### Enable or disable Policy Alerts **(FREE SELF)** + +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. + +The policy alert list displays your policy's alert activity. You can sort the list by the +**Date and time** column, and the **Status** column. Use the selector menu in the **Status** column +to set the status for each alert: + +- Unreviewed +- In review +- Resolved +- Dismissed + +By default, the list doesn't display resolved or dismissed alerts. To show these alerts, clear the +checkbox **Hide dismissed alerts**. + + + +For information on work in progress for the alerts dashboard, see [this epic](https://gitlab.com/groups/gitlab-org/-/epics/5041). diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 705964dba66..50f05b687f7 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -5,60 +5,107 @@ group: Threat Insights info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Vulnerability Pages +# Vulnerability Pages **(ULTIMATE)** > [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 [Security Dashboard](../security_dashboard/index.md#project-security-dashboard) has an individual page which includes: +Each security vulnerability in a project's [Vulnerability Report](../vulnerability_report/index.md) has an individual page which includes: -- Details for the vulnerability. +- Details of the vulnerability. - The status of the vulnerability within the project. - Available actions for the vulnerability. - Any issues related to the vulnerability. -On the vulnerability page, you can interact with the vulnerability in -several different ways: +On the vulnerability's page, you can: -- [Change the Vulnerability Status](#changing-vulnerability-status) - You can change the - status of a vulnerability to **Detected**, **Confirmed**, **Dismissed**, or **Resolved**. -- [Create issue](#creating-an-issue-for-a-vulnerability) - Create a new issue with the - title and description pre-populated with information from the vulnerability report. - By default, such issues are [confidential](../../project/issues/confidential_issues.md). -- [Link issues](#link-issues-to-the-vulnerability) - Link existing issues to vulnerability. -- [Automatic remediation](#automatic-remediation-for-vulnerabilities) - For some vulnerabilities, - a solution is provided for how to fix the vulnerability automatically. +- [Change the vulnerability's status](#change-vulnerability-status). +- [Create a GitLab issue](#create-a-gitlab-issue-for-a-vulnerability). +- [Create a Jira issue](#create-a-jira-issue-for-a-vulnerability). +- [Link issues to the vulnerability](#link-gitlab-issues-to-the-vulnerability). +- [Automatically remediate the vulnerability](#automatically-remediate-the-vulnerability), if an + automatic solution is available. -## Changing vulnerability status +## Change vulnerability status -You can switch the status of a vulnerability using the **Status** dropdown to one of +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 | +| 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 | +| Resolved | The vulnerability has been fixed and is no longer valid | A timeline shows you when the vulnerability status has changed and allows you to comment on a change. -## Creating an issue for a vulnerability +## Create a GitLab issue for a vulnerability -You can create an issue for a vulnerability by selecting the **Create issue** button. +To create a GitLab issue for a vulnerability: -This allows the user to create a [confidential issue](../../project/issues/confidential_issues.md) -in the project the vulnerability came from. Fields are pre-populated with pertinent information -from the vulnerability report. After the issue is created, GitLab redirects you to the -issue page so you can edit, assign, or comment on the issue. +1. In GitLab, go to the vulnerability's page. +1. Select **Create issue**. -## Link issues to the vulnerability +An issue is created in the project, prepopulated with information from the vulnerability report. +The issue is then opened so you can take further action. -You can link one or more existing issues to the vulnerability. This allows you to +## 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. + +Prerequisites: + +- [Enable Jira integration for vulnerabilities](../../project/integrations/jira.md). Select + **Enable Jira issues creation from vulnerabilities** when configuring the integration. + +To create a Jira issue for a vulnerability: + +1. Go to the vulnerability's page. +1. Select **Create Jira issue**. + +An issue is created in the linked Jira project, with the **Summary** and **Description** fields +pre-populated. The Jira issue is then opened in a new browser tab. + +### 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) +``` + +To disable it: + +```ruby +Feature.disable(:jira_for_vulnerabilities) +``` + +## Link GitLab issues to the vulnerability + +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. -## Automatic remediation for vulnerabilities +Linked issues are shown in the Vulnerability Report and the vulnerability's page. + +## Automatically remediate the vulnerability You can fix some vulnerabilities by applying the solution that GitLab automatically generates for you. [Read more about the automatic remediation for vulnerabilities feature](../index.md#automatic-remediation-for-vulnerabilities). diff --git a/doc/user/application_security/vulnerabilities/severities.md b/doc/user/application_security/vulnerabilities/severities.md index ce2297f7a1a..40b8f418737 100644 --- a/doc/user/application_security/vulnerabilities/severities.md +++ b/doc/user/application_security/vulnerabilities/severities.md @@ -37,33 +37,33 @@ the following tables: | GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example | |--------------------------------------------------------------------------------------------------------|--------------------------|----------------------------|------------------------------------| -| [security-code-scan](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) | **{dotted-circle}** No | N/A | N/A | -| [brakeman](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) | **{dotted-circle}** No | N/A | N/A | -| [sobelow](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Unknown` | -| [nodejs-scan](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan) | **{check-circle}** Yes | String | `INFO`, `WARNING`, `ERROR` | -| [flawfinder](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder) | **{check-circle}** Yes | Integer | `0`, `1`, `2`, `3`, `4`, `5` | -| [eslint](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Unknown` | -| [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) | **{check-circle}** Yes | Integer | `1`, `2`, `3`, `11`, `12`, `18` | -| [gosec](https://gitlab.com/gitlab-org/security-products/analyzers/gosec) | **{check-circle}** Yes | String | `HIGH`, `MEDIUM`, `LOW` | -| [bandit](https://gitlab.com/gitlab-org/security-products/analyzers/bandit) | **{check-circle}** Yes | String | `HIGH`, `MEDIUM`, `LOW` | -| [phpcs-security-audit](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit) | **{check-circle}** Yes | String | `ERROR`, `WARNING` | -| [pmd-apex](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) | **{check-circle}** Yes | Integer | `1`, `2`, `3`, `4`, `5` | -| [kubesec](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec) | **{check-circle}** Yes | String | `CriticalSeverity`, `InfoSeverity` | -| [secrets](https://gitlab.com/gitlab-org/security-products/analyzers/secrets) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Critical` | +| [`security-code-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) | **{dotted-circle}** No | N/A | N/A | +| [`brakeman`](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) | **{dotted-circle}** No | N/A | N/A | +| [`sobelow`](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Unknown` | +| [`nodejs-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan) | **{check-circle}** Yes | String | `INFO`, `WARNING`, `ERROR` | +| [`flawfinder`](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder) | **{check-circle}** Yes | Integer | `0`, `1`, `2`, `3`, `4`, `5` | +| [`eslint`](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Unknown` | +| [`SpotBugs`](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) | **{check-circle}** Yes | Integer | `1`, `2`, `3`, `11`, `12`, `18` | +| [`gosec`](https://gitlab.com/gitlab-org/security-products/analyzers/gosec) | **{check-circle}** Yes | String | `HIGH`, `MEDIUM`, `LOW` | +| [`bandit`](https://gitlab.com/gitlab-org/security-products/analyzers/bandit) | **{check-circle}** Yes | String | `HIGH`, `MEDIUM`, `LOW` | +| [`phpcs-security-audit`](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit) | **{check-circle}** Yes | String | `ERROR`, `WARNING` | +| [`pmd-apex`](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) | **{check-circle}** Yes | Integer | `1`, `2`, `3`, `4`, `5` | +| [`kubesec`](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec) | **{check-circle}** Yes | String | `CriticalSeverity`, `InfoSeverity` | +| [`secrets`](https://gitlab.com/gitlab-org/security-products/analyzers/secrets) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Critical` | ## Dependency Scanning | GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example | |------------------------------------------------------------------------------------------|------------------------------|----------------------------|-------------------------------------| -| [bundler-audit](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit) | **{check-circle}** Yes | String | `low`, `medium`, `high`, `critical` | -| [retire.js](https://gitlab.com/gitlab-org/security-products/analyzers/retire.js) | **{check-circle}** Yes | String | `low`, `medium`, `high`, `critical` | -| [gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | **{check-circle}** Yes | CVSS v2.0 Rating and CVSS v3.1 Qualitative Severity Rating | `(AV:N/AC:L/Au:S/C:P/I:P/A:N)`, `CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:H` | +| [`bundler-audit`](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit) | **{check-circle}** Yes | String | `low`, `medium`, `high`, `critical` | +| [`retire.js`](https://gitlab.com/gitlab-org/security-products/analyzers/retire.js) | **{check-circle}** Yes | String | `low`, `medium`, `high`, `critical` | +| [`gemnasium`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | **{check-circle}** Yes | CVSS v2.0 Rating and CVSS v3.1 Qualitative Severity Rating | `(AV:N/AC:L/Au:S/C:P/I:P/A:N)`, `CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:C/C:H/I:H/A:H` | ## Container Scanning | GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example | |------------------------------------------------------------------------|--------------------------|----------------------------|--------------------------------------------------------------| -| [klar](https://gitlab.com/gitlab-org/security-products/analyzers/klar) | **{check-circle}** Yes | String | `Negligible`, `Low`, `Medium`, `High`, `Critical`, `Defcon1` | +| [`klar`](https://gitlab.com/gitlab-org/security-products/analyzers/klar) | **{check-circle}** Yes | String | `Negligible`, `Low`, `Medium`, `High`, `Critical`, `Defcon1` | ## Fuzz Testing diff --git a/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v13_9.png b/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v13_9.png Binary files differnew file mode 100644 index 00000000000..72443180e09 --- /dev/null +++ b/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v13_9.png diff --git a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_dismissal_v13_9.png b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_dismissal_v13_9.png Binary files differnew file mode 100644 index 00000000000..ef96cf31fa4 --- /dev/null +++ b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_dismissal_v13_9.png diff --git a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_v13_9.png b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_v13_9.png Binary files differnew file mode 100644 index 00000000000..83e67a24b78 --- /dev/null +++ b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_v13_9.png diff --git a/doc/user/application_security/security_dashboard/img/vulnerability_details_create_issue_v13_7.png b/doc/user/application_security/vulnerability_report/img/vulnerability_details_create_issue_v13_7.png Binary files differindex 5184ad85fa9..5184ad85fa9 100644 --- a/doc/user/application_security/security_dashboard/img/vulnerability_details_create_issue_v13_7.png +++ b/doc/user/application_security/vulnerability_report/img/vulnerability_details_create_issue_v13_7.png diff --git a/doc/user/application_security/vulnerability_report/img/vulnerability_list_table_v13_9.png b/doc/user/application_security/vulnerability_report/img/vulnerability_list_table_v13_9.png Binary files differnew file mode 100644 index 00000000000..bfde7cd6c80 --- /dev/null +++ b/doc/user/application_security/vulnerability_report/img/vulnerability_list_table_v13_9.png diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md new file mode 100644 index 00000000000..28083e09f1c --- /dev/null +++ b/doc/user/application_security/vulnerability_report/index.md @@ -0,0 +1,95 @@ +--- +type: reference, howto +stage: Secure +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 +--- + +# GitLab Vulnerability Reports **(ULTIMATE)** + +Each vulnerability report contains vulnerabilities from the scans of the most recent branch merged into the default branch. + +The vulnerability reports display the total number of vulnerabilities by severity (for example, +Critical, High, Medium, Low, Info, Unknown). Below this, a table shows each vulnerability's detected date, status, severity, description, identifier, the scanner where it was detected, and activity (including related issues or available solutions). By default, the vulnerability report is filtered to display all detected and confirmed vulnerabilities. + + + +You can filter which vulnerabilities display by: + +| Filter | Available Options | +| --- | --- | +| Status | Detected, Confirmed, Dismissed, Resolved | +| Severity | Critical, High, Medium, Low, Info, Unknown | +| Scanner | [Available Scanners](../index.md#security-scanning-tools) | +| Project | Projects configured in the Security Center settings, or all projects in the group for the group level report. This filter is not displayed on the project level vulnerability report | +| Activity | Vulnerabilities with issues and vulnerabilities that are no longer detected in the default branch | + +The Activity filter behaves differently from the other Vulnerability Report filters. The other filter options all OR together to show results from any vulnerability matching one of the filter criteria. With the Activity filter, the selected values form mutually exclusive sets to allow for precisely locating the desired vulnerability records. Additionally, not all options can be selected in combination. Selection behavior when using the Activity filter: + +| Activity Selection | Results Displayed | +| --- | --- | +| All | Vulnerabilities with any Activity status (same as ignoring this filter). Selecting this will deselect any other Activity filter options. | +| No activity | Only vulnerabilities without either an associated Issue or that are no longer detected. Selecting this will deselect any other Activity filter options. | +| With issues | Only vulnerabilities with one or more associated issues. Does not include vulnerabilities that also are no longer detected. | +| No longer detected | Only vulnerabilities that are no longer detected in the latest pipeline scan of the `default` branch. Does not include vulnerabilities with one or more associated issues. | +| With issues and No longer detected | Only vulnerabilities that have one or more associated issues and also are no longer detected in the latest pipeline scan of the `default` branch. | + +Clicking any vulnerability in the table takes you to its +[vulnerability details](../vulnerabilities) page to see more information on that 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. + + + +Contents of the unfiltered vulnerability report can be exported using our [export feature](#export-vulnerabilities). + +You can also dismiss vulnerabilities in the table: + +1. Select the checkbox for each vulnerability you want to dismiss. +1. In the menu that appears, select the reason for dismissal and click **Dismiss Selected**. + + + +## Project Vulnerability Report + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6165) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.1. + +The vulnerabilities that exist in your project's +[default branch](../../project/repository/branches/index.md#default-branch) are accessed by navigating to +**Security & Compliance > Vulnerability Report**. + +The project vulnerability report first displays the time at which the last pipeline completed on the project's +default branch. There's also a link to view this in more detail. In the case of any pipeline failures, +the number of failures is indicated. The failure notification takes you directly to +the **Failed jobs** tab of the pipeline page. + + + +## Export vulnerabilities + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213014) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. + +You can export all your vulnerabilities in CSV (comma separated values) format by clicking the +**{upload}** **Export** button located at top right of the Security Dashboard. When the report is +ready, the CSV report downloads to your local machine. The report contains all vulnerabilities for +the projects defined in the Security Dashboard, as filters don't apply to the export function. + +NOTE: +It may take several minutes for the download to start if your project contains +thousands of vulnerabilities. Don't close the page until the download finishes. + +The fields in the export include: + +- Group Name +- Project Name +- Scanner Type +- Scanner Name +- Status +- Vulnerability +- Details +- Additional Information +- Severity +- [CVE](https://cve.mitre.org/) (Common Vulnerabilities and Exposures) +- [CWE](https://cwe.mitre.org/) (Common Weakness Enumeration) +- Other Identifiers diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index 546746af535..07593c98da9 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# AsciiDoc +# AsciiDoc **(FREE)** GitLab uses the [Asciidoctor](https://asciidoctor.org) gem to convert AsciiDoc content to HTML5. Consult the [Asciidoctor User Manual](https://asciidoctor.org/docs/user-manual/) for a complete Asciidoctor reference. @@ -40,7 +40,7 @@ Notice how line breaks are now preserved. An indented (literal) paragraph disables text formatting, preserves spaces and line breaks, and is displayed in a -monospaced font: +fixed-width font: ```plaintext This literal paragraph is indented with one space. @@ -186,8 +186,12 @@ Attach a block or paragraph to a list item using a list continuation (which you * [ ] not checked ``` +<!-- vale gitlab.Spelling = NO --> + #### Callout +<!-- vale gitlab.Spelling = YES --> + ```plaintext // enable callout bubbles by adding `:icons: font` to the document header [,ruby] diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md index 4ece94447bc..de250bc5fb4 100644 --- a/doc/user/award_emojis.md +++ b/doc/user/award_emojis.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Award emoji **(CORE)** +# Award emoji **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/1825) in GitLab 8.2. > - GitLab 9.0 [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9570) the usage of native emoji if the platform diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 2c0d9b6c9ce..6f3d1e197f5 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Kubernetes Agent **(PREMIUM ONLY)** +# GitLab Kubernetes Agent **(PREMIUM SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. > - It's disabled on GitLab.com. Rolling this feature out to GitLab.com is [planned](https://gitlab.com/groups/gitlab-org/-/epics/3834). @@ -190,7 +190,7 @@ the Agent in subsequent steps. You can create an Agent record either: For full details, read [Starting a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session). -- Through GraphQL: **(PREMIUM ONLY)** +- Through GraphQL: **(PREMIUM SELF)** ```graphql mutation createAgent { @@ -439,49 +439,23 @@ The following example projects can help you get started with the Kubernetes Agen - [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent) - This basic GitOps example deploys NGINX: [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) -- [Install GitLab Runner](runner.md) ### Deploying GitLab Runner with the Agent -These instructions assume that the Agent is already set up as described in the -[Get started with GitOps](#get-started-with-gitops-and-the-gitlab-agent): +You can use the Kubernetes Agent to +[deploy GitLab Runner in a Kubernetes cluster](http://docs.gitlab.com/runner/install/kubernetes-agent.html). -1. Check the possible - [Runner chart YAML values](https://gitlab.com/gitlab-org/charts/gitlab-runner/blob/master/values.yaml) - on the Runner chart documentation, and create a `runner-chart-values.yaml` file - with the configuration that fits your needs, such as: +## Management interfaces - ```yaml - ## The GitLab Server URL (with protocol) that want to register the runner against - ## ref: https://docs.gitlab.com/runner/commands/README.html#gitlab-runner-register - ## - gitlabUrl: https://gitlab.my.domain.com/ +Users with at least the [Developer](../../permissions.md) can access the user interface +for the GitLab Kubernetes agent at **Operations > Kubernetes** and selecting the +**GitLab Agent managed clusters** tab. This page lists all registered agents for +the current project, and the configuration directory for each agent: - ## The Registration Token for adding new Runners to the GitLab Server. This must - ## be retrieved from your GitLab Instance. - ## ref: https://docs.gitlab.com/ce/ci/runners/README.html - ## - runnerRegistrationToken: "XXXXXXYYYYYYZZZZZZ" + - ## For RBAC support: - rbac: - create: true - - ## Run all containers with the privileged flag enabled - ## This will allow the docker:dind image to run if you need to run Docker - ## commands. Please read the docs before turning this on: - ## ref: https://docs.gitlab.com/runner/executors/kubernetes.html#using-dockerdind - runners: - privileged: true - ``` - -1. Create a single manifest file to install the Runner chart with your cluster agent: - - ```shell - helm template --namespace gitlab gitlab-runner -f runner-chart-values.yaml gitlab/gitlab-runner > manifest.yaml - ``` - -1. Push your `manifest.yaml` to your manifest repository. +Additional management interfaces are planned for the GitLab Kubernetes Agent. +[Provide more feedback in the related epic](https://gitlab.com/groups/gitlab-org/-/epics/4739). ## Troubleshooting diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index b71bbc29ef9..60d8cd352fc 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Kubernetes Agent configuration repository **(PREMIUM ONLY)** +# Kubernetes Agent configuration repository **(PREMIUM SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. > - It's disabled on GitLab.com. Rolling this feature out to GitLab.com is [planned](https://gitlab.com/groups/gitlab-org/-/epics/3834). diff --git a/doc/user/clusters/agent/runner.md b/doc/user/clusters/agent/runner.md index 715b27f951a..bbf07d4ea84 100644 --- a/doc/user/clusters/agent/runner.md +++ b/doc/user/clusters/agent/runner.md @@ -1,452 +1,8 @@ --- -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 +redirect_to: 'https://docs.gitlab.com/runner/install/kubernetes-agent.html' --- -# Install GitLab Runner with Kubernetes Agent **(PREMIUM ONLY)** +This document was moved to [another location](https://docs.gitlab.com/runner/install/kubernetes-agent.html). -These instructions to install the GitLab Runner assume the -[GitLab Kubernetes Agent](index.md) is already configured. - -1. Review the possible [Runner chart YAML values](https://gitlab.com/gitlab-org/charts/gitlab-runner/blob/master/values.yaml) in the Runner chart documentation, - and create a `runner-chart-values.yaml` file with the configuration that fits - your needs, such as: - - ```yaml - # The GitLab Server URL (with protocol) that want to register the runner against - # ref: https://docs.gitlab.com/runner/commands/README.html#gitlab-runner-register - # - gitlabUrl: https://gitlab.my.domain.example.com/ - - # The Registration Token for adding new Runners to the GitLab Server. This must - # be retrieved from your GitLab Instance. - # ref: https://docs.gitlab.com/ce/ci/runners/README.html - # - runnerRegistrationToken: "yrnZW46BrtBFqM7xDzE7dddd" - - # For RBAC support: - rbac: - create: true - - # Run all containers with the privileged flag enabled - # This will allow the docker:dind image to run if you need to run Docker - # commands. Please read the docs before turning this on: - # ref: https://docs.gitlab.com/runner/executors/kubernetes.html#using-dockerdind - runners: - privileged: true - ``` - -1. Create a single manifest file to install the Runner chart with your cluster agent, - replacing `GITLAB GITLAB-RUNNER` with your namespace: - - ```shell - helm template --namespace GITLAB GITLAB-RUNNER -f runner-chart-values.yaml gitlab/gitlab-runner > runner-manifest.yaml - ``` - - An [example file is available](#example-runner-manifest). - -1. Push your `runner-manifest.yaml` to your manifest repository. - -## Example Runner manifest - -```yaml -# This code is an example of a runner manifest looks like. -# Create your own manifest.yaml file to meet your project's needs. - ---- -# Source: gitlab-runner/templates/service-account.yaml -apiVersion: v1 -kind: ServiceAccount -metadata: - annotations: - name: gitlab-runner-gitlab-runner - labels: - app: gitlab-runner-gitlab-runner - chart: gitlab-runner-0.21.1 - release: "gitlab-runner" - heritage: "Helm" ---- -# Source: gitlab-runner/templates/secrets.yaml -apiVersion: v1 -kind: Secret -metadata: - name: "gitlab-runner-gitlab-runner" - labels: - app: gitlab-runner-gitlab-runner - chart: gitlab-runner-0.21.1 - release: "gitlab-runner" - heritage: "Helm" -type: Opaque -data: - runner-registration-token: "FAKE-TOKEN" - runner-token: "" ---- -# Source: gitlab-runner/templates/configmap.yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: gitlab-runner-gitlab-runner - labels: - app: gitlab-runner-gitlab-runner - chart: gitlab-runner-0.21.1 - release: "gitlab-runner" - heritage: "Helm" -data: - entrypoint: | - #!/bin/bash - set -e - mkdir -p /home/gitlab-runner/.gitlab-runner/ - cp /scripts/config.toml /home/gitlab-runner/.gitlab-runner/ - - # Register the runner - if [[ -f /secrets/accesskey && -f /secrets/secretkey ]]; then - export CACHE_S3_ACCESS_KEY=$(cat /secrets/accesskey) - export CACHE_S3_SECRET_KEY=$(cat /secrets/secretkey) - fi - - if [[ -f /secrets/gcs-applicaton-credentials-file ]]; then - export GOOGLE_APPLICATION_CREDENTIALS="/secrets/gcs-applicaton-credentials-file" - elif [[ -f /secrets/gcs-application-credentials-file ]]; then - export GOOGLE_APPLICATION_CREDENTIALS="/secrets/gcs-application-credentials-file" - else - if [[ -f /secrets/gcs-access-id && -f /secrets/gcs-private-key ]]; then - export CACHE_GCS_ACCESS_ID=$(cat /secrets/gcs-access-id) - # echo -e used to make private key multiline (in google json auth key private key is oneline with \n) - export CACHE_GCS_PRIVATE_KEY=$(echo -e $(cat /secrets/gcs-private-key)) - fi - fi - - if [[ -f /secrets/runner-registration-token ]]; then - export REGISTRATION_TOKEN=$(cat /secrets/runner-registration-token) - fi - - if [[ -f /secrets/runner-token ]]; then - export CI_SERVER_TOKEN=$(cat /secrets/runner-token) - fi - - if ! sh /scripts/register-the-runner; then - exit 1 - fi - - # Run pre-entrypoint-script - if ! bash /scripts/pre-entrypoint-script; then - exit 1 - fi - - # Start the runner - exec /entrypoint run --user=gitlab-runner \ - --working-directory=/home/gitlab-runner - - config.toml: | - concurrent = 10 - check_interval = 30 - log_level = "info" - listen_address = ':9252' - configure: | - set -e - cp /init-secrets/* /secrets - register-the-runner: | - #!/bin/bash - MAX_REGISTER_ATTEMPTS=30 - - for i in $(seq 1 "${MAX_REGISTER_ATTEMPTS}"); do - echo "Registration attempt ${i} of ${MAX_REGISTER_ATTEMPTS}" - /entrypoint register \ - --non-interactive - - retval=$? - - if [ ${retval} = 0 ]; then - break - elif [ ${i} = ${MAX_REGISTER_ATTEMPTS} ]; then - exit 1 - fi - - sleep 5 - done - - exit 0 - - check-live: | - #!/bin/bash - if /usr/bin/pgrep -f .*register-the-runner; then - exit 0 - elif /usr/bin/pgrep gitlab.*runner; then - exit 0 - else - exit 1 - fi - - pre-entrypoint-script: | ---- -# Source: gitlab-runner/templates/role.yaml -apiVersion: rbac.authorization.k8s.io/v1 -kind: "Role" -metadata: - name: gitlab-runner-gitlab-runner - labels: - app: gitlab-runner-gitlab-runner - chart: gitlab-runner-0.21.1 - release: "gitlab-runner" - heritage: "Helm" -rules: -- apiGroups: [""] - resources: ["*"] - verbs: ["*"] ---- -# Source: gitlab-runner/templates/role-binding.yaml -apiVersion: rbac.authorization.k8s.io/v1 -kind: "RoleBinding" -metadata: - name: gitlab-runner-gitlab-runner - labels: - app: gitlab-runner-gitlab-runner - chart: gitlab-runner-0.21.1 - release: "gitlab-runner" - heritage: "Helm" -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: "Role" - name: gitlab-runner-gitlab-runner -subjects: -- kind: ServiceAccount - name: gitlab-runner-gitlab-runner - namespace: "gitlab" ---- -# Source: gitlab-runner/templates/deployment.yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: gitlab-runner-gitlab-runner - labels: - app: gitlab-runner-gitlab-runner - chart: gitlab-runner-0.21.1 - release: "gitlab-runner" - heritage: "Helm" -spec: - replicas: 1 - selector: - matchLabels: - app: gitlab-runner-gitlab-runner - template: - metadata: - labels: - app: gitlab-runner-gitlab-runner - chart: gitlab-runner-0.21.1 - release: "gitlab-runner" - heritage: "Helm" - annotations: - checksum/configmap: a6623303f6fcc3a043e87ea937bb8399d2d0068a901aa9c3419ed5c7a5afa9db - checksum/secrets: 32c7d2c16918961b7b84a005680f748e774f61c6f4e4da30650d400d781bbb30 - prometheus.io/scrape: 'true' - prometheus.io/port: '9252' - spec: - securityContext: - runAsUser: 100 - fsGroup: 65533 - terminationGracePeriodSeconds: 3600 - initContainers: - - name: configure - command: ['sh', '/config/configure'] - image: gitlab/gitlab-runner:alpine-v13.4.1 - imagePullPolicy: "IfNotPresent" - env: - - - name: CI_SERVER_URL - value: "https://gitlab.qa.joaocunha.eu/" - - name: CLONE_URL - value: "" - - name: RUNNER_REQUEST_CONCURRENCY - value: "1" - - name: RUNNER_EXECUTOR - value: "kubernetes" - - name: REGISTER_LOCKED - value: "true" - - name: RUNNER_TAG_LIST - value: "" - - name: RUNNER_OUTPUT_LIMIT - value: "4096" - - name: KUBERNETES_IMAGE - value: "ubuntu:16.04" - - - name: KUBERNETES_PRIVILEGED - value: "true" - - - name: KUBERNETES_NAMESPACE - value: "gitlab" - - name: KUBERNETES_POLL_TIMEOUT - value: "180" - - name: KUBERNETES_CPU_LIMIT - value: "" - - name: KUBERNETES_CPU_LIMIT_OVERWRITE_MAX_ALLOWED - value: "" - - name: KUBERNETES_MEMORY_LIMIT - value: "" - - name: KUBERNETES_MEMORY_LIMIT_OVERWRITE_MAX_ALLOWED - value: "" - - name: KUBERNETES_CPU_REQUEST - value: "" - - name: KUBERNETES_CPU_REQUEST_OVERWRITE_MAX_ALLOWED - value: "" - - name: KUBERNETES_MEMORY_REQUEST - value: "" - - name: KUBERNETES_MEMORY_REQUEST_OVERWRITE_MAX_ALLOWED - value: "" - - name: KUBERNETES_SERVICE_ACCOUNT - value: "" - - name: KUBERNETES_SERVICE_CPU_LIMIT - value: "" - - name: KUBERNETES_SERVICE_MEMORY_LIMIT - value: "" - - name: KUBERNETES_SERVICE_CPU_REQUEST - value: "" - - name: KUBERNETES_SERVICE_MEMORY_REQUEST - value: "" - - name: KUBERNETES_HELPER_CPU_LIMIT - value: "" - - name: KUBERNETES_HELPER_MEMORY_LIMIT - value: "" - - name: KUBERNETES_HELPER_CPU_REQUEST - value: "" - - name: KUBERNETES_HELPER_MEMORY_REQUEST - value: "" - - name: KUBERNETES_HELPER_IMAGE - value: "" - - name: KUBERNETES_PULL_POLICY - value: "" - volumeMounts: - - name: runner-secrets - mountPath: /secrets - readOnly: false - - name: scripts - mountPath: /config - readOnly: true - - name: init-runner-secrets - mountPath: /init-secrets - readOnly: true - resources: - {} - serviceAccountName: gitlab-runner-gitlab-runner - containers: - - name: gitlab-runner-gitlab-runner - image: gitlab/gitlab-runner:alpine-v13.4.1 - imagePullPolicy: "IfNotPresent" - lifecycle: - preStop: - exec: - command: ["/entrypoint", "unregister", "--all-runners"] - command: ["/bin/bash", "/scripts/entrypoint"] - env: - - - name: CI_SERVER_URL - value: "https://gitlab.qa.joaocunha.eu/" - - name: CLONE_URL - value: "" - - name: RUNNER_REQUEST_CONCURRENCY - value: "1" - - name: RUNNER_EXECUTOR - value: "kubernetes" - - name: REGISTER_LOCKED - value: "true" - - name: RUNNER_TAG_LIST - value: "" - - name: RUNNER_OUTPUT_LIMIT - value: "4096" - - name: KUBERNETES_IMAGE - value: "ubuntu:16.04" - - - name: KUBERNETES_PRIVILEGED - value: "true" - - - name: KUBERNETES_NAMESPACE - value: "gitlab" - - name: KUBERNETES_POLL_TIMEOUT - value: "180" - - name: KUBERNETES_CPU_LIMIT - value: "" - - name: KUBERNETES_CPU_LIMIT_OVERWRITE_MAX_ALLOWED - value: "" - - name: KUBERNETES_MEMORY_LIMIT - value: "" - - name: KUBERNETES_MEMORY_LIMIT_OVERWRITE_MAX_ALLOWED - value: "" - - name: KUBERNETES_CPU_REQUEST - value: "" - - name: KUBERNETES_CPU_REQUEST_OVERWRITE_MAX_ALLOWED - value: "" - - name: KUBERNETES_MEMORY_REQUEST - value: "" - - name: KUBERNETES_MEMORY_REQUEST_OVERWRITE_MAX_ALLOWED - value: "" - - name: KUBERNETES_SERVICE_ACCOUNT - value: "" - - name: KUBERNETES_SERVICE_CPU_LIMIT - value: "" - - name: KUBERNETES_SERVICE_MEMORY_LIMIT - value: "" - - name: KUBERNETES_SERVICE_CPU_REQUEST - value: "" - - name: KUBERNETES_SERVICE_MEMORY_REQUEST - value: "" - - name: KUBERNETES_HELPER_CPU_LIMIT - value: "" - - name: KUBERNETES_HELPER_MEMORY_LIMIT - value: "" - - name: KUBERNETES_HELPER_CPU_REQUEST - value: "" - - name: KUBERNETES_HELPER_MEMORY_REQUEST - value: "" - - name: KUBERNETES_HELPER_IMAGE - value: "" - - name: KUBERNETES_PULL_POLICY - value: "" - livenessProbe: - exec: - command: ["/bin/bash", "/scripts/check-live"] - initialDelaySeconds: 60 - timeoutSeconds: 1 - periodSeconds: 10 - successThreshold: 1 - failureThreshold: 3 - readinessProbe: - exec: - command: ["/usr/bin/pgrep","gitlab.*runner"] - initialDelaySeconds: 10 - timeoutSeconds: 1 - periodSeconds: 10 - successThreshold: 1 - failureThreshold: 3 - ports: - - name: metrics - containerPort: 9252 - volumeMounts: - - name: runner-secrets - mountPath: /secrets - - name: etc-gitlab-runner - mountPath: /home/gitlab-runner/.gitlab-runner - - name: scripts - mountPath: /scripts - resources: - {} - volumes: - - name: runner-secrets - emptyDir: - medium: "Memory" - - name: etc-gitlab-runner - emptyDir: - medium: "Memory" - - name: init-runner-secrets - projected: - sources: - - secret: - name: "gitlab-runner-gitlab-runner" - items: - - key: runner-registration-token - path: runner-registration-token - - key: runner-token - path: runner-token - - name: scripts - configMap: - name: gitlab-runner-gitlab-runner -``` +<!-- This redirect file can be deleted after <2022-02-01>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
\ No newline at end of file diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index b03dfb79ae0..ad92cf9b4ed 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Managed Apps +# GitLab Managed Apps **(FREE)** GitLab provides **GitLab Managed Apps** for various applications which can be added directly to your configured cluster. These @@ -20,10 +20,9 @@ have been deprecated, and are scheduled for removal in GitLab 14.0. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20822) in GitLab 12.6. WARNING: -This is an _alpha_ feature, and is subject to change at any time without -prior notice. +This is a _beta_ feature, and some applications might miss features to provide full integration with GitLab. -This alternative method allows users to install GitLab-managed +This primary method for installing applications to clusters allows users to install GitLab-managed applications using GitLab CI/CD. It also allows customization of the install using Helm `values.yaml` files. @@ -418,6 +417,8 @@ You can check the recommended variables for each cluster type in the official do - [Google GKE](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-gke/#deploy-cilium) - [AWS EKS](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-eks/#deploy-cilium) +Do not use `clusterType` for sandbox environments like [Minikube](https://minikube.sigs.k8s.io/docs/). + You can customize Cilium's Helm variables by defining the `.gitlab/managed-apps/cilium/values.yaml` file in your cluster management project. Refer to the @@ -1199,53 +1200,8 @@ determine the endpoint of your Ingress or Knative application, you can #### Determining the external endpoint manually -If the cluster is on GKE, click the **Google Kubernetes Engine** link in the -**Advanced settings**, or go directly to the -[Google Kubernetes Engine dashboard](https://console.cloud.google.com/kubernetes/) -and select the proper project and cluster. Then click **Connect** and execute -the `gcloud` command in a local terminal or using the **Cloud Shell**. - -If the cluster is not on GKE, follow the specific instructions for your -Kubernetes provider to configure `kubectl` with the right credentials. -The output of the following examples show the external endpoint of your -cluster. This information can then be used to set up DNS entries and forwarding -rules that allow external access to your deployed applications. - -- If you installed Ingress using the **Applications**, run the following - command: - - ```shell - kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' - ``` - -- Some Kubernetes clusters return a hostname instead, like - [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: - - ```shell - kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' - ``` - - If EKS is used, an [Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/) - is also created, which incurs additional AWS costs. - -- For Istio/Knative, the command is different: - - ```shell - kubectl get svc --namespace=istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' - ``` - -- Otherwise, you can list the IP addresses of all load balancers: - - ```shell - kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' - ``` - -You may see a trailing `%` on some Kubernetes versions. Do not include it. - -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, create -a wildcard DNS CNAME record for the desired domain name. For example, -`*.myekscluster.com` would point to the Ingress hostname obtained earlier. +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 diff --git a/doc/user/clusters/crossplane.md b/doc/user/clusters/crossplane.md index c1ef798f5a8..bdf9d582b93 100644 --- a/doc/user/clusters/crossplane.md +++ b/doc/user/clusters/crossplane.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Crossplane configuration +# Crossplane configuration **(FREE)** After [installing](applications.md#crossplane) Crossplane, you must configure it for use. The process of configuring Crossplane includes: diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index be4ac8151e4..cb721115e76 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Cluster Environments **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13392) for group-level clusters in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14809) for instance-level clusters in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13392) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3 for group-level clusters. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14809) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4 for instance-level clusters. Cluster environments provide a consolidated view of which CI [environments](../../ci/environments/index.md) are deployed to the Kubernetes cluster and it: @@ -38,7 +38,7 @@ In order to: - Show pod usage correctly, you must [enable Deploy Boards](../project/deploy_boards.md#enabling-deploy-boards). -Once you have successful deployments to your group-level or instance-level cluster: +After you have successful deployments to your group-level or instance-level cluster: 1. Navigate to your group's **Kubernetes** page. 1. Click on the **Environments** tab. diff --git a/doc/user/clusters/img/kubernetes-agent-ui-list_v13_8.png b/doc/user/clusters/img/kubernetes-agent-ui-list_v13_8.png Binary files differnew file mode 100644 index 00000000000..3f9cc41838a --- /dev/null +++ b/doc/user/clusters/img/kubernetes-agent-ui-list_v13_8.png diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index 55f507fb318..ef1b3ce44f2 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Cluster management project +# Cluster management project **(FREE)** WARNING: This is an _alpha_ feature, and it is subject to change at any time without diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 1428a0d4e80..74c608fcc38 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -58,7 +58,7 @@ Java 8 and Gradle 1.x projects are not supported. The minimum supported version | JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/) | | | Go | [Godep](https://github.com/tools/godep), [go mod](https://github.com/golang/go/wiki/Modules) | | | Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | | -| .NET | [Nuget](https://www.nuget.org/) | The .NET Framework is supported via the [mono project](https://www.mono-project.com/). There are, however, some limitations. The scanner doesn't support Windows-specific dependencies and doesn't report dependencies of your project's listed dependencies. Also, the scanner always marks detected licenses for all dependencies as `unknown`. | +| .NET | [NuGet](https://www.nuget.org/) | The .NET Framework is supported via the [mono project](https://www.mono-project.com/). There are, however, some limitations. The scanner doesn't support Windows-specific dependencies and doesn't report dependencies of your project's listed dependencies. Also, the scanner always marks detected licenses for all dependencies as `unknown`. | | Python | [pip](https://pip.pypa.io/en/stable/) | Python is supported through [requirements.txt](https://pip.pypa.io/en/stable/user_guide/#requirements-files) and [Pipfile.lock](https://github.com/pypa/pipfile#pipfilelock). | | Ruby | [gem](https://rubygems.org/) | | @@ -70,7 +70,7 @@ The reported licenses might be incomplete or inaccurate. | Language | Package managers | |------------|---------------------------------------------------------------------------------------------------------------| | JavaScript | [Yarn](https://yarnpkg.com/) | -| Go | go get, gvt, glide, dep, trash, govendor | +| Go | `go get`, `gvt`, `glide`, `dep`, `trash`, `govendor` | | Erlang | [Rebar](https://www.rebar3.org/) | | Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage), [CocoaPods](https://cocoapods.org/) v0.39 and below | | Elixir | [Mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) | @@ -118,7 +118,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 [environment variables](#available-variables) by using the +The License Compliance settings can be changed through [CI/CD variables](#available-variables) by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. ### When License Compliance runs @@ -128,20 +128,20 @@ wait for other stages to complete. ### Available variables -License Compliance can be configured using environment variables. +License Compliance can be configured using CI/CD variables. -| Environment variable | Required | Description | +| CI/CD variable | Required | Description | |-----------------------------|----------|-------------| -| `ADDITIONAL_CA_CERT_BUNDLE` | no | Bundle of trusted CA certificates (currently supported in Pip, Pipenv, Maven, Gradle, Yarn, and NPM projects). | +| `ADDITIONAL_CA_CERT_BUNDLE` | no | Bundle of trusted CA certificates (currently supported in Pip, Pipenv, Maven, Gradle, Yarn, and npm projects). | | `ASDF_JAVA_VERSION` | no | Version of Java to use for the scan. | | `ASDF_NODEJS_VERSION` | no | Version of Node.js to use for the scan. | | `ASDF_PYTHON_VERSION` | no | Version of Python to use for the scan. | | `ASDF_RUBY_VERSION` | no | Version of Ruby to use for the scan. | -| `GRADLE_CLI_OPTS` | no | Additional arguments for the gradle executable. If not supplied, defaults to `--exclude-task=test`. | +| `GRADLE_CLI_OPTS` | no | Additional arguments for the Gradle executable. If not supplied, defaults to `--exclude-task=test`. | | `LICENSE_FINDER_CLI_OPTS` | no | Additional arguments for the `license_finder` executable. For example, if you have multiple projects in nested directories, you can update your `.gitlab-ci-yml` template to specify a recursive scan, like `LICENSE_FINDER_CLI_OPTS: '--recursive'`. | | `LM_JAVA_VERSION` | no | Version of Java. If set to `11`, Maven and Gradle use Java 11 instead of Java 8. | | `LM_PYTHON_VERSION` | no | Version of Python. If set to `3`, dependencies are installed using Python 3 instead of Python 2.7. | -| `MAVEN_CLI_OPTS` | no | Additional arguments for the mvn executable. If not supplied, defaults to `-DskipTests`. | +| `MAVEN_CLI_OPTS` | no | Additional arguments for the `mvn` executable. If not supplied, defaults to `-DskipTests`. | | `PIP_INDEX_URL` | no | Base URL of Python Package Index (default: `https://pypi.org/simple/`). | | `SECURE_ANALYZERS_PREFIX` | no | Set the Docker registry base address to download the analyzer from. | | `SETUP_CMD` | no | Custom setup for the dependency installation (experimental). | @@ -154,7 +154,7 @@ The `license_management` image already embeds many auto-detection scripts, langu 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. -For that, a `LICENSE_MANAGEMENT_SETUP_CMD` environment variable can be passed to the container, +For that, a `LICENSE_MANAGEMENT_SETUP_CMD` CI/CD variable can be passed to the container, with the required commands to run before the license detection. If present, this variable overrides the setup step necessary to install all the packages @@ -195,7 +195,7 @@ license_scanning: ### Configuring Maven projects -The License Compliance tool provides a `MAVEN_CLI_OPTS` environment variable which can hold +The License Compliance tool provides a `MAVEN_CLI_OPTS` CI/CD variable which can hold the command line arguments to pass to the `mvn install` command which is executed under the hood. Feel free to use it for the customization of Maven execution. For example: @@ -217,12 +217,12 @@ to explicitly add `-DskipTests` to your options. If you still need to run tests during `mvn install`, add `-DskipTests=false` to `MAVEN_CLI_OPTS`. -#### Using private Maven repos +#### Using private Maven repositories If you have a private Maven repository which requires login credentials, -you can use the `MAVEN_CLI_OPTS` environment variable. +you can use the `MAVEN_CLI_OPTS` CI/CD variable. -Read more on [how to use private Maven repos](../../application_security/index.md#using-private-maven-repos). +Read more on [how to use private Maven repositories](../../application_security/index.md#using-private-maven-repositories). You can also use `MAVEN_CLI_OPTS` to connect to a trusted Maven repository that uses a self-signed or internally trusted certificate. For example: @@ -248,7 +248,7 @@ generate a key store file, see the License Compliance uses Python 3.8 and pip 19.1 by default. If your project requires Python 2, you can switch to Python 2.7 and pip 10.0 -by setting the `LM_PYTHON_VERSION` environment variable to `2`. +by setting the `LM_PYTHON_VERSION` CI/CD variable to `2`. ```yaml include: @@ -262,21 +262,21 @@ 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` [environment variable](#available-variables). +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables). -#### Using private Python repos +#### Using private Python repositories -If you have a private Python repository you can use the `PIP_INDEX_URL` [environment variable](#available-variables) +If you have a private Python repository you can use the `PIP_INDEX_URL` [CI/CD variable](#available-variables) to specify its location. -### Configuring NPM projects +### Configuring npm projects -You can configure NPM projects by using an [`.npmrc`](https://docs.npmjs.com/configuring-npm/npmrc.html/) +You can configure npm projects by using an [`.npmrc`](https://docs.npmjs.com/configuring-npm/npmrc.html/) file. -#### Using private NPM registries +#### Using private npm registries -If you have a private NPM registry you can use the +If you have a private npm registry you can use the [`registry`](https://docs.npmjs.com/using-npm/config/#registry) setting to specify its location. @@ -286,10 +286,10 @@ For example: registry = https://npm.example.com ``` -#### Custom root certificates for NPM +#### Custom root certificates for npm You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables). +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables). To disable TLS verification you can provide the [`strict-ssl`](https://docs.npmjs.com/using-npm/config/#strict-ssl) setting. @@ -320,7 +320,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` [environment variable](#available-variables). +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables). ### Configuring Bower projects @@ -344,7 +344,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` [environment variable](#available-variables), or by +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables), or by specifying a `ca` setting in a [`.bowerrc`](https://bower.io/docs/config/#bowerrc-specification) file. @@ -365,9 +365,9 @@ 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` [environment variable](#available-variables), or by +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables), or by specifying a [`BUNDLE_SSL_CA_CERT`](https://bundler.io/v2.0/man/bundle-config.1.html) -[environment variable](../../../ci/variables/README.md#custom-environment-variables) +[variable](../../../ci/variables/README.md#custom-cicd-variables) in the job definition. ### Configuring Cargo projects @@ -389,9 +389,9 @@ 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` [environment variable](#available-variables). +- Use the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables). - Specify a [`CARGO_HTTP_CAINFO`](https://doc.rust-lang.org/cargo/reference/environment-variables.html) - [environment variable](../../../ci/variables/README.md#custom-environment-variables) + [variable](../../../ci/variables/README.md#custom-cicd-variables) in the job definition. ### Configuring Composer projects @@ -422,9 +422,9 @@ 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` [environment variable](#available-variables), or by +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables), or by specifying a [`COMPOSER_CAFILE`](https://getcomposer.org/doc/03-cli.md#composer-cafile) -[environment variable](../../../ci/variables/README.md#custom-environment-variables) +[variable](../../../ci/variables/README.md#custom-cicd-variables) in the job definition. ### Configuring Conan projects @@ -487,7 +487,7 @@ example: } ``` -If credentials are required to authenticate then you can configure a [protected variable](../../../ci/variables/README.md#protect-a-custom-variable) +If credentials are required to authenticate then you can configure a [protected CI/CD variable](../../../ci/variables/README.md#protect-a-custom-variable) following the naming convention described in the [`CONAN_LOGIN_USERNAME` documentation](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name). #### Custom root certificates for Conan @@ -496,14 +496,14 @@ 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` [environment variable](#available-variables), this +If you specify the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-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`. ### Configuring Go projects To configure [Go modules](https://github.com/golang/go/wiki/Modules) -based projects, specify [environment variables](https://golang.org/pkg/cmd/go/#hdr-Environment_variables) +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`. If a project has [vendored](https://golang.org/pkg/cmd/go/#hdr-Vendor_Directories) its modules, @@ -553,18 +553,18 @@ 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` [environment variable](#available-variables). +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables). ### Migration from `license_management` to `license_scanning` 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 -to update your CI config accordingly: +to update your CI configuration accordingly: 1. Change the CI template to `License-Scanning.gitlab-ci.yml`. 1. Change the job name to `license_scanning` (if you mention it in `.gitlab-ci.yml`). -1. Change the artifact name to `license_scanning`, and the file name to `gl-license-scanning-report.json` (if you mention it in `.gitlab-ci.yml`). +1. Change the artifact name to `license_scanning`, and the filename to `gl-license-scanning-report.json` (if you mention it in `.gitlab-ci.yml`). For example, the following `.gitlab-ci.yml`: @@ -640,7 +640,7 @@ For details on saving and transporting Docker images as a file, see Docker's doc [`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/), [`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/). -### Set License Compliance CI job variables to use local License Compliance analyzers +### Set License Compliance CI/CD variables to use local License Compliance analyzers Add the following configuration to your `.gitlab-ci.yml` file. You must replace `image` to refer to the License Compliance Docker image hosted on your local Docker container registry: @@ -657,15 +657,16 @@ license_scanning: The License Compliance job should now use local copies of the License Compliance analyzers to scan your code and generate security reports, without requiring internet access. -Additional configuration may be needed for connecting to -[private Bower registries](#using-private-bower-registries), -[private Bundler registries](#using-private-bundler-registries), -[private Conan registries](#using-private-bower-registries), -[private Go registries](#using-private-go-registries), -[private Maven repositories](#using-private-maven-repos), -[private NPM registries](#using-private-npm-registries), -[private Python repositories](#using-private-python-repos), -and [private Yarn registries](#using-private-yarn-registries). +Additional configuration may be needed for connecting to private registries for: + +- [Bower](#using-private-bower-registries), +- [Bundler](#using-private-bundler-registries), +- [Conan](#using-private-bower-registries), +- [Go](#using-private-go-registries), +- [Maven repositories](#using-private-maven-repositories), +- [npm](#using-private-npm-registries), +- [Python repositories](#using-private-python-repositories), +- [Yarn](#using-private-yarn-registries). ### SPDX license list name matching @@ -776,7 +777,7 @@ nodejs 12.16.3 ruby 2.7.2 ``` -The next example shows how to activate the same versions of the tools mentioned above by using environment variables defined in your +The next example shows how to activate the same versions of the tools mentioned above by using CI/CD variables defined in your project's `.gitlab-ci.yml` file. ```yaml @@ -789,7 +790,7 @@ license_scanning: ASDF_RUBY_VERSION: '2.7.2' ``` -A full list of variables can be found in [environment variables](#available-variables). +A full list of variables can be found in [CI/CD variables](#available-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/img/apply_suggestion_v12_7.png b/doc/user/discussions/img/apply_suggestion_v12_7.png Binary files differdeleted file mode 100644 index c8c44149fd0..00000000000 --- a/doc/user/discussions/img/apply_suggestion_v12_7.png +++ /dev/null diff --git a/doc/user/discussions/img/apply_suggestion_v13_9.png b/doc/user/discussions/img/apply_suggestion_v13_9.png Binary files differnew file mode 100644 index 00000000000..e27fa629672 --- /dev/null +++ b/doc/user/discussions/img/apply_suggestion_v13_9.png diff --git a/doc/user/discussions/img/confidential_comments_v13_9.png b/doc/user/discussions/img/confidential_comments_v13_9.png Binary files differnew file mode 100644 index 00000000000..b5be5a622a9 --- /dev/null +++ b/doc/user/discussions/img/confidential_comments_v13_9.png diff --git a/doc/user/discussions/img/custom_commit_v13_9.png b/doc/user/discussions/img/custom_commit_v13_9.png Binary files differnew file mode 100644 index 00000000000..170c04542dd --- /dev/null +++ b/doc/user/discussions/img/custom_commit_v13_9.png diff --git a/doc/user/discussions/img/make_suggestion_v12_7.png b/doc/user/discussions/img/make_suggestion_v12_7.png Binary files differdeleted file mode 100644 index 7eb84186b0a..00000000000 --- a/doc/user/discussions/img/make_suggestion_v12_7.png +++ /dev/null diff --git a/doc/user/discussions/img/make_suggestion_v13_9.png b/doc/user/discussions/img/make_suggestion_v13_9.png Binary files differnew file mode 100644 index 00000000000..92d5ba5ddda --- /dev/null +++ b/doc/user/discussions/img/make_suggestion_v13_9.png diff --git a/doc/user/discussions/img/resolve_thread_open_issue.png b/doc/user/discussions/img/resolve_thread_open_issue.png Binary files differdeleted file mode 100644 index 2dd4ea3cb1b..00000000000 --- a/doc/user/discussions/img/resolve_thread_open_issue.png +++ /dev/null diff --git a/doc/user/discussions/img/resolve_thread_open_issue_v13_9.png b/doc/user/discussions/img/resolve_thread_open_issue_v13_9.png Binary files differnew file mode 100644 index 00000000000..8ff0f5e84dd --- /dev/null +++ b/doc/user/discussions/img/resolve_thread_open_issue_v13_9.png diff --git a/doc/user/discussions/img/suggestion_button_v12_7.png b/doc/user/discussions/img/suggestion_button_v12_7.png Binary files differdeleted file mode 100644 index 3b7a4d625a3..00000000000 --- a/doc/user/discussions/img/suggestion_button_v12_7.png +++ /dev/null diff --git a/doc/user/discussions/img/suggestion_button_v13_9.png b/doc/user/discussions/img/suggestion_button_v13_9.png Binary files differnew file mode 100644 index 00000000000..58e0508d8cf --- /dev/null +++ b/doc/user/discussions/img/suggestion_button_v13_9.png diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index bf3e907bd24..9320dbba1b8 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -5,14 +5,14 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Threads +# Threads **(FREE)** -The ability to contribute conversationally is offered throughout GitLab. +GitLab encourages communication through comments, threads, and suggestions. -You can leave a comment in the following places: +For example, you can create a comment in the following places: - Issues -- Epics **(ULTIMATE)** +- Epics - Merge requests - Snippets - Commits @@ -44,7 +44,7 @@ Thread resolution helps keep track of progress during planning or code review. Every standard comment or thread in merge requests, commits, commit diffs, and snippets is initially displayed as unresolved. They can then be individually resolved by anyone with at least Developer access to the project or by the author of the change being reviewed. -If the thread has been resolved and a non-member unresolves their own response, +If the thread has been resolved and a non-member un-resolves their own response, this will also unresolve the discussion thread. If the non-member then resolves this same response, this will resolve the discussion thread. @@ -115,7 +115,7 @@ are resolved](#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolve there will be an **open an issue to resolve them later** link in the merge request widget. - + This will prepare an issue with its content referring to the merge request and the unresolved threads. @@ -161,7 +161,7 @@ box and hit **Save** for the changes to take effect. From now on, you will not be able to merge from the UI until all threads are resolved. - + ### Automatically resolve merge request diff threads when they become outdated @@ -281,10 +281,27 @@ edit existing comments. Non-team members are restricted from adding or editing c Additionally, locked issues and merge requests can not be reopened. +## Confidential Comments + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207473) 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. **(FREE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +When creating a comment, you can decide to make it visible only to the project members (users with Reporter and higher permissions). + +To create a confidential comment, select the **Make this comment confidential** checkbox before you submit it. + + + ## Merge Request Reviews > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/28154) to GitLab Core in 13.1. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/28154) to GitLab Free in 13.1. When looking at a Merge Request diff, you are able to start a review. This allows you to create comments inside a Merge Request that are **only visible to you** until published, @@ -370,13 +387,18 @@ From a merge request's **Discussion** tab, or from an epic/issue overview, find  -Once you select one of the filters in a given issue or MR, GitLab will save +After you select one of the filters in a given issue or MR, GitLab will save your preference, so that it will persist when you visit the same page again from any device you're logged into. ## Suggest Changes -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18008) in GitLab 11.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18008) in GitLab 11.6. +> - Custom commit messages for suggestions was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9. +> - Custom commit messages for suggestions was deployed behind a [feature flag](../feature_flags.md), disabled by default. +> - Custom commit messages for suggestions became enabled by default on GitLab 13.9. +> - Custom commit messages for suggestions is enabled on GitLab.com and is recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disabled it](#enable-or-disable-custom-commit-messages-for-suggestions). **(FREE SELF)** As a reviewer, you're able to suggest code changes with a simple Markdown syntax in Merge Request Diff threads. Then, the @@ -388,20 +410,27 @@ the merge request authored by the user that applied them. 1. Choose a line of code to be changed, add a new comment, then click on the **Insert suggestion** icon in the toolbar: -  +  1. In the comment, add your suggestion to the pre-populated code block: -  +  1. Click either **Start a review** or **Add to review** to add your comment to a [review](#merge-request-reviews), or **Add comment now** to add the comment to the thread immediately. The Suggestion in the comment can be applied by the merge request author directly from the merge request: -  +  + +1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9, + you can opt to add a custom commit message to describe your change. If you don't + specify it, the default commit message will be used. Note that [this feature may not be available to you](#enable-or-disable-custom-commit-messages-for-suggestions). + Also, it is not supported for [batch suggestions](#batch-suggestions). -Once the author applies a Suggestion, it will be marked with the **Applied** label, +  + +After the author applies a Suggestion, it will be marked with the **Applied** label, the thread will be automatically resolved, and GitLab will create a new commit and push the suggested change directly into the codebase in the merge request's branch. [Developer permission](../permissions.md) is required to do so. @@ -501,27 +530,6 @@ to your branch to address your reviewers' requests.  -#### Enable or disable Batch Suggestions **(CORE ONLY)** - -Batch Suggestions is -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can opt to disable it for your instance. - -To enable it: - -```ruby -# Instance-wide -Feature.enable(:batch_suggestions) -``` - -To disable it: - -```ruby -# Instance-wide -Feature.disable(:batch_suggestions) -``` - ## Start a thread by replying to a standard comment > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30299) in GitLab 11.9 @@ -537,7 +545,7 @@ Clicking on the **Reply to comment** button will bring the reply area into focus  Replying to a non-thread comment will convert the non-thread comment to a -thread once the reply is submitted. This conversion is considered an edit +thread after the reply is submitted. This conversion is considered an edit to the original comment, so a note about when it was last edited will appear underneath it. This feature only exists for Issues, Merge requests, and Epics. Commits, Snippets and Merge request diff threads are @@ -554,3 +562,62 @@ In the comment, click the **More Actions** menu and click **Assign to commenting Click the button again to unassign the commenter.  + +## Enable or disable Confidential Comments **(FREE SELF)** + +Confidential Comments 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(:confidential_notes) +``` + +To disable it: + +```ruby +Feature.disable(:confidential_notes) +``` + +## Enable or disable Custom commit messages for suggestions **(FREE SELF)** + +Custom commit messages for suggestions 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 disable custom commit messages for suggestions: + +```ruby +Feature.disable(:suggestions_custom_commit) +``` + +To enable custom commit messages for suggestions: + +```ruby +Feature.enable(:suggestions_custom_commit) +``` + +## Enable or disable Batch Suggestions **(FREE SELF)** + +Batch Suggestions is +deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can opt to disable it for your instance. + +To enable it: + +```ruby +# Instance-wide +Feature.enable(:batch_suggestions) +``` + +To disable it: + +```ruby +# Instance-wide +Feature.disable(:batch_suggestions) +``` diff --git a/doc/user/feature_flags.md b/doc/user/feature_flags.md index 9a601871349..a6be4c69f81 100644 --- a/doc/user/feature_flags.md +++ b/doc/user/feature_flags.md @@ -29,11 +29,11 @@ GitLab.com. To see the full notes: 1. Click the three-dots icon (ellipsis) to expand version history notes: -  +  1. Read the version history information: -  +  If you're a user of a GitLab self-managed instance and you want to try to use a disabled feature, you can ask a [GitLab administrator to enable it](../administration/feature_flags.md), diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 611c1105961..f988d825c9f 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -97,7 +97,7 @@ Any settings or feature limits not listed here are using the defaults listed in | ----------- | ----------------- | ------------- | | Artifacts maximum size (compressed) | 1G | 100M | | Artifacts [expiry time](../../ci/yaml/README.md#artifactsexpire_in) | From June 22, 2020, deleted after 30 days unless otherwise specified (artifacts created before that date have no expiry). | deleted after 30 days unless otherwise specified | -| Scheduled Pipeline Cron | `*/5 * * * *` | `19 * * * *` | +| Scheduled Pipeline Cron | `*/5 * * * *` | `3-59/10 * * * *` | | [Max jobs in active pipelines](../../administration/instance_limits.md#number-of-jobs-in-active-pipelines) | `500` for Free tier, unlimited otherwise | Unlimited | [Max CI/CD subscriptions to a project](../../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project) | `2` | Unlimited | | [Max pipeline schedules in projects](../../administration/instance_limits.md#number-of-pipeline-schedules) | `10` for Free tier, `50` for all paid tiers | Unlimited | @@ -114,7 +114,7 @@ or over the repository size limit, you can [reduce your repository size with Git | Setting | GitLab.com | Default | | ----------- | ----------- | ------------- | | [Repository size including LFS](../admin_area/settings/account_and_limit_settings.md) | 10 GB | Unlimited | -| Maximum import size | 5 GB | Unlimited | +| Maximum import size | 5 GB | Unlimited ([Modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to unlimited in GitLab 13.8. | NOTE: `git push` and GitLab project imports are limited to 5 GB per request through Cloudflare. Git LFS and imports other than a file upload are not affected by this limit. @@ -130,7 +130,7 @@ GitLab.com is fronted by Cloudflare. For incoming connections to GitLab.com you For outgoing connections from CI/CD runners we are not providing static IP addresses. All our runners are deployed into Google Cloud Platform (GCP) - any IP based firewall can be configured by looking up all -[IP address ranges or CIDR blocks for GCP](https://cloud.google.com/compute/docs/faq#where_can_i_find_product_name_short_ip_ranges). +[IP address ranges or CIDR blocks for GCP](https://cloud.google.com/compute/docs/faq#find_ip_range). ## Hostname list @@ -170,7 +170,7 @@ Linux shared runners on GitLab.com run in autoscale mode and are powered by Goog 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 Gold 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. +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 @@ -534,14 +534,16 @@ limiting responses](#rate-limiting-responses). The following table describes the rate limits for GitLab.com, both before and after the limits change in January, 2021: -| Rate limit | Before 2021-01-18 | From 2021-01-18 | -|:--------------------------------------------------------------------------|:----------------------------|:------------------------------| -| **Protected paths** (for a given **IP address**) | **10** requests per minute | **10** requests per minute | -| **Raw endpoint** traffic (for a given **project, commit, and file path**) | **300** requests per minute | **300** requests per minute | -| **Unauthenticated** traffic (from a given **IP address**) | No specific limit | **500** requests per minute | -| **Authenticated** API traffic (for a given **user**) | No specific limit | **2,000** requests per minute | -| **Authenticated** non-API HTTP traffic (for a given **user**) | No specific limit | **1,000** requests per minute | -| **All** traffic (from a given **IP address**) | **600** requests per minute | **2,000** requests per minute | +| Rate limit | Before 2021-01-18 | From 2021-01-18 | From 2021-02-12 | +|:--------------------------------------------------------------------------|:----------------------------|:------------------------------|:------------------------------| +| **Protected paths** (for a given **IP address**) | **10** requests per minute | **10** requests per minute | **10** requests per minute | +| **Raw endpoint** traffic (for a given **project, commit, and file path**) | **300** requests per minute | **300** requests per minute | **300** requests per minute | +| **Unauthenticated** traffic (from a given **IP address**) | No specific limit | **500** requests per minute | **500** requests per minute | +| **Authenticated** API traffic (for a given **user**) | No specific limit | **2,000** requests per minute | **2,000** requests per minute | +| **Authenticated** non-API HTTP traffic (for a given **user**) | No specific limit | **1,000** requests per minute | **1,000** requests per minute | +| **All** traffic (from a given **IP address**) | **600** requests per minute | **2,000** requests per minute | **2,000** requests per minute | +| **Issue creation** | | **300** requests per minute | **300** requests per minute | +| **Note creation** (on issues and merge requests) | | **300** requests per minute | **60** requests per minute | More details are available on the rate limits for [protected paths](#protected-paths-throttle) and [raw @@ -622,13 +624,6 @@ dropped and users get To help avoid abuse, project and group imports, exports, and export downloads are rate limited. See [Project import/export rate limits](../../user/project/settings/import_export.md#rate-limits) and [Group import/export rate limits](../../user/group/settings/import_export.md#rate-limits) for details. -GitLab.com Import/Export Rate Limits are set to the default except: - -| Setting | GitLab.com | Default | -|:-------------------------------------------------|:-----------|:--------| -| Max Project Export requests per minute per user | 1 | 6 | -| Max Group Export requests per minute per user | 1 | 6 | - ### Non-configurable limits See [non-configurable limits](../../security/rate_limits.md#non-configurable-limits) for information on @@ -639,7 +634,7 @@ rate limits that are not configurable, and therefore also used on GitLab.com. We use [Fluentd](https://gitlab.com/gitlab-com/runbooks/tree/master/logging/doc#fluentd) to parse our logs. Fluentd sends our logs to [Stackdriver Logging](https://gitlab.com/gitlab-com/runbooks/tree/master/logging/doc#stackdriver) and [Cloud Pub/Sub](https://gitlab.com/gitlab-com/runbooks/tree/master/logging/doc#cloud-pubsub). Stackdriver is used for storing logs long-term in Google Cold Storage (GCS). Cloud Pub/Sub -is used to forward logs to an [Elastic cluster](https://gitlab.com/gitlab-com/runbooks/tree/master/logging/doc#elastic) using [pubsubbeat](https://gitlab.com/gitlab-com/runbooks/tree/master/logging/doc#pubsubbeat-vms). +is used to forward logs to an [Elastic cluster](https://gitlab.com/gitlab-com/runbooks/tree/master/logging/doc#elastic) using [`pubsubbeat`](https://gitlab.com/gitlab-com/runbooks/tree/master/logging/doc#pubsubbeat-vms). You can view more information in our runbooks such as: diff --git a/doc/user/group/bulk_editing/index.md b/doc/user/group/bulk_editing/index.md index 8db9c7fd76c..651bb7c055e 100644 --- a/doc/user/group/bulk_editing/index.md +++ b/doc/user/group/bulk_editing/index.md @@ -13,26 +13,26 @@ For more details, see [Bulk editing issues and merge requests at the project lev If you want to update attributes across multiple issues, epics, or merge requests in a group, you can do it by bulk editing them, that is, editing them together. -NOTE: Only the items visible on the current page are selected for bulk editing (up to 20).  ## Bulk edit issues at the group level -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7249) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7249) in GitLab 12.1. +> - Assigning epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. +> - Editing health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in GitLab 13.2. +> - Editing iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196806) in GitLab 13.9. -NOTE: -You need a permission level of [Reporter or higher](../../permissions.md) to manage issues. +Users with permission level of [Reporter or higher](../../permissions.md) can manage issues. When bulk editing issues in a group, you can edit the following attributes: -- Epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in - [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.) **(PREMIUM)** -- Milestone -- Labels -- Health status ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in - [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2.) **(ULTIMATE)** +- [Epic](../epics/index.md) +- [Milestone](../../project/milestones/index.md) +- [Labels](../../project/labels.md) +- [Health status](../../project/issues/index.md#health-status) +- [Iteration](../iterations/index.md) To update multiple project issues at the same time: @@ -46,8 +46,7 @@ To update multiple project issues at the same time: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7250) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. -NOTE: -You need a permission level of [Reporter or higher](../../permissions.md) to manage epics. +Users with permission level of [Reporter or higher](../../permissions.md) can manage epics. When bulk editing epics in a group, you can edit their labels. @@ -63,8 +62,7 @@ To update multiple epics at the same time: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12719) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. -NOTE: -You need a permission level of [Developer or higher](../../permissions.md) to manage merge requests. +Users with permission level of [Developer or higher](../../permissions.md) can manage merge requests. When bulk editing merge requests in a group, you can edit the following attributes: diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index ea7629d1f10..d9167388e66 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -5,7 +5,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Group-level Kubernetes clusters +# Group-level Kubernetes clusters **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34758) in GitLab 11.6. @@ -38,12 +38,12 @@ in the project namespace. If the project's cluster is available and not disabled, GitLab uses the project's cluster before using any cluster belonging to the group containing the project. -In the case of sub-groups, GitLab uses the cluster of the closest ancestor group +In the case of subgroups, GitLab uses the cluster of the closest ancestor group to the project, provided the cluster is not disabled. ## Multiple Kubernetes clusters -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) to GitLab Core in 13.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) in GitLab Free 13.2. You can associate more than one Kubernetes cluster to your group, and maintain different clusters for different environments, such as development, staging, and production. @@ -107,7 +107,7 @@ The domain should have a wildcard DNS configured to the Ingress IP address. When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the -[environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables) +[environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-cicd-variables) work. While evaluating which environment matches the environment scope of a diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index 0dbd7af1214..09e899a61ba 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -4,7 +4,7 @@ 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 --- -# Contribution Analytics **(STARTER)** +# Contribution Analytics **(PREMIUM)** > - Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3090) for subgroups in GitLab 12.2. diff --git a/doc/user/group/dependency_proxy/index.md b/doc/user/group/dependency_proxy/index.md deleted file mode 100644 index c4feed24132..00000000000 --- a/doc/user/group/dependency_proxy/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../packages/dependency_proxy/index.md' ---- - -This document was moved to [another location](../../packages/dependency_proxy/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 9cc7a35bc32..d4c1a5fc768 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -16,13 +16,15 @@ to them. > - The New Epic form [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211533) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. > - In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/229621) and later, the New Epic button on the Epics list opens the New Epic form. +> - In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45948) and later, you can create a new epic from an empty Roadmap. To create an epic in the group you're in: 1. Get to the New Epic form: - - From the **Epics** list in your group, select the **New Epic** button. - - From an epic in your group, select the **New Epic** button. + - From the **Epics** list in your group, select **New epic**. + - From an epic in your group, select **New epic**. - From anywhere, in the top menu, select **New...** (**{plus-square}**) **> New epic**. + - In an empty [roadmap](../roadmap/index.md), select **New epic**.  @@ -39,7 +41,7 @@ To create an epic in the group you're in: ## Edit an epic -After you create an epic, you can edit change the following details: +After you create an epic, you can edit the following details: - Title - Description @@ -152,6 +154,9 @@ To make an epic confidential: ## Manage issues assigned to an epic +This section collects instructions for all the things you can do with [issues](../../project/issues/index.md) +in relation to epics. + ### Add a new issue to an epic You can add an existing issue to an epic, or create a new issue that's @@ -176,7 +181,7 @@ To add a new issue to an epic: - Search for the desired issue by entering part of the issue's title, then selecting the desired match (introduced in [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/9126)). - If there are multiple issues to be added, press <kbd>Spacebar</kbd> and repeat this step. + If there are multiple issues to be added, press <kbd>Space</kbd> and repeat this step. 1. Select **Add**. #### Create an issue from an epic @@ -278,7 +283,7 @@ To add a child epic to an epic: - Search for the desired issue by entering part of the epic's title, then selecting the desired match (introduced in [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/9126)). - If there are multiple epics to be added, press <kbd>Spacebar</kbd> and repeat this step. + If there are multiple epics to be added, press <kbd>Space</kbd> and repeat this step. 1. Select **Add**. ### Move child epics between epics diff --git a/doc/user/group/img/group_code_coverage_analytics_v13_7.png b/doc/user/group/img/group_code_coverage_analytics_v13_7.png Binary files differdeleted file mode 100644 index 769953b1355..00000000000 --- a/doc/user/group/img/group_code_coverage_analytics_v13_7.png +++ /dev/null diff --git a/doc/user/group/img/group_code_coverage_analytics_v13_9.png b/doc/user/group/img/group_code_coverage_analytics_v13_9.png Binary files differnew file mode 100644 index 00000000000..8cd71396381 --- /dev/null +++ b/doc/user/group/img/group_code_coverage_analytics_v13_9.png diff --git a/doc/user/group/import/img/bulk_imports_v13_8.png b/doc/user/group/import/img/bulk_imports_v13_8.png Binary files differindex 31234f9fcea..ae4d8567d80 100644 --- a/doc/user/group/import/img/bulk_imports_v13_8.png +++ b/doc/user/group/import/img/bulk_imports_v13_8.png diff --git a/doc/user/group/import/img/import_panel_v13_8.png b/doc/user/group/import/img/import_panel_v13_8.png Binary files differindex 1fb7fbad291..28d61785098 100644 --- a/doc/user/group/import/img/import_panel_v13_8.png +++ b/doc/user/group/import/img/import_panel_v13_8.png diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index d051a134af1..f4d15dce1cd 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/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 --- -# Import groups from another instance of GitLab **(CORE)** +# Import groups from another instance of GitLab **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/249160) in GitLab 13.7. > - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. @@ -16,7 +16,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature is [under construction](https://gitlab.com/groups/gitlab-org/-/epics/2771) and currently migrates only some of the Group data. Please see below for the full list of what is included in the migration at this time. -Using GitLab Group Migration, you can migrate existing top-level groups from GitLab.com or a self-managed instance. Groups can be migrated to a target instance, as a top-level group, or as a sub-group of any existing top-level group. +Using GitLab Group Migration, you can migrate existing top-level groups from GitLab.com or a self-managed instance. Groups can be migrated to a target instance, as a top-level group, or as a subgroup of any existing top-level group. The following resources are migrated to the target instance: diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 069dea40ba5..4c63bae7e44 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -288,7 +288,7 @@ In [GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab adminis There are two different ways to add a new project to a group: -- Select a group, and then click **New project**. You can then continue [creating your project](../../gitlab-basics/create-project.md). +- Select a group, and then click **New project**. You can then continue [creating your project](../../user/project/working_with_projects.md#create-a-project).  @@ -301,7 +301,7 @@ There are two different ways to add a new project to a group: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2534) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.5. > - Brought to [GitLab Starter](https://about.gitlab.com/pricing/) in 10.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25975) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25975) to [GitLab Free](https://about.gitlab.com/pricing/) in 11.10. By default, [Developers and Maintainers](../permissions.md#group-members-permissions) can create projects under a group. @@ -327,7 +327,7 @@ A group's **Details** page includes tabs for: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207164) in GitLab [Starter](https://about.gitlab.com/pricing/) 12.10 as a [beta feature](https://about.gitlab.com/handbook/product/#beta) -The group details view also shows the number of the following items created in the last 90 days: **(STARTER)** +The group details view also shows the number of the following items created in the last 90 days: **(PREMIUM)** - Merge requests. - Issues. @@ -389,7 +389,7 @@ To share a given group, for example, 'Frontend' with another group, for example, All the members of the 'Engineering' group will have been added to 'Frontend'. -## Manage group memberships via LDAP **(STARTER ONLY)** +## Manage group memberships via LDAP **(PREMIUM SELF)** Group syncing allows LDAP groups to be mapped to GitLab groups. This provides more control over per-group user management. To configure group syncing edit the `group_base` **DN** (`'OU=Global Groups,OU=GitLab INT,DC=GitLab,DC=org'`). This **OU** contains all groups that will be associated with GitLab groups. @@ -400,10 +400,12 @@ For more information on the administration of LDAP and group sync, refer to the NOTE: If an LDAP user is a group member when LDAP Synchronization is added, and they are not part of the LDAP group, they will be removed from the group. -### Creating group links via CN **(STARTER ONLY)** +### Creating group links via CN **(PREMIUM SELF)** To create group links via CN: +<!-- vale gitlab.Spelling = NO --> + 1. Select the **LDAP Server** for the link. 1. Select `LDAP Group cn` as the **Sync method**. 1. In the **LDAP Group cn** text input box, begin typing the CN of the group. There will be a dropdown menu with matching CNs within the configured `group_base`. Select your CN from this list. @@ -412,7 +414,9 @@ To create group links via CN:  -### Creating group links via filter **(PREMIUM ONLY)** +<!-- vale gitlab.Spelling = YES --> + +### Creating group links via filter **(PREMIUM SELF)** To create group links via filter: @@ -424,7 +428,7 @@ To create group links via filter:  -### Overriding user permissions **(STARTER ONLY)** +### Overriding user permissions **(PREMIUM SELF)** In GitLab [8.15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/822) and later, LDAP user permissions can now be manually overridden by an admin user. To override a user's permissions: @@ -455,20 +459,19 @@ Group wikis work the same way as [project wikis](../project/wiki/index.md), plea Group wikis can be edited by members with [Developer permissions](../../user/permissions.md#group-members-permissions) and above. +Group wiki repositories can be moved through the [Group repository storage moves API](../../api/group_repository_storage_moves.md). + ### Group wikis limitations There are a few limitations compared to project wikis: - Git LFS is not supported. -- Group wikis are not included in global search, group exports, and Geo replication. +- Group wikis are not included in global search and Geo replication. - Changes to group wikis don't show up in the group's activity feed. -- Group wikis [can't be moved](../../api/project_repository_storage_moves.md#limitations) using the project - repository moves API. For updates, you can follow: - [The epic tracking feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). -- [The issue for adding the ability to move group wikis using the API](https://gitlab.com/gitlab-org/gitlab/-/issues/219003). ## Group Security Dashboard **(ULTIMATE)** @@ -500,7 +503,7 @@ From GitLab 10.5, 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/index.md#redirects-when-changing-repository-paths). +- 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). - 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 will change to match the new parent group's visibility. @@ -523,7 +526,7 @@ access further configurations for your group. #### Changing a group's path Changing a group's path (group URL) can have unintended side effects. Read -[how redirects will behave](../project/index.md#redirects-when-changing-repository-paths) +[how redirects will behave](../project/repository/index.md#redirects-when-changing-repository-paths) before proceeding. If you are vacating the path so it can be claimed by another group or user, @@ -551,12 +554,12 @@ username, you can create a new group and transfer projects to it. You can change settings that are specific to repositories in your group. -#### Custom initial branch name **(CORE ONLY)** +#### Custom initial branch name **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43290) in GitLab 13.6. By default, when you create a new project in GitLab, the initial branch is called `master`. -For groups, a group administrator can customize the initial branch name to something +For groups, a group owner can customize the initial branch name to something else. This way, every new project created under that group from then on will start from the custom branch name rather than `master`. To do so: 1. Go to the **Group page > Settings > Repository** and expand **Default initial @@ -576,7 +579,7 @@ To remove a group and its contents: This action either: - Removes the group, and also queues a background job to delete all projects in that group. -- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium or Silver](https://about.gitlab.com/pricing/premium/) or higher tiers, this action adds a background job to mark a group for deletion. By default, the job schedules the deletion 7 days in the future. You can modify this waiting period through the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). +- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium](https://about.gitlab.com/pricing/premium/) or higher tiers, this action adds a background job to mark a group for deletion. By default, the job schedules the deletion 7 days in the future. You can modify this waiting period through the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). Since [GitLab 13.6](https://gitlab.com/gitlab-org/gitlab/-/issues/39504), if the user who sets up the deletion leaves or is otherwise removed from the group before the actual deletion happens, the job is cancelled, and the group is no longer scheduled for deletion. @@ -612,7 +615,7 @@ To enable this feature, navigate to the group settings page. Select  -#### Member Lock **(STARTER)** +#### Member Lock **(PREMIUM)** Member lock lets a group owner prevent any new project membership to all of the projects within a group, allowing tighter control over project membership. @@ -634,8 +637,8 @@ request to add a new user to a project through API will not be possible. #### IP access restriction **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in [GitLab Ultimate and Gold](https://about.gitlab.com/pricing/) 12.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215410) to [GitLab Premium and Silver](https://about.gitlab.com/pricing/) in 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1985) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215410) to [GitLab Premium](https://about.gitlab.com/pricing/) in 13.1. NOTE: IP Access Restrictions are currently not functioning as expected on GitLab.com. Some users @@ -645,9 +648,9 @@ more information. To make sure only people from within your organization can access particular resources, you have the option to restrict access to groups and their -underlying projects, issues, etc, by IP address. This can help ensure that +underlying subgroups, projects, issues, and so on, by IP address. This can help ensure that particular content doesn't leave the premises, while not blocking off access to -the entire instance. +the entire instance. IP access restrictions can only be configured at the group level. Add one or more allowed IP subnets using CIDR notation to the group settings and anyone coming from a different IP address won't be able to access the restricted @@ -672,7 +675,7 @@ To enable this feature: #### Allowed domain restriction **(PREMIUM)** ->- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7297) in [GitLab Premium and Silver](https://about.gitlab.com/pricing/) 12.2. +>- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7297) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. >- Support for specifying multiple email domains [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33143) in GitLab 13.1 You can restrict access to groups by allowing only users with email addresses in particular domains to be added to the group. @@ -702,6 +705,9 @@ To enable this feature: This will enable the domain-checking for all new users added to the group from this moment on. +NOTE: +Domain restrictions only apply to groups and do not prevent users from being added as members of projects owned by the restricted group. + #### Group file templates **(PREMIUM)** Group file templates allow you to share a set of templates for common file @@ -726,6 +732,9 @@ To enable this feature, navigate to the group settings page, expand the  +To learn how to create templates for issues and merge requests, visit +[Description templates](../project/description_templates.md). + #### Group-level project templates **(PREMIUM)** Define project templates at a group level by setting a group as the template source. @@ -765,7 +774,7 @@ To enable this feature: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. By default, projects within a group are deleted immediately. -Optionally, on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, +Optionally, on [Premium](https://about.gitlab.com/pricing/) or higher tiers, you can configure the projects within a group to be deleted after a delayed interval. During this interval period, the projects will be in a read-only state and can be restored, if required. @@ -778,14 +787,14 @@ To enable delayed deletion of projects: 1. Click **Save changes**. NOTE: -The group setting for delayed deletion is not inherited by sub-groups and has to be individually defined for each group. +The group setting for delayed deletion is not inherited by subgroups and has to be individually defined for each group. #### Prevent project forking outside group **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216987) in GitLab 13.3. By default, projects within a group can be forked. -Optionally, on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, +Optionally, on [Premium](https://about.gitlab.com/pricing/) or higher tiers, you can prevent the projects within a group from being forked outside of the current top-level group. Previously this setting was available only for groups enforcing group managed account. This setting will be @@ -804,11 +813,11 @@ To enable prevent project forking: - **Webhooks**: Configure [webhooks](../project/integrations/webhooks.md) for your group. - **Kubernetes cluster integration**: Connect your GitLab group with [Kubernetes clusters](clusters/index.md). - **Audit Events**: View [Audit Events](../../administration/audit_events.md) - for the group. **(STARTER ONLY)** + for the group. **(PREMIUM SELF)** - **Pipelines quota**: Keep track of the [pipeline quota](../admin_area/settings/continuous_integration.md) for the group. - **Integrations**: Configure [integrations](../admin_area/settings/project_integration_management.md) for your group. -#### Group push rules **(STARTER)** +#### Group push rules **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34370) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/224129) in GitLab 13.4. @@ -824,12 +833,12 @@ When set, new subgroups have push rules set for them based on either: - The closest parent group with push rules defined. - Push rules set at the instance level, if no parent groups have push rules defined. -### Maximum artifacts size **(CORE ONLY)** +### Maximum artifacts size **(FREE SELF)** For information about setting a maximum artifact size for a group, see [Maximum artifacts size](../admin_area/settings/continuous_integration.md#maximum-artifacts-size). -## User contribution analysis **(STARTER)** +## User contribution analysis **(PREMIUM)** With [GitLab Contribution Analytics](contribution_analytics/index.md), you have an overview of the contributions (pushes, merge requests, @@ -844,17 +853,7 @@ With [GitLab Issue Analytics](issues_analytics/index.md), you can see a bar char > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263478) in GitLab 13.6. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/276003) in GitLab 13.7. -With [GitLab Repositories Analytics](repositories_analytics/index.md), you can download a CSV of the latest coverage data for all the projects in your group. - -### Check code coverage for all projects - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263478) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. - -See the overall activity of all projects with code coverage with [GitLab Repositories Analytics](repositories_analytics/index.md). - -It displays the current code coverage data available for your projects: - - +With [GitLab Repositories Analytics](repositories_analytics/index.md), you can view overall activity of all projects with code coverage. ## Dependency Proxy @@ -871,3 +870,13 @@ questions that you know someone might ask. Each scenario can be a third-level heading, e.g. `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> + +## DORA4 analytics overview **(ULTIMATE ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291747) in GitLab [Ultimate](https://about.gitlab.com/pricing/) 13.9 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). + +Group details include the following analytics: + +- Deployment Frequency + +For more information, see [DORA4 Project Analytics API](../../api/dora4_group_analytics.md). diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index 269be19f759..97f62becdb6 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7478) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. Issue Analytics is a bar graph which illustrates the number of issues created each month. -The default timespan is 13 months, which includes the current month, and the 12 months +The default time span is 13 months, which includes the current month, and the 12 months prior. To access the chart, navigate to your group sidebar and select **{chart}** **Analytics > Issue Analytics**. diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 65d3129a825..8e125a0cc6e 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -5,15 +5,16 @@ 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 --- -# Iterations **(STARTER)** +# Iterations **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214713) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214713) in GitLab 13.1. > - It was deployed behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/221047) on GitLab 13.2. > - It's enabled on GitLab.com. > - It's able to be enabled or disabled per-group. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-iterations). **(STARTER ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-iterations). **(PREMIUM ONLY)** +> - Moved to GitLab Premium in 13.9. Iterations are a way to track issues over a period of time. This allows teams to track velocity and volatility metrics. Iterations can be used with [milestones](../../project/milestones/index.md) @@ -50,7 +51,7 @@ To create an iteration: ## Edit an iteration -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218277) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218277) in GitLab 13.2. NOTE: You need Developer [permissions](../../permissions.md) or higher to edit an iteration. @@ -59,14 +60,14 @@ To edit an iteration, click the three-dot menu (**{ellipsis_v}**) > **Edit itera ## Add an issue to an iteration -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216158) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216158) in GitLab 13.2. To learn how to add an issue to an iteration, see the steps in [Managing issues](../../project/issues/managing_issues.md#add-an-issue-to-an-iteration). ## View an iteration report -> Viewing iteration reports in projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222763) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. +> Viewing iteration reports in projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222763) in GitLab 13.5. You can track the progress of an iteration by reviewing iteration reports. An iteration report displays a list of all the issues assigned to an iteration and their status. @@ -79,8 +80,8 @@ To view an iteration report, go to the iterations list page and click an iterati ### Iteration burndown and burnup charts -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222750) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/269972) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222750) in GitLab 13.5. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/269972) in GitLab 13.7. The iteration report includes [burndown and burnup charts](../../project/milestones/burndown_and_burnup_charts.md), similar to how they appear when viewing a [milestone](../../project/milestones/index.md). @@ -104,7 +105,7 @@ To group issues by label: You can also search for labels by typing in the search input. 1. Click or tap outside of the label dropdown. The page is now grouped by the selected labels. -## Disable iterations **(STARTER ONLY)** +## Disable iterations **(PREMIUM SELF)** GitLab Iterations feature is deployed with a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index fc4fb0236de..1cb7c05bb5f 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -12,6 +12,25 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature might not be available to you. Check the **version history** note above for details. + + +## Current group code coverage + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263478) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. + +The **Analytics > Repositories** group page displays the overall test coverage of all your projects in your group. +In the **Overall activity** section, you can see: + +- The number of projects with coverage reports. +- The average percentage of coverage across all your projects. +- The total number of pipeline jobs that produce coverage reports. + +## Average group test coverage from the last 30 days + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215140) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.9. + +The **Analytics > Repositories** group page displays the average test coverage of all your projects in your group in a graph for the last 30 days. + ## Latest project test coverage list > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267624) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. @@ -30,10 +49,10 @@ You can get a CSV of the code coverage data for all of the projects in your grou To get the report: 1. Go to your group's **Analytics > Repositories** page -1. Click **Download historic test coverage data (.csv)**, +1. Click **Download historic test coverage data (`.csv`)**, 1. In the popup, select the projects you want to include in the report. 1. Select the date range for the report from the preset options. -1. Click **Download test coverage data (.csv)**. +1. Click **Download test coverage data (`.csv`)**. The projects dropdown shows up to 100 projects from your group. If the project you want to check is not in the dropdown list, you can select **All projects** to download the report for all projects in your group, including any projects that are not listed. There is a plan to improve this behavior in this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/250684). diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index f3b7be536ae..e2c01987e36 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -40,7 +40,8 @@ toggle the list of the milestone bars. > - Filtering roadmaps by milestone is [deployed behind a feature flag](../../feature_flags.md), enabled by default. > - Filtering roadmaps by milestone is enabled on GitLab.com. > - Filtering roadmaps by milestone is recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-filtering-roadmaps-by-milestone). **(PREMIUM ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-filtering-roadmaps-by-milestone). **(PREMIUM SELF)** +> - Filtering by epic confidentiality [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218624) in GitLab 13.8. WARNING: Filtering roadmaps by milestone might not be available to you. Check the **version history** note above for details. @@ -62,18 +63,18 @@ You can sort epics in the Roadmap view by: Each option contains a button that toggles the sort order between **ascending** and **descending**. The sort option and order persist when browsing Epics, including the [epics list view](../epics/index.md). -You can also filter epics in the Roadmap view by: +You can also filter epics in the Roadmap view by the epics': - Author - Label - Milestone -- Confidentiality of epics +- Confidentiality  Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap-in-epics). -### Enable or disable filtering roadmaps by milestone **(PREMIUM ONLY)** +### Enable or disable filtering roadmaps by milestone **(PREMIUM SELF)** Filtering roadmaps by milestone is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md index 7158b7bc86b..dd0888a610f 100644 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ b/doc/user/group/saml_sso/group_managed_accounts.md @@ -9,9 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This [Closed Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#sts=Closed%20Beta) feature is being re-evaluated in favor of a different -[identity model](https://gitlab.com/groups/gitlab-org/-/epics/4345) that does not require separate accounts. -We recommend that group administrators who haven't yet implemented this feature wait for -the new solution. +[approach](https://gitlab.com/groups/gitlab-org/-/epics/4786) that aligns more closely with our [Subscription Agreement](https://about.gitlab.com/handbook/legal/subscription-agreement/). +We recommend that group owners who haven't yet implemented this feature wait for the new solution. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/709) in GitLab 12.1. > - It's deployed behind a feature flag, disabled by default. @@ -50,7 +49,7 @@ assertions to be able to create a user. | First Name | `first_name`, `firstname`, `firstName` | | Last Name | `last_name`, `lastname`, `lastName` | -## Feature flag **(PREMIUM ONLY)** +## Feature flag **(PREMIUM SELF)** The group-managed accounts feature is behind these feature flags: `group_managed_accounts`, `sign_up_on_sso` and `convert_user_to_group_managed_accounts`. The flags are disabled by default. To activate the feature, ask a GitLab administrator with Rails console access to run: diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 0ce92eac1a3..d1c490b0769 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -5,7 +5,7 @@ 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 --- -# SAML SSO for GitLab.com groups **(SILVER ONLY)** +# SAML SSO for GitLab.com groups **(PREMIUM SAAS)** > Introduced in GitLab 11.0. @@ -18,14 +18,15 @@ If you follow our guidance to automate user provisioning using [SCIM](scim_setup User synchronization of SAML SSO groups is supported through [SCIM](scim_setup.md). SCIM supports adding and removing users from the GitLab group. For example, if you remove a user from the SCIM app, SCIM removes that same user from the GitLab group. -SAML SSO is not supported at the subgroup level. +SAML SSO is only configurable at the top-level group. ## Configuring your Identity Provider -1. Navigate to the group and click **Settings > SAML SSO**. +1. Navigate to the group and select **Settings > SAML SSO**. 1. Configure your SAML server using the **Assertion consumer service URL**, **Identifier**, and **GitLab single sign-on URL**. Alternatively GitLab provides [metadata XML configuration](#metadata-configuration). See [specific identity provider documentation](#providers) for more details. 1. Configure the SAML response to include a NameID that uniquely identifies each user. 1. Configure [required assertions](group_managed_accounts.md#assertions) if using [Group Managed Accounts](group_managed_accounts.md). +1. While the default is enabled for most SAML providers, please ensure the app is set to have [Service Provider](#glossary) initiated calls in order to link existing GitLab accounts. 1. Once the identity provider is set up, move on to [configuring GitLab](#configuring-gitlab).  @@ -56,7 +57,7 @@ We recommend setting the NameID format to `Persistent` unless using a field (suc GitLab provides metadata XML that can be used to configure your Identity Provider. -1. Navigate to the group and click **Settings > SAML SSO**. +1. Navigate to the group and select **Settings > SAML SSO**. 1. Copy the provided **GitLab metadata URL**. 1. Follow your Identity Provider's documentation and paste the metadata URL when it's requested. @@ -68,8 +69,8 @@ After you set up your identity provider to work with GitLab, you must configure 1. Find the SSO URL from your Identity Provider and enter it the **Identity provider single sign-on URL** field. 1. Find and enter the fingerprint for the SAML token signing certificate in the **Certificate** field. 1. Select the access level to be applied to newly added users in the **Default membership role** field. The default access level is 'Guest'. -1. Click the **Enable SAML authentication for this group** toggle switch. -1. Click the **Save changes** button. +1. Select the **Enable SAML authentication for this group** toggle switch. +1. Select the **Save changes** button.  @@ -110,7 +111,8 @@ When [configuring your identify provider](#configuring-your-identity-provider), ### Azure setup notes <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a demo of the Azure SAML setup including SCIM, see [SCIM Provisioning on Azure Using SAML SSO for Groups Demo](https://youtu.be/24-ZxmTeEBU). Please note that the video is outdated in regards to objectID mapping and the [SCIM documentation should be followed](scim_setup.md#azure-configuration-steps). +For a demo of the Azure SAML setup including SCIM, see [SCIM Provisioning on Azure Using SAML SSO for Groups Demo](https://youtu.be/24-ZxmTeEBU). Please note that the video is outdated in regard to +objectID mapping and the [SCIM documentation should be followed](scim_setup.md#azure-configuration-steps). | GitLab Setting | Azure Field | |--------------|----------------| @@ -214,7 +216,7 @@ To link SAML to your existing GitLab.com account: 1. Sign in to your GitLab.com account. 1. Locate and visit the **GitLab single sign-on URL** for the group you're signing in to. A group owner can find this on the group's **Settings > SAML SSO** page. If the sign-in URL is configured, users can connect to the GitLab app from the Identity Provider. -1. Click **Authorize**. +1. Select **Authorize**. 1. Enter your credentials on the Identity Provider if prompted. 1. You are then redirected back to GitLab.com and should now have access to the group. In the future, you can use SAML to sign in to GitLab.com. @@ -223,7 +225,7 @@ On subsequent visits, you should be able to go [sign in to GitLab.com with SAML] ### Signing in to GitLab.com with SAML 1. Sign in to your identity provider. -1. From the list of apps, click on the "GitLab.com" app (The name is set by the administrator of the identity provider). +1. From the list of apps, select the "GitLab.com" app. (The name is set by the administrator of the identity provider.) 1. You are then signed in to GitLab.com and redirected to the group. ### Configure user settings from SAML response @@ -280,7 +282,7 @@ If a user is already a member of the group, linking the SAML identity does not c To rescind access to the group, perform the following steps, in order: -1. Remove the user from the user datastore on the identity provider or the list of users on the specific app. +1. Remove the user from the user data store on the identity provider or the list of users on the specific app. 1. Remove the user from the GitLab.com group. ### Unlinking accounts @@ -291,10 +293,19 @@ Users can unlink SAML for a group from their profile page. This can be helpful i - Your SAML NameID has changed and so GitLab can no longer find your user. WARNING: -Unlinking an account removes all roles assigned to that user within the group. -If a user relinks their account, roles need to be reassigned. +Unlinking an account removes all roles assigned to that user in the group. +If a user re-links their account, roles need to be reassigned. -For example, to unlink the `MyOrg` account, the following **Disconnect** button is available under **Profile > Accounts**: +Groups require at least one owner. If your account is the only owner in the +group, you are not allowed to unlink the account. In that case, set up another user as a +group owner, and then you can unlink the account. + +For example, to unlink the `MyOrg` account: + +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Account**. +1. In the **Social sign-in** section, select **Disconnect** next to the connected account.  @@ -341,9 +352,9 @@ access. | Term | Description | |------|-------------| -| Identity Provider | The service which manages your user identities such as ADFS, Okta, Onelogin, or Ping Identity. | +| Identity Provider | The service which manages your user identities such as ADFS, Okta, OneLogin, or Ping Identity. | | Service Provider | SAML considers GitLab to be a service provider. | -| Assertion | A piece of information about a user's identity, such as their name or role. Also know as claims or attributes. | +| Assertion | A piece of information about a user's identity, such as their name or role. Also known as claims or attributes. | | SSO | Single Sign On. | | Assertion consumer service URL | The callback on GitLab where users are redirected after successfully authenticating with the identity provider. | | Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". | @@ -376,7 +387,7 @@ For convenience, we've included some [example resources](../../../administration ### Verifying NameID -In troubleshooting the Group SAML setup, any authenticated user can use the API to verify the NameID GitLab already has linked to the user by visiting [https://gitlab.com/api/v4/user](https://gitlab.com/api/v4/user) and checking the `extern_uid` under identities. +In troubleshooting the Group SAML setup, any authenticated user can use the API to verify the NameID GitLab already has linked to the user by visiting [`https://gitlab.com/api/v4/user`](https://gitlab.com/api/v4/user) and checking the `extern_uid` under identities. Similarly, group members of a role with the appropriate permissions can make use of the [members API](../../../api/members.md) to view group SAML identity information for members of the group. @@ -387,7 +398,7 @@ This can then be compared to the [NameID](#nameid) being sent by the Identity Pr If a user is trying to sign in for the first time and the GitLab single sign-on URL has not [been configured](#configuring-your-identity-provider), they may see a 404. As outlined in the [user access section](#linking-saml-to-your-existing-gitlabcom-account), a group Owner will need to provide the URL to users. -### Message: "SAML authentication failed: Extern uid has already been taken" +### Message: "SAML authentication failed: Extern UID has already been taken" This error suggests you are signed in as a GitLab user but have already linked your SAML identity to a different GitLab user. Sign out and then try to sign in again using the SSO SAML link, which should log you into GitLab with the linked user account. @@ -408,7 +419,7 @@ Here are possible causes and solutions: |------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------| | When a user account with the email address already exists in GitLab, but the user does not have the SAML identity tied to their account. | The user will need to [link their account](#user-access-and-management). | -### Message: "SAML authentication failed: Extern uid has already been taken, User has already been taken" +### Message: "SAML authentication failed: Extern UID has already been taken, User has already been taken" Getting both of these errors at the same time suggests the NameID capitalization provided by the Identity Provider didn't exactly match the previous value for that user. @@ -418,6 +429,11 @@ This can be prevented by configuring the [NameID](#nameid) to return a consisten Ensure that the user who is trying to link their GitLab account has been added as a user within the identity provider's SAML app. +Alternatively, the SAML response may be missing the `InResponseTo` attribute in the +`samlp:Response` tag, which is [expected by the SAML gem](https://github.com/onelogin/ruby-saml/blob/9f710c5028b069bfab4b9e2b66891e0549765af5/lib/onelogin/ruby-saml/response.rb#L307-L316). +The [Identity Provider](#glossary) administrator should ensure that the login is +initiated by the Service Provider (typically GitLab) and not the Identity Provider. + ### Stuck in a login "loop" Ensure that the **GitLab single sign-on URL** has been configured as "Login URL" (or similarly named field) in the identity provider's SAML app. @@ -446,3 +462,25 @@ However, self-managed GitLab instances use a configuration file that supports mo Internally that uses the [`ruby-saml` library](https://github.com/onelogin/ruby-saml), so we sometimes check there to verify low level details of less commonly used options. It can also help to compare the XML response from your provider with our [example XML used for internal testing](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/spec/fixtures/saml/response.xml). + +### Searching Rails log + +With access to the rails log or `production_json.log` (available only to GitLab team members for GitLab.com), +you should be able to find the base64 encoded SAML response by searching with the following filters: + +- `json.meta.caller_id`: `Groups::OmniauthCallbacksController#group_saml` +- `json.meta.user` or `json.username`: `username` +- `json.method`: `POST` +- `json.path`: `/groups/GROUP-PATH/-/saml/callback` + +In a relevant log entry, the `json.params` should provide a valid response with: + +- `"key": "SAMLResponse"` and the `"value": (full SAML response)`, +- `"key": "RelayState"` with `"value": "/group-path"`, and +- `"key": "group_id"` with `"value": "group-path"`. + +In some cases, if the SAML response is lengthy, you may receive a `"key": "truncated"` with `"value":"..."`. +In these cases, please ask a group owner for a copy of the SAML response from when they select +the "Verify SAML Configuration" button on the group SSO Settings page. + +Use a base64 decoder to see a human-readable version of the SAML response. diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index cd3e99ae541..3a34a4b0599 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -5,9 +5,9 @@ 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 --- -# SCIM provisioning using SAML SSO for GitLab.com groups **(SILVER ONLY)** +# SCIM provisioning using SAML SSO for GitLab.com groups **(PREMIUM SAAS)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in GitLab Premium 11.10. System for Cross-domain Identity Management (SCIM), is an open standard that enables the automation of user provisioning. When SCIM is provisioned for a GitLab group, membership of @@ -260,7 +260,7 @@ It is important not to update these to incorrect values, since this will cause u Individual users can follow the instructions in the ["SAML authentication failed: User has already been taken"](index.md#i-need-to-change-my-saml-app) section. -Alternatively, users can be removed from the SCIM app which will delink all removed users. Sync can then be turned on for the new SCIM app to [link existing users](#user-access-and-linking-setup). +Alternatively, users can be removed from the SCIM app which de-links all removed users. Sync can then be turned on for the new SCIM app to [link existing users](#user-access-and-linking-setup). ### The SCIM app is throwing `"User has already been taken","status":409` error message diff --git a/doc/user/group/security_dashboard/index.md b/doc/user/group/security_dashboard/index.md deleted file mode 100644 index 3feccf2e342..00000000000 --- a/doc/user/group/security_dashboard/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../application_security/security_dashboard/index.md' ---- - -This document was moved to [another location](../../application_security/security_dashboard/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index 6b95388bf2e..bb7c1e26544 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -48,6 +48,7 @@ The following items are exported: - Subgroups (including all the aforementioned data) - Epics - Events +- Wikis **(PREMIUM SELF)** (Introduced in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247)) The following items are **not** exported: @@ -69,7 +70,7 @@ For more details on the specific data persisted in a group export, see the  -1. Once the export is generated, you should receive an e-mail with a link to the [exported contents](#exported-contents) +1. After the export is generated, you should receive an e-mail with a link to the [exported contents](#exported-contents) in a compressed tar archive, with contents in JSON format. 1. Alternatively, you can come back to the project settings and download the @@ -77,7 +78,7 @@ For more details on the specific data persisted in a group export, see the NOTE: The maximum import file size can be set by the Administrator, default is `0` (unlimited). -As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin UI](../../admin_area/settings/account_and_limit_settings.md). +As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin UI](../../admin_area/settings/account_and_limit_settings.md). Default [modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to 0 in GitLab 13.8. ### Between CE and EE diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 438769872c0..4fcef07a04e 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -324,7 +324,7 @@ To delete a custom value stream: This chart visually depicts the total number of days it takes for cycles to be completed. (Totals are being replaced with averages in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/262070).) This chart uses the global page filters for displaying data based on the selected -group, projects, and timeframe. In addition, specific stages can be selected +group, projects, and time frame. In addition, specific stages can be selected from within the chart itself. The chart data is limited to the last 500 items. @@ -345,7 +345,7 @@ Feature.disable(:cycle_analytics_scatterplot_enabled) This chart shows a cumulative count of issues and merge requests per day. This chart uses the global page filters for displaying data based on the selected -group, projects, and timeframe. The chart defaults to showing counts for issues but can be +group, projects, and time frame. The chart defaults to showing counts for issues but can be toggled to show data for merge requests and further refined for specific group-level labels. By default the top group-level labels (max. 10) are pre-selected, with the ability to diff --git a/doc/user/img/activity_followed_users_v13_9.png b/doc/user/img/activity_followed_users_v13_9.png Binary files differnew file mode 100644 index 00000000000..3c0a9de74b4 --- /dev/null +++ b/doc/user/img/activity_followed_users_v13_9.png diff --git a/doc/user/incident_management/index.md b/doc/user/incident_management/index.md deleted file mode 100644 index ed3516df168..00000000000 --- a/doc/user/incident_management/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../operations/incident_management/index.md' ---- - -This document was moved to [../../operations/incident_management/index.md](../../operations/incident_management/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/index.md b/doc/user/index.md index 3b2acfab34c..a678038507f 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -43,7 +43,7 @@ GitLab is a Git-based platform that integrates a great number of essential tools - Hosting code in repositories with version control. - Tracking proposals for new implementations, bug reports, and feedback with a fully featured [Issue Tracker](project/issues/index.md#issues-list). -- Organizing and prioritizing with [Issue Boards](project/issues/index.md#issue-boards). +- Organizing and prioritizing with [Issue Boards](project/issue_board.md). - Reviewing code in [Merge Requests](project/merge_requests/index.md) with live-preview changes per branch with [Review Apps](../ci/review_apps/index.md). - Building, testing, and deploying with built-in [Continuous Integration](../ci/README.md). @@ -83,6 +83,14 @@ There are several types of users in GitLab: self-managed instances' features and settings. - [Internal users](../development/internal_users.md). +## User activity + +You can follow or unfollow other users from their [user profiles](profile/index.md#user-profile). +To see their activity in the top-level Activity view, select Follow or Unfollow, and select +the Followed Users tab: + + + ## Projects In GitLab, you can create [projects](project/index.md) to host diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index 60453b007ba..6ba5e49d553 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Infrastructure as code with Terraform and GitLab +# Infrastructure as code with Terraform and GitLab **(FREE)** ## Motivation @@ -26,6 +26,8 @@ variables: # If not using GitLab's HTTP backend, remove this line and specify TF_HTTP_* variables TF_STATE_NAME: default TF_CACHE_KEY: default + # If your terraform files are in a subdirectory, set TF_ROOT accordingly + # TF_ROOT: terraform/production ``` This template uses `.latest.`, instead of stable, and may include breaking changes. @@ -39,6 +41,15 @@ This template also includes some opinionated decisions, which you can override: [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.latest.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: + +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=iGXjUrkkzDI">Terraform with GitLab</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube.com/embed/iGXjUrkkzDI" frameborder="0" allowfullscreen="true"> </iframe> +</figure> + ## GitLab Managed Terraform state [Terraform remote backends](https://www.terraform.io/docs/backends/index.html) diff --git a/doc/user/infrastructure/mr_integration.md b/doc/user/infrastructure/mr_integration.md index 2704e7b7c8d..927552b90be 100644 --- a/doc/user/infrastructure/mr_integration.md +++ b/doc/user/infrastructure/mr_integration.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Terraform integration in Merge Requests +# Terraform integration in Merge Requests **(FREE)** Collaborating around Infrastructure as Code (IaC) changes requires both code changes and expected infrastructure changes to be checked and approved. GitLab provides a solution to help collaboration around Terraform code changes and their expected effects using the Merge Request pages. This way users don't have to build custom tools or rely on 3rd party solutions to streamline their IaC workflows. diff --git a/doc/user/infrastructure/terraform_state.md b/doc/user/infrastructure/terraform_state.md index 30838b1cabd..ae35ebce0dc 100644 --- a/doc/user/infrastructure/terraform_state.md +++ b/doc/user/infrastructure/terraform_state.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab managed Terraform State +# GitLab managed Terraform State **(FREE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. @@ -18,10 +18,14 @@ The GitLab managed Terraform state backend can store your Terraform state easily securely, and spares you from setting up additional remote resources like Amazon S3 or Google Cloud Storage. Its features include: +- Versioning of Terraform state files. - Supporting encryption of the state file both in transit and at rest. - Locking and unlocking state. - Remote Terraform plan and apply execution. +A GitLab **administrator** must [setup the Terraform state storage configuration](../../administration/terraform_state.md) +before using this feature. + ## Permissions for using Terraform In GitLab version 13.1, [Maintainer access](../permissions.md) was required to use a diff --git a/doc/user/markdown.md b/doc/user/markdown.md index be6e483aa54..5f974d75522 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# GitLab Markdown +# GitLab 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) @@ -21,7 +21,7 @@ We encourage you to view this document as [rendered by GitLab itself](https://gi ## GitLab Flavored Markdown (GFM) GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification](https://spec.commonmark.org/current/) -(which is based on standard Markdown) in several ways to add additional useful functionality. +(which is based on standard Markdown) in several ways to add more features. It was inspired by [GitHub Flavored Markdown](https://docs.github.com/en/free-pro-team@latest/github/writing-on-github/basic-writing-and-formatting-syntax). You can use GFM in the following areas: @@ -41,20 +41,23 @@ for more information. ### Transition from Redcarpet to CommonMark -Since 11.1, GitLab uses 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. Since 11.3, wiki pages and Markdown files (`*.md`) in -repositories are also processed with CommonMark. As of 11.8, the [Redcarpet Ruby library](https://github.com/vmg/redcarpet) -has been removed and all issues and comments, including those from pre-11.1, are now processed -using the [CommonMark Ruby Library](https://github.com/gjtorikian/commonmarker). - -The documentation website had its [Markdown engine migrated from Redcarpet to Kramdown](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/108) +- 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. + +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 were written using some of the nuances of the GitLab RedCarpet version -of Markdown. Since CommonMark uses slightly stricter syntax, these documents -might now appear a little differently since we have transitioned to CommonMark. +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: @@ -80,23 +83,24 @@ character of the top list item (`C` in this case): We flag any significant differences between Redcarpet and CommonMark Markdown in this document. -If you have a large volume of Markdown files, it can be tedious to determine +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 (not an officially supported product) to generate a list of files and the -differences between how RedCarpet and CommonMark render the files. It gives -an indication if anything needs to be changed - often nothing needs -to change. +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. ### GFM extends standard Markdown -GitLab makes full use of the standard (CommonMark) formatting, but also includes additional -functionality useful for GitLab users. +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-gfm-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) - [Front matter](#front-matter) @@ -124,7 +128,7 @@ changing how standard Markdown is used: ### Colors -If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#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). It's possible to have color written in HEX, RGB, or HSL format rendered with a color indicator. @@ -168,9 +172,12 @@ It's also possible to use [Kroki](https://kroki.io) to create a wide variety of > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15107) in GitLab 10.3. -Visit the [official page](https://mermaidjs.github.io/) for more details. If you're new to using Mermaid or need help identifying issues in your Mermaid code, the [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) is a helpful tool for creating and resolving issues within Mermaid diagrams. +Visit the [official page](https://mermaidjs.github.io/) for more details. The +[Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) helps you +learn Mermaid and debug issues in your Mermaid code. Use it to identify and resolve +issues in your diagrams. -In order to generate a diagram or flowchart, you should write your text inside the `mermaid` block: +To generate a diagram or flowchart, write your text inside the `mermaid` block: ````markdown ```mermaid @@ -239,42 +246,46 @@ Read more in the [Kroki integration](../administration/integration/kroki.md) pag ### Emoji -If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#emoji). +If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#emoji). ```markdown Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: :zap: You can use emoji anywhere GFM is supported. :v: -You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that. +You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People :heart: you for that. If you're new to this, don't be :fearful:. You can join the emoji :family:. All you need to do is to look up one of the supported codes. Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup: ``` -Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/monkey.png" width="20px" height="20px" style="display:inline;margin:0"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/star2.png" width="20px" height="20px" style="display:inline;margin:0"> to your <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/speech_balloon.png" width="20px" height="20px" style="display:inline;margin:0">. Well we have a gift for you: +Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/monkey.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/star2.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> to your <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/speech_balloon.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. Well we have a gift for you: -<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/zap.png" width="20px" height="20px" style="display:inline;margin:0">You can use emoji anywhere GFM is supported. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/v.png" width="20px" height="20px" style="display:inline;margin:0"> +<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/zap.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">You can use emoji anywhere GFM is supported. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/v.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> -You can use it to point out a <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/bug.png" width="20px" height="20px" style="display:inline;margin:0"> or warn about <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/speak_no_evil.png" width="20px" height="20px" style="display:inline;margin:0"> patches. And if someone improves your really <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/snail.png" width="20px" height="20px" style="display:inline;margin:0"> code, send them some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/birthday.png" width="20px" height="20px" style="display:inline;margin:0">. People will <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/heart.png" width="20px" height="20px" style="display:inline;margin:0"> you for that. +You can use it to point out a<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/bug.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> or warn about <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/speak_no_evil.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> patches. If someone improves your really <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/snail.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> code, send them some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/birthday.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. People <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/heart.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> you for that. -If you're new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/fearful.png" width="20px" height="20px" style="display:inline;margin:0">. You can join the emoji <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/family.png" width="20px" height="20px" style="display:inline;margin:0">. All you need to do is to look up one of the supported codes. +If you're new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/fearful.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. You can join the emoji <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/family.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. All you need to do is to look up one of the supported codes. -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"> +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 -The emoji example above uses hard-coded images for this documentation. The emoji, -when rendered within GitLab, may appear different depending on the OS and browser used. +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. Most emoji are natively supported on macOS, Windows, iOS, Android, and fall back on image-based emoji where there is no support. +<!-- vale gitlab.Spelling = NO --> + On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) to get full native emoji support. Ubuntu 18.04 (like many modern Linux distributions) has this font installed by default. +<!-- vale gitlab.Spelling = YES --> + ### Front matter > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23331) in GitLab 11.6. @@ -284,8 +295,9 @@ its content. This data can be used by static site generators such as [Jekyll](ht [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, -in a box at the top of the document, before the rendered HTML content. 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). +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). In GitLab, front matter is only used 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 @@ -340,7 +352,7 @@ $example = array( ### Inline diff -If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#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). With inline diff tags you can display `{+ additions +}` or `[- deletions -]`. @@ -413,7 +425,7 @@ the [Asciidoctor user manual](https://asciidoctor.org/docs/user-manual/#activati ### Special GitLab references GFM recognizes special GitLab related references. For example, you can reference -an issue, a commit, a team member, or even the whole team within a project. GFM turns +an issue, a commit, a team member, or even an entire project team. GFM turns that reference into a link so you can navigate between them. Additionally, GFM recognizes certain cross-project references and also has a shorthand @@ -421,7 +433,7 @@ version to reference other projects from the same namespace. GFM recognizes the following: -| references | input | cross-project reference | shortcut within same namespace | +| references | input | cross-project reference | shortcut inside same namespace | | :------------------------------ | :------------------------- | :-------------------------------------- | :----------------------------- | | specific user | `@user_name` | | | | specific group | `@group_name` | | | @@ -432,6 +444,7 @@ GFM recognizes the following: | 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"` | @@ -447,8 +460,8 @@ GFM recognizes the following: 1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222483) in GitLab 13.7. -For example, referencing an issue by using `#123` will format the output as a link -to issue number 123 with text `#123`. Likewise, a link to issue number 123 will be +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`. In addition to this, links to some objects are also recognized and formatted. Some examples of these are: @@ -459,12 +472,12 @@ In addition to this, links to some objects are also recognized and formatted. So ### Task lists -If this section is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#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). -You can add task lists anywhere Markdown is supported, but you can only "click" -to toggle the boxes if they are in issues, merge requests, or comments. In other -places you must edit the Markdown manually to change the status by adding or -removing an `x` within the square brackets. +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. To create a task list, add a specially-formatted Markdown list. You can use either unordered or ordered lists: @@ -482,13 +495,13 @@ unordered or ordered lists: 1. [x] Sub-task 2 ``` - + ### Table of contents -You can add a table of contents to a Markdown file, wiki page, or issue/merge request -description, by adding the tag `[[_TOC_]]` on its own line. -It appears as an unordered list that links to the various headers. +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. ```markdown This is an intro sentence to my Wiki page. @@ -504,7 +517,7 @@ First section content. Second section content. ``` - + ### Wiki-specific Markdown @@ -583,38 +596,39 @@ This snippet links to `<wiki_root>/miscellaneous.md`: ### Embedding metrics in GitLab Flavored Markdown -Metric charts can be embedded within GitLab Flavored Markdown. See [Embedding Metrics within GitLab flavored Markdown](../operations/metrics/embed.md) for more details. +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 -All standard Markdown formatting should work as expected within GitLab. Some standard +All standard Markdown formatting should work as expected in GitLab. Some standard functionality is extended with additional features, without affecting the standard usage. If a functionality is extended, the new option is listed as a sub-section. ### Blockquotes -Blockquotes are useful to highlight information, such as a side-note. It's generated +Use a blockquote to highlight information, such as a side note. It's generated by starting the lines of the blockquote with `>`: ```markdown -> Blockquotes are very handy to emulate reply text. +> Blockquotes help you emulate reply text. > This line is part of the same quote. Quote break. -> This is a very long line that is still quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. +> This is a very long line that is still quoted properly when it wraps. Keep writing to make sure this line is long enough to actually wrap for everyone. You can also *add* **Markdown** into a blockquote. ``` -> Blockquotes are very handy to emulate reply text. +> Blockquotes help you emulate reply text. > This line is part of the same quote. Quote break. -> This is a very long line that is still quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. +> This is a very long line that is still quoted properly when it wraps. Keep writing to make sure this line is long enough to actually wrap for everyone. You can also *add* **Markdown** into a blockquote. #### Multiline blockquote -If this section is not 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). GFM extends the standard Markdown by also supporting multi-line blockquotes fenced by `>>>`: @@ -639,9 +653,9 @@ you can quote that without having to manually prepend `>` to every line! ### Code spans and blocks -You can highlight anything that should be viewed as code and not simple text. +You can highlight anything that should be viewed as code and not standard text. -Simple inline code is highlighted with single backticks `` ` ``: +Inline code is highlighted with single backticks `` ` ``: ```markdown Inline `code` has `back-ticks around` it. @@ -651,9 +665,11 @@ Inline `code` has `back-ticks around` it. --- -Similarly, a whole block of code can be fenced with triple backticks (```` ``` ````), -triple tildes (`~~~`), or indented 4 or more spaces to achieve a similar effect for -a larger body of code. +To achieve a similar effect for a larger code example, you can: + +- Fence an entire block of code with triple backticks (```` ``` ````). +- Fence an entire block of code with triple tildes (`~~~`). +- Indent it four or more spaces. ````markdown ```python @@ -695,16 +711,16 @@ Tildes are OK too. #### Colored code and syntax highlighting -If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#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). 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 [Rouge project wiki](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers). -Syntax highlighting is only supported in code blocks, so it's not possible to highlight -code when it's inline. +Syntax highlighting is supported only in code blocks, so you can't highlight inline code. -Blocks of code are fenced by lines with three back-ticks (```` ``` ````) or three tildes (`~~~`), and have -the language identified at the end of the first fence: +To fence and apply syntax highlighting to a block of code, append the code language +to the opening code declaration, three back-ticks (```` ``` ````) or three tildes (`~~~`): ````markdown ```javascript @@ -761,7 +777,7 @@ But let's throw in a <b>tag</b>. ### Emphasis There are multiple ways to emphasize text in Markdown. You can italicize, bold, strikethrough, -as well as combine these emphasis styles together. +and combine these emphasis styles together. Strikethrough is not part of the core Markdown standard, but is part of GFM. Examples: @@ -786,10 +802,11 @@ Strikethrough uses two tildes. ~~Scratch this.~~ #### Multiple underscores in words and mid-word emphasis -If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#multiple-underscores-in-words). +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). -It's not usually useful to italicize just _part_ of a word, especially when you're -dealing with code and names that often appear with multiple underscores. As a result, +Avoid italicizing a portion of a word, especially when you're +dealing with code and names that often appear with multiple underscores. GFM extends the standard Markdown standard by ignoring multiple underlines in words, to allow better rendering of Markdown documents discussing code: @@ -922,8 +939,7 @@ emoji is converted to an image which is then removed from the ID. ### Horizontal Rule -It's very simple to create a horizontal rule, by using three or more hyphens, asterisks, -or underscores: +Create a horizontal rule by using three or more hyphens, asterisks, or underscores: ```markdown Three or more hyphens, @@ -978,7 +994,7 @@ Do not change to a reference style link. #### Videos -If this section is not 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`: @@ -995,7 +1011,7 @@ Here's a sample video: #### Audio -If this section is not 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`: @@ -1012,7 +1028,8 @@ Here's a sample audio clip: ### Inline HTML -To see the Markdown rendered within HTML in the second example, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#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). You can also use raw HTML in your Markdown, and it usually works pretty well. @@ -1076,11 +1093,12 @@ Markdown is fine in GitLab. #### Details and summary -To see the Markdown rendered within HTML in the second example, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#details-and-summary). +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). 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) -tags. This is especially useful for collapsing long logs so they take up less screen space. +tags. For example, collapse a long log file so it takes up less screen space. ```html <p> @@ -1108,7 +1126,7 @@ These details <em>remain</em> <strong>hidden</strong> until expanded. --- -Markdown inside these tags is supported as well. +Markdown inside these tags is also supported. NOTE: If your Markdown isn't rendering correctly, try adding @@ -1150,7 +1168,7 @@ These details <em>remain</em> <b>hidden</b> until expanded. A line break is inserted (a new paragraph starts) if the previous text is ended with two newlines, like when you hit <kbd>Enter</kbd> twice in a row. If you only use one newline (hit <kbd>Enter</kbd> once), the next sentence remains part of the -same paragraph. This is useful if you want to keep long lines from wrapping, and keep +same paragraph. Use this approach if you want to keep long lines from wrapping, and keep them editable: ```markdown @@ -1180,7 +1198,7 @@ GFM adheres to the Markdown specification in how [paragraphs and line breaks are A paragraph is one or more consecutive lines of text, separated by one or more blank lines (two newlines at the end of the first paragraph), as [explained above](#line-breaks). -If you need more control over line breaks or soft returns, you can add a single line break +Need more control over line breaks or soft returns? Add a single line break by ending a line with a backslash, or two or more spaces. Two newlines in a row create a new paragraph, with a blank line in between: @@ -1268,6 +1286,8 @@ GFM auto-links almost any URL you put into your text: - http://localhost:3000 ``` +<!-- vale gitlab.Spelling = NO --> + - <https://www.google.com> - <https://www.google.com> - <ftp://ftp.us.debian.org/debian/> @@ -1275,6 +1295,7 @@ GFM auto-links almost any URL you put into your text: - <irc://irc.freenode.net/> - <http://localhost:3000> +<!-- vale gitlab.Spelling = YES --> ### Lists Ordered and unordered lists can be created. @@ -1397,17 +1418,21 @@ Example: ### Superscripts / Subscripts -Currently, CommonMark and GFM don't support the superscript syntax ( `x^2` ) that -Redcarpet does. You can use the standard HTML syntax for superscripts and subscripts: +CommonMark and GFM don't support the Redcarpet superscript syntax ( `x^2` ). +Use the standard HTML syntax for superscripts and subscripts: ```html The formula for water is H<sub>2</sub>O while the equation for the theory of relativity is E = mc<sup>2</sup>. ``` +<!-- vale gitlab.Spelling = NO --> + The formula for water is H<sub>2</sub>O while the equation for the theory of relativity is E = mc<sup>2</sup>. +<!-- vale gitlab.Spelling = YES --> + ### Tables Tables are not part of the core Markdown spec, but they are part of GFM. @@ -1437,7 +1462,7 @@ Example: | 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 | -Additionally, you can choose the alignment of text within columns by adding colons (`:`) +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 @@ -1452,7 +1477,7 @@ to the sides of the "dash" lines in the second row. This affects every cell in t | Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 5 | Cell 6 | | Cell 7 | Cell 8 | Cell 9 | Cell 10 | Cell 11 | Cell 12 | -[Within 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 @@ -1470,7 +1495,7 @@ use `<br>` tags to force a cell to have multiple lines: | Item1 | This is on one line | | Item2 | This item has:<br>- Multiple items<br>- That we want listed separately | -You can use HTML formatting within GitLab itself to add [task lists](#task-lists) with checkboxes, +You can use HTML formatting in GitLab itself to add [task lists](#task-lists) with checkboxes, but they do not render properly on `docs.gitlab.com`: ```markdown @@ -1485,8 +1510,8 @@ but they do not render properly on `docs.gitlab.com`: [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27205) in GitLab 12.7. If you're working in spreadsheet software (for example, Microsoft Excel, Google -Sheets, or Apple Numbers), you can copy from a spreadsheet, and GitLab -pastes it as a Markdown table. For example, suppose you have the +Sheets, or Apple Numbers), GitLab creates a Markdown table when you copy-and-paste +from a spreadsheet. For example, suppose you have the following spreadsheet:  @@ -1502,4 +1527,4 @@ entry and paste the spreadsheet: - The original [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax) 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/) is a handy tool for testing CommonMark syntax. +- The [CommonMark Dingus](https://spec.commonmark.org/dingus/) helps you test CommonMark syntax. diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index bef768cad4e..be3454dbd02 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -6,23 +6,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Operations Dashboard **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5781) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/9218) to [GitLab Premium](https://about.gitlab.com/pricing/) in 11.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5781) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/9218) to [GitLab Premium](https://about.gitlab.com/pricing/) in 11.10. The Operations Dashboard provides a summary of each project's operational health, including pipeline and alert status. -The dashboard can be accessed via the top bar, by clicking **More > Operations**. +The dashboard can be accessed from the top bar, by clicking **More > Operations**. ## Adding a project to the dashboard NOTE: For GitLab.com, you can add your project to the Operations Dashboard for free if your project is public. If your project is private, the group it belongs to must -have a [Silver](https://about.gitlab.com/pricing/) plan. +have a [GitLab Premium](https://about.gitlab.com/pricing/) plan. To add a project to the dashboard: -1. Click the **Add projects** button in the homescreen of the dashboard. +1. Ensure your alerts + [populate the `gitlab_environment_name` field](../../operations/metrics/alerts.md#external-prometheus-instances). + In GitLab 13.9, you can display alerts for the `production` environment only. +1. Click the **Add projects** button in the home screen of the dashboard. 1. Search and add one or more projects using the **Search your projects** field. 1. Click the **Add projects** button. diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 6159ea395fa..f935fa87d68 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -4,10 +4,10 @@ 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 --- -# Composer packages in the Package Registry +# Composer packages in the Package Registry **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in GitLab Premium 13.2. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. Publish [Composer](https://getcomposer.org/) packages in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. @@ -273,5 +273,5 @@ Output indicates that the package has been successfully installed. WARNING: Never commit the `auth.json` file to your repository. To install packages from a CI/CD job, consider using the [`composer config`](https://getcomposer.org/doc/articles/handling-private-packages.md#satis) tool with your personal access token -stored in a [GitLab CI/CD environment variable](../../../ci/variables/README.md) or in +stored in a [GitLab CI/CD variable](../../../ci/variables/README.md) or in [HashiCorp Vault](../../../ci/secrets/index.md). diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index f90c220a622..c115f94b964 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -4,12 +4,12 @@ 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 --- -# Conan packages in the Package Registry +# Conan packages in the Package Registry **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8248) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8248) in GitLab Premium 12.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. -Publish Conan packages in your project’s Package Registry. Then install the +Publish Conan packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency. To publish Conan packages to the Package Registry, add the Package Registry as a @@ -98,7 +98,8 @@ For more details about creating and managing Conan packages, see the ## Add the Package Registry as a Conan remote To run `conan` commands, you must add the Package Registry as a Conan remote for -your project or instance. +your project or instance. Then you can publish packages to +and install packages from the Package Registry. ### Add a remote for your project @@ -170,13 +171,13 @@ convention. ## Authenticate to the Package Registry -To authenticate to the Package Registry, you need either a personal access token -or deploy token. +To authenticate to the Package Registry, you need one of the following: -- If you use a [personal access token](../../../user/profile/personal_access_tokens.md), - set the scope to `api`. -- If you use a [deploy token](../../project/deploy_tokens/index.md), set the - scope to `read_package_registry`, `write_package_registry`, or both. +- A [personal access token](../../../user/profile/personal_access_tokens.md) + with the scope set to `api`. +- A [deploy token](../../project/deploy_tokens/index.md) with the + scope set to `read_package_registry`, `write_package_registry`, or both. +- A [CI job token](#publish-a-conan-package-by-using-cicd). ### Add your credentials to the GitLab remote @@ -278,10 +279,19 @@ create_package: Additional Conan images to use as the basis of your CI file are available in the [Conan docs](https://docs.conan.io/en/latest/howtos/run_conan_in_docker.html#available-docker-images). +### Re-publishing a package with the same recipe + +When you publish a package that has the same recipe (`package-name/version@user/channel`) +as an existing package, the duplicate files are uploaded successfully and +are accessible through the UI. However, when the package is installed, +only the most recently-published package is returned. + ## Install a Conan package Install a Conan package from the Package Registry so you can use it as a -dependency. +dependency. You can install a package from the scope of your instance or your project. +If multiple packages have the same recipe, when you install +a package, the most recently-published package is retrieved. WARNING: Project-level packages [cannot be downloaded currently](https://gitlab.com/gitlab-org/gitlab/-/issues/270129). diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 8c284ccb9a3..e3a469c4b6c 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -144,7 +144,7 @@ Before you can build and push images by using GitLab CI/CD, you must authenticat To use CI/CD to authenticate, you can use: -- The `CI_REGISTRY_USER` variable. +- The `CI_REGISTRY_USER` CI/CD variable. This variable has read-write access to the Container Registry and is valid for one job only. Its password is also automatically created and assigned to `CI_REGISTRY_PASSWORD`. @@ -209,7 +209,7 @@ build: - docker push $CI_REGISTRY/group/project/image:latest ``` -You can also make use of [other variables](../../../ci/variables/README.md) to avoid hard-coding: +You can also make use of [other CI/CD variables](../../../ci/variables/README.md) to avoid hard-coding: ```yaml build: @@ -382,7 +382,7 @@ The following example defines two stages: `build`, and `clean`. The `build_image` job builds the Docker image for the branch, and the `delete_image` job deletes it. The `reg` executable is downloaded and used to remove the image matching the `$CI_PROJECT_PATH:$CI_COMMIT_REF_SLUG` -[environment variable](../../../ci/variables/predefined_variables.md). +[predefined CI/CD variable](../../../ci/variables/predefined_variables.md). To use this example, change the `IMAGE_TAG` variable to match your needs: @@ -559,18 +559,70 @@ Here are examples of regex patterns you may want to use: v.+ ``` -- Match tags that contain `master`: +- Match only the tag named `master`: ```plaintext master ``` -- Match tags that either start with `v`, contain `master`, or contain `release`: +- Match tags that are either named or start with `release`: ```plaintext - (?:v.+|master|release) + release.* ``` +- Match tags that either start with `v`, are named `master`, or begin with `release`: + + ```plaintext + (?:v.+|master|release.*) + ``` + +### Set cleanup limits to conserve resources + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/288812) in GitLab 13.9. +> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - It's enabled 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-cleanup-policy-limits). + +Cleanup policies are executed as a background process. This process is complex, and depending on the number of tags to delete, +the process can take time to finish. + +To prevent server resource starvation, the following application settings are available: + +- `container_registry_expiration_policies_worker_capacity`. The maximum number of cleanup workers running concurrently. This must be greater than `1`. + We recommend starting with a low number and increasing it after monitoring the resources used by the background workers. +- `container_registry_delete_tags_service_timeout`. The maximum time, in seconds, that the cleanup process can take to delete a batch of tags. +- `container_registry_cleanup_tags_service_max_list_size`. The maximum number of tags that can be deleted in a single execution. Additional tags must be deleted in another execution. + We recommend starting with a low number, like `100`, and increasing it after monitoring that container images are properly deleted. + +For self-managed instances, those settings can be updated in the [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): + + ```ruby + ApplicationSetting.last.update(container_registry_expiration_policies_worker_capacity: 3) + ``` + +Alternatively, once the limits are [enabled](#enable-or-disable-cleanup-policy-limits), they are available in the [admin area](../../admin_area/index.md) **Settings > CI/CD > Container Registry**. + +#### Enable or disable cleanup policy limits + +The cleanup policies limits are under development and not ready for production use. They are +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(:container_registry_expiration_policies_throttling) +``` + +To disable it: + +```ruby +Feature.disable(:container_registry_expiration_policies_throttling) +``` + ### Use the cleanup policy API You can set, update, and disable the cleanup policies using the GitLab API. @@ -603,7 +655,7 @@ If you see the following message: Check the regex patterns to ensure they are valid. -You can use [Rubular](https://rubular.com/) to check your regex. +GitLab uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax) for regular expressions in the cleanup policy. You can test them with the [regex101 regex tester](https://regex101.com/). View some common [regex pattern examples](#regex-pattern-examples). ## Use the Container Registry to store Helm Charts diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index 5e5aadfae2b..fdf0caba090 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -35,7 +35,7 @@ The following images and packages are supported. | Docker | 11.11+ | For a list of planned additions, view the -[direction page](https://about.gitlab.com/direction/package/dependency_proxy/#top-vision-items). +[direction page](https://about.gitlab.com/direction/package/#dependency-proxy). ## Enable the Dependency Proxy @@ -64,7 +64,7 @@ Prerequisites: > - 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](../../../administration/packages/dependency_proxy.md#disabling-authentication). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](../../../administration/packages/dependency_proxy.md#disabling-authentication). **(FREE SELF)** WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -91,94 +91,35 @@ You can authenticate using: #### Authenticate within CI/CD -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280582) in GitLab 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280582) in GitLab 13.7. +> - Automatic runner authentication [added](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27302) in GitLab 13.9. -To work with the Dependency Proxy in [GitLab CI/CD](../../../ci/README.md), you can use: - -- `CI_DEPENDENCY_PROXY_USER`: A CI user for logging in to the Dependency Proxy. -- `CI_DEPENDENCY_PROXY_PASSWORD`: A CI password for logging in to the Dependency Proxy. -- `CI_DEPENDENCY_PROXY_SERVER`: The server for logging in to the Dependency Proxy. -- `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX`: The image prefix for pulling images through the Dependency Proxy. - -This script shows how to use these variables to log in and pull an image from the Dependency Proxy: +Runners log in to the Dependency Proxy automatically. To pull through +the Dependency Proxy, use the `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` +[predefined CI/CD variable](../../../ci/variables/predefined_variables.md): ```yaml # .gitlab-ci.yml - -dependency-proxy-pull-master: - # Official docker image. - image: docker:latest - stage: build - services: - - docker:dind - before_script: - - docker login -u "$CI_DEPENDENCY_PROXY_USER" -p "$CI_DEPENDENCY_PROXY_PASSWORD" "$CI_DEPENDENCY_PROXY_SERVER" - script: - - docker pull "$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX"/alpine:latest +image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/node:latest ``` -`CI_DEPENDENCY_PROXY_SERVER` and `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` include the server port. So if you use `CI_DEPENDENCY_PROXY_SERVER` to log in, for example, you must explicitly include the port in your pull command and vice-versa: +There are other additional predefined CI/CD variables you can also use: + +- `CI_DEPENDENCY_PROXY_USER`: A CI/CD user for logging in to the Dependency Proxy. +- `CI_DEPENDENCY_PROXY_PASSWORD`: A CI/CD password for logging in to the Dependency Proxy. +- `CI_DEPENDENCY_PROXY_SERVER`: The server for logging in to the Dependency Proxy. +- `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX`: The image prefix for pulling images through the Dependency Proxy. + +`CI_DEPENDENCY_PROXY_SERVER` and `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` +include the server port. If you explicitly include the Dependency Proxy +path, the port must be included, unless you have logged into the Dependency +Proxy manually without including the port: ```shell docker pull gitlab.example.com:443/my-group/dependency_proxy/containers/alpine:latest ``` -You can also use [custom environment variables](../../../ci/variables/README.md#custom-environment-variables) to store and access your personal access token or other valid credentials. - -##### Authenticate with `DOCKER_AUTH_CONFIG` - -You can use the Dependency Proxy to pull your base image. - -1. [Create a `DOCKER_AUTH_CONFIG` environment variable](../../../ci/docker/using_docker_images.md#define-an-image-from-a-private-container-registry). -1. Get credentials that allow you to log into the Dependency Proxy. -1. Generate the version of these credentials that will be used by Docker: - - ```shell - # The use of "-n" - prevents encoding a newline in the password. - echo -n "my_username:my_password" | base64 - - # Example output to copy - bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= - ``` - - This can also be a [personal access token](../../../user/profile/personal_access_tokens.md) such as: - - ```shell - echo -n "my_username:personal_access_token" | base64 - ``` - -1. Create a [custom environment variables](../../../ci/variables/README.md#custom-environment-variables) -named `DOCKER_AUTH_CONFIG` with a value of: - - ```json - { - "auths": { - "https://gitlab.example.com": { - "auth": "(Base64 content from above)" - } - } - } - ``` - - To use `$CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` when referencing images, you must explicitly include the port in your `DOCKER_AUTH_CONFIG` value: - - ```json - { - "auths": { - "https://gitlab.example.com:443": { - "auth": "(Base64 content from above)" - } - } - } - ``` - -1. Now reference the Dependency Proxy in your base image: - - ```yaml - # .gitlab-ci.yml - image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/node:latest - ... - ``` +You can also use [custom CI/CD variables](../../../ci/variables/README.md#custom-cicd-variables) to store and access your personal access token or other valid credentials. ### Store a Docker image in Dependency Proxy cache @@ -284,3 +225,19 @@ RateLimit-Remaining: 98;w=21600 ``` This example shows the total limit of 100 pulls in six hours, with 98 pulls remaining. + +#### Check the rate limit in a CI/CD job + +This example shows a GitLab CI/CD job that uses an image with `jq` and `curl` installed: + +```yaml +hub_docker_quota_check: + stage: build + image: alpine:latest + tags: + - <optional_runner_tag> + before_script: apk add curl jq + script: + - | + TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq --raw-output .token) && curl --head --header "Authorization: Bearer $TOKEN" "https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest" 2>&1 +``` diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 82c72481984..73b84c04b6d 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -4,7 +4,7 @@ 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 --- -# GitLab Generic Packages Repository **(CORE)** +# GitLab Generic Packages Repository **(FREE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4209) in GitLab 13.5. > - It's [deployed behind a feature flag](../../../user/feature_flags.md), enabled by default. @@ -48,7 +48,8 @@ PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name | `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/README.md#namespaced-path-encoding). | | `package_name` | string | yes | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), or underscores (`_`). | `package_version` | string | yes | The package version. It can contain only numbers (`0-9`), and dots (`.`). Must be in the format of `X.Y.Z`, i.e. should match `/\A\d+\.\d+\.\d+\z/` regular expression. -| `file_name` | string | yes | The file name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), or underscores (`_`). +| `file_name` | string | yes | The filename. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), or underscores (`_`). +| `status` | string | no | The package status. It can be `default` (default) or `hidden`. Hidden packages do not appear in the UI or [package API list endpoints](../../../api/packages.md). Provide the file context in the request body. @@ -87,7 +88,7 @@ GET /projects/:id/packages/generic/:package_name/:package_version/:file_name | `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/README.md#namespaced-path-encoding). | | `package_name` | string | yes | The package name. | | `package_version` | string | yes | The package version. | -| `file_name` | string | yes | The file name. | +| `file_name` | string | yes | The filename. | The file context is served in the response body. The response content type is `application/octet-stream`. diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index 87cd4a4a9a6..c9397f8d9f6 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -4,14 +4,14 @@ 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 --- -# Go proxy for GitLab +# Go proxy for GitLab **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27376) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27376) in GitLab Premium 13.1. > - It's deployed behind a feature flag, disabled by default. > - It's disabled for 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-the-go-proxy). -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. With the Go proxy for GitLab, every project in GitLab can be fetched with the [Go proxy protocol](https://proxy.golang.org/). diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index 9da14842845..d2bd9ef5646 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -20,7 +20,7 @@ The Package Registry supports the following formats: <tr><td><a href="https://docs.gitlab.com/ee/user/packages/conan_repository/index.html">Conan</a></td><td>12.6+</td></tr> <tr><td><a href="https://docs.gitlab.com/ee/user/packages/go_proxy/index.html">Go</a></td><td>13.1+</td></tr> <tr><td><a href="https://docs.gitlab.com/ee/user/packages/maven_repository/index.html">Maven</a></td><td>11.3+</td></tr> -<tr><td><a href="https://docs.gitlab.com/ee/user/packages/npm_registry/index.html">NPM</a></td><td>11.7+</td></tr> +<tr><td><a href="https://docs.gitlab.com/ee/user/packages/npm_registry/index.html">npm</a></td><td>11.7+</td></tr> <tr><td><a href="https://docs.gitlab.com/ee/user/packages/nuget_repository/index.html">NuGet</a></td><td>12.8+</td></tr> <tr><td><a href="https://docs.gitlab.com/ee/user/packages/pypi_repository/index.html">PyPI</a></td><td>12.10+</td></tr> <tr><td><a href="https://docs.gitlab.com/ee/user/packages/generic_packages/index.html">Generic packages</a></td><td>13.5+</td></tr> @@ -35,6 +35,8 @@ You can also use the [API](../../api/packages.md) to administer the Package Regi The below table lists formats that are not supported, but are accepting Community contributions for. Consider contributing to GitLab. This [development documentation](../../development/packages.md) guides you through the process. +<!-- vale gitlab.Spelling = NO --> + | Format | Status | | ------ | ------ | | Chef | [#36889](https://gitlab.com/gitlab-org/gitlab/-/issues/36889) | @@ -51,6 +53,7 @@ guides you through the process. | Terraform | [WIP: 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 --> ## Container Registry 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. diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index e0f5a400977..828eec812fa 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -4,10 +4,10 @@ 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 --- -# Maven packages in the Package Repository +# Maven packages in the Package Repository **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5811) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5811) in GitLab Premium 11.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. Publish [Maven](https://maven.apache.org) artifacts in your project’s Package Registry. Then, install the packages whenever you need to use them as a dependency. @@ -186,10 +186,11 @@ published to the GitLab Package Registry. ## Authenticate to the Package Registry with Maven -To authenticate to the Package Registry, you need either a personal access token or deploy token. +To authenticate to the Package Registry, you need one of the following: -- If you use a [personal access token](../../../user/profile/personal_access_tokens.md), set the scope to `api`. -- If you use a [deploy token](../../project/deploy_tokens/index.md), set the scope to `read_package_registry`, `write_package_registry`, or both. +- A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api`. +- A [deploy token](../../project/deploy_tokens/index.md) with the scope set to `read_package_registry`, `write_package_registry`, or both. +- A [CI_JOB_TOKEN](#authenticate-with-a-ci-job-token-in-maven). ### Authenticate with a personal access token in Maven @@ -219,7 +220,7 @@ The `name` must be `Private-Token`. ### Authenticate with a deploy token in Maven > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) deploy token authentication in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. To use a deploy token, add this section to your [`settings.xml`](https://maven.apache.org/settings.html) file. @@ -354,12 +355,13 @@ repositories { To use the GitLab endpoint for Maven packages, choose an option: -- **Project-level**: Use when you have few Maven packages and they are not in - the same GitLab group. -- **Group-level**: Use when you have many Maven packages in the same GitLab - group. -- **Instance-level**: Use when you have many Maven packages in different - GitLab groups or in their own namespace. +- **Project-level**: To publish Maven packages to a project, use a project-level endpoint. + To install Maven packages, use a project-level endpoint when you have few Maven packages + and they are not in the same GitLab group. +- **Group-level**: Use a group-level endpoint when you want to install packages from + many different projects in the same GitLab group. +- **Instance-level**: Use an instance-level endpoint when you want to install many + packages from different GitLab groups or in their own namespace. The option you choose determines the settings you add to your `pom.xml` file. @@ -414,7 +416,7 @@ repositories { ### Group-level Maven endpoint > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8798) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. If you rely on many packages, it might be inefficient to include the `repository` section with a unique URL for each package. Instead, you can use the group-level endpoint for @@ -462,7 +464,7 @@ repositories { ``` - For the `id`, use what you [defined in `settings.xml`](#authenticate-to-the-package-registry-with-maven). -- For `my-group`, use your group name. +- For `GROUP_ID`, use your group ID, which you can view on your group's home page. - For `PROJECT_ID`, use your project ID, which you can view on your project's home page. - Replace `gitlab.example.com` with your domain name. - For retrieving artifacts, use either the @@ -472,7 +474,7 @@ repositories { ### Instance-level Maven endpoint > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8274) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. If you rely on many packages, it might be inefficient to include the `repository` section with a unique URL for each package. Instead, you can use the instance-level endpoint for @@ -533,7 +535,7 @@ repositories { After you have set up the [remote and authentication](#authenticate-to-the-package-registry-with-maven) and [configured your project](#use-the-gitlab-endpoint-for-maven-packages), -publish a Maven artifact from your project. +publish a Maven package to your project. ### Publish by using Maven @@ -604,11 +606,35 @@ To publish a package by using Gradle: Now navigate to your project's **Packages & Registries** page and view the published artifacts. +### 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. + +#### Do not allow duplicate Maven packages + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296895) in GitLab Free 13.9. + +To prevent users from publishing duplicate Maven packages, you can use the [GraphQl API](../../../api/graphql/reference/index.md#packagesettings) or the UI. + +In the UI: + +1. For your group, go to **Settings > Packages & Registries**. +1. Expand the **Package Registry** section. +1. Turn on the **Reject duplicates** toggle. +1. Optional. To allow some duplicate packages, in the **Exceptions** box, enter a regex pattern that matches the names of packages you want to allow. + +Your changes are automatically saved. + ## Install a package To install a package from the GitLab Package Registry, you must configure the [remote and authenticate](#authenticate-to-the-package-registry-with-maven). -When this is completed, there are two ways to install a package. +When this is completed, you can install a package from a project, +group, or namespace. + +If multiple packages have the same name and version, when you install +a package, the most recently-published package is retrieved. ### Use Maven with `mvn install` @@ -706,7 +732,7 @@ You can create a new package each time the `master` branch is updated. ``` 1. Make sure your `pom.xml` file includes the following. - You can either let Maven use the CI environment variables, as shown in this example, + You can either let Maven use the [predefined CI/CD variables](../../../ci/variables/predefined_variables.md), as shown in this example, or you can hard code your server's hostname and project's ID. ```xml @@ -745,7 +771,7 @@ The next time the `deploy` job runs, it copies `ci_settings.xml` to the user's home location. In this example: - The user is `root`, because the job runs in a Docker container. -- Maven uses the configured CI [environment variables](../../../ci/variables/README.md#predefined-environment-variables). +- Maven uses the configured CI/CD variables. ### Create Maven packages with GitLab CI/CD by using Gradle diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index c16fea1d00a..b1075e19b7b 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -4,37 +4,37 @@ 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 --- -# NPM packages in the Package Registry +# npm packages in the Package Registry **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5934) in GitLab Premium 11.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. -Publish NPM packages in your project's Package Registry. Then install the +Publish npm packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency. Only [scoped](https://docs.npmjs.com/misc/scope/) packages are supported. -## Build an NPM package +## Build an npm package -This section covers how to install NPM or Yarn and build a package for your +This section covers how to install npm or Yarn and build a package for your JavaScript project. -If you already use NPM and know how to build your own packages, go to +If you already use npm and know how to build your own packages, go to the [next section](#authenticate-to-the-package-registry). -### Install NPM +### Install npm -Install Node.js and NPM in your local development environment by following +Install Node.js and npm in your local development environment by following the instructions at [npmjs.com](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/). -When installation is complete, verify you can use NPM in your terminal by +When installation is complete, verify you can use npm in your terminal by running: ```shell npm --version ``` -The NPM version is shown in the output: +The npm version is shown in the output: ```plaintext 6.10.3 @@ -42,7 +42,7 @@ The NPM version is shown in the output: ### Install Yarn -As an alternative to NPM, you can install Yarn in your local environment by following the +As an alternative to npm, you can install Yarn in your local environment by following the instructions at [yarnpkg.com](https://classic.yarnpkg.com/en/docs/install). When installation is complete, verify you can use Yarn in your terminal by @@ -81,13 +81,13 @@ To create a project: A `package.json` file is created. -## Use the GitLab endpoint for NPM packages +## Use the GitLab endpoint for npm packages -To use the GitLab endpoint for NPM packages, choose an option: +To use the GitLab endpoint for npm packages, choose an option: -- **Project-level**: Use when you have few NPM packages and they are not in +- **Project-level**: Use when you have few npm packages and they are not in the same GitLab group. -- **Instance-level**: Use when you have many NPM packages in different +- **Instance-level**: Use when you have many npm packages in different GitLab groups or in their own namespace. Be sure to comply with the [package naming convention](#package-naming-convention). Some features such as [publishing](#publish-an-npm-package) a package is only available on the project-level endpoint. @@ -103,17 +103,17 @@ To authenticate, use one of the following: (required for two-factor authentication (2FA)), with the scope set to `api`. - A [deploy token](../../project/deploy_tokens/index.md), with the scope set to `read_package_registry`, `write_package_registry`, or both. - 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. + 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 To authenticate with the Package Registry, you need a [personal access token](../../profile/personal_access_tokens.md) or [deploy token](../../project/deploy_tokens/index.md). -#### Project-level NPM endpoint +#### Project-level npm endpoint -To use the [project-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, set your NPM configuration: +To use the [project-level](#use-the-gitlab-endpoint-for-npm-packages) npm endpoint, set your npm configuration: ```shell # Set URL for your scoped packages. @@ -129,14 +129,14 @@ npm config set '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/ - `<your_token>` is your personal access token or deploy token. - Replace `gitlab.example.com` with your domain name. -You should now be able to publish and install NPM packages in your project. +You should now be able to publish and install npm packages in your project. If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view [troubleshooting steps](#troubleshooting). -#### Instance-level NPM endpoint +#### Instance-level npm endpoint -To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, set your NPM configuration: +To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) npm endpoint, set your npm configuration: ```shell # Set URL for your scoped packages. @@ -151,7 +151,7 @@ npm config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_tok - `<your_token>` is your personal access token or deploy token. - Replace `gitlab.example.com` with your domain name. -You should now be able to publish and install NPM packages in your project. +You should now be able to publish and install npm packages in your project. If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view [troubleshooting steps](#troubleshooting). @@ -159,23 +159,23 @@ If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view ### Authenticate with a CI job token > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9104) in GitLab Premium 12.5. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. -If you're using NPM with GitLab CI/CD, a CI job token can be used instead of a personal access token or deploy token. +If you're using npm with GitLab CI/CD, a CI job token can be used instead of a personal access token or deploy token. The token inherits the permissions of the user that generates the pipeline. -#### Project-level NPM endpoint +#### Project-level npm endpoint -To use the [project-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, add a corresponding section to your `.npmrc` file: +To use the [project-level](#use-the-gitlab-endpoint-for-npm-packages) npm endpoint, add a corresponding section to your `.npmrc` file: ```ini @foo:registry=https://gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/ //gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN} ``` -#### Instance-level NPM endpoint +#### Instance-level npm endpoint -To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, add a corresponding section to your `.npmrc` file: +To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) npm endpoint, add a corresponding section to your `.npmrc` file: ```ini @foo:registry=https://gitlab.example.com/api/v4/packages/npm/ @@ -199,12 +199,12 @@ Then, you can run `npm publish` either locally or by using GitLab CI/CD. NPM_TOKEN=<your_token> npm publish ``` -- **GitLab CI/CD:** Set an `NPM_TOKEN` [variable](../../../ci/variables/README.md) +- **GitLab CI/CD:** Set an `NPM_TOKEN` [CI/CD variable](../../../ci/variables/README.md) under your project's **Settings > CI/CD > Variables**. ## Package naming convention -Your NPM package name must be in the format of `@scope/package-name`. +Your npm package name must be in the format of `@scope/package-name`. - The `@scope` is the root namespace of the GitLab project. It must match exactly, including the case. - The `package-name` can be whatever you want. @@ -227,26 +227,28 @@ In GitLab, this regex validates all package names from all package managers: /\A\@?(([\w\-\.\+]*)\/)*([\w\-\.]+)@?(([\w\-\.\+]*)\/)*([\w\-\.]*)\z/ ``` -This regex allows almost all of the characters that NPM allows, with a few exceptions (for example, `~` is not allowed). +This regex allows almost all of the characters that npm allows, with a few exceptions (for example, `~` is not allowed). -The regex also allows for capital letters, while NPM does not. Capital letters are needed because the scope must be +The regex also allows for capital letters, while npm does not. Capital letters are needed because the scope must be identical to the root namespace of the project. WARNING: When you update the path of a user or group, or transfer a subgroup or project, -you must remove any NPM packages first. You cannot update the root namespace -of a project with NPM packages. Make sure you update your `.npmrc` files to follow +you must remove any npm packages first. You cannot update the root namespace +of a project with npm packages. Make sure you update your `.npmrc` files to follow the naming convention and run `npm publish` if necessary. -## Publish an NPM package +## Publish an npm package 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). It must match exactly, including the case. +- 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). + 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. -To upload an NPM package to your project, run this command: +To upload an npm package to your project, run this command: ```shell npm publish @@ -257,17 +259,20 @@ To view the package, go to your project's **Packages & Registries**. If you try to publish a package [with a name that already exists](#publishing-packages-with-the-same-name-or-version) within a given scope, you get a `403 Forbidden!` error. -## Publish an NPM package by using CI/CD +## Publish an npm package by using CI/CD Prerequisites: - [Authenticate](#authenticate-to-the-package-registry) to the Package Registry. -- Set a [project-level NPM endpoint](#use-the-gitlab-endpoint-for-npm-packages). +- 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). + 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. -To work with NPM commands within [GitLab CI/CD](../../../ci/README.md), you can use +To work with npm commands within [GitLab CI/CD](../../../ci/README.md), you can use `CI_JOB_TOKEN` in place of the personal access token or deploy token in your commands. -An example `.gitlab-ci.yml` file for publishing NPM packages: +An example `.gitlab-ci.yml` file for publishing npm packages: ```yaml image: node:latest @@ -283,7 +288,7 @@ deploy: ``` See the -[Publish NPM packages to the GitLab Package Registry using semantic-release](../../../ci/examples/semantic-release.md) +[Publish npm packages to the GitLab Package Registry using semantic-release](../../../ci/examples/semantic-release.md) step-by-step guide and demo project for a complete example. ## Publishing packages with the same name or version @@ -296,8 +301,9 @@ the same version more than once, even if it has been deleted. ## Install a package -NPM packages are commonly-installed by using the `npm` or `yarn` commands -in a JavaScript project. +npm packages are commonly-installed by using the `npm` or `yarn` commands +in a JavaScript project. You can install a package from the scope of a project, group, +or instance. 1. Set the URL for scoped packages by running: @@ -309,24 +315,24 @@ in a JavaScript project. 1. Ensure [authentication](#authenticate-to-the-package-registry) is configured. -1. In your project, to install a package, run: +1. To install a package in your project, run: ```shell - npm install @my-project-scope/my-package + npm install @my-scope/my-package ``` Or if you're using Yarn: ```shell - yarn add @my-project-scope/my-package + yarn add @my-scope/my-package ``` In [GitLab 12.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/55344), -when an NPM package is not found in the Package Registry, the request is forwarded to [npmjs.com](https://www.npmjs.com/). +when an npm package is not found in the Package Registry, the request is forwarded to [npmjs.com](https://www.npmjs.com/). Administrators can disable this behavior in the [Continuous Integration settings](../../admin_area/settings/continuous_integration.md). -### Install NPM packages from other organizations +### Install npm packages from other organizations You can route package requests to organizations and users outside of GitLab. @@ -343,12 +349,12 @@ and use your organization's URL. The name is case-sensitive and must match the n //gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken= "<your_token>" ``` -### NPM dependencies metadata +### npm dependencies metadata > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11867) in GitLab Premium 12.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. -In GitLab 12.6 and later, packages published to the Package Registry expose the following attributes to the NPM client: +In GitLab 12.6 and later, packages published to the Package Registry expose the following attributes to the npm client: - name - version @@ -360,10 +366,10 @@ In GitLab 12.6 and later, packages published to the Package Registry expose the - peerDependencies - deprecated -## Add NPM distribution tags +## Add npm distribution tags > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9425) in GitLab Premium 12.8. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. You can add [distribution tags](https://docs.npmjs.com/cli/dist-tag/) to newly-published packages. Tags are optional and can be assigned to only one package at a time. @@ -384,13 +390,13 @@ npm install @scope/package@my-tag # Install a specific tag You cannot use your `CI_JOB_TOKEN` or deploy token with the `npm dist-tag` commands. View [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/258835) for details. -Due to a bug in NPM 6.9.0, deleting distribution tags fails. Make sure your NPM version is 6.9.1 or later. +Due to a bug in npm 6.9.0, deleting distribution tags fails. Make sure your npm version is 6.9.1 or later. ## Troubleshooting -### Error running Yarn with NPM registry +### Error running Yarn with the Package Registry for npm registry -If you are using [Yarn](https://classic.yarnpkg.com/en/) with the NPM registry, you may get +If you are using [Yarn](https://classic.yarnpkg.com/en/) with the npm registry, you may get an error message like: ```shell @@ -419,7 +425,7 @@ yarn config set '//gitlab.example.com/api/v4/projects/<your_project_id>/packages yarn config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_token>" ``` -### `npm publish` targets default NPM registry (`registry.npmjs.org`) +### `npm publish` targets default npm registry (`registry.npmjs.org`) Ensure that your package scope is set consistently in your `package.json` and `.npmrc` files. @@ -430,7 +436,7 @@ should look like: { "name": "@foo/my-package", "version": "1.0.0", - "description": "Example package for GitLab NPM registry", + "description": "Example package for GitLab npm registry", } ``` @@ -442,9 +448,9 @@ And the `.npmrc` file should look like: @foo:registry=https://gitlab.example.com/api/v4/packages/npm/ ``` -### `npm install` returns `Error: Failed to replace env in config: ${NPM_TOKEN}` +### `npm install` returns `Error: Failed to replace env in config: ${npm_TOKEN}` -You do not need a token to run `npm install` unless your project is private. The token is only required to publish. If the `.npmrc` file was checked in with a reference to `$NPM_TOKEN`, you can remove it. If you prefer to leave the reference in, you must set a value prior to running `npm install` or set the value by using [GitLab environment variables](../../../ci/variables/README.md): +You do not need a token to run `npm install` unless your project is private. The token is only required to publish. If the `.npmrc` file was checked in with a reference to `$npm_TOKEN`, you can remove it. If you prefer to leave the reference in, you must set a value prior to running `npm install` or set the value by using [GitLab CI/CD variables](../../../ci/variables/README.md): ```shell NPM_TOKEN=<your_token> npm install @@ -456,7 +462,7 @@ If you get this error, ensure that: - Your token is not expired and has appropriate permissions. - [Your token does not begin with `-`](https://gitlab.com/gitlab-org/gitlab/-/issues/235473). -- A package with the same name doesn't already exist within the given scope. +- A package with the same name or version doesn't already exist within the given scope. - The scoped packages URL includes a trailing slash: - Correct: `//gitlab.example.com/api/v4/packages/npm/` - Incorrect: `//gitlab.example.com/api/v4/packages/npm` diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 35172663cc1..101bb810a0e 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -4,10 +4,10 @@ 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 --- -# NuGet packages in the Package Registry +# NuGet packages in the Package Registry **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20050) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20050) in GitLab Premium 12.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. Publish NuGet packages in your project’s Package Registry. Then, install the packages whenever you need to use them as a dependency. @@ -62,11 +62,13 @@ NuGet CLI. ## Use the GitLab endpoint for NuGet Packages +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36423) group-level endpoint in GitLab 13.8. + To use the GitLab endpoint for NuGet Packages, choose an option: - **Project-level**: Use when you have few NuGet packages and they are not in the same GitLab group. -- **Group-level**: Use when you have many NuGet packages in different within the +- **Group-level**: Use when you have many NuGet packages in different projects within the same GitLab group. Some features such as [publishing](#publish-a-nuget-package) a package are only available on the project-level endpoint. @@ -104,6 +106,9 @@ You can now add a new source to NuGet with: #### Project-level endpoint +A project-level endpoint is required to publish NuGet packages to the Package Registry. +A project-level endpoint is also required to install NuGet packages from a project. + To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with `nuget`: ```shell @@ -120,6 +125,8 @@ nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/proje #### Group-level endpoint +To install a NuGet package from a group, use a group-level endpoint. + To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with `nuget`: ```shell @@ -138,6 +145,9 @@ nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/group #### Project-level endpoint +A project-level endpoint is required to publish NuGet packages to the Package Registry. +A project-level endpoint is also required to install NuGet packages from a project. + To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with Visual Studio: 1. Open [Visual Studio](https://visualstudio.microsoft.com/vs/). @@ -165,6 +175,8 @@ If you get a warning, ensure that the **Location**, **Username**, and #### Group-level endpoint +To install a package from a group, use a group-level endpoint. + To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) NuGet endpoint, add the Package Registry as a source with Visual Studio: 1. Open [Visual Studio](https://visualstudio.microsoft.com/vs/). @@ -194,6 +206,9 @@ If you get a warning, ensure that the **Location**, **Username**, and #### Project-level endpoint +A project-level endpoint is required to publish NuGet packages to the Package Registry. +A project-level endpoint is also required to install NuGet packages from a project. + To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Registry as a source for .NET: 1. In the root of your project, create a file named `nuget.config`. @@ -217,6 +232,8 @@ To use the [project-level](#use-the-gitlab-endpoint-for-nuget-packages) Package #### Group-level endpoint +To install a package from a group, use a group-level endpoint. + To use the [group-level](#use-the-gitlab-endpoint-for-nuget-packages) Package Registry as a source for .NET: 1. In the root of your project, create a file named `nuget.config`. @@ -246,7 +263,7 @@ Prerequisite: When publishing packages: -- The Package Registry on GitLab.com can store up to 500 MB of content. +- The Package Registry on GitLab.com can store up to 5 GB of content. This limit is [configurable for self-managed GitLab instances](../../../administration/instance_limits.md#package-registry-limits). - If you publish the same package with the same version multiple times, each consecutive upload is saved as a separate file. When installing a package, @@ -324,8 +341,19 @@ updated: 1. Commit the changes and push it to your GitLab repository to trigger a new CI/CD build. +### 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. + ## Install packages +To install a NuGet package from the Package Registry, you must first +[add a project-level or group-level endpoint](#add-the-package-registry-as-a-source-for-nuget-packages). + +If multiple packages have the same name and version, when you install +a package, the most recently-published package is retrieved. + ### Install a package with the NuGet CLI WARNING: diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index 5876ef19ad9..19796de0f51 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Package Registry -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. With the GitLab Package Registry, you can use GitLab as a private or public registry for a variety of common package managers. You can publish and share @@ -21,15 +21,21 @@ You can view packages for your project or group. You can search, sort, and filter packages on this page. +When you view packages in a group: + +- All projects 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. ## Use GitLab CI/CD to build packages You can use [GitLab CI/CD](../../../ci/README.md) to build packages. -For Maven, NuGet, NPM, Conan, and PyPI packages, and Composer dependencies, you can +For Maven, NuGet, npm, Conan, and PyPI packages, and Composer dependencies, you can authenticate with GitLab by using the `CI_JOB_TOKEN`. -CI/CD templates, which you can use to get started, are in [this repo](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). +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: @@ -37,7 +43,7 @@ Learn more about using CI/CD to build: - [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) +- [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) If you use CI/CD to build a package, extended activity information is displayed diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 376c0439f32..763dbee3a82 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -4,10 +4,10 @@ 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 --- -# PyPI packages in the Package Registry +# PyPI packages in the Package Registry **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in GitLab Premium 12.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3. Publish PyPI packages in your project’s Package Registry. Then install the packages whenever you need to use them as a dependency. diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index d20c75e2d7a..9b99b126996 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -13,7 +13,7 @@ Then you can configure your remote repositories to point to the project in GitLa You might want to do this because: - You want to publish your packages in GitLab, but to a different project from where your code is stored. -- You want to group packages together in one project. For example, you might want to put all NPM packages, +- You want to group packages together in one project. For example, you might want to put all npm packages, or all packages for a specific department, or all private packages in the same project. - When you install packages for other projects, you want to use one remote. - You want to migrate your packages from a third-party package registry to a single place in GitLab and do not @@ -27,7 +27,7 @@ No functionality is specific to this feature. Instead, we're taking advantage of of each package management system to publish different package types to the same place. - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> - Watch a video of how to add Maven, NPM, and Conan packages to [the same project](https://youtu.be/ui2nNBwN35c). + Watch a video of how to add Maven, npm, and Conan packages to [the same project](https://youtu.be/ui2nNBwN35c). - [View an example project](https://gitlab.com/sabrams/my-package-registry/-/packages). ## Store different package types in one GitLab project @@ -44,14 +44,14 @@ Let's take a look at how you might create a public place to hold all of your pub You can upload all types of packages to the same project, or split things up based on package type or package visibility level. -### NPM +### npm -If you're using NPM, create an `.npmrc` file. Add the appropriate URL for publishing +If you're using npm, create an `.npmrc` file. Add the appropriate URL for publishing packages to your project. Finally, add a section to your `package.json` file. Follow the instructions in the -[GitLab NPM Registry documentation](../npm_registry/index.md#authenticate-to-the-package-registry). After -you do this, you can publish your NPM package to your project using `npm publish`, as described in the +[GitLab Package Registry npm documentation](../npm_registry/index.md#authenticate-to-the-package-registry). After +you do this, you can publish your npm package to your project using `npm publish`, as described in the [publishing packages](../npm_registry/index.md#publish-an-npm-package) section. ### Maven diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 3dbae78ccc4..68a68ed65ad 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -142,13 +142,13 @@ The following table depicts the various user permission levels in a project. | Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | | Run CI/CD pipeline against a protected branch | | | ✓ (*5*) | ✓ | ✓ | | Delete [packages](packages/index.md) | | | | ✓ | ✓ | -| Request a CVE ID **(FREE ONLY)** | | | | ✓ | ✓ | +| Request a CVE ID **(FREE SAAS)** | | | | ✓ | ✓ | | Use environment terminals | | | | ✓ | ✓ | -| Run Web IDE's Interactive Web Terminals **(ULTIMATE ONLY)** | | | | ✓ | ✓ | +| Run Web IDE's Interactive Web Terminals **(ULTIMATE SELF)** | | | | ✓ | ✓ | | Add new team members | | | | ✓ | ✓ | | Enable/disable branch protection | | | | ✓ | ✓ | | Push to protected branches | | | | ✓ | ✓ | -| Turn on/off protected branch push for devs | | | | ✓ | ✓ | +| Turn on/off protected branch push for developers | | | | ✓ | ✓ | | Enable/disable tag protections | | | | ✓ | ✓ | | Edit project settings | | | | ✓ | ✓ | | Edit project badges | | | | ✓ | ✓ | @@ -172,7 +172,7 @@ The following table depicts the various user permission levels in a project. | Delete wiki pages | | | | ✓ | ✓ | | View project Audit Events | | | ✓ (*12*) | ✓ | ✓ | | Manage [push rules](../push_rules/push_rules.md) | | | | ✓ | ✓ | -| Manage [project access tokens](project/settings/project_access_tokens.md) **(CORE ONLY)** | | | | ✓ | ✓ | +| Manage [project access tokens](project/settings/project_access_tokens.md) **(FREE SELF)** | | | | ✓ | ✓ | | Switch visibility level | | | | | ✓ | | Transfer project to another namespace | | | | | ✓ | | Rename project | | | | | ✓ | @@ -183,13 +183,14 @@ The following table depicts the various user permission levels in a project. | Delete pipelines | | | | | ✓ | | Delete merge request | | | | | ✓ | | Disable notification emails | | | | | ✓ | +| Administer project compliance frameworks | | | | | ✓ | | Force push to protected branches (*4*) | | | | | | | Remove protected branches (*4*) | | | | | | 1. Guest users are able to perform this action on public and internal projects, but not private projects. This doesn't apply to [external users](#external-users) where explicit access must be given even if the project is internal. 1. Guest users can only view the confidential issues they created themselves. 1. If **Public pipelines** is enabled in **Project Settings > CI/CD**. -1. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [Protected Branches](project/protected_branches.md). +1. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [protected branches](project/protected_branches.md). 1. If the [branch is protected](project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings), this depends on the access Developers and Maintainers are given. 1. Guest users can access GitLab [**Releases**](project/releases/index.md) for downloading assets but are not allowed to download the source code nor see repository information like tags and commits. 1. Actions are limited only to records owned (referenced) by user. @@ -282,7 +283,7 @@ group. | Manage group members | | | | | ✓ | | Delete group | | | | | ✓ | | Delete group epic **(PREMIUM)** | | | | | ✓ | -| Edit SAML SSO Billing **(SILVER ONLY)** | ✓ | ✓ | ✓ | ✓ | ✓ (4) | +| Edit SAML SSO Billing **(PREMIUM SAAS)** | ✓ | ✓ | ✓ | ✓ | ✓ (4) | | View group Audit Events | | | ✓ (7) | ✓ (7) | ✓ | | Disable notification emails | | | | | ✓ | | View Contribution analytics | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -290,9 +291,10 @@ group. | View Issue analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View Productivity analytics **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | | View Value Stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | -| View Billing **(FREE ONLY)** | | | | | ✓ (4) | -| View Usage Quotas **(FREE ONLY)** | | | | | ✓ (4) | +| View Billing **(FREE SAAS)** | | | | | ✓ (4) | +| View Usage Quotas **(FREE SAAS)** | | | | | ✓ (4) | | Filter members by 2FA status | | | | | ✓ | +| Administer project compliance frameworks | | | | | ✓ | 1. Groups can be set to [allow either Owners or Owners and Maintainers to create subgroups](group/subgroups/index.md#creating-a-subgroup) @@ -314,7 +316,7 @@ nested groups if you have membership in one of its parents. To learn more, read through the documentation on [subgroups memberships](group/subgroups/index.md#membership). -## External users **(CORE ONLY)** +## External users **(FREE SELF)** In cases where it is desired that a user has access only to some internal or private projects, there is the option of creating **External Users**. This @@ -352,6 +354,9 @@ An administrator can flag a user as external by either of the following methods: 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). + ### Setting new users to external By default, new users are not set as external users. This behavior can be changed @@ -396,7 +401,7 @@ Beware though that even if a user is external, if they already have Reporter or higher permissions in any project or group, they are **not** counted as a free guest user. -## Auditor users **(PREMIUM ONLY)** +## Auditor users **(PREMIUM SELF)** >[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/998) in [GitLab Premium](https://about.gitlab.com/pricing/) 8.17. @@ -421,7 +426,8 @@ details such as projects or subgroups. They do not have access to the group's pa ### Minimal access users take license seats Users with even a "minimal access" role are counted against your number of license seats. This -requirement does not apply for [GitLab Gold/Ultimate](https://about.gitlab.com/pricing/) subscriptions. +requirement does not apply for [GitLab Ultimate](https://about.gitlab.com/pricing/) +subscriptions. ## Project features @@ -518,4 +524,4 @@ Read through the documentation on [LDAP users permissions](group/index.md#manage ## Project aliases Project aliases can only be read, created and deleted by a GitLab administrator. -Read through the documentation on [Project aliases](../user/project/index.md#project-aliases) to learn more. +Read through the documentation on [Project aliases](../user/project/import/index.md#project-aliases) to learn more. diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index cdf80f722f7..91688989e55 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -5,7 +5,7 @@ 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 --- -# Creating users **(CORE ONLY)** +# Creating users **(FREE SELF)** You can create users: @@ -37,3 +37,5 @@ Users will be: - 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. diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index e347221bd66..a33b6742d61 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -17,20 +17,21 @@ Deleting a user will delete all projects in that user namespace. ## As a user -As a user, you can delete your own account by: +As a user, to delete your own account: -1. Clicking on your avatar. -1. Navigating to **Settings > Account**. -1. Selecting **Delete account**. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Account**. +1. Select **Delete account**. ## As an administrator -As an administrator, you can delete a user account by: +As an administrator, to delete a user account: -1. Navigating to **Admin Area > Overview > Users**. -1. Selecting a user. -1. Under the **Account** tab, clicking: - - **Delete user** to delete only the user but maintaining their +1. Go to **Admin Area > Overview > Users**. +1. Select a user. +1. Under the **Account** tab, select: + - **Delete user** to delete only the user but maintain their [associated records](#associated-records). - **Delete user and contributions** to delete the user and their associated records. diff --git a/doc/user/profile/account/index.md b/doc/user/profile/account/index.md deleted file mode 100644 index b10cc778f45..00000000000 --- a/doc/user/profile/account/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../index.md#profile-settings' ---- - -This document was moved to [../index.md#profile-settings](../index.md#profile-settings). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 6cdd2d6f161..44bf97bdd42 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -44,7 +44,7 @@ To enable 2FA: 1. **In GitLab:** 1. Sign in to your GitLab account. - 1. Go to your [**Profile settings**](../index.md#profile-settings). + 1. Go to your [**User settings**](../index.md#user-settings). 1. Go to **Account**. 1. Select **Enable Two-factor Authentication**. 1. **On your device (usually your phone):** @@ -240,13 +240,13 @@ following desktop browsers: NOTE: For Firefox 47-66, you can enable the FIDO U2F API in -[about:config](https://support.mozilla.org/en-US/kb/about-config-editor-firefox). +[`about:config`](https://support.mozilla.org/en-US/kb/about-config-editor-firefox). Search for `security.webauth.u2f` and double click on it to toggle to `true`. To set up 2FA with a U2F device: 1. Sign in to your GitLab account. -1. Go to your [**Profile settings**](../index.md#profile-settings). +1. Go to your [**User settings**](../index.md#user-settings). 1. Go to **Account**. 1. Click **Enable Two-Factor Authentication**. 1. Connect your U2F device. @@ -262,7 +262,7 @@ Click on **Register U2F Device** to complete the process. > - 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-webauthn). **(CORE ONLY)** +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-webauthn). **(FREE SELF)** The WebAuthn workflow is [supported by](https://caniuse.com/#search=webauthn) the following desktop browsers: @@ -282,7 +282,7 @@ and the following mobile browsers: To set up 2FA with a WebAuthn compatible device: 1. Sign in to your GitLab account. -1. Go to your [**Profile settings**](../index.md#profile-settings). +1. Go to your [**User settings**](../index.md#user-settings). 1. Go to **Account**. 1. Select **Enable Two-Factor Authentication**. 1. Plug in your WebAuthn device. @@ -349,7 +349,7 @@ request and you're automatically signed in. If you ever need to disable 2FA: 1. Sign in to your GitLab account. -1. Go to your [**Profile settings**](../index.md#profile-settings). +1. Go to your [**User settings**](../index.md#user-settings). 1. Go to **Account**. 1. Click **Disable**, under **Two-Factor Authentication**. @@ -384,7 +384,7 @@ codes. If you saved these codes, you can use one of them to sign in. To use a recovery code, enter your username/email and password on the GitLab sign-in page. When prompted for a two-factor code, enter the recovery code. -Once you use a recovery code, you cannot re-use it. You can still use the other +After you use a recovery code, you cannot re-use it. You can still use the other recovery codes you saved. ### Generate new recovery codes using SSH @@ -434,7 +434,7 @@ a new set of recovery codes with SSH: When prompted for a two-factor code, enter one of the recovery codes obtained from the command-line output. -After signing in, visit your **Profile settings > Account** immediately to set +After signing in, visit your **User settings > Account** immediately to set up two-factor authentication with a new device. ### Regenerate 2FA recovery codes @@ -443,8 +443,8 @@ To regenerate 2FA recovery codes, you need access to a desktop browser: 1. Navigate to GitLab. 1. Sign in to your GitLab account. -1. Go to your [**Profile settings**](../index.md#profile-settings). -1. Select **{account}** **Account > Two-Factor Authentication (2FA)**. +1. Go to your [**User settings**](../index.md#user-settings). +1. Select **Account > Two-Factor Authentication (2FA)**. 1. If you've already configured 2FA, click **Manage two-factor authentication**. 1. In the **Register Two-Factor Authenticator** pane, click **Regenerate recovery codes**. @@ -479,7 +479,7 @@ Sign in and re-enable two-factor authentication as soon as possible. - To enforce 2FA at the system or group levels see [Enforce Two-factor Authentication](../../../security/two_factor_authentication.md). -## Enable or disable WebAuthn **(CORE ONLY)** +## Enable or disable WebAuthn **(FREE SELF)** Support for WebAuthn is under development and not ready for production use. It is deployed behind a feature flag that is **disabled by default**. diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index 381015f17c3..e55b92378bd 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -14,9 +14,11 @@ review the sessions, and revoke any you don't recognize. ## Listing all active sessions -1. Click your avatar. -1. Select **Settings**. -1. Click **Active Sessions** in the sidebar. +To list all active sessions: + +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Active Sessions**.  @@ -29,8 +31,12 @@ exceeds 100, the oldest ones are deleted. ## Revoking a session -1. Use the previous steps to navigate to **Active Sessions**. -1. Click on **Revoke** besides a session. The current session cannot be revoked, as this would sign you out of GitLab. +To revoke an active session: + +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Active Sessions**. +1. Select **Revoke** next to a session. The current session cannot be revoked, as this would sign you out of GitLab. NOTE: When any session is revoked all **Remember me** tokens for all diff --git a/doc/user/profile/img/profil-preferences-navigation-theme.png b/doc/user/profile/img/profil-preferences-navigation-theme.png Binary files differdeleted file mode 100644 index 335a19ac290..00000000000 --- a/doc/user/profile/img/profil-preferences-navigation-theme.png +++ /dev/null diff --git a/doc/user/profile/img/profile_following_v13_9.png b/doc/user/profile/img/profile_following_v13_9.png Binary files differnew file mode 100644 index 00000000000..878dce83997 --- /dev/null +++ b/doc/user/profile/img/profile_following_v13_9.png diff --git a/doc/user/profile/img/profile_settings_dropdown.png b/doc/user/profile/img/profile_settings_dropdown.png Binary files differdeleted file mode 100644 index 99b06a1bf58..00000000000 --- a/doc/user/profile/img/profile_settings_dropdown.png +++ /dev/null diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index a96975fea92..d2cbf9e4acd 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # User account Each GitLab account has a user profile, and settings. Your [profile](#user-profile) -contains information about you, and your GitLab activity. Your [settings](#profile-settings) +contains information about you, and your GitLab activity. Your [settings](#user-settings) allow you to customize some aspects of GitLab to suit yourself. ## Creating users @@ -29,8 +29,8 @@ See [Unknown Sign-In Notification](unknown_sign_in_notification.md) for more det To access your profile: -1. Click on your avatar. -1. Select **Profile**. +1. In the top-right corner, select your avatar. +1. Select your name or username. On your profile page, you can see the following information: @@ -41,13 +41,19 @@ On your profile page, you can see the following information: - Personal projects: your personal projects (respecting the project's visibility level) - Starred projects: projects you starred - Snippets: your personal code [snippets](../snippets.md#personal-snippets) +- Followers: people following you +- Following: people you are following -## Profile settings +Profile page with active Following view: -To access your profile settings: + -1. Click on your avatar. -1. Select **Settings**. +## User settings + +To access your user settings: + +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. From there, you can: @@ -78,11 +84,12 @@ From there, you can: ## Changing your password -1. Navigate to your [profile's](#profile-settings) **Settings > Password**. -1. Enter your current password in the 'Current password' field. -1. Enter your desired new password twice, once in the 'New password' field and - once in the 'Password confirmation' field. -1. Click the 'Save password' button. +1. Go to your [user settings](#user-settings). +1. In the left sidebar, select **Password**. +1. Enter your current password in the **Current password** field. +1. Enter your desired new password twice, once in the **New password** field and + once in the **Password confirmation** field. +1. Select **Save password**. If you don't know your current password, select the 'I forgot my password' link. @@ -92,17 +99,18 @@ If you don't know your current password, select the 'I forgot my password' link. Your `username` is a unique [`namespace`](../group/index.md#namespaces) related to your user ID. Changing it can have unintended side effects, read -[how redirects behave](../project/index.md#redirects-when-changing-repository-paths) +[how redirects behave](../project/repository/index.md#redirects-when-changing-repository-paths) before proceeding. To change your `username`: -1. Navigate to your [profile's](#profile-settings) **Settings > Account**. +1. Navigate to your [user settings](#user-settings). +1. In the left sidebar, select **Account**. 1. Enter a new username under **Change username**. -1. Click **Update username**. +1. Select **Update username**. WARNING: -It is currently not possible to change your username if it contains a +It is not possible to change your username if it contains a project with [Container Registry](../packages/container_registry/index.md) tags, because the project cannot be moved. @@ -127,33 +135,31 @@ The following information is hidden from the user profile page (`https://gitlab. - Starred projects tab - Snippets tab -To enable private profile: +To make your profile private: -1. Click your avatar. -1. Select **Profile**. -1. Click **Edit profile** (pencil icon). -1. Check the **Private profile** option in the **Main settings** section. -1. Click **Update profile settings**. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. Select the **Private profile** checkbox. +1. Select **Update profile settings**. NOTE: -All your profile information can be seen by yourself, and GitLab admins, even if +All your profile information can be seen by yourself and GitLab administrators even if the **Private profile** option is enabled. ## Add details of external accounts -GitLab allows you to add links to certain other external accounts you might have, like Skype and Twitter. They can help other users connect with you on other platforms. +You can add links to certain other external accounts you might have, like Skype and Twitter. +They can help other users connect with you on other platforms. To add links to other accounts: -1. Click your avatar. -1. Select **Profile**. -1. Click **Edit profile** (pencil icon). -1. Complete the desired fields for external accounts, in the **Main settings** - section: +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. Edit the desired fields for external accounts: - Skype - - Twitter - LinkedIn -1. Click **Update profile settings**. + - Twitter +1. Select **Update profile settings**. ## Private contributions @@ -163,11 +169,10 @@ Enabling private contributions includes contributions to private projects, in th To enable private contributions: -1. Click on your avatar. -1. Select **Profile**. -1. Click **Edit profile** (pencil icon). -1. Check the **Private contributions** option. -1. Click **Update profile settings**. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. Select the **Private contributions** checkbox. +1. Select **Update profile settings**. ## Current status @@ -183,23 +188,23 @@ They may however contain emoji codes such as `I'm on vacation :palm_tree:`. To set your current status: -1. Click your avatar. -1. Click **Set status**, or **Edit status** if you have already set a status. -1. Set the desired emoji and/or status message. -1. Click **Set status**. Alternatively, you can click **Remove status** to remove your user status entirely. +1. In the top-right corner, select your avatar. +1. Select **Set status**, or **Edit status** if you have already set a status. +1. Set the desired emoji and status message. +1. Select **Set status**. Alternatively, you can select **Remove status** to remove your user status entirely. or -1. Click your avatar. -1. Select **Profile**. -1. Click **Edit profile** (pencil icon). +1. In the top-right corner, select your avatar. +1. Select your name or username. +1. Select the Edit profile icon (**{pencil}**). 1. Enter your status message in the **Your status** text field. -1. Click **Add status emoji** (smiley face), and select the desired emoji. -1. Click **Update profile settings**. +1. Select Add status emoji icon (**{slight-smile}**), and select the desired emoji. +1. Select **Update profile settings**. You can also set your current status [using the API](../../api/users.md#user-status). -If you previously selected the "Busy" checkbox, remember to deselect it when you become available again. +If you previously selected the **Busy** checkbox, remember to deselect it when you become available again. ## Busy status indicator @@ -210,7 +215,7 @@ If you previously selected the "Busy" checkbox, remember to deselect it when you > - It's not recommended for production use. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-busy-status-feature). -To indicate to others that you are busy, you can set an indicator +To indicate to others that you are busy, you can set an indicator.  @@ -218,16 +223,15 @@ To set the busy status indicator, either: - Set it directly: - 1. Click your avatar. - 1. Click **Set status**, or **Edit status** if you have already set a status. - 1. Select the **Busy** checkbox + 1. In the top-right corner, select your avatar. + 1. Select **Set status**, or **Edit status** if you have already set a status. + 1. Select the **Busy** checkbox. - Set it on your profile: - 1. Click your avatar. - 1. Select **Profile**. - 1. Click **Edit profile** (**{pencil}**). - 1. Select the **Busy** checkbox + 1. In the top-right corner, select your avatar. + 1. Select **Edit profile**. + 1. Select the **Busy** checkbox. ### Disable busy status feature @@ -256,12 +260,11 @@ Any of your own verified email addresses can be used as the commit email. To change your commit email: -1. Click your avatar. -1. Select **Profile**. -1. Click **Edit profile** (pencil icon). -1. Click **Commit email** dropdown. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. Select the **Commit email** dropdown. 1. Select any of the verified emails. -1. Click **Update profile settings**. +1. Select **Update profile settings**. ### Private commit email @@ -272,14 +275,13 @@ which allows the user to keep their email information private. To enable this option: -1. Click your avatar. -1. Select **Profile**. -1. Click **Edit profile** (pencil icon). -1. Click **Commit email** dropdown. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. Select the **Commit email** dropdown. 1. Select **Use a private email** option. -1. Click **Update profile settings**. +1. Select **Update profile settings**. -Once this option is enabled, every Git-related action is performed using the private commit email. +After this option is enabled, every Git-related action is performed using the private commit email. To stay fully anonymous, you can also copy this private commit email and configure it on your local machine using the following command: @@ -298,7 +300,7 @@ and expires after "Application settings -> Session duration (minutes)"/`session_ (defaults to `10080` minutes = 7 days) of no activity. When signing in to the main GitLab application, you can also check the -"Remember me" option which sets the `remember_user_token` +**Remember me** option which sets the `remember_user_token` cookie (via [`devise`](https://github.com/heartcombo/devise)). `remember_user_token` expires after `config/initializers/devise.rb` -> `config.remember_for` (defaults to 2 weeks). @@ -326,7 +328,8 @@ GitLab uses both session and persistent cookies: - Session cookie: Session cookies are normally removed at the end of the browser session when the browser is closed. The `_gitlab_session` cookie has no fixed expiration date. However, it expires based on its [`session_expire_delay`](#why-do-i-keep-getting-signed-out). -- Persistent cookie: The `remember_user_token` is a cookie with an expiration date of two weeks. GitLab activates this cookie if you click Remember Me when you sign in. +- Persistent cookie: The `remember_user_token` is a cookie with an expiration date of two weeks. + GitLab activates this cookie if you select **Remember Me** when you sign in. By default, the server sets a time-to-live (TTL) of 1-week on any session that is used. @@ -336,15 +339,3 @@ The server continues to reset the TTL for that session, independent of whether 2 If you close your browser and open it up again, the `remember_user_token` cookie allows your user to reauthenticate itself. Without the `config.extend_remember_period` flag, you would be forced to sign in again after two weeks. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index ae672d8414f..703154945db 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -15,8 +15,9 @@ Notifications are sent via email. You receive notifications for one of the following reasons: -- You participate in an issue, merge request, epic or design. In this context, _participate_ means comment, or edit. -- You enable notifications in an issue, merge request, or epic. To enable notifications, click the **Notifications** toggle in the sidebar to _on_. +- You participate in an issue, merge request, epic, or design. In this context, _participate_ means comment, or edit. +- You [enable notifications in an issue, merge request, or epic](#notifications-on-issues-merge-requests-and-epics). +- You configured notifications at the [project](#project-notifications) and/or [group](#group-notifications) level. While notifications are enabled, you receive notification of actions occurring in that issue, merge request, or epic. @@ -25,7 +26,9 @@ Notifications can be blocked by an administrator, preventing them from being sen ## Tuning your notifications -The quantity of notifications can be overwhelming. GitLab allows you to tune the notifications you receive. For example, you may want to be notified about all activity in a specific project, but for others, only be notified when you are mentioned by name. +The number of notifications can be overwhelming. GitLab allows you to tune the notifications you receive. +For example, you might want to be notified about all activity in a specific project. +For other projects, you only need to be notified when you are mentioned by name. You can tune the notifications you receive by combining your notification settings: @@ -53,6 +56,8 @@ Your **Global notification settings** are the default settings unless you select - This is the email address your notifications are sent to. - Global notification level - This is the default [notification level](#notification-levels) which applies to all your notifications. +- Receive product marketing emails + - Check this checkbox if you want to receive periodic emails related to GitLab features. - Receive notifications about your own activity. - Check this checkbox if you want to receive notification about your own activity. Default: Not checked. @@ -159,49 +164,64 @@ Users are notified of the following events: | Project moved | Project members (1) | (1) not disabled | | New release | Project members | Custom notification | -## Issue / Epics / Merge request events +## Notifications on issues, merge requests, and epics -In most of the below cases, the notification is sent to: +To enable notifications on one specific issue, merge request or epic, you need to enable the **Notifications** toggle in the right sidebar. + +- **Enable**: If you are not a participant in the discussion on that issue, but + want to receive notifications on each update, subscribe to it. +- **Disable**: If you are receiving notifications for updates to that issue but no + longer want to receive them, unsubscribe from it. + +Configuring this notification on an epic doesn't make you automatically subscribed to the issue that are linked to the epic. + +For most events, the notification is sent to: - Participants: - - the author and assignee of the issue/merge request - - authors of comments on the issue/merge request - - anyone mentioned by `@username` in the title or description of the issue, merge request or epic **(ULTIMATE)** - - anyone with notification level "Participating" or higher that is mentioned by `@username` in any of the comments on the issue, merge request, or epic **(ULTIMATE)** -- Watchers: users with notification level "Watch" -- Subscribers: anyone who manually subscribed to the issue, merge request, or epic **(ULTIMATE)** -- Custom: Users with notification level "custom" who turned on notifications for any of the events present in the table below + - The author and assignee of the issue/merge request. + - Authors of comments on the issue/merge request. + - Anyone mentioned by `@username` in the title or description of the issue, merge request or epic. + - Anyone with notification level "Participating" or higher that is mentioned by `@username` in any of the comments on the issue, merge request, or epic. +- Watchers: users with notification level "Watch". +- Subscribers: anyone who manually subscribed to the issue, merge request, or epic. +- Custom: Users with notification level "custom" who turned on notifications for any of the events present in the table below. NOTE: -To minimize the number of notifications that do not require any action, from [GitLab 12.9 onwards](https://gitlab.com/gitlab-org/gitlab/-/issues/616), eligible approvers are no longer notified for all the activities in their projects. To receive them they have to change their user notification settings to **Watch** instead. +To minimize the number of notifications that do not require any action, in +[GitLab versions 12.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/616), eligible +approvers are no longer notified for all the activities in their projects. To receive them they have +to change their user notification settings to **Watch** instead. + +The following table presents the events that generate notifications for issues, merge requests, and +epics: | Event | Sent to | |------------------------|---------| -| New issue | | +| Change milestone issue | Subscribers, participants mentioned, and Custom notification level with this event selected | +| Change milestone merge request | Subscribers, participants mentioned, and Custom notification level with this event selected | +| Close epic | | | Close issue | | -| Reassign issue | The above, plus the old assignee | -| Reopen issue | | +| Close merge request | | | Due issue | Participants and Custom notification level with this event selected | -| Change milestone issue | Subscribers, participants mentioned, and Custom notification level with this event selected | -| Remove milestone issue | Subscribers, participants mentioned, and Custom notification level with this event selected | +| Failed pipeline | The author of the pipeline | +| Fixed pipeline ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24309) in GitLab 13.1.) | The author of the pipeline. Enabled by default. | +| Merge merge request | | +| Merge when pipeline succeeds ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211961) in GitLab 13.4) | | +| New comment | Participants, Watchers, Subscribers, and Custom notification level with this event selected, plus anyone mentioned by `@username` in the comment, with notification level "Mention" or higher | +| New epic | | +| New issue | | | New merge request | | | Push to merge request | Participants and Custom notification level with this event selected | -| Reassign merge request | The above, plus the old assignee | -| Close merge request | | -| Reopen merge request | | -| Merge merge request | | -| Merge when pipeline succeeds ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211961) in GitLab 13.4) | | -| Change milestone merge request | Subscribers, participants mentioned, and Custom notification level with this event selected | +| Reassign issue | Participants, Watchers, Subscribers, and Custom notification level with this event selected, plus the old assignee | +| Reassign merge request | Participants, Watchers, Subscribers, and Custom notification level with this event selected, plus the old assignee | +| Remove milestone issue | Subscribers, participants mentioned, and Custom notification level with this event selected | | Remove milestone merge request | Subscribers, participants mentioned, and Custom notification level with this event selected | -| New comment | The above, plus anyone mentioned by `@username` in the comment, with notification level "Mention" or higher | -| Failed pipeline | The author of the pipeline | -| Fixed pipeline | The author of the pipeline. Enabled by default. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24309) in GitLab 13.1. | +| Reopen epic | | +| Reopen issue | | +| Reopen merge request | | | Successful pipeline | The author of the pipeline, if they have the custom notification setting for successful pipelines set. If the pipeline failed previously, a `Fixed pipeline` message is sent for the first successful pipeline after the failure, then a `Successful pipeline` message for any further successful pipelines. | -| New epic **(ULTIMATE)** | | -| Close epic **(ULTIMATE)** | | -| Reopen epic **(ULTIMATE)** | | -In addition, if the title or description of an Issue or Merge Request is +If the title or description of an issue or merge request is changed, notifications are sent to any **new** mentions by `@username` as if they had been mentioned in the original text. diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 49889cd3017..99db0c4b898 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -33,13 +33,14 @@ You can create as many personal access tokens as you like from your GitLab profile. 1. Sign in to GitLab. -1. In the upper-right corner, click your avatar and select **Settings**. -1. On the **User Settings** menu, select **Access Tokens**. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **Access Tokens**. 1. Choose a name and optional expiry date for the token. 1. Choose the [desired scopes](#limiting-scopes-of-a-personal-access-token). -1. Click the **Create personal access token** button. +1. Select **Create personal access token**. 1. Save the personal access token somewhere safe. If you navigate away or refresh -your page, and you did not save the token, you must create a new one. + your page, and you did not save the token, you must create a new one. ### Revoking a personal access token diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index af7bfb80cac..464edf13a7e 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -12,9 +12,8 @@ of GitLab to their liking. To navigate to your profile's preferences: -1. Click your avatar. -1. Select **Settings**. -1. Click **Preferences** in the sidebar. +1. In the top-right corner, select your avatar. +1. Select **Preferences**. ## Navigation theme @@ -36,8 +35,7 @@ The default theme is Indigo. You can choose between 10 themes: - Light Red - Dark - Light - - +- [Dark Mode](#dark-mode) ## Dark mode @@ -47,7 +45,8 @@ GitLab has started work on dark mode! The dark mode Alpha release is available i spirit of iteration and the lower expectations of [Alpha versions](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). -Progress on dark mode is tracked in the [Dark theme epic](https://gitlab.com/groups/gitlab-org/-/epics/2902). See the epic for: +Progress on dark mode is tracked in the [Dark theme epic](https://gitlab.com/groups/gitlab-org/-/epics/2902). +See the epic for: - A list of known issues. - Our planned direction and next steps. @@ -60,14 +59,15 @@ the future, we plan to make it configurable in its own section along with suppor [different navigation themes](https://gitlab.com/gitlab-org/gitlab/-/issues/219512). NOTE: -Dark theme currently only works with the 'Dark' syntax highlighting. +Dark theme only works with the **Dark** syntax highlighting theme. ## Syntax highlighting theme NOTE: GitLab uses the [rouge Ruby library](http://rouge.jneen.net/ "Rouge website") for syntax highlighting outside of any Editor context. The WebIDE (like Snippets) -uses [Monaco Editor](https://microsoft.github.io/monaco-editor/) and it's provided [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) library for +uses [Monaco Editor](https://microsoft.github.io/monaco-editor/) and it's provided +[Monarch](https://microsoft.github.io/monaco-editor/monarch.html) library for syntax highlighting. For a list of supported languages, visit the documentation of the respective libraries. @@ -76,12 +76,16 @@ syntax highlighted code on GitLab. The default syntax theme is White, and you can choose among 5 different themes: +<!-- vale gitlab.Spelling = NO --> + - White - Dark - Solarized light - Solarized dark - Monokai +<!-- vale gitlab.Spelling = YES --> +  [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2389) in 13.0, the theme @@ -117,7 +121,7 @@ You have 8 options here that you can use for your default dashboard view: - Your projects' activity - Starred projects' activity - Your groups -- Your [to-dos](../todos.md) +- Your [To-Do List](../todos.md) - Assigned Issues - Assigned Merge Requests - Operations Dashboard **(PREMIUM)** diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md index 1aa040c9cb8..8d8ff942d05 100644 --- a/doc/user/project/autocomplete_characters.md +++ b/doc/user/project/autocomplete_characters.md @@ -3,10 +3,12 @@ stage: Create group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference -description: "Autocomplete chars in Markdown fields." +description: "Autocomplete characters in Markdown fields." --- -# Autocomplete characters +# Autocomplete characters **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36705) in GitLab 13.9: you can search using the full name in user autocomplete. The autocomplete characters provide a quick way of entering field values into Markdown fields. When you start typing a word in a Markdown field with one of @@ -57,4 +59,7 @@ If you continue to type, `@le`, the popup list changes to the following. The popup now only includes users where `le` appears in their username, or a word in their name. - + + +You can also search across the full name to find a user. +To find `Rosy Grant`, even if their username is for example `hunter2`, you can type their full name without spaces like `@rosygrant`. diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index f7bb88c33aa..7e6bba30001 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Badges +# Badges **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41174) in GitLab 10.7. diff --git a/doc/user/project/builds/artifacts.md b/doc/user/project/builds/artifacts.md deleted file mode 100644 index e7572b4ff1f..00000000000 --- a/doc/user/project/builds/artifacts.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../pipelines/job_artifacts.md' ---- - -This document was moved to [pipelines/job_artifacts](../pipelines/job_artifacts.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/bulk_editing.md b/doc/user/project/bulk_editing.md index a29c0754d31..d7e8133f9ad 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -14,27 +14,28 @@ For more details, see If you want to update attributes across multiple issues or merge requests, you can do it by bulk editing them, that is, editing them together. -NOTE: Only the items visible on the current page are selected for bulk editing (up to 20).  ## Bulk edit issues at the project level -NOTE: -You need a permission level of [Reporter or higher](../permissions.md) to manage issues. +> - Assigning epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. +> - Editing health status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in GitLab 13.2. +> - Editing iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196806) in GitLab 13.9. + +Users with permission level of [Reporter or higher](../permissions.md) can manage issues. When bulk editing issues in a project, you can edit the following attributes: - Status (open/closed) - Assignee -- Epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in - [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.) **(PREMIUM)** -- Milestone -- Labels -- Health status ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218395) in - [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2.) **(ULTIMATE)** -- Subscriptions +- [Epic](../group/epics/index.md) +- [Milestone](milestones/index.md) +- [Labels](labels.md) +- [Health status](issues/index.md#health-status) +- Notification subscription +- [Iteration](../group/iterations/index.md) To update multiple project issues at the same time: @@ -46,8 +47,7 @@ To update multiple project issues at the same time: ## Bulk edit merge requests at the project level -NOTE: -You need a permission level of [Developer or higher](../permissions.md) to manage merge requests. +Users with permission level of [Developer or higher](../permissions.md) can manage merge requests. When bulk editing merge requests in a project, you can edit the following attributes: diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index 85ac641f6e4..f7394093a3a 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -4,10 +4,10 @@ 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 --- -# Canary Deployments **(CORE)** +# Canary Deployments **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1659) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to GitLab Core in 13.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to GitLab Free in 13.8. A popular [Continuous Deployment](https://en.wikipedia.org/wiki/Continuous_deployment) strategy, where a small portion of the fleet is updated to the new version of @@ -72,7 +72,7 @@ can easily notice them. ### Advanced traffic control with Canary Ingress > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215501) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to Core in GitLab 13.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to Free in GitLab 13.8. Canary deployments can be more strategic with [Canary Ingress](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#canary), which is an advanced traffic routing service that controls incoming HTTP diff --git a/doc/user/project/ci_cd_for_external_repo.md b/doc/user/project/ci_cd_for_external_repo.md deleted file mode 100644 index 57747be3859..00000000000 --- a/doc/user/project/ci_cd_for_external_repo.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../ci/ci_cd_for_external_repos/index.md' ---- - -This document was moved to [another location](../../ci/ci_cd_for_external_repos/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 9047e564598..eb6b8302667 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Adding EKS clusters +# Adding EKS clusters **(FREE)** GitLab supports adding new and existing EKS clusters. @@ -20,7 +20,7 @@ requirements are met: - `kubectl` [installed and configured](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl) for access to the EKS cluster. -### Additional requirements for self-managed instances **(CORE ONLY)** +### Additional requirements for self-managed instances **(FREE SELF)** If you are using a self-managed GitLab instance, GitLab must first be configured with a set of Amazon credentials. These credentials are used to assume an Amazon IAM role provided by the user diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index e3e6efc887f..af3a17dc60c 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Adding GKE clusters +# Adding GKE clusters **(FREE)** GitLab supports adding new and existing GKE clusters. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index beb8b71b917..718c60ccf0e 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Adding and removing Kubernetes clusters +# Adding and removing Kubernetes clusters **(FREE)** GitLab offers integrated cluster creation for the following Kubernetes providers: @@ -40,7 +40,7 @@ Before [adding a Kubernetes cluster](#create-new-cluster) using GitLab, you need - [Maintainer access to 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. **(CORE ONLY)** + cluster. **(FREE SELF)** ## Access controls @@ -387,3 +387,13 @@ If you encounter this error while adding a Kubernetes cluster, ensure you're properly pasting the service token. Some shells may add a line break to the service token, making it invalid. Ensure that there are no line breaks by pasting your token into an editor and removing any additional spaces. + +You may also experience this error if your certificate is not valid. To check that your certificate's +subject alternative names contain the correct domain for your cluster's API, run this: + +```shell +echo | openssl s_client -showcerts -connect kubernetes.example.com:443 2>/dev/null | +openssl x509 -inform pem -noout -text +``` + +Note that the `-connect` argument expects a `host:port` combination. For example, `https://kubernetes.example.com` would be `kubernetes.example.com:443`. diff --git a/doc/user/project/clusters/eks_and_gitlab/index.md b/doc/user/project/clusters/eks_and_gitlab/index.md deleted file mode 100644 index e38fbb871c1..00000000000 --- a/doc/user/project/clusters/eks_and_gitlab/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../add_eks_clusters.md#existing-eks-cluster' ---- - -This document was moved to [another location](../add_eks_clusters.md#existing-eks-cluster). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index a06846e33a6..d3d434762ab 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -4,7 +4,7 @@ group: Health 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 --- -# Kubernetes clusters +# Kubernetes clusters **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35954) in GitLab 10.1 for projects. > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34758) in @@ -33,8 +33,10 @@ integrated at the [group level](../../group/clusters/index.md) or To view your project level Kubernetes clusters, navigate to **Operations > 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 nodes count and rough estimates -of memory and CPU usage. +and view information about your existing clusters, such as: + +- Nodes count. +- Rough estimates of memory and CPU usage. ## Setting up @@ -72,13 +74,12 @@ to: ### Multiple Kubernetes clusters > - Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3 -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) to GitLab Core in 13.2. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) to GitLab Free in 13.2. You can associate more than one Kubernetes cluster to your project. That way you can have different clusters for different environments, -like dev, staging, production, and so on. - -Simply add another cluster, like you did the first time, and make sure to +like development, staging, production, and so on. +Add another cluster, like you did the first time, and make sure to [set an environment scope](#setting-the-environment-scope) that differentiates the new cluster from the rest. @@ -86,7 +87,7 @@ differentiates the new cluster from the rest. When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the -[environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables) work. +[environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-cicd-variables) work. The default environment scope is `*`, which means all jobs, regardless of their environment, use that cluster. Each scope can be used only by a single cluster @@ -165,7 +166,7 @@ details about the created resources. If you choose to manage your own cluster, project-specific resources aren't created automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you must explicitly provide the `KUBE_NAMESPACE` [deployment variable](#deployment-variables) -for your deployment jobs to use; otherwise a namespace is created for you. +for your deployment jobs to use. Otherwise, a namespace is created for you. #### Important notes @@ -182,10 +183,10 @@ Note the following with GitLab and clusters: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31759) in GitLab 12.6. -If you choose to allow GitLab to manage your cluster for you, GitLab stores a cached +If you allow GitLab to manage your cluster, GitLab stores a cached version of the namespaces and service accounts it creates for your projects. If you modify these resources in your cluster manually, this cache can fall out of sync with -your cluster, which can cause deployment jobs to fail. +your cluster. This can cause deployment jobs to fail. To clear the cache: @@ -204,12 +205,61 @@ Specifying a base domain automatically sets `KUBE_INGRESS_BASE_DOMAIN` as an env 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)), +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: - 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`. +To determine the external Ingress IP address, or external Ingress hostname: + +- *If the cluster is on GKE*: + 1. Click the **Google Kubernetes Engine** link in the **Advanced settings**, + or go directly to the [Google Kubernetes Engine dashboard](https://console.cloud.google.com/kubernetes/). + 1. Select the proper project and cluster. + 1. Click **Connect** + 1. Execute the `gcloud` command in a local terminal or using the **Cloud Shell**. + +- *If the cluster is not on GKE*: Follow the specific instructions for your + Kubernetes provider to configure `kubectl` with the right credentials. + The output of the following examples show the external endpoint of your + cluster. This information can then be used to set up DNS entries and forwarding + rules that allow external access to your deployed applications. + +Depending an your Ingress, the external IP address can be retrieved in various ways. +This list provides a generic solution, and some GitLab-specific approaches: + +- In general, you can list the IP addresses of all load balancers by running: + + ```shell + kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' + ``` + +- If you installed Ingress using the **Applications**, run: + + ```shell + kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' + ``` + +- Some Kubernetes clusters return a hostname instead, like + [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: + + ```shell + kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' + ``` + + If you use EKS, an [Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/) + is also created, which incurs additional AWS costs. + +- Istio/Knative uses a different command. Run: + + ```shell + kubectl get svc --namespace=istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' + ``` + +If you see a trailing `%` on some Kubernetes versions, do not include it. + ## Installing applications GitLab can install and manage some applications like Helm, GitLab Runner, Ingress, @@ -224,10 +274,10 @@ Auto DevOps automatically detects, builds, tests, deploys, and monitors your applications. To make full use of Auto DevOps (Auto Deploy, Auto Review Apps, and -Auto Monitoring) the Kubernetes project integration must be enabled, but +Auto Monitoring) the Kubernetes project integration must be enabled. However, Kubernetes clusters can be used without Auto DevOps. -[Read more about Auto DevOps](../../../topics/autodevops/index.md) +[Read more about Auto DevOps](../../../topics/autodevops/index.md). ## Deploying to a Kubernetes cluster @@ -239,7 +289,7 @@ A Kubernetes cluster can be the destination for a deployment job. If the cluster from your jobs using tools such as `kubectl` or `helm`. - You don't use the GitLab cluster integration, you can still deploy to your cluster. However, you must configure Kubernetes tools yourself - using [environment variables](../../../ci/variables/README.md#custom-environment-variables) + using [environment variables](../../../ci/variables/README.md#custom-cicd-variables) before you can interact with the cluster from your jobs. ### Deployment variables @@ -260,9 +310,9 @@ following command in your deployment job script, for Kubernetes to access the re kubectl create secret docker-registry gitlab-registry --docker-server="$CI_REGISTRY" --docker-username="$CI_DEPLOY_USER" --docker-password="$CI_DEPLOY_PASSWORD" --docker-email="$GITLAB_USER_EMAIL" -o yaml --dry-run | kubectl apply -f - ``` -The Kubernetes cluster integration exposes the following -[deployment variables](../../../ci/variables/README.md#deployment-environment-variables) in the -GitLab CI/CD build environment to deployment jobs, which are jobs that have +The Kubernetes cluster integration exposes these +[deployment variables](../../../ci/variables/README.md#deployment-variables) in the +GitLab CI/CD build environment to deployment jobs. Deployment jobs have [defined a target environment](../../../ci/environments/index.md#defining-environments). | Variable | Description | @@ -303,11 +353,11 @@ When you customize the namespace, existing environments remain linked to their c namespaces until you [clear the cluster cache](#clearing-the-cluster-cache). WARNING: -By default, anyone who can create a deployment job can access any CI variable within +By default, anyone who can create a deployment job can access any CI 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), +[protected environments](../../../ci/environments/protected_environments.md), combined with either - a GitLab-managed cluster and namespace per environment, @@ -327,8 +377,8 @@ the need to leave GitLab. #### Deploy Boards GitLab Deploy Boards offer a consolidated view of the current health and -status of each CI [environment](../../../ci/environments/index.md) running on Kubernetes, -displaying the status of the pods in the deployment. Developers and other +status of each CI [environment](../../../ci/environments/index.md) running on Kubernetes. +They display the status of the pods in the deployment. Developers and other teammates can view the progress and status of a rollout, pod by pod, in the workflow they already use without any need to access Kubernetes. @@ -336,7 +386,7 @@ workflow they already use without any need to access Kubernetes. #### Viewing pod logs -GitLab makes it easy to view the logs of running pods in connected Kubernetes +GitLab enables you to view the logs of running pods in connected Kubernetes clusters. By displaying the logs directly in GitLab, developers can avoid having to manage console tools or jump to a different interface. @@ -349,7 +399,7 @@ to manage console tools or jump to a different interface. When enabled, the Kubernetes integration adds [web terminal](../../../ci/environments/index.md#web-terminals) support to your [environments](../../../ci/environments/index.md). This is based on the `exec` functionality found in Docker and Kubernetes, so you get a new -shell session within your existing containers. To use this integration, you +shell session in your existing containers. To use this integration, you should deploy to Kubernetes using the deployment variables above, ensuring any deployments, replica sets, and pods are annotated with: @@ -402,7 +452,7 @@ Automatically detect and monitor Kubernetes metrics. Automatic monitoring of ### Visualizing cluster health > - [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 Core in 13.2. +> - [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. diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index 2523dc3e0a2..349040e0bf6 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -4,10 +4,10 @@ group: Health 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 --- -# Kubernetes Logs +# Kubernetes Logs **(FREE)** > - [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 Core](https://about.gitlab.com/pricing/) 12.9. +> - [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 [connected Kubernetes clusters](index.md). By displaying the logs directly in GitLab 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 8299844e511..a7cdd73acd7 100644 --- a/doc/user/project/clusters/protect/container_network_security/index.md +++ b/doc/user/project/clusters/protect/container_network_security/index.md @@ -28,10 +28,9 @@ chart. - GitLab managed installation of Cilium. - Support for L3, L4, and L7 policies. - Ability to export logs to a SIEM. -- Statistics page showing volume of packets processed and dropped over time (Gold/Ultimate users - only). +- Statistics page showing volume of packets processed and dropped over time (Ultimate users only). - Management of NetworkPolicies through code in a project (Available for auto DevOps users only). -- Management of CiliumNetworkPolicies through a UI policy manager (Gold/Ultimate users only). +- Management of CiliumNetworkPolicies through a UI policy manager (Ultimate users only). ## Supported container orchestrators 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 10f9380a1f2..e530f0dfcda 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 @@ -46,11 +46,11 @@ Network Policies can be managed through GitLab in one of two ways: - Management through a YAML file in each application's project (for projects using Auto DevOps). For more information, see the [Network Policy documentation](../../../../../topics/autodevops/stages.md#network-policy). - Management through the GitLab Policy management UI (for projects not using Auto DevOps). For more - information, see the [Container Network Policy documentation](../../../../application_security/threat_monitoring/index.md#container-network-policy-management) (Ultimate/Gold only). + information, see the [Container Network Policy documentation](../../../../application_security/threat_monitoring/index.md#container-network-policy-management) (Ultimate only). Each method has benefits and drawbacks: -| | YAML method | UI method (Ultimate/Gold only) | +| | YAML method | UI method (Ultimate only) | |--|:------------|:-------------------------------| | **Benefits** | A change control process is possible by requiring [MR Approvals](../../../merge_requests/merge_request_approvals.md). All changes are fully tracked and audited in the same way that Git tracks the history of any file in its repository. | The UI provides a simple rules editor for users who are less familiar with the YAML syntax of NetworkPolicies. This view is a live representation of the policies currently deployed in the Kubernetes cluster. The UI also allows for multiple network policies to be created per environment. | | **Drawbacks** | Only one network policy can be deployed per environment (although that policy can be as detailed as needed). Also, if changes were made in Kubernetes directly rather than through the `auto-deploy-values.yaml` file, the YAML file's contents don't represent the actual state of policies deployed in Kubernetes. | Policy changes aren't audited and a change control process isn't available. | 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 index e9a05b58fec..e7d8d591510 100644 --- 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 @@ -43,7 +43,7 @@ Google Kubernetes Engine integration. All you have to do is [follow this link](h ## Creating a new project from a template We use a GitLab project templates to get started. As the name suggests, -those projects provide a barebones application built on some well-known frameworks. +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**. @@ -55,7 +55,7 @@ those projects provide a barebones application built on some well-known framewor 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 Gold plan](https://about.gitlab.com/pricing/#gitlab-com). + [GitLab Ultimate plan](https://about.gitlab.com/pricing/).  diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 8572ab850e4..7f344349984 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Runbooks +# Runbooks **(FREE)** Runbooks are a collection of documented procedures that explain how to carry out a particular process, be it starting, stopping, debugging, diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index a52d3400aa2..192a7c7cd39 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Deploying AWS Lambda function using GitLab CI/CD +# Deploying AWS Lambda function using GitLab CI/CD **(FREE)** GitLab allows users to easily deploy AWS Lambda functions and create rich serverless applications. @@ -25,7 +25,7 @@ Additionally, in the [How To section](#how-to), you can read about different use - Working with secrets. - Setting up CORS. -Alternatively, you can quickly [create a new project with a template](../../../../gitlab-basics/create-project.md#project-templates). The [`Serverless Framework/JS` template](https://gitlab.com/gitlab-org/project-templates/serverless-framework/) already includes all parts described below. +Alternatively, you can quickly [create a new project with a template](../../working_with_projects.md#create-a-project). The [`Serverless Framework/JS` template](https://gitlab.com/gitlab-org/project-templates/serverless-framework/) already includes all parts described below. ### Example @@ -74,7 +74,7 @@ Place this code in the file `src/handler.js`. In our case, `module.exports.hello` defines the `hello` handler to reference later in the `serverless.yml`. -You can learn more about the AWS Lambda Node.js function handler and all its various options here: <https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html> +You can learn more about the [AWS Lambda Node.js function handler](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html) and all its various options in its documentation. #### Creating a `serverless.yml` file @@ -290,7 +290,7 @@ The example code is available: - As a [clonable repository](https://gitlab.com/gitlab-org/serverless/examples/serverless-framework-js). - In a version with [tests and secret variables](https://gitlab.com/gitlab-org/project-templates/serverless-framework/). -You can also use a [template](../../../../gitlab-basics/create-project.md#project-templates) +You can also use a [template](../../working_with_projects.md#project-templates) (based on the version with tests and secret variables) from within the GitLab UI (see the `Serverless Framework/JS` template). diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 043c5e4ca79..c7ed8d6d2a5 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Serverless +# Serverless **(FREE)** > Introduced in GitLab 11.5. diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index 19dc3588162..0e8c1bf8f4d 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Code Intelligence +# Code Intelligence **(FREE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/1576) in GitLab 13.1. diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 63ea84e42c9..3135aa78719 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -5,11 +5,11 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Code Owners **(STARTER)** +# Code Owners **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916) -in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. -> - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916) in GitLab 11.3. +> - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in GitLab Premium 11.9. +> - Moved to GitLab Premium in 13.9. ## Introduction @@ -18,7 +18,7 @@ to find out who should review or approve merge requests. Additionally, if you have a question over a specific file or code block, it may be difficult to know who to find the answer from. -GitLab Code Owners is a feature to define who owns specific +The GitLab Code Owners feature defines who owns specific files or paths in a repository, allowing other users to understand who is responsible for each file or path. @@ -32,7 +32,7 @@ the process of finding the right reviewers and approvers for a given merge request. In larger organizations or popular open source projects, Code Owners -can also be useful to understand who to contact if you have +can help you understand who to contact if you have a question that may not be related to code review or a merge request approval. @@ -49,12 +49,12 @@ You can choose to add the `CODEOWNERS` file in three places: - Inside the `docs/` directory The `CODEOWNERS` file is valid for the branch where it lives. For example, if you change the code owners -in a feature branch, they won't be valid in the main branch until the feature branch is merged. +in a feature branch, the changes aren't valid in the main branch until the feature branch is merged. If you introduce new files to your repository and you want to identify the code owners for that file, -you have to update `CODEOWNERS` accordingly. If you update the code owners when you are adding the files (in the same -branch), GitLab will count the owners as soon as the branch is merged. If -you don't, you can do that later, but your new files will not belong to anyone until you update your +you must update `CODEOWNERS` accordingly. If you update the code owners when you are adding the files (in the same +branch), GitLab counts the owners as soon as the branch is merged. If +you don't, you can do that later, but your new files don't belong to anyone until you update your `CODEOWNERS` file in the TARGET branch. When a file matches multiple entries in the `CODEOWNERS` file, @@ -73,29 +73,32 @@ The user that would show for `README.md` would be `@user2`. ## Approvals by Code Owners -Once you've added Code Owners to a project, you can configure it to +After you've added Code Owners to a project, you can configure it to be used for merge request approvals: - As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers). - As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** -Developer or higher [permissions](../permissions.md) are required in order to +Developer or higher [permissions](../permissions.md) are required to approve a merge request. -Once set, Code Owners are displayed in merge requests widgets: +After it's set, Code Owners are displayed in merge request widgets:  -While the `CODEOWNERS` file can be used in addition to Merge Request [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules), -it can also be used as the sole driver of merge request approvals -(without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules)). -To do so, create the file in one of the three locations specified above and -set the code owners as required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). -Use [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files) -to specify the actual owners and granular permissions. +While you can use the `CODEOWNERS` file in addition to Merge Request +[Approval Rules](merge_requests/merge_request_approvals.md#approval-rules), +you can also use it as the sole driver of merge request approvals +without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules): -Using Code Owners in conjunction with [Protected Branches](protected_branches.md#protected-branches-approval-by-code-owners) -will prevent any user who is not specified in the `CODEOWNERS` file from pushing +1. Create the file in one of the three locations specified above. +1. Set the code owners as required approvers for + [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). +1. Use [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files) + to specify the actual owners and granular permissions. + +Using Code Owners in conjunction with [protected branches](protected_branches.md#protected-branches-approval-by-code-owners) +prevents any user who is not specified in the `CODEOWNERS` file from pushing changes for the specified files/paths, except those included in the **Allowed to push** column. This allows for a more inclusive push strategy, as administrators don't have to restrict developers from pushing directly to the @@ -114,13 +117,13 @@ in the `.gitignore` file followed by one or more of: - The `@name` of one or more groups that should be owners of the file. - Lines starting with `#` are ignored. -The order in which the paths are defined is significant: the last pattern that -matches a given path will be used to find the code owners. +The path definition order is significant: the last pattern +matching a given path is used to find the code owners. ### Groups as Code Owners -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab Starter 12.1. -> - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab 12.1. +> - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0. Groups and subgroups members are inherited as eligible Code Owners to a project, as long as the hierarchy is respected. @@ -131,7 +134,7 @@ suppose you have a project called "Project A" within the group and a "Project B" within the subgroup. The eligible Code Owners to Project B are both the members of the Group X and -the Subgroup Y. And the eligible Code Owners to the Project A are just the +the Subgroup Y. The eligible Code Owners to the Project A are just the members of the Group X, given that Project A doesn't belong to the Subgroup Y:  @@ -142,9 +145,9 @@ Code Owners:  -Once invited, any member (`@user`) of the group or subgroup can be set -as Code Owner to files of the Project A or B, as well as the entire Group X -(`@group-x`) or Subgroup Y (`@group-x/subgroup-y`), as exemplified below: +After being invited, any member (`@user`) of the group or subgroup can be set +as Code Owner to files of the Project A or B, and the entire Group X +(`@group-x`) or Subgroup Y (`@group-x/subgroup-y`), as follows: ```plaintext # A member of the group or subgroup as Code Owner to a file @@ -162,7 +165,7 @@ file.md @group-x @group-x/subgroup-y ### Code Owners Sections **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2 behind a feature flag, enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab Premium 13.2 behind a feature flag, enabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. Code Owner rules can be grouped into named sections. This allows for better @@ -185,8 +188,8 @@ changes, to set their own independent patterns by specifying discrete sections i teams can be added as reviewers. Sections can be added to `CODEOWNERS` files as a new line with the name of the -section inside square brackets. Every entry following it is assigned to that -section. The following example would create 2 Code Owner rules for the "README +section inside square brackets. Every entry following is assigned to that +section. The following example would create two Code Owner rules for the "README Owners" section: ```plaintext @@ -196,7 +199,7 @@ internal/README.md @user2 ``` Multiple sections can be used, even with matching file or directory patterns. -Reusing the same section name will group the results together under the same +Reusing the same section name groups the results together under the same section, with the most specific rule or last matching pattern being used. For example, consider the following entries in a `CODEOWNERS` file: @@ -213,7 +216,7 @@ model/db @gl-database README.md @gl-docs ``` -This will result in 3 entries under the "Documentation" section header, and 2 +This results in three entries under the "Documentation" section header, and two entries under "Database". Case is not considered when combining sections, so in this example, entries defined under the sections "Documentation" and "DOCUMENTATION" would be combined into one, using the case of the first instance @@ -227,9 +230,11 @@ the rules for "Groups" and "Documentation" sections: #### Optional Code Owners Sections **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.8 behind a feature flag, enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab Premium 13.8 behind a feature flag, enabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53227) in GitLab 13.9. -When you want to make a certain section optional, you can do so by adding a code owners section prepended with the caret `^` character. Approvals from owners listed in the section will **not** be required. For example: +To make a certain section optional, add a code owners section prepended with the +caret `^` character. Approvals from owners listed in the section are **not** required. For example: ```plaintext [Documentation] @@ -242,13 +247,13 @@ When you want to make a certain section optional, you can do so by adding a code *.go @root ``` -The optional code owners section will be displayed in merge requests under the **Approval Rules** area: +The optional code owners section displays in merge requests under the **Approval Rules** area:  -If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the requirement prevails. +If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the requirement prevails. -For example, the code owners of the "Documentation" section below will still be required to approve merge requests: +For example, the code owners of the "Documentation" section below is still required to approve merge requests: ```plaintext [Documentation] @@ -264,12 +269,12 @@ For example, the code owners of the "Documentation" section below will still be *.txt @root ``` -Optional sections in the code owners file are currently treated as optional only -when changes are submitted via merge requests. If a change is submitted directly -to the protected branch, approval from code owners will still be required, even if the -section is marked as optional. We plan to change this in a +Optional sections in the code owners file are treated as optional only +when changes are submitted by using merge requests. If a change is submitted directly +to the protected branch, approval from code owners is still required, even if the +section is marked as optional. We plan to change this behavior in a [future release](https://gitlab.com/gitlab-org/gitlab/-/issues/297638), -where direct pushes to the protected branch will be allowed for sections marked as optional. +and allow direct pushes to the protected branch for sections marked as optional. ## Example `CODEOWNERS` file diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md deleted file mode 100644 index 17e86b6d7e8..00000000000 --- a/doc/user/project/container_registry.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../packages/container_registry/index.md' ---- - -This document was moved to [another location](../packages/container_registry/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/cycle_analytics.md b/doc/user/project/cycle_analytics.md deleted file mode 100644 index 5c235f6708b..00000000000 --- a/doc/user/project/cycle_analytics.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../analytics/value_stream_analytics.md' ---- - -This document was moved to [another location](../analytics/value_stream_analytics.md) - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 831a8803622..72695580d9d 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -5,10 +5,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto, reference --- -# Deploy Boards **(CORE)** +# Deploy Boards **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. -> - [Moved](<https://gitlab.com/gitlab-org/gitlab/-/issues/212320>) to GitLab Core in 13.8. +> - [Moved](<https://gitlab.com/gitlab-org/gitlab/-/issues/212320>) to GitLab Free in 13.8. GitLab Deploy Boards offer a consolidated view of the current health and status of each CI [environment](../../ci/environments/index.md) running on [Kubernetes](https://kubernetes.io), displaying the status @@ -93,7 +93,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ `$CI_PROJECT_PATH_SLUG` are the values of the CI variables. This is so we can lookup the proper environment in a cluster/namespace which may have more than one. These resources should be contained in the namespace defined in - the Kubernetes service setting. You can use an [Autodeploy](../../topics/autodevops/stages.md#auto-deploy) `.gitlab-ci.yml` + the Kubernetes service setting. You can use an [Auto deploy](../../topics/autodevops/stages.md#auto-deploy) `.gitlab-ci.yml` template which has predefined stages and commands to use, and automatically applies the annotations. Each project must have a unique namespace in Kubernetes as well. The image below demonstrates how this is shown inside @@ -158,7 +158,7 @@ version of your application. ## Further reading -- [GitLab Autodeploy](../../topics/autodevops/stages.md#auto-deploy) +- [GitLab Auto deploy](../../topics/autodevops/stages.md#auto-deploy) - [GitLab CI/CD environment variables](../../ci/variables/README.md) - [Environments and deployments](../../ci/environments/index.md) - [Kubernetes deploy example](https://gitlab.com/gitlab-examples/kubernetes-deploy) diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 93ed1030e1f..a45c3d26f1a 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -5,12 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto, reference --- -# Deploy Keys +# Deploy keys -Deploy keys allow read-only or read-write (if enabled) access to one or -more repositories, by importing an SSH public key to your GitLab instance. +Deploy keys allow read-only or read-write access to your +repositories by importing an SSH public key into your GitLab instance. -This is useful for cloning repositories to your Continuous +This is useful, for example, for cloning repositories to your Continuous Integration (CI) server. By using deploy keys, you don't have to set up a fake user account. @@ -21,7 +21,7 @@ There are two types of deploy keys: ## Key details on deploy keys -Deploy Keys allow a remote machine (VM, physical, and so on) to access a GitLab +Deploy keys allow a remote machine (VM, physical, and so on) to access a GitLab repository with just a few steps. If you want a remote machine to interact with a GitLab repository in automation, it's a simple solution. @@ -35,7 +35,7 @@ If this security implication is a concern for your organization, [Deploy Tokens](../deploy_tokens/index.md) works as an alternative, but with more security control. -## Deploy Keys Permissions +## Deploy keys permissions You can choose the access level of a deploy key when you enable it on a project: @@ -72,7 +72,7 @@ help you access a repository, but there are some notables differences between th on it, but this [is possible with deploy tokens](../deploy_tokens/index.md#gitlab-deploy-token). - You need an SSH key pair to use deploy keys, but not deploy tokens. -## How to enable Deploy Keys +## How to enable deploy keys ### Project deploy keys @@ -80,17 +80,17 @@ help you access a repository, but there are some notables differences between th can add or enable a deploy key for a project repository: 1. Navigate to the project's **Settings > Repository** page. -1. Expand the **Deploy Keys** section. +1. Expand the **Deploy keys** section. 1. Specify a title for the new deploy key and paste your public SSH key. -1. (Optional) Check **Write access allowed** to allow `read-write` access. Leave it unchecked for `read-only` access. +1. (Optional) Check **Grant write permissions to this key** to allow `read-write` access. Leave it unchecked for `read-only` access. -There are three lists of Project Deploy Keys: +There are three lists of project deploy keys: - Enabled deploy keys - Privately accessible deploy keys - Public accessible deploy keys - + After you add a key, it's enabled for this project by default and it appears in the **Enabled deploy keys** tab. @@ -129,7 +129,7 @@ Instance administrators can add public deploy keys: if the key gives access to a SaaS CI/CD instance, use the name of that service in the key name if that is all the key is used for. - + After adding a key, it's available to any shared systems. Project maintainers or higher can [authorize a public deploy key](#project-deploy-keys) to start using it with the project. @@ -153,7 +153,7 @@ until a project maintainer chooses to make use of it. ## Troubleshooting -### Deploy Key cannot push to a protected branch +### Deploy key cannot push to a protected branch If the owner of this deploy key doesn't have access to a [protected branch](../protected_branches.md), then this deploy key doesn't have access to diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 5a62730d989..6f05c40eefc 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -67,7 +67,7 @@ following table along with GitLab version it was introduced in: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29639) in GitLab 12.1. -The default username format is `gitlab+deploy-token-#{n}`. Some tools or +The default username format is `gitlab+deploy-token-{n}`. Some tools or platforms may not support this format; in this case you can specify a custom username to be used when creating the deploy token. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 3108bdda7a0..c56470ee07a 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -6,16 +6,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Description templates ->[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4981) in GitLab 8.11. - We all know that a properly submitted issue is more likely to be addressed in a timely manner by the developers of a project. -Description templates allow you to define context-specific templates for issue -and merge request description fields for your project, as well as help filter -out a lot of unnecessary noise from issues. - -## Overview +With description templates, you can define context-specific templates for issue and merge request +description fields for your project, and filter out unnecessary noise from issues. By using the description templates, users that create a new issue or merge request can select a description template to help them communicate with other @@ -28,7 +23,10 @@ Description templates must be written in [Markdown](../markdown.md) and stored in your project's repository under a directory named `.gitlab`. Only the templates of the default branch are taken into account. -## Use-cases +To learn how to create templates for various file types in groups, visit +[Group file templates](../group/index.md#group-file-templates). + +## Use cases - Add a template to be used in every issue for a specific project, giving instructions and guidelines, requiring for information specific to that subject. @@ -39,6 +37,8 @@ templates of the default branch are taken into account. images guidelines, link to the related issue, reviewer name, and so on. - You can also create issues and merge request templates for different stages of your workflow, for example, feature proposal, feature improvement, or a bug report. +- You can use an [issue description template](#creating-issue-templates) as a + [Service Desk email template](service_desk.md#new-service-desk-issues). ## Creating issue templates @@ -47,20 +47,20 @@ directory in your repository. Commit and push to your default branch. To create a Markdown file: - 1. Click the `+` button next to `master` and click **New file**. - 1. Add the name of your issue template to the **File name** text field next to `master`. - Make sure that your file has the `.md` extension, for - example `feature_request.md` or `Feature Request.md`. - 1. Commit and push to your default branch. +1. Click the `+` button next to `master` and click **New file**. +1. Add the name of your issue template to the **File name** text field next to `master`. + Make sure that your file has the `.md` extension, for + example `feature_request.md` or `Feature Request.md`. +1. Commit and push to your default branch. If you don't have a `.gitlab/issue_templates` directory in your repository, you need to create it. To create the `.gitlab/issue_templates` directory: - 1. Click the `+` button next to `master` and select **New directory**. - 1. Name this new directory `.gitlab` and commit to your default branch. - 1. Click the `+` button next to `master` again and select **New directory**.This time, n - 1. Name your directory `issue_templates` and commit to your default branch. +1. Click the `+` button next to `master` and select **New directory**. +1. Name this new directory `.gitlab` and commit to your default branch. +1. Click the `+` button next to `master` again and select **New directory**. +1. Name your directory `issue_templates` and commit to your default branch. To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-a-new-issue) and see if you can choose a description template. @@ -80,17 +80,16 @@ to the issue description field. The **Reset template** button discards any changes you made after picking the template and returns it to its initial status. NOTE: -You can create short-cut links to create an issue using a designated template. For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal`. +You can create shortcut links to create an issue using a designated template. +For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal`.  -## Setting a default template for merge requests and issues **(STARTER)** +## Setting a default template for merge requests and issues **(PREMIUM)** -> - This feature was introduced before [description templates](#overview) and is available in [GitLab Starter](https://about.gitlab.com/pricing/). It can be enabled in the project's settings. -> - Templates for issues were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28) in GitLab EE 8.1. -> - Templates for merge requests were [introduced](https://gitlab.com/gitlab-org/gitlab/commit/7478ece8b48e80782b5465b96c79f85cc91d391b) in GitLab EE 6.9. +> - Moved to GitLab Premium in 13.9. -The visibility of issues and/or merge requests should be set to either "Everyone +The visibility of issues or merge requests should be set to either "Everyone with access" or "Only Project Members" in your project's **Settings / Visibility, project features, permissions** section, otherwise the template text areas don't show. This is the default behavior, so in most cases you should be fine. @@ -113,52 +112,46 @@ pre-filled with the text you entered in the template(s). ## Description template example -We make use of Description Templates for Issues and Merge Requests within the GitLab Community -Edition project. Please refer to the [`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/tree/master/.gitlab) -for some examples. +We make use of description templates for issues and merge requests in the GitLab project. +For some examples, refer to the [`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/tree/master/.gitlab). NOTE: -It's possible to use [quick actions](quick_actions.md) within description templates to quickly add +It's possible to use [quick actions](quick_actions.md) in description templates to quickly add labels, assignees, and milestones. The quick actions are only executed if the user submitting the issue or merge request has the permissions to perform the relevant actions. Here is an example of a Bug report template: -```plaintext -Summary +```markdown +## Summary (Summarize the bug encountered concisely) - -Steps to reproduce +## Steps to reproduce (How one can reproduce the issue - this is very important) +## Example Project -Example Project - -(If possible, please create an example project here on GitLab.com that exhibits the problematic behaviour, and link to it here in the bug report) +(If possible, please create an example project here on GitLab.com that exhibits the problematic +behavior, and link to it here in the bug report. +If you are using an older version of GitLab, this will also determine whether the bug has been fixed +in a more recent version) -(If you are using an older version of GitLab, this will also determine whether the bug has been fixed in a more recent version) - - -What is the current bug behavior? +## What is the current bug behavior? (What actually happens) - -What is the expected correct behavior? +## What is the expected correct behavior? (What you should see instead) +## Relevant logs and/or screenshots -Relevant logs and/or screenshots - -(Paste any relevant logs - please use code blocks (```) to format console output, -logs, and code as it's very hard to read otherwise.) - +(Paste any relevant logs - please use code blocks (```) to format console output, logs, and code, as +it's very hard to read otherwise.) -Possible fixes +## Possible fixes (If you can, link to the line of code that might be responsible for the problem) diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 49918b8f023..5c24ec6caf6 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# File Locking **(CORE)** +# File Locking **(FREE)** Preventing wasted work caused by unresolvable merge conflicts requires a different way of working. This means explicitly requesting write permissions, @@ -26,7 +26,7 @@ GitLab supports two different modes of file locking: - [Exclusive file locks](#exclusive-file-locks) for binary files: done **through the command line** with Git LFS and `.gitattributes`, it prevents locked - files from being modified on any branch. **(CORE)** + files from being modified on any branch. **(FREE)** - [Default branch locks](#default-branch-file-and-directory-locks): done **through the GitLab UI**, it prevents locked files and directories being modified on the default branch. **(PREMIUM)** @@ -41,7 +41,7 @@ users will be prevented from modifying locked files by pushing, merging, or any other means, and will be shown an error like: `The path '.gitignore' is locked by Administrator`. -## Exclusive file locks +## Exclusive file locks **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35856) in GitLab 10.5. @@ -198,7 +198,8 @@ Suggested workflow for shared projects: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/440) in GitLab Enterprise Edition 8.9. Available in [GitLab Premium](https://about.gitlab.com/pricing/). This process allows you to lock one file at a time through the GitLab UI and -requires access to [GitLab Premium, GitLab.com Silver](https://about.gitlab.com/pricing/), or higher tiers. +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`). diff --git a/doc/user/project/git_attributes.md b/doc/user/project/git_attributes.md index 459abea455b..2806f6e48d1 100644 --- a/doc/user/project/git_attributes.md +++ b/doc/user/project/git_attributes.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Git Attributes +# Git Attributes **(FREE)** GitLab supports defining custom [Git attributes](https://git-scm.com/docs/gitattributes) such as what files to treat as binary, and what language to use for syntax highlighting diff --git a/doc/user/project/gpg_signed_commits/index.md b/doc/user/project/gpg_signed_commits/index.md deleted file mode 100644 index 206013210a0..00000000000 --- a/doc/user/project/gpg_signed_commits/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../repository/gpg_signed_commits/index.md' ---- - -This document was moved to [another location](../repository/gpg_signed_commits/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index 1d92e32e071..c914c90c923 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -5,24 +5,30 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Syntax Highlighting +# Syntax Highlighting **(FREE)** -GitLab provides syntax highlighting on all files through the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It will try to guess what language to use based on the file extension, which most of the time is sufficient. +GitLab provides syntax highlighting on all files through the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It attempts to guess what language to use based on the file extension, which most of the time is sufficient. NOTE: The [Web IDE](web_ide/index.md) and [Snippets](../snippets.md) use [Monaco Editor](https://microsoft.github.io/monaco-editor/) for text editing, which internally uses the [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) library for syntax highlighting. -If GitLab is guessing wrong, you can override its choice of language using the `gitlab-language` attribute in `.gitattributes`. For example, if you are working in a Prolog project and using the `.pl` file extension (which would normally be highlighted as Perl), you can add the following to your `.gitattributes` file: +If GitLab is guessing wrong, you can override its choice of language using the +`gitlab-language` attribute in `.gitattributes`. For example, if you are working in a +<!-- vale gitlab.Spelling = NO --> Prolog <!-- vale gitlab.Spelling = YES --> +project and using the `.pl` file extension (which would normally be highlighted as Perl), +you can add the following to your `.gitattributes` file: ``` conf *.pl gitlab-language=prolog ``` -When you check in and push that change, all `*.pl` files in your project will be highlighted as Prolog. +<!-- vale gitlab.Spelling = NO --> +When you check in and push that change, all `*.pl` files in your project are highlighted as Prolog. +<!-- vale gitlab.Spelling = YES --> -The paths here are simply Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). So, if you were to invent a file format called a `Nicefile` at the root of your project that used Ruby syntax, all you need is: +The paths here are Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). So, if you were to invent a file format called a `Nicefile` at the root of your project that used Ruby syntax, all you need is: ``` conf /Nicefile gitlab-language=ruby @@ -38,7 +44,8 @@ To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shen /other-file gitlab-language=text?token=Error ``` -Please note that these configurations will only take effect when the `.gitattributes` file is in your default branch (usually `master`). +Please note that these configurations only take effect when the `.gitattributes` +file is in your default branch (usually `master`). NOTE: The Web IDE does not support `.gitattribute` files, but it's [planned for a future release](https://gitlab.com/gitlab-org/gitlab/-/issues/22014). diff --git a/doc/user/project/img/optional_code_owners_sections_v13_8.png b/doc/user/project/img/optional_code_owners_sections_v13_8.png Binary files differindex 7a5a2fab6e3..50916466226 100644 --- a/doc/user/project/img/optional_code_owners_sections_v13_8.png +++ b/doc/user/project/img/optional_code_owners_sections_v13_8.png diff --git a/doc/user/project/img/service_desk_nav_item.png b/doc/user/project/img/service_desk_nav_item.png Binary files differdeleted file mode 100644 index fdf8fa024c3..00000000000 --- a/doc/user/project/img/service_desk_nav_item.png +++ /dev/null diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index 82ff889c043..61d4d29aa4d 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -62,7 +62,7 @@ Migrating to Git/GitLab will benefit you: an open source end-to-end software development platform with built-in version control, issue tracking, code review, CI/CD, and more. - **Support for many network protocols**. Git supports SSH, HTTP/HTTPS and rsync - among others, whereas CVS supports only SSH and its own insecure pserver + among others, whereas CVS supports only SSH and its own insecure `pserver` protocol with no user authentication. ## How to migrate @@ -70,7 +70,7 @@ Migrating to Git/GitLab will benefit you: Here's a few links to get you started with the migration: - [Migrate using the `cvs-fast-export` tool](https://gitlab.com/esr/cvs-fast-export) -- [Stack Overflow post on importing the CVS repo](https://stackoverflow.com/a/11490134/974710) +- [Stack Overflow post on importing the CVS repository](https://stackoverflow.com/a/11490134/974710) - [Convert a CVS repository to Git](https://www.techrepublic.com/blog/linux-and-open-source/convert-cvs-repositories-to-git/) - [Man page of the `git-cvsimport` tool](https://mirrors.edge.kernel.org/pub/software/scm/git/docs/git-cvsimport.html) - [Migrate using `reposurgeon`](http://www.catb.org/~esr/reposurgeon/repository-editing.html#conversion) diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md index 38679914a9d..bac10cb0948 100644 --- a/doc/user/project/import/gemnasium.md +++ b/doc/user/project/import/gemnasium.md @@ -29,7 +29,8 @@ If you want to continue monitoring your dependencies, see the ## What happened to my account? Your account has been automatically closed on May 15th, 2018. If you had a paid -subscription at that time, your card will be refunded on a pro rata temporis basis. +subscription at that time, your card will be refunded on a +<!-- vale gitlab.Spelling = NO --> pro rata temporis <!-- vale gitlab.Spelling = YES --> basis. You may contact `gemnasium@gitlab.com` regarding your closed account. ## Will my account/data be transferred to GitLab Inc.? @@ -66,15 +67,18 @@ GitHub.com or GitHub Enterprise repository. This will automatically prompt GitLab CI/CD to run whenever code is pushed to GitHub and post CI/CD results back to both GitLab and GitHub when completed. -1. Create a new project, and select "CI/CD for external repo": +<!-- vale gitlab.Spelling = NO --> + +1. Create a new project, and select **CI/CD for external repo**:  + <!-- vale gitlab.Spelling = YES --> -1. Use the "GitHub" button to connect your repositories. +1. Use the **GitHub** button to connect your repositories.  -1. Select the project(s) to be set up with GitLab CI/CD and chose "Connect". +1. Select the project(s) to be set up with GitLab CI/CD and choose **Connect**.  diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 754c3e31799..f6ed53763dd 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -74,3 +74,25 @@ In the event of merging two GitLab instances together (for example, both instanc refer to the instructions in [Migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). Additionally, you can migrate users using the [Users API](../../../api/users.md) with an administrator user. + +## Project aliases **(PREMIUM SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in GitLab Premium 12.1. + +When migrating repositories to GitLab and they are being accessed by other systems, +it's very useful to be able to access them using the same name especially when +they are a lot. It reduces the risk of changing significant number of Git URLs in +a large number of systems. + +GitLab provides a functionality to help with this. In GitLab, repositories are +usually accessed with a namespace and project name. It is also possible to access +them via a project alias. This feature is only available on Git over SSH. + +A project alias can be only created via API and only by GitLab administrators. +Follow the [Project Aliases API documentation](../../../api/project_aliases.md) for +more details. + +After an alias has been created for a project (such as an alias `gitlab` for the +project `https://gitlab.com/gitlab-org/gitlab`), you can clone the repository +with the alias (e.g `git clone git@gitlab.com:gitlab.git` instead of +`git clone git@gitlab.com:gitlab-org/gitlab.git`). diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 0e8cc159aec..3ff612c51a7 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -9,11 +9,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can import your existing repositories by providing the Git URL: -1. From your GitLab dashboard click **New project** -1. Switch to the **Import project** tab -1. Click on the **Repo by URL** button -1. Fill in the "Git repository URL" and the remaining project fields -1. Click **Create project** to begin the import process -1. Once complete, you will be redirected to your newly created project +<!-- vale gitlab.Spelling = NO --> +<!-- vale gitlab.SubstitutionWarning = NO --> + +1. From your GitLab dashboard click **New project**. +1. Switch to the **Import project** tab. +1. Click on the **Repo by URL** button. +1. Fill in the "Git repository URL" and the remaining project fields. +1. Click **Create project** to begin the import process. +1. Once complete, you will be redirected to your newly created project. + +<!-- vale gitlab.Spelling = YES --> +<!-- vale gitlab.SubstitutionWarning = YES -->  diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index 3642d07106c..a816dca59bc 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -30,7 +30,7 @@ There are two approaches to SVN to Git migration: migration. It creates a writable Git mirror of a local or remote Subversion repository and that way you can use both Subversion and Git as long as you like. It requires access to your GitLab server as it talks with the Git repositories -directly in a filesystem level. +directly in a file system level. ### SubGit prerequisites diff --git a/doc/user/project/import/tfs.md b/doc/user/project/import/tfs.md deleted file mode 100644 index 31f9b200558..00000000000 --- a/doc/user/project/import/tfs.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'tfvc.md' ---- - -This document was moved to [another location](tfvc.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/index.md b/doc/user/project/index.md index e3079c3731d..a8ab1cbbb63 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -5,63 +5,59 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Projects +# Projects **(FREE)** -In GitLab, you can create projects for hosting -your codebase, use it as an issue tracker, collaborate on code, and continuously -build, test, and deploy your app with built-in GitLab CI/CD. +In GitLab, you can create projects to host +your codebase. You can also use projects to track issues, plan work, +collaborate on code, and continuously build, test, and use +built-in CI/CD to deploy your app. -Your projects can be [available](../../public_access/public_access.md) -publicly, internally, or privately, at your choice. GitLab does not limit -the number of private projects you create. +Projects can be available [publicly, internally, or privately](../../public_access/public_access.md). +GitLab does not limit the number of private projects you can create. ## Project features -When you create a project in GitLab, you'll have access to a large number of -[features](https://about.gitlab.com/features/): +Projects include the following [features](https://about.gitlab.com/features/): **Repositories:** -- [Issue tracker](issues/index.md): Discuss implementations with your team within issues - - [Issue Boards](issue_board.md): Organize and prioritize your workflow - - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Allow your teams to create their own workflows (Issue Boards) for the same project -- [Repositories](repository/index.md): Host your code in a fully - integrated platform - - [Branches](repository/branches/index.md): use Git branching strategies to - collaborate on code +- [Issue tracker](issues/index.md): Discuss implementations with your team. + - [Issue Boards](issue_board.md): Organize and prioritize your workflow. + - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (Issue Boards) for a project. +- [Repositories](repository/index.md): Host your code in a fully-integrated platform. + - [Branches](repository/branches/index.md): Use Git branching strategies to + collaborate on code. - [Protected branches](protected_branches.md): Prevent collaborators - from messing with history or pushing code without review - - [Protected tags](protected_tags.md): Control over who has - permission to create tags, and prevent accidental update or deletion + from changing history or pushing code without review. + - [Protected tags](protected_tags.md): Control who has + permission to create tags and prevent accidental updates or deletions. - [Repository mirroring](repository/repository_mirroring.md) - - [Signing commits](repository/gpg_signed_commits/index.md): use GPG to sign your commits - - [Deploy tokens](deploy_tokens/index.md): Manage project-based deploy tokens that allow permanent access to the repository and Container Registry. + - [Signing commits](repository/gpg_signed_commits/index.md): Use GNU Privacy Guard (GPG) to sign your commits. + - [Deploy tokens](deploy_tokens/index.md): Manage access to the repository and Container Registry. - [Web IDE](web_ide/index.md) - [CVE ID Requests](../application_security/cve_id_request.md): Request a CVE identifier to track a vulnerability in your project. **Issues and merge requests:** -- [Issue tracker](issues/index.md): Discuss implementations with your team within issues - - [Issue Boards](issue_board.md): Organize and prioritize your workflow - - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Allow your teams to create their own workflows (Issue Boards) for the same project -- [Merge Requests](merge_requests/index.md): Apply your branching - strategy and get reviewed by your team +- [Issue tracker](issues/index.md): Discuss implementations with your team. + - [Issue Boards](issue_board.md): Organize and prioritize your workflow. + - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (Issue Boards) for a project. +- [Merge Requests](merge_requests/index.md): Apply a branching + strategy and get reviewed by your team. - [Merge Request Approvals](merge_requests/merge_request_approvals.md): Ask for approval before - implementing a change **(STARTER)** - - [Fix merge conflicts from the UI](merge_requests/resolve_conflicts.md): - Your Git diff tool right from the GitLab UI - - [Review Apps](../../ci/review_apps/index.md): Live preview the results - of the changes proposed in a merge request in a per-branch basis -- [Labels](labels.md): Organize issues and merge requests by labels -- [Time Tracking](time_tracking.md): Track estimate time - and time spent on - the conclusion of an issue or merge request -- [Milestones](milestones/index.md): Work towards a target date + implementing a change. + - [Fix merge conflicts from the UI](merge_requests/resolve_conflicts.md): View Git diffs from the GitLab UI. + - [Review Apps](../../ci/review_apps/index.md): By branch, preview the results + of the changes proposed in a merge request. +- [Labels](labels.md): Organize issues and merge requests by labels. +- [Time Tracking](time_tracking.md): Track time estimated and + spent on issues and merge requests. +- [Milestones](milestones/index.md): Work toward a target date. - [Description templates](description_templates.md): Define context-specific - templates for issue and merge request description fields for your project -- [Slash commands (quick actions)](quick_actions.md): Textual shortcuts for - common actions on issues or merge requests + templates for issue and merge request description fields. +- [Slash commands (quick actions)](quick_actions.md): Create text shortcuts for + common actions. - [Autocomplete characters](autocomplete_characters.md): Autocomplete references to users, groups, issues, merge requests, and other GitLab elements. @@ -69,109 +65,55 @@ When you create a project in GitLab, you'll have access to a large number of **GitLab CI/CD:** -- [GitLab CI/CD](../../ci/README.md): the GitLab built-in [Continuous Integration, Delivery, and Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) tool +- [GitLab CI/CD](../../ci/README.md): Use the built-in [Continuous Integration, Delivery, and Deployment](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) tool. - [Container Registry](../packages/container_registry/index.md): Build and push Docker - images out-of-the-box + images. - [Auto Deploy](../../topics/autodevops/stages.md#auto-deploy): Configure GitLab CI/CD - to automatically set up your app's deployment + to automatically set up your app's deployment. - [Enable and disable GitLab CI/CD](../../ci/enable_or_disable_ci.md) - [Pipelines](../../ci/pipelines/index.md): Configure and visualize - your GitLab CI/CD pipelines from the UI + your GitLab CI/CD pipelines from the UI. - [Scheduled Pipelines](../../ci/pipelines/schedules.md): Schedule a pipeline - to start at a chosen time + to start at a chosen time. - [Pipeline Graphs](../../ci/pipelines/index.md#visualize-pipelines): View your - entire pipeline from the UI + pipeline from the UI. - [Job artifacts](../../ci/pipelines/job_artifacts.md): Define, - browse, and download job artifacts - - [Pipeline settings](../../ci/pipelines/settings.md): Set up Git strategy (choose the default way your repository is fetched from GitLab in a job), - timeout (defines the maximum amount of time in minutes that a job is able run), custom path for `.gitlab-ci.yml`, test coverage parsing, pipeline's visibility, and much more - - [Kubernetes cluster integration](clusters/index.md): Connecting your GitLab project - with a Kubernetes cluster - - [Feature Flags](../../operations/feature_flags.md): Feature flags allow you to ship a project in - different flavors by dynamically toggling certain functionality **(PREMIUM)** + browse, and download job artifacts. + - [Pipeline settings](../../ci/pipelines/settings.md): Set up Git strategy (how jobs fetch your repository), + timeout (the maximum amount of time a job can run), custom path for `.gitlab-ci.yml`, test coverage parsing, pipeline visibility, and more. + - [Kubernetes cluster integration](clusters/index.md): Connect your GitLab project + with a Kubernetes cluster. + - [Feature Flags](../../operations/feature_flags.md): Ship different features + by dynamically toggling functionality. **(PREMIUM)** - [GitLab Pages](pages/index.md): Build, test, and deploy your static - website with GitLab Pages + website. **Other features:** -- [Wiki](wiki/index.md): document your GitLab project in an integrated Wiki. -- [Snippets](../snippets.md): store, share and collaborate on code snippets. -- [Value Stream Analytics](../analytics/value_stream_analytics.md): review your development lifecycle. -- [Insights](insights/index.md): configure the Insights that matter for your projects. **(ULTIMATE)** -- [Security Dashboard](../application_security/security_dashboard/index.md): Security Dashboard. **(ULTIMATE)** -- [Syntax highlighting](highlighting.md): an alternative to customize - your code blocks, overriding the GitLab default choice of language. -- [Badges](badges.md): badges for the project overview. -- [Releases](releases/index.md): a way to track deliverables in your project as snapshot in time of - the source, build output, other metadata, and other artifacts +- [Wiki](wiki/index.md): Document your GitLab project in an integrated Wiki. +- [Snippets](../snippets.md): Store, share and collaborate on code snippets. +- [Value Stream Analytics](../analytics/value_stream_analytics.md): Review your development lifecycle. +- [Insights](insights/index.md): Configure the insights that matter for your projects. **(ULTIMATE)** +- [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. +- [Releases](releases/index.md): Take a snapshot of + the source, build output, metadata, and artifacts associated with a released version of your code. -- [Conan packages](../packages/conan_repository/index.md): your private Conan repository in GitLab. -- [Maven packages](../packages/maven_repository/index.md): your private Maven repository in GitLab. -- [NPM packages](../packages/npm_registry/index.md): your private NPM package registry in GitLab. -- [Code owners](code_owners.md): specify code owners for certain files **(STARTER)** -- [License Compliance](../compliance/license_compliance/index.md): approve and deny licenses for projects. **(ULTIMATE)** -- [Dependency List](../application_security/dependency_list/index.md): view project dependencies. **(ULTIMATE)** -- [Requirements](requirements/index.md): Requirements allow you to create criteria to check your products against. **(ULTIMATE)** -- [Static Site Editor](static_site_editor/index.md): quickly edit content on static websites without prior knowledge of the codebase or Git commands. -- [Code Intelligence](code_intelligence.md): code navigation features. +- [Package Registry](../packages/package_registry/index.md): Publish and install packages. +- [Code owners](code_owners.md): Specify code owners for specific files. +- [License Compliance](../compliance/license_compliance/index.md): Approve and deny licenses for projects. **(ULTIMATE)** +- [Dependency List](../application_security/dependency_list/index.md): View project dependencies. **(ULTIMATE)** +- [Requirements](requirements/index.md): Create criteria to check your products against. **(ULTIMATE)** +- [Static Site Editor](static_site_editor/index.md): Edit content on static websites without prior knowledge of the codebase or Git commands. +- [Code Intelligence](code_intelligence.md): Navigate code. -### Project integrations +## Project integrations [Integrate your project](integrations/index.md) with Jira, Mattermost, Kubernetes, Slack, and a lot more. -## New project - -Learn how to [create a new project](../../gitlab-basics/create-project.md) in GitLab. - -### Fork a project - -You can [fork a project](repository/forking_workflow.md) in order to: - -- Collaborate on code by forking a project and creating a merge request - from your fork to the upstream project -- Fork a sample project to work on the top of that - -### Star a project - -You can star a project to make it easier to find projects you frequently use. -The number of stars a project has can indicate its popularity. - -To star a project: - -1. Go to the home page of the project you want to star. -1. In the upper right corner of the page, click **Star**. - -To view your starred projects: - -1. Click **Projects** in the navigation bar. -1. Click **Starred Projects**. -1. GitLab displays information about your starred projects, including: - - - Project description, including name, description, and icon - - Number of times this project has been starred - - Number of times this project has been forked - - Number of open merge requests - - Number of open issues - -### Explore projects - -You can explore other popular projects available on GitLab. To explore projects: - -1. Click **Projects** in the navigation bar. -1. Click **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 -projects with the largest number of comments in the past month, click **Trending**. - -## Project settings - -Set the project's visibility level and the access levels to its various pages -and perform actions like archiving, renaming or transferring a project. - -Read through the documentation on [project settings](settings/index.md). - ## Import or export a project - [Import a project](import/index.md) from: @@ -182,64 +124,6 @@ Read through the documentation on [project settings](settings/index.md). - [Export a project from GitLab](settings/import_export.md#exporting-a-project-and-its-data) - [Importing and exporting projects between GitLab instances](settings/import_export.md) -## Delete a project - -To delete a project, first navigate to the home page for that project. - -1. Navigate to **Settings > General**. -1. Expand the **Advanced** section. -1. Scroll down to the **Delete project** section. -1. Click **Delete project** -1. Confirm this action by typing in the expected text. - -Projects in personal namespaces are deleted immediately on request. For information on delayed deletion of projects within a group, please see [Enabling delayed project removal](../group/index.md#enabling-delayed-project-removal). - -## CI/CD for external repositories **(PREMIUM)** - -Instead of importing a repository directly to GitLab, you can connect your repository -as a CI/CD project. - -Read through the documentation on [CI/CD for external repositories](../../ci/ci_cd_for_external_repos/index.md). - -## Project members - -Learn how to [add members to your projects](members/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**. - -### Leave a project - -**Leave project** will only display on the project's dashboard -when a project is part of a group (under a -[group namespace](../group/index.md#namespaces)). -If you choose to leave a project you will no longer be a project -member, therefore, unable to contribute. - -## Project's landing page - -The project's landing page shows different information depending on -the project's visibility settings and user permissions. - -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) - is displayed (if any), followed by the list of directories within the - project's repository. -- If the project doesn't contain either of these files, the - visitor will see the list of files and directories of the repository. - -For users without permissions to view the project's code: - -- The wiki homepage is displayed, if any. -- The list of issues within the project is displayed. - ## GitLab Workflow - VS Code extension To avoid switching from the GitLab UI and VS Code while working in GitLab repositories, you can integrate @@ -248,142 +132,6 @@ the [VS Code](https://code.visualstudio.com/) editor with GitLab through the To review or contribute to the extension's code, visit [its codebase in GitLab](https://gitlab.com/gitlab-org/gitlab-vscode-extension/). -## 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. - -Depending on the situation, different things apply. - -When [renaming a user](../profile/index.md#changing-your-username), -[changing a group path](../group/index.md#changing-a-groups-path) or [renaming a repository](settings/index.md#renaming-a-repository): - -- Existing web URLs for the namespace and anything under it (e.g., projects) will - redirect to the new URLs. -- Starting with GitLab 10.3, existing Git remote URLs for projects under the - namespace will 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 will be displayed instead of rejecting your action. - This means that any automation scripts, or Git clients will continue to - work after a rename, making any transition a lot smoother. -- The redirects will be available as long as the original path is not claimed by - another group, user or project. - -## Use your project as a Go package - -Any project can be used as a Go package. GitLab responds correctly to `go get` -and `godoc.org` discovery requests, including the -[`go-import`](https://golang.org/cmd/go/#hdr-Remote_import_paths) and -[`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) meta tags. - -Private projects, including projects in subgroups, can be used as a Go package, -but may require configuration to work correctly. GitLab will respond correctly -to `go get` discovery requests for projects that *are not* in subgroups, -regardless of authentication or authorization. -[Authentication](#authenticate-go-requests) is required to use a private project -in a subgroup as a Go package. Otherwise, GitLab will truncate the path for -private projects in subgroups to the first two segments, causing `go get` to -fail. - -GitLab implements its own Go proxy. This feature must be enabled by an -administrator and requires additional configuration. See [GitLab Go -Proxy](../packages/go_proxy/index.md). - -### Disable Go module features for private projects - -In Go 1.12 and later, Go queries module proxies and checksum databases in the -process of [fetching a -module](../../development/go_guide/dependencies.md#fetching). This can be -selectively disabled with `GOPRIVATE` (disable both), -[`GONOPROXY`](../../development/go_guide/dependencies.md#proxies) (disable proxy -queries), and [`GONOSUMDB`](../../development/go_guide/dependencies.md#fetching) -(disable checksum queries). - -`GOPRIVATE`, `GONOPROXY`, and `GONOSUMDB` are comma-separated lists of Go -modules and Go module prefixes. For example, -`GOPRIVATE=gitlab.example.com/my/private/project` will disable queries for that -one project, but `GOPRIVATE=gitlab.example.com` will disable queries for *all* -projects on GitLab.com. Go will not query module proxies if the module name or a -prefix of it appears in `GOPRIVATE` or `GONOPROXY`. Go will not query checksum -databases if the module name or a prefix of it appears in `GONOPRIVATE` or -`GONOSUMDB`. - -### Authenticate Go requests - -To authenticate requests to private projects made by Go, use a [`.netrc` -file](https://ec.haxx.se/usingcurl-netrc.html) and a [personal access -token](../profile/personal_access_tokens.md) in the password field. **This only -works if your GitLab instance can be accessed with HTTPS.** The `go` command -will not transmit credentials over insecure connections. This will authenticate -all HTTPS requests made directly by Go but will not authenticate requests made -through Git. - -For example: - -```plaintext -machine gitlab.example.com -login <gitlab_user_name> -password <personal_access_token> -``` - -NOTE: -On Windows, Go reads `~/_netrc` instead of `~/.netrc`. - -### Authenticate Git fetches - -If a module cannot be fetched from a proxy, Go will fall back to using Git (for -GitLab projects). Git will use `.netrc` to authenticate requests. Alternatively, -Git can be configured to embed specific credentials in the request URL, or to -use SSH instead of HTTPS (as Go always uses HTTPS to fetch Git repositories): - -```shell -# embed credentials in any request to GitLab.com: -git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com" - -# use SSH instead of HTTPS: -git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com" -``` - -## Access project page with project ID - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. - -To quickly access a project from the GitLab UI using the project ID, -visit the `/projects/:id` URL in your browser or other tool accessing the project. - -## Project aliases **(PREMIUM ONLY)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. - -When migrating repositories to GitLab and they are being accessed by other systems, -it's very useful to be able to access them using the same name especially when -they are a lot. It reduces the risk of changing significant number of Git URLs in -a large number of systems. - -GitLab provides a functionality to help with this. In GitLab, repositories are -usually accessed with a namespace and project name. It is also possible to access -them via a project alias. This feature is only available on Git over SSH. - -A project alias can be only created via API and only by GitLab administrators. -Follow the [Project Aliases API documentation](../../api/project_aliases.md) for -more details. - -Once an alias has been created for a project (e.g., an alias `gitlab` for the -project `https://gitlab.com/gitlab-org/gitlab`), the repository can be cloned -using the alias (e.g `git clone git@gitlab.com:gitlab.git` instead of -`git clone git@gitlab.com:gitlab-org/gitlab.git`). - -## Project activity analytics overview **(ULTIMATE ONLY)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in GitLab [Ultimate](https://about.gitlab.com/pricing/) 13.7 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). - -Project details include the following analytics: - -- Deployment Frequency - -For more information, see [Project Analytics API](../../api/project_analytics.md). - ## Project APIs There are numerous [APIs](../../api/README.md) to use with your projects: @@ -404,4 +152,14 @@ There are numerous [APIs](../../api/README.md) to use with your projects: - [Traffic](../../api/project_statistics.md) - [Variables](../../api/project_level_variables.md) - [Aliases](../../api/project_aliases.md) -- [Analytics](../../api/project_analytics.md) +- [DORA4 Analytics](../../api/dora4_project_analytics.md) + +## DORA4 analytics overview **(ULTIMATE ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in GitLab [Ultimate](https://about.gitlab.com/pricing/) 13.7 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). + +Project details include the following analytics: + +- Deployment Frequency + +For more information, see [DORA4 Project Analytics API](../../api/dora4_project_analytics.md). diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 30a21dd7f66..fb9314f7504 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -50,7 +50,7 @@ service in GitLab. 1. Enter the build key from your Bamboo build plan. Build keys are typically made up from the Project Key and Plan Key that are set on project/plan creation and separated with a dash (`-`), for example **PROJ-PLAN**. This is a short, all - uppercase identifier that is unique. When viewing a plan within Bamboo, the + uppercase identifier that is unique. When viewing a plan in Bamboo, the build key is also shown in the browser URL, for example `https://bamboo.example.com/browse/PROJ-PLAN`. 1. If necessary, enter username and password for a Bamboo user that has access to trigger the build plan. Leave these fields blank if you do not require @@ -60,8 +60,12 @@ service in GitLab. ## Troubleshooting +### Builds not triggered + If builds are not triggered, ensure you entered the right GitLab IP address in Bamboo under 'Trigger IP addresses'. Also check [service hook logs](overview.md#troubleshooting-integrations) for request failures. -NOTE: -Starting with GitLab 8.14.0, builds are triggered on push events. +### Advanced Atlassian Bamboo features not available in GitLab UI + +Advanced Atlassian Bamboo features are not compatible with GitLab. These features +include, but are not limited to, the ability to watch the build logs from the GitLab UI. diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index 434ae760aff..d63599d02bc 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -4,7 +4,7 @@ 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 --- -# IBM Engineering Workflow Management (EWM) Integration **(CORE)** +# IBM Engineering Workflow Management (EWM) Integration **(FREE)** This service allows you to navigate from GitLab to EWM work items mentioned in merge request descriptions and commit messages. Each work item reference is automatically converted to a link back to the work item. diff --git a/doc/user/project/integrations/generic_alerts.md b/doc/user/project/integrations/generic_alerts.md deleted file mode 100644 index 1fbbee36173..00000000000 --- a/doc/user/project/integrations/generic_alerts.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/incident_management/generic_alerts.md' ---- - -This document was moved to [another location](../../../operations/incident_management/generic_alerts.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index ccf4b6cb303..ef8c9d59132 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -4,7 +4,7 @@ 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 --- -# GitLab Slack application **(FREE ONLY)** +# GitLab Slack application **(FREE SAAS)** > - Introduced in GitLab 9.4. > - Distributed to Slack App Directory in GitLab 10.2. diff --git a/doc/user/project/integrations/img/mattermost_configuration.png b/doc/user/project/integrations/img/mattermost_configuration.png Binary files differdeleted file mode 100644 index 18c0036846d..00000000000 --- a/doc/user/project/integrations/img/mattermost_configuration.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_configuration_v2.png b/doc/user/project/integrations/img/mattermost_configuration_v2.png Binary files differnew file mode 100644 index 00000000000..0470869c4f7 --- /dev/null +++ b/doc/user/project/integrations/img/mattermost_configuration_v2.png diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 8dd7e4309b4..58f7ea3279f 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -10,7 +10,7 @@ GitLab provides a way to push update messages to an Irker server. When configured, pushes to a project trigger the service to send data directly to the Irker server. -See the project homepage for further information: <https://gitlab.com/esr/irker> +See the [project homepage](https://gitlab.com/esr/irker) for further information. ## Needed setup diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 306a16bd873..5857c3da803 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -6,57 +6,83 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Jira integration -If you need to use Jira to track work that's implemented in GitLab, Jira integrations with GitLab make the process of working across systems more efficient. +You can use Jira to track work implemented in GitLab. The Jira integration with GitLab makes the +process of working across these systems more efficient. -This page is about the GitLab Jira integration, which is available in every GitLab project by default, allowing you to connect it to any Jira instance, whether Cloud or self-managed. To compare features with the complementary Jira Development Panel integration, see [Jira integrations](jira_integrations.md). +The GitLab Jira integration, available in every GitLab project by default, allows you to connect +to any Jira instance, whether on Atlassian cloud or self-managed. -After you set up this integration, you can cross-reference activity in the GitLab project with any of your projects in Jira. This includes the ability to close or transition Jira issues when work is completed in GitLab. +You can also install the [Jira Development Panel integration](../../../integration/jira_development_panel.md). +For more information about the differences between the two integrations, see +[Jira integrations](jira_integrations.md). -Features include: +After you set up this integration, you can cross-reference activity in the GitLab project with any +of your projects in Jira. This includes the ability to close or transition Jira issues when work is +completed in GitLab and: -- **Mention a Jira issue ID** in a commit message or MR (merge request) and +- Mention a Jira issue ID in a commit message or MR (merge request) and: - GitLab links to the Jira issue. - The Jira issue adds a comment with details and a link back to the activity in GitLab. -- **Mention that a commit or MR resolves or closes a specific Jira issue** and when it's merged to the default branch: +- Mention that a commit or MR resolves or closes a specific Jira issue and when it's merged to the default branch: - The GitLab MR displays a note that it closed the Jira issue. Prior to the merge, MRs indicate which issue they close. - The Jira issue shows the activity and is closed or otherwise transitioned as specified in your GitLab settings. -- **View a list of Jira issues directly in GitLab** **(PREMIUM)** +- Run a pipeline on an MR linked to a Jira issue: + - The Jira issue shows the current pipeline status (in the sidebar as "builds"). +- Deploy to an environment from an MR linked to a Jira issue: + - The Jira issue shows the status of the deployment (in the sidebar as "deployments"). +- Create or modify a feature flag that mentions a Jira issue in its description: + - The Jira issue shows the details of the feature-flag (in the sidebar as "feature flags"). +- View a list of Jira issues directly in GitLab. **(PREMIUM)** +- Create a Jira issue from a vulnerability. **(ULTIMATE)** -For additional features, you can install the -[Jira Development Panel integration](../../../integration/jira_development_panel.md). -This enables you to: +Additional features provided by the Jira Development Panel integration include: - In a Jira issue, display relevant GitLab information in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/), including related branches, commits, and merge requests. - Use Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) in GitLab to add Jira comments, log time spent on the issue, or apply any issue transition. - -See the [feature comparison](jira_integrations.md#feature-comparison) for more details. +- Showing pipeline, deployment, and feature flags in Jira issues. ## Configuration <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Agile Management - GitLab-Jira Basic Integration](https://www.youtube.com/watch?v=fWvwkx5_00E&feature=youtu.be). -Each GitLab project can be configured to connect to an entire Jira instance. That -means one GitLab project can interact with _all_ Jira projects in that instance, once -configured. Therefore, you do not have to explicitly associate -a GitLab project with any single Jira project. +Each GitLab project can be configured to connect to an entire Jira instance. That means one GitLab +project can interact with _all_ Jira projects in that instance, once configured. For: + +- The [view Jira issues](#view-jira-issues) feature, you must associate a GitLab project with a + specific Jira project. +- Other features, you do not have to explicitly associate a GitLab project with any single Jira + project. + +If you have one Jira instance, you can pre-fill the settings. For more information, see the +documentation for: + +- [Project integration management](../../admin_area/settings/project_integration_management.md). +- [Services Templates](services_templates.md). + +To enable the Jira service in GitLab, you must: -If you have one Jira instance, you can pre-fill the settings page with a default -template. See the [Services Templates](services_templates.md) docs. +1. Configure the project in Jira. +1. Enter the correct values in GitLab. -In order to enable the Jira service in GitLab, you need to first configure the project in Jira and then enter the correct values in GitLab. +### Configure Jira -### Configuring Jira +The process for configuring Jira depends on whether you host Jira on your own server or on +[Atlassian cloud](https://www.atlassian.com/cloud). #### Jira Server -**Jira Server** supports basic authentication. When connecting, a **username and password** are required. Note that connecting to Jira Server via CAS is not possible. [Set up a user in Jira Server](jira_server_configuration.md) first and then proceed to [Configuring GitLab](#configuring-gitlab). +Jira Server supports basic authentication. When connecting, a **username and password** are +required. Connecting to Jira Server via CAS is not possible. For more information, see +[set up a user in Jira Server](jira_server_configuration.md). -#### Jira Cloud +#### Jira on Atlassian cloud -**Jira Cloud** supports authentication through an API token. When connecting to **Jira Cloud**, an **email and API token** are required. [Set up a user in Jira Cloud](jira_cloud_configuration.md) first and then proceed to [Configuring GitLab](#configuring-gitlab). +Jira on Atlassian cloud supports authentication through an API token. When connecting to Jira on +Atlassian cloud, an **email and API token** are required. For more information, see +[set up a user in Jira on Atlassian cloud](jira_cloud_configuration.md). -### Configuring GitLab +### Configure GitLab > **Notes:** > @@ -65,37 +91,52 @@ In order to enable the Jira service in GitLab, you need to first configure the p > to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with > a value of `fromDialog`. -To enable the Jira integration in a project, navigate to the -[Integrations page](overview.md#accessing-integrations) and click -the **Jira** service. +To enable the Jira integration in a project: + +1. Go to the project's [Integrations page](overview.md#accessing-integrations) and select the + **Jira** service. + +1. Select **Enable integration**. + +1. Select **Trigger** actions. + This determines whether a mention of a Jira issue in GitLab commits, merge requests, or both, + should link the Jira issue back to that source commit/MR and transition the Jira issue, if + indicated. + +1. To include a comment on the Jira issue when the above reference is made in GitLab, select + **Enable comments**. + + 1. Select the **Comment detail**: **Standard** or **All details**. -Select **Enable integration**. +1. Enter the further details on the page as described in the following table. -Select a **Trigger** action. This determines whether a mention of a Jira issue in GitLab commits, merge requests, or both, should link the Jira issue back to that source commit/MR and transition the Jira issue, if indicated. + | Field | Description | + | ----- | ----------- | + | `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. For example, `https://jira.example.com`. | + | `Jira API URL` | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira on Atlassian cloud**. | + | `Username or Email` | Created in [configure Jira](#configure-jira) step. Use `username` for **Jira Server** or `email` for **Jira on Atlassian cloud**. | + | `Password/API token` | Created in [configure Jira](#configure-jira) step. Use `password` for **Jira Server** or `API token` for **Jira on Atlassian cloud**. | + | `Jira workflow transition IDs` | Required for closing Jira issues via commits or merge requests. These are the IDs of transitions in Jira that move issues to a particular state. (See [Obtaining a transition ID](#obtaining-a-transition-id).) If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. In GitLab 13.6 and earlier, field was called `Transition ID`. | -To include a comment on the Jira issue when the above reference is made in GitLab, check **Enable comments**. +1. To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and + enter a Jira project key. **(PREMIUM)** -Enter the further details on the page as described in the following table. + You can only display issues from a single Jira project within a given GitLab project. -| Field | Description | -| ----- | ----------- | -| `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. E.g., `https://jira.example.com`. | -| `Jira API URL` | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira Cloud**. | -| `Username or Email` | Created in [configuring Jira](#configuring-jira) step. Use `username` for **Jira Server** or `email` for **Jira Cloud**. | -| `Password/API token` |Created in [configuring Jira](#configuring-jira) step. Use `password` for **Jira Server** or `API token` for **Jira Cloud**. | -| `Jira workflow transition IDs` | Required for closing Jira issues via commits or merge requests. These are the IDs of transitions in Jira that move issues to a particular state. (See [Obtaining a transition ID](#obtaining-a-transition-id).) If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. In GitLab 13.6 and earlier, field was called `Transition ID`. | + WARNING: + If you enable Jira issues with the setting above, all users that have access to this GitLab project + are able to view all issues from the specified Jira project. -To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and enter a Jira project key. **(PREMIUM)** +1. To enable creation of issues for vulnerabilities, select **Enable Jira issues creation from vulnerabilities**. -You can only display issues from a single Jira project within a given GitLab project. + 1. Select the **Jira issue type**. If the dropdown is empty, select refresh (**{retry}**) and try again. -WARNING: -If you enable Jira issues with the setting above, all users that have access to this GitLab project -are able to view all issues from the specified Jira project. +1. To verify the Jira connection is working, select **Test settings**. -When you have configured all settings, click **Test settings and save changes**. +1. Select **Save changes**. -Your GitLab project can now interact with all Jira projects in your instance and the project now displays a Jira link that opens the Jira project. +Your GitLab project can now interact with all Jira projects in your instance and the project now +displays a Jira link that opens the Jira project. #### Obtaining a transition ID @@ -107,19 +148,19 @@ administration UI. You can get the ID you need in either of the following ways: 1. By mousing over the link for the transition you want and looking for the "action" parameter in the URL -Note that the transition ID may vary between workflows (e.g., bug vs. story), +Note that the transition ID may vary between workflows (for example, bug vs. story), even if the status you are changing to is the same. #### Disabling comments on Jira issues You can continue to have GitLab cross-link a source commit/MR with a Jira issue while disabling the comment added to the issue. -See the [Configuring GitLab](#configuring-gitlab) section and uncheck the **Enable comments** setting. +See the [Configure GitLab](#configure-gitlab) section and uncheck the **Enable comments** setting. ## Jira issues -By now you should have [configured Jira](#configuring-jira) and enabled the -[Jira service in GitLab](#configuring-gitlab). If everything is set up correctly +By now you should have [configured Jira](#configure-jira) and enabled the +[Jira service in GitLab](#configure-gitlab). If everything is set up correctly you should be able to reference and close Jira issues by just mentioning their ID in GitLab commits and merge requests. @@ -201,7 +242,7 @@ with a link to the commit that resolved the issue. > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3622) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. -You can browse and search issues from a selected Jira project directly in GitLab. This requires [configuration](#configuring-gitlab) in GitLab by an administrator. +You can browse and search issues from a selected Jira project directly in GitLab. This requires [configuration](#configure-gitlab) in GitLab by an administrator.  diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index b8eebef8e42..e9f30f32308 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -4,10 +4,10 @@ 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 --- -# Creating an API token in Jira Cloud +# Create an API token in Jira on Atlassian cloud -An API token is needed when integrating with Jira Cloud, follow the steps -below to create one: +For [integrations with Jira](jira.md), an API token is needed when integrating with Jira +on Atlassian cloud. To create an API token: 1. Log in to [`id.atlassian.com`](https://id.atlassian.com/manage-profile/security/api-tokens) with your email address. @@ -17,10 +17,11 @@ below to create one: 1. Click **Create API token**. - +  - +1. Click **Copy**, or click **View** and write down the new API token. It is required when [configuring GitLab](jira.md#configure-gitlab). -1. Click **Copy**, or click **View** and write down the new API token. It is required when [configuring GitLab](jira.md#configuring-gitlab). +  -The Jira configuration is complete. You need the newly created token, and the associated email address, when [configuring GitLab](jira.md#configuring-gitlab) in the next section. +The Jira configuration is complete. You need the newly created token, and the associated email +address, when [configuring GitLab](jira.md#configure-gitlab). diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md index 3c91fd3549f..6a1529f001a 100644 --- a/doc/user/project/integrations/jira_integrations.md +++ b/doc/user/project/integrations/jira_integrations.md @@ -6,26 +6,46 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Jira integrations -## Introduction +GitLab can be integrated with [Jira](https://www.atlassian.com/software/jira). -GitLab Issues are a tool for discussing ideas and planning and tracking work. However, your organization may already use Jira for these purposes, with -extensive, established data and business processes they rely on. +[Issues](../issues/index.md) are a tool for discussing ideas, and planning and tracking work. +However, your organization may already use Jira for these purposes, with extensive, established data +and business processes they rely on. -Although you can [migrate](../../../user/project/import/jira.md) your Jira issues and work exclusively in GitLab, you also have the option of continuing to use Jira by using the GitLab Jira integrations. +Although you can [migrate](../../../user/project/import/jira.md) your Jira issues and work +exclusively in GitLab, you can also continue to use Jira by using the GitLab Jira integrations. -## Integrations +## Integration types -The following Jira integrations allow different types of cross-referencing between GitLab activity and Jira issues, with additional features: +There are two different Jira integrations that allow different types of cross-referencing between +GitLab activity and Jira issues, with additional features: -- [**Jira integration**](jira.md) - This is built in to GitLab. In a given GitLab project, it can be configured to connect to any Jira instance, self-managed or Cloud. -- [**Jira development panel integration**](../../../integration/jira_development_panel.md) - This connects all GitLab projects under a specified group or personal namespace. - - If you're using Jira Cloud and GitLab.com, install the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) app in the Atlassian Marketplace and see its [documentation](../../../integration/jira_development_panel.md#gitlab-for-jira-app). - - For all other environments, use the [Jira DVCS Connector configuration instructions](../../../integration/jira_development_panel.md#configuration). +- [Jira integration](jira.md), built in to GitLab. In a given GitLab project, it can be configured + to connect to any Jira instance, either hosted by you or hosted in + [Atlassian cloud](https://www.atlassian.com/cloud). +- [Jira development panel integration](../../../integration/jira_development_panel.md). Connects all + GitLab projects under a specified group or personal namespace. -### Feature comparison +Jira development panel integration configuration depends on whether: + +- You're using GitLab.com or a self-managed GitLab instance. +- You're using Jira on [Atlassian cloud](https://www.atlassian.com/cloud) or on your own server. + +| You use Jira on: | For the Jira development panel integration, GitLab.com customers need: | For the Jira development panel integration, GitLab self-managed customers need: | +|:-------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Atlassian cloud | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) application installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See a [relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/268278) for more information. | +| Your own server | The [Jira DVCS connector](../../../integration/jira_development_panel.md). | The [Jira DVCS connector](../../../integration/jira_development_panel.md). | + +NOTE: +DVCS means distributed version control system. + +## Feature comparison + +The integration to use depends on the capabilities your require. You can install both at the same +time. | Capability | Jira integration | Jira Development Panel integration | -|-----------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| +|:----------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------| | Mention of Jira issue ID in GitLab is automatically linked to that issue | Yes | No | | Mention of Jira issue ID in GitLab issue/MR is reflected in the Jira issue | Yes, as a Jira comment with the GitLab issue/MR title and a link back to it. Its first mention also adds the GitLab page to the Jira issue under “Web links”. | Yes, in the issue’s Development panel | | Mention of Jira issue ID in GitLab commit message is reflected in the issue | Yes. The entire commit message is added to the Jira issue as a comment and under “Web links”, each with a link back to the commit in GitLab. | Yes, in the issue’s Development panel and optionally with a custom comment on the Jira issue using Jira Smart Commits. | @@ -33,3 +53,4 @@ The following Jira integrations allow different types of cross-referencing betwe | Record Jira time tracking information against an issue | No | Yes. Time can be specified via Jira Smart Commits. | | Transition or close a Jira issue with a Git commit or merge request | Yes. Only a single transition type, typically configured to close the issue by setting it to Done. | Yes. Transition to any state using Jira Smart Commits. | | Display a list of Jira issues | Yes **(PREMIUM)** | No | +| Create a Jira issue from a vulnerability or finding **(ULTIMATE)** | Yes | No | diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index d2a42c0535e..5bb17388a1e 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -4,61 +4,65 @@ 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 --- -# Creating a username and password for Jira Server +# Create Jira Server username and password -We need to create a user in Jira to have access to all projects that need to integrate with GitLab. +For [integrations with Jira](jira.md), you must create a user account in Jira to have access to +all projects that need to integrate with GitLab. -As an example, we create a user named `gitlab` and add it to a new group -named `gitlab-developers`. +The Jira user account created for the integration must have write access to +your Jira projects. -NOTE: -It is important that the Jira user created for the integration is given 'write' -access to your Jira projects. This is covered in the process below. +As an example, the following process creates a user named `gitlab` and that's a +member of a new group named `gitlab-developers`: -1. Log in to your Jira instance as an administrator and under **Jira Administration** - go to **User Management** to create a new user. +1. Sign in to your Jira instance as an administrator, and + then go to the gear icon and select **User Management**.  -1. The next step is to create a new user (e.g., `gitlab`) who has write access - to projects in Jira. Enter the user's name and a _valid_ e-mail address - since Jira sends a verification e-mail to set up the password. +1. Create a new user account (for example, `gitlab`) with write access to + projects in Jira. Enter the user account's name and a valid e-mail address, + because Jira sends a verification email to set up the password. - Jira creates the username automatically by using the e-mail - prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You - need to create an HTTP basic authentication password. You can do this by visiting the user - profile, looking up the username, and setting a password. + Jira creates the username by using the email prefix. You can change the + username later, if needed. The GitLab integration doesn't support SSO (such + as SAML). You need to create an HTTP basic authentication password. You can + do this by visiting the user profile, looking up the username, and setting a + password.  -1. Create a `gitlab-developers` group (we give this group write access to Jira - projects in a later step.) Go to the **Groups** tab on the left, and select **Add group**. +1. From the sidebar, select **Groups**.  - Give it a name and click **Add group**. +1. In the **Add group** section, enter a **Name** for the group (for example, + `gitlab-developers`), and then select **Add group**. -1. Add the `gitlab` user to the `gitlab-developers` group by clicking **Edit members**. - The `gitlab-developers` group should be listed in the leftmost box as a selected group. - Under **Add members to selected group(s)**, enter `gitlab`. +1. Add the `gitlab` user to the `gitlab-developers` group by selecting **Edit members**. + The `gitlab-developers` group should be listed in the leftmost box as a + selected group. In the **Add members to selected group(s)** area, enter `gitlab`.  - Click **Add selected users** and `gitlab` should appear in the **Group member(s)** box. - This membership is saved automatically. + Select **Add selected users**, and `gitlab` should appear in the **Group member(s)** + area. This membership is saved automatically.  -1. To give the newly-created group 'write' access, you need to create a **Permission Scheme**. - To do this, click the gear icon and select **Issues**. Then click **Permission Schemes**. - Click **Add Permission Scheme** and enter a **Name** and, optionally, a **Description**. +1. To give the newly-created group 'write' access, you must create a permission + scheme. To do this, in the admin menu, go to the gear icon and select **Issues**. -1. Once your permission scheme is created, you are taken back to the permissions scheme list. - Locate your new permissions scheme and click **Permissions**. Next to **Administer Projects**, - click **Edit**. In the resulting dialog box, select **Group** and select `gitlab-developers` - from the dropdown. +1. From the sidebar, select **Permission Schemes**. + +1. Select **Add Permission Scheme**, enter a **Name** and (optionally) a + **Description**, and then select **Add**. + +1. In the permissions scheme list, locate your new permissions scheme, and + select **Permissions**. Next to **Administer Projects**, select **Edit**. In + the **Group** list, select `gitlab-developers`.  The Jira configuration is complete. Write down the new Jira username and its -password as they are needed when [configuring GitLab in the next section](jira.md#configuring-gitlab). +password, as you need them when [configuring GitLab](jira.md#configure-gitlab). diff --git a/doc/user/project/integrations/kubernetes.md b/doc/user/project/integrations/kubernetes.md deleted file mode 100644 index 646c9ed66d5..00000000000 --- a/doc/user/project/integrations/kubernetes.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../clusters/index.md' ---- - -This document was moved to [another location](../clusters/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index e80f672d05d..db190f47b01 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -58,5 +58,7 @@ At the end, fill in your Mattermost details: | **Webhook** | The incoming webhook URL which you have to set up on Mattermost, similar to: `http://mattermost.example/hooks/5xo…` | | **Username** | Optional username which can be on messages sent to Mattermost. Fill this in if you want to change the username of the bot. | | **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. | +| **Branches to be notified** | Select which types of branches to send notifications for. | +| **Labels to be notified** | Optional labels that the issue or merge request must have in order to trigger a notification. Leave blank to get all notifications. | - + diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index c391877be20..b22a7c0295e 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -13,7 +13,7 @@ functionality to GitLab. ## Accessing integrations You can find the available integrations under your project's -**Settings ➔ Integrations** page. +**Settings > Integrations** page. There are more than 20 integrations to integrate with. Click on the one that you want to configure. @@ -39,7 +39,7 @@ Click on the service links to see further configuration instructions and details | [Emails on push](emails_on_push.md) | Email the commits and diff of each push to a list of recipients | No | | External Wiki | Replaces the link to the internal wiki with a link to an external wiki | No | | Flowdock | Flowdock is a collaboration web app for technical teams | No | -| [Generic alerts](../../../operations/incident_management/alert_integrations.md) **(ULTIMATE)** | Receive alerts on GitLab from any source | No | +| [Generic alerts](../../../operations/incident_management/integrations.md) **(ULTIMATE)** | Receive alerts on GitLab from any source | No | | [GitHub](github.md) **(PREMIUM)** | Sends pipeline notifications to GitHub | No | | [Hangouts Chat](hangouts_chat.md) | Receive events notifications in Google Hangouts Chat | No | | [HipChat](hipchat.md) | Private group chat and IM | No | @@ -53,8 +53,8 @@ Click on the service links to see further configuration instructions and details | Packagist | Update your projects on Packagist, the main Composer repository | Yes | | Pipelines emails | Email the pipeline status to a list of recipients | No | | [Slack Notifications](slack.md) | Send GitLab events (for example, an issue was created) to Slack as notifications | No | -| [Slack slash commands](slack_slash_commands.md) **(CORE ONLY)** | Use slash commands in Slack to control GitLab | No | -| [GitLab Slack application](gitlab_slack_application.md) **(FREE ONLY)** | Use Slack's official application | No | +| [Slack slash commands](slack_slash_commands.md) **(FREE SELF)** | Use slash commands in Slack to control GitLab | No | +| [GitLab Slack application](gitlab_slack_application.md) **(FREE SAAS)** | Use Slack's official application | No | | PivotalTracker | Project Management Software (Source Commits Endpoint) | No | | [Prometheus](prometheus.md) | Monitor the performance of your deployed apps | No | | Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop | No | diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md deleted file mode 100644 index 69e2ea2856c..00000000000 --- a/doc/user/project/integrations/project_services.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'overview.md' ---- - -This document was moved to [Integrations](overview.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 1507cea348a..c307fd8d628 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -4,22 +4,25 @@ group: Health 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 --- -# Prometheus integration +# Prometheus integration **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8935) in GitLab 9.0. -GitLab offers powerful integration with [Prometheus](https://prometheus.io) for monitoring key metrics of your apps, directly within GitLab. +GitLab offers powerful integration with [Prometheus](https://prometheus.io) for +monitoring key metrics of your apps, directly in GitLab. Metrics for each environment are retrieved from Prometheus, and then displayed -within the GitLab interface. +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 other deployment targets, simply [specify the Prometheus server](#manual-configuration-of-prometheus). +- For other deployment targets, [specify the Prometheus server](#manual-configuration-of-prometheus). -Once enabled, GitLab detects metrics from known services in the [metric library](prometheus_library/index.md). You can also [add your own metrics](../../../operations/metrics/index.md#adding-custom-metrics) and create +Once enabled, GitLab detects metrics from known services in the +[metric library](prometheus_library/index.md). You can also +[add your own metrics](../../../operations/metrics/index.md#adding-custom-metrics) and create [custom dashboards](../../../operations/metrics/dashboards/index.md). ## Enabling Prometheus Integration @@ -28,7 +31,8 @@ Once enabled, GitLab detects metrics from known services in the [metric library] > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28916) in GitLab 10.5. -GitLab can seamlessly deploy and manage Prometheus on a [connected Kubernetes cluster](../clusters/index.md), making monitoring of your apps easy. +GitLab can seamlessly deploy and manage Prometheus on a +[connected Kubernetes cluster](../clusters/index.md), to help you monitor your apps. #### Requirements @@ -36,7 +40,7 @@ GitLab can seamlessly deploy and manage Prometheus on a [connected Kubernetes cl #### Getting started -Once you have a connected Kubernetes cluster, deploying a managed Prometheus is as easy as a single click. +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 @@ -46,17 +50,28 @@ Once you have a connected Kubernetes cluster, deploying a managed Prometheus is #### 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 within the cluster, with GitLab communicating through the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/). +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, simply set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): +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) in order to determine the environment. If you are using [Auto DevOps](../../../topics/autodevops/index.md), this is handled automatically. +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. +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 @@ -161,15 +176,16 @@ Installing and configuring Prometheus to monitor applications is fairly straight 1. [Install Prometheus](https://prometheus.io/docs/prometheus/latest/installation/) 1. Set up one of the [supported monitoring targets](prometheus_library/index.md) -1. Configure the Prometheus server to [collect their metrics](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) +1. Configure the Prometheus server to + [collect their metrics](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) #### Configuration in GitLab -The actual configuration of Prometheus integration within GitLab +The actual configuration of Prometheus integration in GitLab requires the domain name or IP address of the Prometheus server you'd like to integrate with. If the Prometheus resource is secured with Google's Identity-Aware Proxy (IAP), -additional information like Client ID and Service Account credentials can be passed which -GitLab can use to access the resource. More information about authentication from a +you can pass information like Client ID and Service Account credentials. +GitLab can use these to access the resource. More information about authentication from a service account can be found at Google's documentation for [Authenticating from a service account](https://cloud.google.com/iap/docs/authentication-howto#authenticating_from_a_service_account). @@ -191,12 +207,13 @@ service account can be found at Google's documentation for #### Thanos configuration in GitLab You can configure [Thanos](https://thanos.io/) as a drop-in replacement for Prometheus -with GitLab, using the domain name or IP address of the Thanos server you'd like +with GitLab. Use the domain name or IP address of the Thanos server you'd like to integrate with. 1. Navigate to the [Integrations page](overview.md#accessing-integrations). 1. Click the **Prometheus** service. -1. Provide the domain name or IP address of your server, for example `http://thanos.example.com/` or `http://192.0.2.1/`. +1. Provide the domain name or IP address of your server, for example + `http://thanos.example.com/` or `http://192.0.2.1/`. 1. Click **Save changes**. ### Precedence with multiple Prometheus configurations @@ -223,7 +240,7 @@ can use only one: > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10408) in GitLab 9.2. > - GitLab 9.3 added the [numeric comparison](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/27439) of the 30 minute averages. -Developers can view the performance impact of their changes within the merge +Developers can view the performance impact of their changes in the merge request workflow. This feature requires [Kubernetes](prometheus_library/kubernetes.md) metrics. When a source branch has been deployed to an environment, a sparkline and diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index b563dd34896..4a88010a343 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -4,7 +4,7 @@ group: Health 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 --- -# Monitoring AWS resources +# Monitoring AWS resources **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12621) in GitLab 9.4 diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index c14c14658b7..290313ac1af 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -4,7 +4,7 @@ group: Health 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 --- -# Monitoring HAProxy +# Monitoring HAProxy **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12621) in GitLab 9.4 diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index 501e8ba7c1d..998300e255f 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -4,7 +4,7 @@ group: Health 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 --- -# Prometheus Metrics library +# Prometheus Metrics library **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8935) in GitLab 9.0. @@ -35,6 +35,6 @@ In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do that, GitLab uses the defined queries and fills in the environment specific variables. Typically this involves looking for the -[`$CI_ENVIRONMENT_SLUG`](../../../../ci/variables/README.md#predefined-environment-variables), +[`$CI_ENVIRONMENT_SLUG`](../../../../ci/variables/README.md#predefined-cicd-variables), but may also include other information such as the project's Kubernetes namespace. Each search query is defined in the [exporter specific documentation](#exporters). diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index ae330158a58..2a6bc810f71 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -4,7 +4,7 @@ group: Health 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 --- -# Monitoring Kubernetes +# Monitoring Kubernetes **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8935) in GitLab 9.0. @@ -40,7 +40,7 @@ Prometheus needs to be deployed into the cluster and configured properly in orde In order to isolate and only display relevant CPU and Memory metrics for a given environment, GitLab needs a method to detect which containers it is running. Because these metrics are tracked at the container level, traditional Kubernetes labels are not available. -Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/README.md#predefined-environment-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment. +Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/README.md#predefined-cicd-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment. ## Displaying Canary metrics **(PREMIUM)** diff --git a/doc/user/project/integrations/prometheus_library/metrics.md b/doc/user/project/integrations/prometheus_library/metrics.md deleted file mode 100644 index a275efce5bb..00000000000 --- a/doc/user/project/integrations/prometheus_library/metrics.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'index.md' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index 4cb827b3b4a..dcaef1e2ae6 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -4,7 +4,7 @@ group: Health 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 --- -# Monitoring NGINX +# Monitoring NGINX **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12621) in GitLab 9.4 diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index f7542ec78f7..f7e6b6e76d6 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -4,7 +4,7 @@ group: Health 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 --- -# Monitoring NGINX Ingress Controller +# Monitoring NGINX Ingress Controller **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22133) in GitLab 11.7. 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 c855e564753..0c86c4921b3 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -4,7 +4,7 @@ group: Health 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 --- -# Monitoring NGINX Ingress Controller with VTS metrics +# Monitoring NGINX Ingress Controller with VTS metrics **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13438) in GitLab 9.5. diff --git a/doc/user/project/integrations/prometheus_units.md b/doc/user/project/integrations/prometheus_units.md deleted file mode 100644 index 0c2ce3002ee..00000000000 --- a/doc/user/project/integrations/prometheus_units.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/metrics/dashboards/yaml_number_format.md' ---- - -This document was moved to [another location](../../../operations/metrics/dashboards/yaml_number_format.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md index a60af93a899..7507792bb02 100644 --- a/doc/user/project/integrations/services_templates.md +++ b/doc/user/project/integrations/services_templates.md @@ -6,6 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Service templates +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. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 9e9f5b8297f..ab798675278 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -45,6 +45,7 @@ separately configured [Slack slash commands](slack_slash_commands.md). 1. Select the **Notify only broken pipelines** check box to only notify on failures. 1. In the **Branches to be notified** select box, choose which types of branches to send notifications for. +1. Leave the **Labels to be notified** field blank to get all notifications or add labels that the issue or merge request must have in order to trigger a notification. 1. Click **Test settings and save changes**. Your Slack team now starts receiving GitLab event notifications as configured. diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 1e4577fb88e..4f206cd3e45 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -4,7 +4,7 @@ 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 --- -# Slack slash commands **(CORE ONLY)** +# Slack slash commands **(FREE SELF)** > Introduced in GitLab 8.15. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 47a44e53b47..0cf01adef13 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -31,7 +31,7 @@ update a backup mirror, or even deploy to your production server. Webhooks are available: -- Per project, at a project's **Settings > Webhooks** menu. **(CORE)** +- Per project, at a project's **Settings > Webhooks** menu. **(FREE)** - Additionally per group, at a group's **Settings > Webhooks** menu. **(PREMIUM)** NOTE: @@ -1029,6 +1029,9 @@ X-Gitlab-Event: Wiki Page Hook ### Pipeline events +In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53159) +and later, the pipeline webhook returns only the latest jobs. + Triggered on status change of Pipeline. **Request Header**: @@ -1151,10 +1154,15 @@ X-Gitlab-Event: Pipeline Hook "email": "admin@example.com" }, "runner": { - "id":380987, - "description":"shared-runners-manager-6.gitlab.com", - "active":true, - "is_shared":true + "id": 380987, + "description": "shared-runners-manager-6.gitlab.com", + "active": true, + "is_shared": true, + "tags": [ + "linux", + "docker", + "shared-runner" + ] }, "artifacts_file":{ "filename": null, @@ -1183,7 +1191,11 @@ X-Gitlab-Event: Pipeline Hook "id":380987, "description":"shared-runners-manager-6.gitlab.com", "active":true, - "is_shared":true + "is_shared":true, + "tags": [ + "linux", + "docker" + ] }, "artifacts_file":{ "filename": null, @@ -1209,10 +1221,14 @@ X-Gitlab-Event: Pipeline Hook "email": "admin@example.com" }, "runner": { - "id":380987, - "description":"shared-runners-manager-6.gitlab.com", - "active":true, - "is_shared":true + "id": 380987, + "description": "shared-runners-manager-6.gitlab.com", + "active": true, + "is_shared": true, + "tags": [ + "linux", + "docker" + ] }, "artifacts_file":{ "filename": null, @@ -1308,7 +1324,11 @@ X-Gitlab-Event: Job Hook "active": true, "is_shared": false, "id": 380987, - "description": "shared-runners-manager-6.gitlab.com" + "description": "shared-runners-manager-6.gitlab.com", + "tags": [ + "linux", + "docker" + ] } } ``` @@ -1468,6 +1488,74 @@ X-Gitlab-Event: Member Hook } ``` +### Subgroup events **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260419) in GitLab 13.9. + +Subgroup events are triggered when: + +- A [subgroup is created in a group](#subgroup-created-in-a-group) +- A [subgroup is removed from a group](#subgroup-removed-from-a-group) + +#### Subgroup created in a group + +**Request Header**: + +```plaintext +X-Gitlab-Event: Subgroup Hook +``` + +**Request Body**: + +```json +{ + + "created_at": "2021-01-20T09:40:12Z", + "updated_at": "2021-01-20T09:40:12Z", + "event_name": "subgroup_create", + "name": "subgroup1", + "path": "subgroup1", + "full_path": "group1/subgroup1", + "group_id": 10, + "parent_group_id": 7, + "parent_name": "group1", + "parent_path": "group1", + "parent_full_path": "group1" + +} +``` + +#### Subgroup removed from a group + +**Request Header**: + +```plaintext +X-Gitlab-Event: Subgroup Hook +``` + +**Request Body**: + +```json +{ + + "created_at": "2021-01-20T09:40:12Z", + "updated_at": "2021-01-20T09:40:12Z", + "event_name": "subgroup_destroy", + "name": "subgroup1", + "path": "subgroup1", + "full_path": "group1/subgroup1", + "group_id": 10, + "parent_group_id": 7, + "parent_name": "group1", + "parent_path": "group1", + "parent_full_path": "group1" + +} +``` + +NOTE: +Webhooks for when a [subgroup is removed from a group](#subgroup-removed-from-a-group) are not triggered when a [subgroup is transferred to a new parent group](../../group/index.md#transferring-groups) + ### Feature Flag events Triggered when a feature flag is turned on or off. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 7119970fca0..e4f42b97b84 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -4,9 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Issue Boards **(CORE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5554) in [GitLab 8.11](https://about.gitlab.com/releases/2016/08/22/gitlab-8-11-released/#issue-board). +# Issue Boards **(FREE)** The GitLab Issue Board is a software project management tool used to plan, organize, and visualize a workflow for a feature or product release. @@ -38,10 +36,9 @@ 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) | |------------------|--------------------------------|------------------------------|---------------------------|----------------| -| Core / Free | Multiple | 1 | No | No | -| Starter / Bronze | Multiple | 1 | Yes | No | -| Premium / Silver | Multiple | Multiple | Yes | Yes | -| Ultimate / Gold | Multiple | Multiple | Yes | Yes | +| 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. @@ -53,11 +50,10 @@ the Issue Board feature. ## Multiple issue boards -> - [Introduced](https://about.gitlab.com/releases/2016/10/22/gitlab-8-13-released/) in GitLab 8.13. -> - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 12.1. -> - Multiple issue boards per group are available in [GitLab Premium](https://about.gitlab.com/pricing/). +> - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to GitLab Free in 12.1. +> - Multiple issue boards per group are available in GitLab Premium. -Multiple issue boards allow for more than one issue board for a given project **(CORE)** or group **(PREMIUM)**. +Multiple issue boards allow for more than one issue board for a given project **(FREE)** or group **(PREMIUM)**. This is great for large projects with more than one team or when a repository hosts the code of multiple products. Using the search box at the top of the menu, you can filter the listed boards. @@ -228,13 +224,13 @@ and vice versa. ## GitLab Enterprise features for issue boards -GitLab issue boards are available on GitLab Core and GitLab.com Free tiers, but some +GitLab issue boards are available on the GitLab Free tier, but some advanced functionality is present in [higher tiers only](https://about.gitlab.com/pricing/). -### Configurable issue boards **(STARTER)** +### Configurable issue boards **(PREMIUM)** -> - [Introduced](https://about.gitlab.com/releases/2017/11/22/gitlab-10-2-released/#issue-boards-configuration) in GitLab 10.2. > - Setting current iteration as scope [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196804) in GitLab 13.8. +> - Moved to GitLab Premium in 13.9. An issue board can be associated with a [milestone](milestones/index.md#milestones), [labels](labels.md), assignee, weight, and current [iteration](../group/iterations/index.md), @@ -257,14 +253,15 @@ the Configurable Issue Board feature. ### Focus mode -> - [Introduced]((https://about.gitlab.com/releases/2017/04/22/gitlab-9-1-released/#issue-boards-focus-mode-ees-eep)) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.1. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28597) to the Free tier of GitLab.com in 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212331) to GitLab Core in 13.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28597) to GitLab Free SaaS in 12.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212331) to GitLab Free self-managed in 13.0. To enable or disable focus mode, select the **Toggle focus mode** button (**{maximize}**) at the top right. In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board. -### Sum of issue weights **(STARTER)** +### Sum of issue weights **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. The top of each list indicates the sum of issue weights for the issues that belong to that list. This is useful when using boards for capacity allocation, @@ -274,9 +271,6 @@ especially in combination with [assignee lists](#assignee-lists). ### Group issue boards **(PREMIUM)** -> - One group issue board per group introduced in GitLab 10.6. -> - Multiple group issue boards [introduced](https://about.gitlab.com/releases/2017/09/22/gitlab-10-0-released/#group-issue-boards) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0. - 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 @@ -360,9 +354,10 @@ You can also [drag issues](#drag-issues-between-lists) to change their position  -## Work In Progress limits **(STARTER)** +## Work In Progress limits **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11403) in GitLab 12.7 +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11403) in GitLab 12.7 +> - Moved to GitLab Premium in 13.9. You can set a Work In Progress (WIP) limit for each issue list on an issue board. When a limit is set, the list's header shows the number of issues in the list and the soft limit of issues. @@ -435,13 +430,13 @@ To remove a list from an issue board: 1. Select **Remove list**. A confirmation dialog appears. 1. Select **OK**. -### Add issues to a list **(CORE ONLY)** +### Add issues to a list **(FREE SELF)** > - Feature flag [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47898) in GitLab 13.7. > - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. > - It's disabled on GitLab.com. > - It's recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-adding-issues-to-the-list). **(CORE ONLY)** +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-adding-issues-to-the-list). **(FREE SELF)** You can add issues to a list in a project issue board by clicking the **Add issues** button in the top right corner of the issue board. This opens up a modal @@ -461,7 +456,7 @@ the list by filtering by the following: - Release - Weight -#### Enable or disable adding issues to the list **(CORE ONLY)** +#### Enable or disable adding issues to the list **(FREE SELF)** Adding issues to the list is deployed behind a feature flag that is **disabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) @@ -547,8 +542,8 @@ to another list, the label changes and a system note is recorded. When dragging issues between lists, different behavior occurs depending on the source list and the target list. -| | To Open | To Closed | To label `B` list | To assignee `Bob` list | -|----------------------------|--------------------|--------------|------------------------------|---------------------------------------| +| | 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 | @@ -563,7 +558,7 @@ another list. This makes it faster to reorder many issues at once. To select and move multiple cards: -1. Select each card with <kbd>Ctrl</kbd>+`Click` on Windows or Linux, or <kbd>Cmd</kbd>+`Click` on MacOS. +1. Select each card with <kbd>Control</kbd>+`Click` on Windows or Linux, or <kbd>Command</kbd>+`Click` on MacOS. 1. Drag one of the selected cards to another position or list and all selected cards are moved.  diff --git a/doc/user/project/issues/automatic_issue_closing.md b/doc/user/project/issues/automatic_issue_closing.md deleted file mode 100644 index 6fa2822aa9a..00000000000 --- a/doc/user/project/issues/automatic_issue_closing.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'managing_issues.md#closing-issues-automatically' ---- - -This document was moved to [another location](managing_issues.md#closing-issues-automatically). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/closing_issues.md b/doc/user/project/issues/closing_issues.md deleted file mode 100644 index 45b905f2fb5..00000000000 --- a/doc/user/project/issues/closing_issues.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'managing_issues.md#closing-issues' ---- - -This document was moved to [another location](managing_issues.md#closing-issues). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index d4fbc4fb10b..e1918b68ddc 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -99,9 +99,9 @@ confidential information prematurely. To make a confidential commit public, open a merge request from the private fork to the public upstream project. Permissions are inherited from parent groups. Developers have the same permissions -for private forks created in the same group or in a sub-group of the original +for private forks created in the same group or in a subgroup of the original Permissions are inherited from parent groups. When private forks are created -in the same group or sub-group as the original upstream repository, users +in the same group or subgroup as the original upstream repository, users receive the same permissions in both projects. This inheritance ensures Developer users have the needed permissions to both view confidential issues and resolve them. diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md deleted file mode 100644 index 53648b53ea3..00000000000 --- a/doc/user/project/issues/create_new_issue.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'managing_issues.md#create-a-new-issue' ---- - -This document was moved to [another location](managing_issues.md#create-a-new-issue). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index e7cd1377603..5c95665230a 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -6,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Export Issues to CSV -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1126) in [GitLab Starter 9.0](https://about.gitlab.com/releases/2017/03/22/gitlab-9-0-released/#export-issues-ees-eep). -> - Moved to GitLab Core in GitLab 12.10. +> 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. @@ -20,7 +19,7 @@ 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) CSV files can be used with any plotter or spreadsheet-based program, such as Microsoft Excel, -Open Office Calc, or Google Spreadsheets. +Open Office <!-- vale gitlab.Spelling = NO --> Calc, <!-- vale gitlab.Spelling = NO --> or Google Spreadsheets. ## Use cases @@ -49,10 +48,6 @@ Exported issues are always sorted by `Issue ID`. ## Format -> **Time Estimate** and **Time Spent** columns were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2627) in GitLab Starter 10.0. -> -> **Weight** and **Locked** columns were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5300) in GitLab Starter 10.8. - 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 | diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index 0d10f028cbf..2757642e458 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -1,6 +1,6 @@ --- -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 --- @@ -9,7 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23532) in GitLab 11.7. Issues can be imported to a project by uploading a CSV file with the columns -`title` and `description`. +`title` and `description`. Other columns are **not** imported. If you want to +retain columns such as labels and milestones, consider the [Move Issue feature](managing_issues.md#moving-issues). The user uploading the CSV file is set as the author of the imported issues. diff --git a/doc/user/project/issues/deleting_issues.md b/doc/user/project/issues/deleting_issues.md deleted file mode 100644 index d8e1485a2dc..00000000000 --- a/doc/user/project/issues/deleting_issues.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'managing_issues.md#deleting-issues' ---- - -This document was moved to [another location](managing_issues.md#deleting-issues). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 3739070be01..b6dff0842d8 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -1,14 +1,14 @@ --- -stage: Create -group: Knowledge +stage: Plan +group: Product Planning 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" --- -# Design Management **(CORE)** +# Design Management **(FREE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. > - Support for SVGs was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12771) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. -> - Design Management was [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Core in 13.0. +> - Design Management was [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Free in 13.0. Design Management allows you to upload design assets (wireframes, mockups, etc.) to GitLab issues and keep them stored in one single place, accessed by the Design @@ -46,7 +46,7 @@ If the requirements are not met, the **Designs** tab displays a message to the u ## Supported files Files uploaded must have a file extension of either `png`, `jpg`, `jpeg`, -`gif`, `bmp`, `tiff`, `ico`, or `svg`. +`gif`, `bmp`, `tiff`, `ico`, `webp`, or `svg`. Support for [PDF](https://gitlab.com/gitlab-org/gitlab/issues/32811) is planned for a future release. @@ -259,4 +259,4 @@ This will be rendered as: User activity events on designs (creation, deletion, and updates) are tracked by GitLab and displayed on the [user profile](../../profile/index.md#user-profile), [group](../../group/index.md#view-group-activity), -and [project](../index.md#project-activity) activity pages. +and [project](../working_with_projects.md#project-activity) activity pages. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 34e9340067c..909a20f0e2f 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -41,7 +41,7 @@ You can see issues with their due dates in the [issues list](index.md#issues-lis Overdue issues have their icon and date colored red. To sort issues by their due dates, select **Due date** from the dropdown menu on the right. Issues are then sorted from the earliest due date to the latest. -To display isses with the latest due dates at the top, select **Sort direction** (**{sort-lowest}**). +To display issues with the latest due dates at the top, select **Sort direction** (**{sort-lowest}**). Due dates also appear in your [to-do list](../../todos.md). diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 74311eefd83..e398c6f86d0 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -4,35 +4,29 @@ 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 --- -# Issues **(CORE)** +# Issues **(FREE)** -Issues are the fundamental medium for collaborating on ideas and planning work in GitLab. +Issues are the fundamental mechanism in GitLab to collaborate on ideas, solve +problems, and plan work. -## Overview +Using issues, you can share and discuss proposals (both before and during their +implementation) between you and your team, and outside collaborators. -The GitLab issue tracker is an advanced tool for collaboratively developing ideas, solving problems, -and planning work. +You can use issues for many purposes, customized to your needs and workflow. +Common use cases include: -Issues can allow sharing and discussion of proposals before, and during, -their implementation between: +- Discussing the implementation of a new idea. +- Tracking tasks and work status. +- Accepting feature proposals, questions, support requests, or bug reports. +- Elaborating on new code implementations. -- You and your team. -- Outside collaborators. +For more information about using issues, see the +[Always start a discussion with an issue](https://about.gitlab.com/blog/2016/03/03/start-with-an-issue/) +GitLab blog post. -They can also be used for a variety of other purposes, customized to your -needs and workflow. - -Issues are always associated with a specific project. If you have multiple projects in a group, -you can view all of the issues collectively at the group level. - -**Common use cases include:** - -- Discussing the implementation of a new idea -- Tracking tasks and work status -- Accepting feature proposals, questions, support requests, or bug reports -- Elaborating on new code implementations - -See also [Always start a discussion with an issue](https://about.gitlab.com/blog/2016/03/03/start-with-an-issue/). +Issues are always associated with a specific project. If you have multiple +projects in a group, you can view all of the issues collectively at the group +level. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> To learn how our Strategic Marketing department uses GitLab issues with [labels](../labels.md) and @@ -41,63 +35,30 @@ To learn how our Strategic Marketing department uses GitLab issues with [labels] ## Parts of an issue -Issues contain a variety of content and metadata, enabling a large range of flexibility -in how they are used. Each issue can contain the following attributes, though not all items -must be set. - -<table class="borderless-table fixed-table"> -<tr> - <td> - <ul> - <li>Content</li> - <ul> - <li>Title</li> - <li>Description and tasks</li> - <li>Comments and other activity</li> - </ul> - <li>People</li> - <ul> - <li>Author</li> - <li>Assignee(s)</li> - </ul> - <li>State</li> - <ul> - <li>State (open or closed)</li> - <li>Health status (on track, needs attention, or at risk)</li> - <li>Confidentiality</li> - <li>Tasks (completed vs. outstanding)</li> - </ul> - </ul> - </td> - <td> - <ul> - <li>Planning and tracking</li> - <ul> - <li>Milestone</li> - <li>Due date</li> - <li>Weight</li> - <li>Time tracking</li> - <li>Labels</li> - <li>Votes</li> - <li>Reaction emoji</li> - <li>Linked issues</li> - <li>Assigned epic</li> - <li>Unique issue number and URL</li> - </ul> - </ul> - </td> -</tr> -</table> - -## Viewing and managing issues - -While you can view and manage details of an issue on the [issue page](#issue-page), -you can also work with multiple issues at a time using: - -- [Issues List](#issues-list). -- [Issue Boards](#issue-boards). -- Issue references. -- [Epics](#epics) **(PREMIUM)**. +Issues have a flexible content and metadata structure. Here are some of the +elements you can provide in an issue: + +- Title +- Description and tasks +- Comments and other activity +- Author +- Assignees +- State (open or closed) +- Health status (on track, needs attention, or at risk) +- Confidentiality +- Tasks (completed vs. outstanding) +- Milestone +- Due date +- Weight +- Time tracking +- Labels +- Votes +- Reaction emoji +- Linked issues +- Assigned epic +- Unique issue number and URL + +## View and manage issues Key actions for issues include: @@ -105,7 +66,17 @@ Key actions for issues include: - [Moving issues](managing_issues.md#moving-issues) - [Closing issues](managing_issues.md#closing-issues) - [Deleting issues](managing_issues.md#deleting-issues) -- [Promoting issues](managing_issues.md#promote-an-issue-to-an-epic) **(PREMIUM)** +- [Promoting issues](managing_issues.md#promote-an-issue-to-an-epic) + +Although you can view and manage details of an issue on the [issue page](#issue-page), +you can also work with several issues at a time by using these features: + +- [Issues List](#issues-list): View a list of issues in a project or group. +- [Issue Boards](../issue_board.md): Organize issues with a project management + workflow for a feature or product release. +- Issue references +- [Epics](../../group/epics/index.md): Manage your portfolio of projects by + tracking groups of issues with a shared theme. ### Issue page @@ -114,18 +85,18 @@ Key actions for issues include: On an issue's page, you can view [all aspects of the issue](issue_data_and_actions.md), and modify them if you have the necessary [permissions](../../permissions.md). -#### Real-time sidebar **(CORE ONLY)** +#### Real-time sidebar **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 13.3. Assignees in the sidebar are updated in real time. This feature is **disabled by default**. -To enable, you need to enable [ActionCable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html). +To enable it, you need to enable [ActionCable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html). ### Issues List  -On the Issues List, you can: +In the Issues List, you can: - View all issues in a project when opening the Issues List from a project context. - View all issues in a groups's projects when opening the Issues List from a group context. @@ -137,20 +108,22 @@ view, you can also make certain changes [in bulk](../bulk_editing.md) to the dis For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page for a rundown of all the fields and information in an issue. -You can sort a list of issues in several ways, for example by issue creation date, milestone due date. For more information, see the [Sorting and Ordering Issue Lists](sorting_issue_lists.md) page. +You can sort a list of issues in several ways, for example by issue creation date, milestone due date. +For more information, see the [Sorting and ordering issue lists](sorting_issue_lists.md) page. -### Issue boards +#### Cached issue count - +> - [Introduced]([link-to-issue](https://gitlab.com/gitlab-org/gitlab/-/issues/243753)) 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 this feature in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-cached-issue-count) **(FREE SELF)** -[Issue boards](../issue_board.md) are Kanban boards with columns that display issues based on their -labels or their assignees**(PREMIUM)**. They offer the flexibility to manage issues using -highly customizable workflows. +WARNING: +This feature might not be available to you. Check the **version history** note above for details. -You can reorder issues in the column. If you drag an issue card to another column, its -associated label or assignee is changed to match that of the new column. The entire -board can also be filtered to only include issues from a certain milestone or an overarching -label. +In a group, the sidebar displays the total count of open issues and this value is cached if higher +than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. ### Design Management @@ -158,12 +131,6 @@ With [Design Management](design_management.md), you can upload design assets to issues and view them all together for sharing and collaboration with your team. -### Epics **(PREMIUM)** - -[Epics](../../group/epics/index.md) let you manage your portfolio of projects more -efficiently and with less effort. Epics track groups of issues that share a theme, across -projects and milestones. - ### Related issues You can mark two issues as related, so that when viewing one, the other is always @@ -226,3 +193,22 @@ You can then see issue statuses in the [issue list](#issues-list) and the - [Issues API](../../../api/issues.md) - Configure an [external issue tracker](../../../integration/external-issue-tracker.md) such as Jira, Redmine, Bugzilla, or EWM. + +## Enable or disable cached issue count **(FREE SELF)** + +Cached issue count in the left sidebar 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(:cached_sidebar_open_issues_count) +``` + +To disable it: + +```ruby +Feature.disable(:cached_sidebar_open_issues_count) +``` diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 4c8630581f5..c3adce33826 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -23,13 +23,13 @@ The numbers in the image correspond to the following features: - **1.** [Issue actions](#issue-actions) - **2.** [To Do](#to-do) - **3.** [Assignee](#assignee) - - **3.1.** [Multiple Assignees **(STARTER)**](#multiple-assignees) -- **4.** [Epic **(PREMIUM)**](#epic) + - **3.1.** [Multiple Assignees](#multiple-assignees) +- **4.** [Epic](#epic) - **5.** [Milestone](#milestone) - **6.** [Time tracking](#time-tracking) - **7.** [Due date](#due-date) - **8.** [Labels](#labels) -- **9.** [Weight **(STARTER)**](#weight) +- **9.** [Weight](#weight) - **10.** [Confidentiality](#confidentiality) - **11.** [Lock issue](#lock-issue) - **12.** [Participants](#participants) @@ -86,7 +86,7 @@ An issue can be assigned to: - Yourself. - Another person. -- [Many people](#multiple-assignees). **(STARTER)** +- [Many people](#multiple-assignees). **(PREMIUM)** The assignees can be changed as often as needed. The idea is that the assignees are responsible for that issue until it's reassigned to someone else to take it from there. @@ -96,7 +96,7 @@ NOTE: If a user is not member of that project, it can only be assigned to them if they created the issue themselves. -#### Multiple Assignees **(STARTER)** +#### Multiple Assignees **(PREMIUM)** Often, multiple people work on the same issue together. This can be difficult to track in large teams where there is shared ownership of an issue. @@ -129,7 +129,7 @@ element. Due dates can be changed as many times as needed. ### Labels Categorize issues by giving them [labels](../labels.md). They help to organize workflows, -and they enable you to work with the [GitLab Issue Board](index.md#issue-boards). +and they enable you to work with the [GitLab Issue Board](../issue_board.md). Group Labels, which allow you to use the same labels for all projects in the same group, can also be given to issues. They work exactly the same, but are immediately @@ -138,7 +138,7 @@ available to all projects in the group. If a label doesn't exist yet, you can create one by clicking **Edit** followed by **Create new label** in the dropdown menu. -### Weight **(STARTER)** +### Weight **(PREMIUM)** [Assign a weight](issue_weight.md) to an issue. Larger values are used to indicate more effort is required to complete the issue. Only @@ -161,14 +161,9 @@ or were mentioned in the description or threads. ### Notifications -Click on the icon to enable/disable [notifications](../../profile/notifications.md#issue--epics--merge-request-events) +Select the toggle to enable or disable [notifications](../../profile/notifications.md#notifications-on-issues-merge-requests-and-epics) for the issue. Notifications are automatically enabled after you participate in the issue in any way. -- **Enable**: If you are not a participant in the discussion on that issue, but - want to receive notifications on each update, subscribe to it. -- **Disable**: If you are receiving notifications for updates to that issue but no - longer want to receive them, unsubscribe from it. - ### Reference - A quick "copy" button for that issue's reference, which looks like @@ -194,13 +189,14 @@ The plain text title and description of the issue fill the top center of the iss The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm), allowing many formatting options. -> [In GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/10103) and later, changes to an issue's description are listed in the [issue history](#issue-history). **(STARTER)** +[In GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/10103) and later, changes to an +issue's description are listed in the [issue history](#issue-history). **(PREMIUM)** ### Mentions You can mention a user or a group present in your GitLab instance with `@username` or `@groupname`. All mentioned users are notified via to-do items and emails, -unless they have disabled all notifications in their profile settings. +unless they have disabled all [notifications](#notifications) in their user settings. This is controlled in the [notification settings](../../profile/notifications.md). Mentions for yourself (the current logged in user) are highlighted @@ -244,8 +240,8 @@ Also: - You can mention a user or a group present in your GitLab instance with `@username` or `@groupname` and they are notified via to-do items - and emails, unless they have [disabled all notifications](#notifications) - in their profile settings. + and emails, unless they have disabled all [notifications](#notifications) + in their user settings. - Mentions for yourself (the current logged-in user) are highlighted in a different color, which allows you to quickly see which comments involve you. @@ -291,7 +287,7 @@ supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-g After you write a comment, you can: -- Click **Comment** and to publish your comment. +- Click **Comment** to publish your comment. - Choose **Start thread** from the dropdown list and start a new [thread](../../discussions/index.md#threaded-discussions) in that issue's main thread to discuss specific points. This invites other participants to reply directly to your thread, keeping related comments grouped together. diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index 4e2c8bfd7f1..b10debf9888 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -5,15 +5,15 @@ 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 --- -# Issue weight **(STARTER)** +# Issue weight **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/76) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3. +> - Moved to GitLab Premium in 13.9. When you have a lot of issues, it can be hard to get an overview. By adding a weight to each issue, you can get a better idea of how much time, value or complexity a given issue has or costs. -You can set the weight of an issue during its creation, by simply changing the +You can set the weight of an issue during its creation, by changing the value in the dropdown menu. You can set it to a non-negative integer value from 0, 1, 2, and so on. (The database stores a 4-byte value, so the upper bound is essentially limitless). diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index ef860df054e..f1739726cf8 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -270,7 +270,7 @@ 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. -#### Customizing the issue closing pattern **(CORE ONLY)** +#### Customizing the issue closing pattern **(FREE SELF)** In order to change the default issue closing pattern, GitLab administrators must edit the [`gitlab.rb` or `gitlab.yml` file](../../../administration/issue_closing_pattern.md) @@ -287,9 +287,9 @@ editing it and clicking on the delete button. ## Promote an issue to an epic **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8. -> - Promoting issues to epics via the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233974) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in GitLab Ultimate 11.6. +> - Moved to GitLab Premium in 12.8. +> - Promoting issues to epics via the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233974) in GitLab Premium 13.6. You can promote an issue to an epic in the immediate parent group. @@ -302,9 +302,10 @@ Alternatively, you can use the `/promote` [quick action](../quick_actions.md#qui Read more about promoting an issue to an epic on the [Manage epics page](../../group/epics/manage_epics.md#promote-an-issue-to-an-epic). -## Add an issue to an iteration **(STARTER)** +## Add an issue to an iteration **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216158) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216158) in GitLab 13.2. +> - Moved to GitLab Premium in 13.9. To add an issue to an [iteration](../../group/iterations/index.md): diff --git a/doc/user/project/issues/moving_issues.md b/doc/user/project/issues/moving_issues.md deleted file mode 100644 index 3b40affcdc3..00000000000 --- a/doc/user/project/issues/moving_issues.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'managing_issues.md#moving-issues' ---- - -This document was moved to [another location](managing_issues.md#moving-issues). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index bb9038062f7..189777d40e7 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -4,9 +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 --- -# Multiple Assignees for Issues **(STARTER)** +# Multiple Assignees for Issues **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1904) in [GitLab Starter 9.2](https://about.gitlab.com/releases/2017/05/22/gitlab-9-2-released/#multiple-assignees-for-issues). +> - Moved to GitLab Premium in 13.9. In large teams, where there is shared ownership of an issue, it can be difficult to track who is working on it, who already completed their contributions, who @@ -40,4 +40,4 @@ to assign the issue to.  -An assignee can be easily removed by deselecting them from the same dropdown menu. +To remove an assignee, deselect them from the same dropdown menu. diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 82b2d4fde52..91c26d49532 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -4,10 +4,10 @@ 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 --- -# Related issues **(CORE)** +# Related issues **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1797) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.4. -> - The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.4. +> - The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.4. Related issues are a bi-directional relationship between any two issues and appear in a block below the issue description. Issues can be across groups diff --git a/doc/user/project/issues/similar_issues.md b/doc/user/project/issues/similar_issues.md deleted file mode 100644 index 79a50d5f812..00000000000 --- a/doc/user/project/issues/similar_issues.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'index.md#similar-issues' ---- - -This document was moved to [another location](index.md#similar-issues). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index b4cb1c383ba..3a393b18579 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Sorting and ordering issue lists **(CORE)** +# Sorting and ordering issue lists **(FREE)** You can sort a list of issues several ways, including by: diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 22dfd3a8719..c0a66343a88 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -59,21 +59,25 @@ and edit labels. > Showing all inherited labels [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241990) in GitLab 13.5. -To view the project labels list, navigate to the project and click **Issues > Labels**. -The list includes all labels that are defined at the project level, as well as all -labels defined by its ancestor groups. -For each label, you can see the project or group path from where it was created. -You can filter the list by entering a search query at the top and clicking search (**{search}**). +To view a project's available labels, in the project, go to **Issues > Labels**. +Its list of labels includes both the labels defined at the project level, and +all labels defined by its ancestor groups. For each label, you can see the +project or group path from where it was created. You can filter the list by +entering a search query in the **Filter** field, and then clicking its search +icon (**{search}**). To create a new project label: -1. Navigate to **Issues > Labels** in the project. -1. Click the **New label** button. - - Enter the title. - - (Optional) Enter a description. - - (Optional) Select a background color by clicking on the available colors, or input - a hex color value for a specific color. -1. Click **Create label** to create the label. +1. In your project, go to **Issues > Labels**. +1. Select the **New label** button. +1. In the **Title** field, enter a short, descriptive name for the label. You + can also use this field to create [scoped, mutually exclusive labels](#scoped-labels). +1. (Optional) In the **Description** field, you can enter additional + information about how and when to use this label. +1. (Optional) Select a background color for the label by selecting one of the + available colors, or by entering a hex color value in the **Background color** + field. +1. Select **Create label**. You can also create a new project label from within an issue or merge request. In the label section of the right sidebar of an issue or a merge request: diff --git a/doc/user/project/maven_packages.md b/doc/user/project/maven_packages.md deleted file mode 100644 index 5bfa08de2ed..00000000000 --- a/doc/user/project/maven_packages.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../packages/maven_repository/index.md' ---- - -This document was moved to [another location](../packages/maven_repository/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/members/img/access_requests_management_13_8.png b/doc/user/project/members/img/access_requests_management_13_8.png Binary files differdeleted file mode 100644 index 950ef4dec01..00000000000 --- a/doc/user/project/members/img/access_requests_management_13_8.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..b7883e9d134 --- /dev/null +++ b/doc/user/project/members/img/access_requests_management_v13_9.png diff --git a/doc/user/project/members/img/add_user_email_accept_13_8.png b/doc/user/project/members/img/add_user_email_accept_13_8.png Binary files differdeleted file mode 100644 index ed980036af5..00000000000 --- a/doc/user/project/members/img/add_user_email_accept_13_8.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 differnew file mode 100644 index 00000000000..a6b303e05ca --- /dev/null +++ b/doc/user/project/members/img/add_user_email_accept_v13_9.png diff --git a/doc/user/project/members/img/add_user_email_ready_13_8.png b/doc/user/project/members/img/add_user_email_ready_v13_8.png Binary files differindex a610b46a176..a610b46a176 100644 --- a/doc/user/project/members/img/add_user_email_ready_13_8.png +++ b/doc/user/project/members/img/add_user_email_ready_v13_8.png diff --git a/doc/user/project/members/img/add_user_email_search_13_8.png b/doc/user/project/members/img/add_user_email_search_v13_8.png Binary files differindex 934cf19bd3d..934cf19bd3d 100644 --- a/doc/user/project/members/img/add_user_email_search_13_8.png +++ b/doc/user/project/members/img/add_user_email_search_v13_8.png diff --git a/doc/user/project/members/img/add_user_give_permissions_13_8.png b/doc/user/project/members/img/add_user_give_permissions_v13_8.png Binary files differindex 1916d056a52..1916d056a52 100644 --- a/doc/user/project/members/img/add_user_give_permissions_13_8.png +++ b/doc/user/project/members/img/add_user_give_permissions_v13_8.png diff --git a/doc/user/project/members/img/add_user_import_members_from_another_project_13_8.png b/doc/user/project/members/img/add_user_import_members_from_another_project_v13_8.png Binary files differindex a6dddec3fb7..a6dddec3fb7 100644 --- a/doc/user/project/members/img/add_user_import_members_from_another_project_13_8.png +++ b/doc/user/project/members/img/add_user_import_members_from_another_project_v13_8.png diff --git a/doc/user/project/members/img/add_user_imported_members_13_8.png b/doc/user/project/members/img/add_user_imported_members_13_8.png Binary files differdeleted file mode 100644 index 725e447604f..00000000000 --- a/doc/user/project/members/img/add_user_imported_members_13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_imported_members_v13_9.png b/doc/user/project/members/img/add_user_imported_members_v13_9.png Binary files differnew file mode 100644 index 00000000000..e40240df2b2 --- /dev/null +++ b/doc/user/project/members/img/add_user_imported_members_v13_9.png diff --git a/doc/user/project/members/img/add_user_list_members_13_8.png b/doc/user/project/members/img/add_user_list_members_13_8.png Binary files differdeleted file mode 100644 index b8c0160c6d8..00000000000 --- a/doc/user/project/members/img/add_user_list_members_13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/add_user_list_members_v13_9.png b/doc/user/project/members/img/add_user_list_members_v13_9.png Binary files differnew file mode 100644 index 00000000000..7a07ea01d14 --- /dev/null +++ b/doc/user/project/members/img/add_user_list_members_v13_9.png diff --git a/doc/user/project/members/img/add_user_search_people_13_8.png b/doc/user/project/members/img/add_user_search_people_v13_8.png Binary files differindex e9aa58512ab..e9aa58512ab 100644 --- a/doc/user/project/members/img/add_user_search_people_13_8.png +++ b/doc/user/project/members/img/add_user_search_people_v13_8.png diff --git a/doc/user/project/members/img/project_groups_tab_13_8.png b/doc/user/project/members/img/project_groups_tab_13_8.png Binary files differdeleted file mode 100644 index 5d7948f0761..00000000000 --- a/doc/user/project/members/img/project_groups_tab_13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/project_groups_tab_v13_9.png b/doc/user/project/members/img/project_groups_tab_v13_9.png Binary files differnew file mode 100644 index 00000000000..d1b6a640341 --- /dev/null +++ b/doc/user/project/members/img/project_groups_tab_v13_9.png diff --git a/doc/user/project/members/img/project_members_13_8.png b/doc/user/project/members/img/project_members_13_8.png Binary files differdeleted file mode 100644 index 9120d471b3b..00000000000 --- a/doc/user/project/members/img/project_members_13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/project_members_filter_direct_v13_9.png b/doc/user/project/members/img/project_members_filter_direct_v13_9.png Binary files differnew file mode 100644 index 00000000000..50115ee4052 --- /dev/null +++ b/doc/user/project/members/img/project_members_filter_direct_v13_9.png diff --git a/doc/user/project/members/img/project_members_filter_inherited_v13_9.png b/doc/user/project/members/img/project_members_filter_inherited_v13_9.png Binary files differnew file mode 100644 index 00000000000..433003fe58b --- /dev/null +++ b/doc/user/project/members/img/project_members_filter_inherited_v13_9.png diff --git a/doc/user/project/members/img/project_members_search_v13_9.png b/doc/user/project/members/img/project_members_search_v13_9.png Binary files differnew file mode 100644 index 00000000000..67280d11dca --- /dev/null +++ b/doc/user/project/members/img/project_members_search_v13_9.png diff --git a/doc/user/project/members/img/project_members_sort_v13_9.png b/doc/user/project/members/img/project_members_sort_v13_9.png Binary files differnew file mode 100644 index 00000000000..47abe18ba49 --- /dev/null +++ b/doc/user/project/members/img/project_members_sort_v13_9.png diff --git a/doc/user/project/members/img/project_members_v13_9.png b/doc/user/project/members/img/project_members_v13_9.png Binary files differnew file mode 100644 index 00000000000..3b48c752c6a --- /dev/null +++ b/doc/user/project/members/img/project_members_v13_9.png diff --git a/doc/user/project/members/img/share_project_with_groups_tab_v13_8.png b/doc/user/project/members/img/share_project_with_groups_tab_v13_8.png Binary files differdeleted file mode 100644 index 6cbbb386396..00000000000 --- a/doc/user/project/members/img/share_project_with_groups_tab_v13_8.png +++ /dev/null diff --git a/doc/user/project/members/img/share_project_with_groups_tab_v13_9.png b/doc/user/project/members/img/share_project_with_groups_tab_v13_9.png Binary files differnew file mode 100644 index 00000000000..99be996c03e --- /dev/null +++ b/doc/user/project/members/img/share_project_with_groups_tab_v13_9.png diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index cccb998fc31..00474098487 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -21,42 +21,74 @@ project's **Members**. When your project belongs to the group, group members inherit the membership and permission level for the project from the group. - + From the image above, we can deduce the following things: - 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. -- For User1 there is no indication of a group, therefore they belong directly +- 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. -[From GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/21727), you can filter this list -using the dropdown on the right side: +## Filter and sort members - +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) in GitLab 12.6. +> - [Improved](https://gitlab.com/groups/gitlab-org/-/epics/4901) in GitLab 13.9. +> - Improvements are [deployed behind a feature flag](../../feature_flags.md), enabled by default. +> - Improvements are enabled on GitLab.com. +> - Improvements are recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable improvements](#enable-or-disable-improvements-to-project-member-management). **(FREE SELF)** -- **Show only direct members** displays only User1. -- **Show only inherited members** displays User0 and Administrator. +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. + +#### Display inherited members + +To display inherited members, include `Membership` `=` `Inherited` in the search text box. + + + +#### Display direct members + +To display direct members, include `Membership` `=` `Direct` in the search text box. + + + +### Search + +You can search for members by name, username, or email. + + + +### Sort + +You can sort members by **Account**, **Access granted**, **Max role**, or **Last sign-in** in ascending or descending order. + + ## Add a user Right next to **People**, start typing the name or username of the user you want to add. - + Select the user and the [permission level](../../permissions.md) that you'd like to give the user. Note that you can select more than one user. - + Once done, select **Add users to project** and they are immediately added to your project with the permissions you gave them above. - + From there on, you can either remove an existing user or change their access level to the project. @@ -68,14 +100,14 @@ You can import another project's users in your own project by hitting the In the dropdown menu, you can see only the projects you are Maintainer on. - + Select the one you want and hit **Import project members**. A flash message displays, notifying you that the import was successful, and the new members are now in the project's members list. Notice that the permissions that they had on the project you imported from are retained. - + ## Invite people using their e-mail address @@ -83,18 +115,18 @@ 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. - + As you can imagine, you can mix inviting multiple people and adding existing GitLab users to the project. - + 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. - + While unaccepted, the system automatically sends reminder emails on the second, fifth, and tenth day after the invitation was initially sent. @@ -130,7 +162,7 @@ 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. @@ -167,3 +199,27 @@ To remove a member from a project: A **Remove member** modal appears. 1. (Optional) Select the **Also unassign this user from related issues and merge requests** checkbox. 1. Click **Remove member**. + +## Enable or disable improvements to project member management **(FREE SELF)** + +Project member management improvements are 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 the improvements. + +To disable them: + +```ruby +# For the instance +Feature.disable(:vue_project_members_list) +# For a single project +Feature.disable(:vue_project_members_list, Project.find(<project id>)) +``` + +To enable them: + +```ruby +# For the instance +Feature.enable(:vue_project_members_list) +# For a single project +Feature.enable(:vue_project_members_list, Project.find(<project id>)) +``` diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index d17717fb29c..7000988d9bf 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -26,7 +26,7 @@ To share 'Project Acme' with the 'Engineering' group: 1. For 'Project Acme' use the left navigation menu to go to **Members**. -  +  1. Select the **Invite group** tab. 1. Add the 'Engineering' group with the maximum access level of your choice. @@ -35,7 +35,7 @@ To share 'Project Acme' with the 'Engineering' group: 1. After sharing 'Project Acme' with 'Engineering': - The group is listed in the **Groups** tab. -  +  - The project is listed on the group dashboard. diff --git a/doc/user/project/merge_requests.md b/doc/user/project/merge_requests.md deleted file mode 100644 index 5762177882e..00000000000 --- a/doc/user/project/merge_requests.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'merge_requests/index.md' ---- - -This document was moved to [merge_requests/index.md](merge_requests/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 8adaae3b2ef..7aa7673366d 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Allow collaboration on merge requests across forks +# Allow collaboration on merge requests across forks **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17395) in GitLab 10.6. @@ -23,7 +23,7 @@ of the merge request. ## Enabling commit edits from upstream members -From [GitLab 13.7 onwards](https://gitlab.com/gitlab-org/gitlab/-/issues/23308), +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 will also be able to retry the pipelines and jobs of the merge request: @@ -78,8 +78,23 @@ Here's how the process would look like: local branch `thedude-awesome-project-update-docs` to the `update-docs` branch of the `git@gitlab.com:thedude/awesome-project.git` repository. -<!-- ## Troubleshooting +## 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 +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. +To see the pipeline status from the merge request page of a forked project +going back to the original project: + +1. Create a group containing all the upstream members. +1. Go to the **Members** tab in the forked project and invite the newly-created + group to the forked project. + +<!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues one might have when setting this up, or when something is changed, or on upgrading, it's important to describe those, too. Think of things that may go wrong and include them here. 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 7bb64987a31..36481ac0133 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts --- -# Authorization for Merge requests +# Authorization for Merge requests **(FREE)** There are two main ways to have a merge request flow with GitLab: diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 4e87876b036..4c9a6557320 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Cherry-pick changes +# Cherry-pick changes **(FREE)** GitLab implements Git's powerful feature to [cherry-pick any commit](https://git-scm.com/docs/git-cherry-pick "Git cherry-pick documentation") @@ -13,12 +13,13 @@ with introducing a **Cherry-pick** button in merge requests and commit details. ## Cherry-picking a merge request -After the merge request has been merged, a **Cherry-pick** button will be available +After the merge request has been merged, a **Cherry-pick** button displays to cherry-pick the changes introduced by that merge request.  -After you click that button, a modal will appear showing a [branch filter search box](../repository/branches/index.md#branch-filter-search-box) +After you click that button, a modal displays a +[branch filter search box](../repository/branches/index.md#branch-filter-search-box) where you can choose to either: - Cherry-pick the changes directly into the selected branch. @@ -28,12 +29,12 @@ where you can choose to either: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2675) in GitLab 12.9. -When you cherry-pick a merge commit, GitLab will output a system note to the related merge -request thread crosslinking the new commit and the existing merge request. +When you cherry-pick a merge commit, GitLab displays a system note to the related merge +request thread. It crosslinks the new commit and the existing merge request.  -Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) will include cherry-picked merge commits. +Each deployment's [list of associated merge requests](../../../api/deployments.md#list-of-merge-requests-associated-with-a-deployment) includes cherry-picked merge commits. NOTE: We only track cherry-pick executed from GitLab (both UI and API). Support for [tracking cherry-picked commits through the command line](https://gitlab.com/gitlab-org/gitlab/-/issues/202215) is planned for a future release. @@ -44,15 +45,15 @@ You can cherry-pick a commit from the commit details page:  -Similar to cherry-picking a merge request, you can opt to cherry-pick the changes +Similar to cherry-picking a merge request, you can cherry-pick the changes directly into the target branch or create a new merge request to cherry-pick the changes. -Please note that when cherry-picking merge commits, the mainline will always be the -first parent. If you want to use a different mainline then you need to do that +When cherry-picking merge commits, the mainline is always the +first parent. If you want to use a different mainline, you need to do that from the command line. -Here is a quick example to cherry-pick a merge commit using the second parent as the +Here's a quick example to cherry-pick a merge commit using the second parent as the mainline: ```shell diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index ca15ec154fc..55dc0bcc41a 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -5,9 +5,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Code Quality +# Code Quality **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in GitLab 9.3. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in 13.2. Ensuring your project's code stays simple, readable and easy to contribute to can be problematic. With the help of [GitLab CI/CD](../../../ci/README.md), you can analyze your @@ -28,7 +28,7 @@ Code Quality: ## Code Quality Widget -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in GitLab 9.3. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in 13.2. Going a step further, GitLab can show the Code Quality report right @@ -73,9 +73,9 @@ GitLab 11.4 or earlier, you can view the deprecated job definitions in the [documentation archive](https://docs.gitlab.com/12.10/ee/user/project/merge_requests/code_quality.html#previous-job-definitions). - Using shared runners, the job should be configured For the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). -- Using private runners, there is an [alternative configuration](#set-up-a-private-runner-for-code-quality-without-docker-in-docker) recommended for running CodeQuality analysis more efficiently. +- Using private runners, there is an [alternative configuration](#set-up-a-private-runner-for-code-quality-without-docker-in-docker) recommended for running Code Quality analysis more efficiently. -In either configuration, the runner mmust have enough disk space to handle generated Code Quality files. For example on the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB. +In either configuration, the runner must have enough disk space to handle generated Code Quality files. For example on the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB. Once you set up GitLab Runner, include the Code Quality template in your CI configuration: @@ -161,6 +161,7 @@ to be consider, but may be preferable depending on your use case. --locked="false" \ --access-level="not_protected" \ --docker-volumes "/cache"\ + --docker-volumes "/builds:/builds"\ --docker-volumes "/var/run/docker.sock:/var/run/docker.sock" \ --registration-token="<project_token>" \ --non-interactive @@ -173,8 +174,8 @@ to be consider, but may be preferable depending on your use case. in the previous step. ```shell - --builds-dir /tmp/builds - --docker-volumes /tmp/builds:/tmp/builds + --builds-dir "/tmp/builds" + --docker-volumes "/tmp/builds:/tmp/builds" # Use this instead of --docker-volumes "/builds:/builds" ``` The resulting configuration: @@ -219,8 +220,8 @@ The end result is that: - Docker images, including all CodeClimate images, are cached, and not re-fetched for subsequent jobs. With this configuration, the run time for a second pipeline is much shorter. For example -this [small change](https://gitlab.com/drewcimino/test-code-quality-template/-/merge_requests/4/diffs?commit_id=1e705607aef7236c1b20bb6f637965f3f3e53a46) -to an [open merge request](https://gitlab.com/drewcimino/test-code-quality-template/-/merge_requests/4/pipelines) +this [small change](https://gitlab.com/drew/test-code-quality-template/-/merge_requests/4/diffs?commit_id=1e705607aef7236c1b20bb6f637965f3f3e53a46) +to an [open merge request](https://gitlab.com/drew/test-code-quality-template/-/merge_requests/4/pipelines) running Code Quality analysis ran significantly faster the second time:  @@ -358,7 +359,7 @@ After the Code Quality job completes: [downloadable artifact](../../../ci/pipelines/job_artifacts.md#downloading-artifacts) for the `code_quality` job. - The full list of code quality violations generated by a pipeline is shown in the - Code Quality tab of the Pipeline Details page. **(STARTER)** + Code Quality tab of the Pipeline Details page. **(PREMIUM)** ### Generating an HTML report @@ -411,7 +412,7 @@ plugins: enabled: true ``` -This adds SonarJava to the `plugins:` section of the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml) +This adds SonarJava to the `plugins:` section of the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template) included in your project. Changes to the `plugins:` section do not affect the `exclude_patterns` section of the @@ -421,6 +422,71 @@ for more details. Here's [an example project](https://gitlab.com/jheimbuck_gl/jh_java_example_project) that uses Code Quality with a `.codeclimate.yml` file. +## Use a Code Quality image hosted in a registry with untrusted certificates + +If you set the `CODE_QUALITY_IMAGE` to an image that is hosted in a +Docker registry which uses a TLS certificate that is not trusted, such as +a self-signed certificate, you can see errors like the one below: + +```shell +$ docker pull --quiet "$CODE_QUALITY_IMAGE" +Error response from daemon: Get https://gitlab.example.com/v2/: x509: certificate signed by unknown authority +``` + +To fix this, configure the Docker daemon to [trust certificates](https://docs.docker.com/registry/insecure/#use-self-signed-certificates) +by putting the certificate inside of the `/etc/docker/certs.d` +directory. + +This Docker daemon is exposed to the subsequent Code Quality Docker container in the +[GitLab Code Quality template](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.8.3-ee/lib/gitlab/ci/templates/Jobs/Code-Quality.gitlab-ci.yml#L41) +and should be to exposed any other containers in which you want to have +your certificate configuration apply. + +### Docker + +If you have access to GitLab Runner configuration, add the directory as a +[volume mount](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#volumes-in-the-runnersdocker-section). For example: + +```toml +[[runners]] + ... + executor = "docker" + [runners.docker] + ... + privileged = true + volumes = ["/cache", "/etc/gitlab-runner/certs/gitlab.example.com.crt:/etc/docker/certs.d/gitlab.example.com/ca.crt:ro"] +``` + +Replace `gitlab.example.com` with the actual domain of the registry. + +### Kubernetes + +If you have access to GitLab Runner configuration and the Kubernetes cluster, +you can [mount a ConfigMap](https://docs.gitlab.com/runner/executors/kubernetes.html#configmap-volumes): + +1. Create a ConfigMap with the certificate: + + ```shell + kubectl create configmap registry-crt --namespace gitlab-runner --from-file /etc/gitlab-runner/certs/gitlab.example.com.crt + ``` + +1. Update GitLab Runner `config.toml` to specify the ConfigMap: + + ```toml + [[runners]] + ... + executor = "kubernetes" + [runners.kubernetes] + image = "alpine:3.12" + privileged = true + [[runners.kubernetes.volumes.config_map]] + name = "registry-crt" + mount_path = "/etc/docker/certs.d/gitlab.example.com/ca.crt" + sub_path = "gitlab.example.com.crt" + ``` + +Replace `gitlab.example.com` with the actual domain of the registry. + ## Troubleshooting ### Changing the default configuration has no effect @@ -428,7 +494,7 @@ Here's [an example project](https://gitlab.com/jheimbuck_gl/jh_java_example_proj A common issue is that the terms `Code Quality` (GitLab specific) and `Code Climate` (Engine used by GitLab) are very similar. You must add a **`.codeclimate.yml`** file to change the default configuration, **not** a `.codequality.yml` file. If you use -the wrong filename, the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml) +the wrong filename, the [default `.codeclimate.yml`](https://gitlab.com/gitlab-org/ci-cd/codequality/-/blob/master/codeclimate_defaults/.codeclimate.yml.template) is still used. ### No Code Quality report is displayed in a Merge Request @@ -438,21 +504,51 @@ 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 will not have anything 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. - 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 setting can cause the Code Quality artifact(s) to expire faster than desired. - If you use the [`REPORT_STDOUT` environment variable](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables), no report file is generated and nothing displays in the merge request. -- Large `codeclimate.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). +- Large `gl-code-quality-report.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). As a work-around, try removing [properties](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types) that are [ignored by GitLab](#implementing-a-custom-tool). You can: - Configure the Code Quality tool to not output those types. - Use `sed`, `awk` or similar commands in the `.gitlab-ci.yml` script to - edit the `codeclimate.json` before the job completes. + edit the `gl-code-quality-report.json` before the job completes. ### Only a single Code Quality report is displayed, but more are defined GitLab only uses the Code Quality artifact from the latest created job (with the largest job ID). If multiple jobs in a pipeline generate a code quality artifact, those of earlier jobs are ignored. -To avoid confusion, configure only one job to generate a `codeclimate.json`. +To avoid confusion, configure only one job to generate a `gl-code-quality-report.json`. + +### Rubocop errors + +When using Code Quality jobs on a Ruby project, you can encounter problems running Rubocop. +For example, the following error can appear when using either a very recent or very old version +of Ruby: + +```plaintext +/usr/local/bundle/gems/rubocop-0.52.1/lib/rubocop/config.rb:510:in `check_target_ruby': +Unknown Ruby version 2.7 found in `.ruby-version`. (RuboCop::ValidationError) +Supported versions: 2.1, 2.2, 2.3, 2.4, 2.5 +``` + +This is caused by the default version of Rubocop used by the check engine not covering +support for the Ruby version in use. + +To use a custom version of Rubocop that +[supports the version of Ruby used by the project](https://docs.rubocop.org/rubocop/compatibility.html#support-matrix), +you can [override the configuration through a `.codeclimate.yml` file](https://docs.codeclimate.com/docs/rubocop#using-rubocops-newer-versions) +created in the project repository. + +For example, to specify using Rubocop release **0.67**: + +```yaml +version: "2" +plugins: + rubocop: + enabled: true + channel: rubocop-0-67 +``` diff --git a/doc/user/project/merge_requests/code_quality_diff.md b/doc/user/project/merge_requests/code_quality_diff.md deleted file mode 100644 index 2b7b2574ef7..00000000000 --- a/doc/user/project/merge_requests/code_quality_diff.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'code_quality.md' ---- - -This document was moved to [another location](code_quality.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/container_scanning.md b/doc/user/project/merge_requests/container_scanning.md deleted file mode 100644 index 5d61f2b36e8..00000000000 --- a/doc/user/project/merge_requests/container_scanning.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../application_security/container_scanning/index.md' ---- - -This document was moved to [another location](../../application_security/container_scanning/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 5adc4ab6b6e..5cfedc6c9f1 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -7,7 +7,7 @@ description: "How to create Merge Requests in GitLab." disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html' --- -# How to create a merge request +# How to create a merge request **(FREE)** Before creating a merge request, read through an [introduction to Merge Requests](getting_started.md) @@ -178,7 +178,7 @@ fork from its upstream project in the **Settings > Advanced Settings** section b For further details, [see the forking workflow documentation](../repository/forking_workflow.md). -## New merge request by email **(CORE ONLY)** +## New merge request by email **(FREE SELF)** _This feature needs [incoming email](../../../administration/incoming_email.md) to be configured by a GitLab administrator to be available._ It isn't diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index 0de9f246ceb..f4843b96c99 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -4,7 +4,7 @@ group: Compliance info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Export Merge Requests to CSV **(CORE)** +# Export Merge Requests to CSV **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3619) in GitLab 13.6. diff --git a/doc/user/project/merge_requests/dast.md b/doc/user/project/merge_requests/dast.md deleted file mode 100644 index 37c0d5b4e37..00000000000 --- a/doc/user/project/merge_requests/dast.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../application_security/dast/index.md' ---- - -This document was moved to [another location](../../application_security/dast/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/dependency_scanning.md b/doc/user/project/merge_requests/dependency_scanning.md deleted file mode 100644 index dd5910121ed..00000000000 --- a/doc/user/project/merge_requests/dependency_scanning.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../application_security/dependency_scanning/index.md' ---- - -This document was moved to [another location](../../application_security/dependency_scanning/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index a89acff4bfc..c4a34f9c65c 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Fast-forward merge requests +# Fast-forward merge requests **(FREE)** Sometimes, a workflow policy might mandate a clean commit history without merge commits. In such cases, the fast-forward merge is the perfect candidate. diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index dc5e1f81a63..b1a57d9c3e6 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -6,7 +6,7 @@ type: index, reference description: "Getting started with Merge Requests." --- -# Getting started with Merge Requests +# Getting started with Merge Requests **(FREE)** A Merge Request (**MR**) is the basis of GitLab as a code collaboration and version control. @@ -53,10 +53,10 @@ When you start a new merge request, you can immediately include the following options, or add them later by clicking the **Edit** button on the merge request's page at the top-right side: -- [Assign](#assignee) the merge request to a colleague for review. With GitLab Starter and higher tiers, you can [assign it to more than one person at a time](#multiple-assignees). +- [Assign](#assignee) the merge request to a colleague for review. With [multiple assignees](#multiple-assignees), you can assign it to more than one person at a time. - Set a [milestone](../milestones/index.md) to track time-sensitive changes. - Add [labels](../labels.md) to help contextualize and filter your merge requests over time. -- Require [approval](merge_request_approvals.md) from your team. **(STARTER)** +- Require [approval](merge_request_approvals.md) from your team. **(PREMIUM)** - [Close issues automatically](#merge-requests-to-close-issues) when they are merged. - Enable the [delete source branch when merge request is accepted](#deleting-the-source-branch) option to keep your repository clean. - Enable the [squash commits when merge request is accepted](squash_and_merge.md) option to combine all the commits into one before merging, thus keep a clean commit history in your repository. @@ -87,9 +87,10 @@ Open the drop down box to search for the user you wish to assign, and the merge request will be added to their [assigned merge request list](../../search/index.md#issues-and-merge-requests). -#### Multiple assignees **(STARTER)** +#### Multiple assignees **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2004) in [GitLab Starter 11.11](https://about.gitlab.com/pricing/). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2004) in GitLab 11.11. +> - Moved to GitLab Premium in 13.9 Multiple people often review merge requests at the same time. GitLab allows you to have multiple assignees for merge requests @@ -114,16 +115,9 @@ It is also possible to manage multiple assignees: ### Reviewer > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. -> - It was [deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49787) on GitLab 13.7. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - It can be enabled or disabled for a single project. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-merge-request-reviewers). **(CORE ONLY)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245190) in GitLab 13.9. WARNING: -This feature might not be available to you. Check the **version history** note above for details. - Requesting a code review is an important part of contributing code. However, deciding who should review your code and asking for a review are no easy tasks. Using the "assignee" field for both authors and reviewers makes it hard for others to determine who's doing what on a merge request. @@ -136,48 +130,14 @@ This makes it easy to determine the relevant roles for the users involved in the To request it, open the **Reviewers** drop-down box to search for the user you wish to get a review from. -#### Enable or disable Merge Request Reviewers **(CORE ONLY)** - -Merge Request Reviewers 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 -# For the instance -Feature.enable(:merge_request_reviewers) -# For a single project -Feature.enable(:merge_request_reviewers, Project.find(<project id>)) -``` - -To disable it: +#### Approval Rule information for Reviewers **(PREMIUM)** -```ruby -# For the instance -Feature.disable(:merge_request_reviewers) -# For a single project -Feature.disable(:merge_request_reviewers, Project.find(<project id>)) -``` - -#### Approval Rule information for Reviewers **(STARTER)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. -> - It was [deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51183) in GitLab 13.8. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - It can be enabled or disabled for a single project. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-approval-rule-information-for-reviewers). **(STARTER ONLY)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233736) in GitLab 13.8. For this version only, GitLab administrators can opt to [enable it](#enable-or-disable-approval-rule-information). +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. When editing the **Reviewers** field in a new or existing merge request, GitLab displays the name of the matching [approval rule](merge_request_approvals.md#approval-rules) -below the name of each suggested reviewer. [Code Owners](../code_owners.md) are displayed as **Code Owner** without group detail. -We intend to iterate on this feature in future releases. +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: @@ -187,30 +147,20 @@ This example shows reviewers and approval rules in a merge request sidebar:  -##### Enable or disable Approval Rule information for Reviewers **(STARTER ONLY)** +#### Requesting a new review -Merge Request Reviewers is under development and 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: +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/293933) in GitLab 13.9. -```ruby -# For the instance -Feature.enable(:reviewer_approval_rules) -# For a single project -Feature.enable(:reviewer_approval_rules, Project.find(<project id>)) -``` +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: -To disable it: +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. -```ruby -# For the instance -Feature.disable(:reviewer_approval_rules) -# For a single project -Feature.disable(:reviewer_approval_rules, Project.find(<project id>)) -``` +GitLab creates a new [to-do item](../../todos.md) for the reviewer, and sends +them a notification email. ### Merge requests to close issues @@ -244,6 +194,33 @@ is set for deletion, the merge request widget displays the  +### Branch retargeting on merge **(FREE SELF)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. +> - 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-branch-retargeting-on-merge). + +In specific circumstances, GitLab can retarget the destination branch of +open merge request, if the destination branch merges while the merge request is +open. Merge requests are often chained in this manner, with one merge request +depending on another: + +- **Merge request 1**: merge `feature-alpha` into `master`. +- **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 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`. + +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 +forks are not retargeted. + ## Recommendations and best practices for Merge Requests - When working locally in your branch, add multiple commits and only push when @@ -253,3 +230,49 @@ is set for deletion, the merge request widget displays the - Take one thing at a time and ship the smallest changes possible. By doing so, reviews are faster and your changes are less prone to errors. - Do not use capital letters nor special chars in branch names. + +## Enable or disable Approval Rule information **(PREMIUM SELF)** + +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293742) in GitLab 13.9. + +Merge Request Reviewers is under development and 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 +# For the instance +Feature.enable(:reviewer_approval_rules) +# For a single project +Feature.enable(:reviewer_approval_rules, Project.find(<project id>)) +``` + +To disable it: + +```ruby +# For the instance +Feature.disable(:reviewer_approval_rules) +# For a single project +Feature.disable(:reviewer_approval_rules, Project.find(<project id>)) +``` + +### Enable or disable branch retargeting on merge **(FREE SELF)** + +Automatically retargeting merge requests 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(:retarget_merge_requests) +``` + +To disable it: + +```ruby +Feature.disable(:retarget_merge_requests) +``` diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 6af6cad5cdd..8ccf50e48b8 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Merge requests +# Merge requests **(FREE)** A Merge Request (**MR**) is a _request_ to _merge_ one branch into another. diff --git a/doc/user/project/merge_requests/license_management.md b/doc/user/project/merge_requests/license_management.md deleted file mode 100644 index 4c598d851a9..00000000000 --- a/doc/user/project/merge_requests/license_management.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../compliance/license_compliance/index.md' ---- - -This document was moved to [another location](../../compliance/license_compliance/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/maintainer_access.md b/doc/user/project/merge_requests/maintainer_access.md deleted file mode 100644 index 29afff289fd..00000000000 --- a/doc/user/project/merge_requests/maintainer_access.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'allow_collaboration.md' ---- - -This document was moved to [another location](allow_collaboration.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 887f563be51..1fcc09a9d8a 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -5,27 +5,28 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# Merge Request Approvals **(CORE)** +# Merge Request Approvals **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/580) in GitLab Enterprise Edition 7.2. Available in GitLab Core and higher tiers. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/580) in GitLab Enterprise Edition 7.2. Available in GitLab Free and higher tiers. > - Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0. -Code review is an essential practice of every successful project, and giving your -approval once a merge request is in good shape is an important part of the review +Code review is an essential practice of every successful project. Approving a +merge request is an important part of the review process, as it clearly communicates the ability to merge the change. ## Optional Approvals > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27426) in GitLab 13.2. -Any user with Developer or greater [permissions](../../permissions.md) can approve a merge request in GitLab Core and higher tiers. -This provides a consistent mechanism for reviewers to approve merge requests, and makes it easy for -maintainers to know when a change is ready to merge. Approvals in Core are optional and do +Any user with Developer or greater [permissions](../../permissions.md) can approve a merge request in GitLab Free and higher tiers. +This provides a consistent mechanism for reviewers to approve merge requests, and ensures +maintainers know a change is ready to merge. Approvals in Free are optional, and do not prevent a merge request from being merged when there is no approval. -## Required Approvals **(STARTER)** +## Required Approvals **(PREMIUM)** -> [Introduced](https://about.gitlab.com/releases/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only) in GitLab Enterprise Edition 7.12. Available in [GitLab Starter](https://about.gitlab.com/pricing/) and higher tiers. +> - [Introduced](https://about.gitlab.com/releases/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only) in GitLab Enterprise Edition 7.12. +> - Moved to GitLab Premium in 13.9. Required approvals enable enforced code review by requiring specified people to approve a merge request before it can be merged. @@ -50,13 +51,12 @@ be merged, and optionally which users should do the approving. Approvals can be - [As project defaults](#adding--editing-a-default-approval-rule). - [Per merge request](#editing--overriding-approval-rules-per-merge-request). -If no approval rules are defined, any user can approve a merge request, though the default -minimum number of required approvers can still be set in the [project settings for merge request approvals](#merge-request-approvals-project-settings). +If no approval rules are defined, any user can approve a merge request. However, the default +minimum number of required approvers can still be set in the +[project settings for merge request approvals](#merge-request-approvals-project-settings). You can opt to define one single rule to approve a merge request among the available rules -or choose more than one. Single approval rules are available in GitLab Starter and higher tiers, -while [multiple approval rules](#multiple-approval-rules) are available in -[GitLab Premium](https://about.gitlab.com/pricing/) and above. +or choose more than one with [multiple approval rules](#multiple-approval-rules). NOTE: On GitLab.com, you can add a group as an approver if you're a member of that group or the @@ -64,7 +64,7 @@ group is public. #### Eligible Approvers -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.3, when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10294) in GitLab 13.3, when an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget. The following users can approve merge requests: @@ -83,29 +83,31 @@ A group of users can also be added as approvers. In the future, group approvers [restricted to only groups with share access to the project](https://gitlab.com/gitlab-org/gitlab/-/issues/2048). If a user is added as an individual approver and is also part of a group approver, -then that user is just counted once. The merge request author, as well as users who have committed +then that user is just counted once. The merge request author, and users who have committed to the merge request, do not count as eligible approvers, if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) (enabled by default) and [**Prevent committers approval**](#prevent-approval-of-merge-requests-by-their-committers) (disabled by default) are enabled on the project settings. -When an eligible approver comments on a merge request, it appears in the **Commented by** column of the Approvals widget, -indicating who has engaged in the merge request review. Authors and reviewers can also easily identify who they should reach out -to if they have any questions or inputs about the content of the merge request. +When an eligible approver comments on a merge request, it displays in the +**Commented by** column of the Approvals widget. It indicates who participated in +the merge request review. Authors and reviewers can also identify who they should reach out +to if they have any questions about the content of the merge request. ##### Implicit Approvers If the number of required approvals is greater than the number of assigned approvers, -approvals from other users will count towards meeting the requirement. These would be +approvals from other users counts towards meeting the requirement. These would be users with developer [permissions](../../permissions.md) or higher in the project who were not explicitly listed in the approval rules. ##### Code Owners as eligible approvers -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in GitLab 11.5. +> - Moved to GitLab Premium in 13.9. If you add [Code Owners](../code_owners.md) to your repository, the owners to the -corresponding files will become eligible approvers, together with members with Developer +corresponding files become eligible approvers, together with members with Developer or higher [permissions](../../permissions.md). To enable this merge request approval rule: @@ -117,16 +119,17 @@ To enable this merge request approval rule:  Once set, merge requests can only be merged once approved by the -number of approvals you've set. GitLab will accept approvals from +number of approvals you've set. GitLab accepts approvals from users with Developer or higher permissions, as well as by Code Owners, indistinguishably. Alternatively, you can **require** -[Code Owner's approvals for Protected Branches](../protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** +[Code Owner's approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** #### Merge Request approval segregation of duties -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. +> - Moved to Premium in 13.9. Managers or operators with [Reporter permissions](../../permissions.md#project-members-permissions) to a project sometimes need to be required approvers of a merge request, @@ -156,27 +159,27 @@ To add or edit the default merge request approval rule: 1. Click **Add approval rule**, or **Edit**. - Add or change the **Rule name**. - Set the number of required approvals in **Approvals required**. The minimum value is `0`. - - (Optional) Search for users or groups that will be [eligible to approve](#eligible-approvers) + - (Optional) Search for users or groups that are [eligible to approve](#eligible-approvers) merge requests and click the **Add** button to add them as approvers. Before typing - in the search field, approvers will be suggested based on the previous authors of + in the search field, approvers are suggested based on the previous authors of the files being changed by the merge request. - (Optional) Click the **{remove}** **Remove** button next to a group or user to delete it from the rule. 1. Click **Add approval rule** or **Update approval rule**. When [approval rule overrides](#prevent-overriding-default-approvals) are allowed, -changes to these default rules will **not** be applied to existing merge +changes to these default rules are not applied to existing merge requests, except for changes to the [target branch](#scoped-to-protected-branch) of the rule. When approval rule overrides are not allowed, all changes to these default rules -will be applied to existing merge requests. Any approval rules that had previously been +are applied to existing merge requests. Any approval rules that had previously been manually [overridden](#editing--overriding-approval-rules-per-merge-request) during a -period when approval rule overrides where allowed, will not be modified. +period when approval rule overrides where allowed, are not modified. NOTE: If a merge request targets a different project, such as from a fork to the upstream project, -the default approval rules will be taken from the target (upstream) project, not the +the default approval rules are taken from the target (upstream) project, not the source (fork). ##### Editing / overriding approval rules per merge request @@ -195,8 +198,8 @@ the same steps as [Adding / editing a default approval rule](#adding--editing-a- #### Set up an optional approval rule -MR approvals can be configured to be optional. -This can be useful if you're working on a team where approvals are appreciated, but not required. +MR approvals can be configured to be optional, which can help if you're working +on a team where approvals are appreciated, but not required. To configure an approval to be optional, set the number of required approvals in **Approvals required** to `0`. @@ -211,20 +214,20 @@ as well as multiple default approval rules per project. Adding or editing multiple default rules is identical to [adding or editing a single default approval rule](#adding--editing-a-default-approval-rule), -except the **Add approval rule** button will be available to add more rules, even after +except the **Add approval rule** button is available to add more rules, even after a rule is already defined. Similarly, editing or overriding multiple approval rules per merge request is identical to [editing or overriding approval rules per merge request](#editing--overriding-approval-rules-per-merge-request), -except the **Add approval rule** button will be available to add more rules, even after +except the **Add approval rule** button is available to add more rules, even after a rule is already defined. -When an [eligible approver](#eligible-approvers) approves a merge request, it will -reduce the number of approvals left for all rules that the approver belongs to. +When an [eligible approver](#eligible-approvers) approves a merge request, it +reduces the number of approvals left for all rules that the approver belongs to.  -#### Scoped to Protected Branch **(PREMIUM)** +#### Scoped to protected branch **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. @@ -236,7 +239,7 @@ the **Target branch** dropdown. Alternatively, you can select a very specific protected branch from the **Target branch** dropdown: - + To enable this configuration, see [Code Owner’s approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). @@ -269,7 +272,7 @@ The merge request author is not allowed to approve their own merge request if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) is enabled in the project settings. -Once the approval rules have been met, the merge request can be merged if there is nothing +After the approval rules have been met, the merge request can be merged if there is nothing else blocking it. Note that the merge request could still be blocked by other conditions, such as merge conflicts, [pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved), or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md). @@ -291,7 +294,7 @@ To prevent that from happening: #### Resetting approvals on push You can force all approvals on a merge request to be removed when new commits are -pushed to the source branch of the merge request. If disabled, approvals will persist +pushed to the source branch of the merge request. If disabled, approvals persist even if there are changes added to the merge request. To enable this feature: 1. Check the **Require new approvals when new commits are added to an MR.** @@ -300,11 +303,12 @@ even if there are changes added to the merge request. To enable this feature: NOTE: Approvals do not get reset when [rebasing a merge request](fast_forward_merge.md) -from the UI. However, approvals will be reset if the target branch is changed. +from the UI. However, approvals are reset if the target branch is changed. -#### Allowing merge request authors to approve their own merge requests +#### Allowing merge request authors to approve their own merge requests **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in GitLab 11.3. +> - Moved to GitLab Premium in 13.9. By default, projects are configured to prevent merge requests from being approved by their own authors. To change this setting: @@ -315,24 +319,38 @@ their own authors. To change this setting: Note that users can edit the approval rules in every merge request and override pre-defined settings unless it's set [**not to allow** overrides](#prevent-overriding-default-approvals). -#### Prevent approval of merge requests by their committers +You can prevent authors from approving their own merge requests +[at the instance level](../../admin_area/merge_requests_approvals.md). When enabled, +this setting is disabled on the project level, and not editable. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.10. +#### Prevent approval of merge requests by their committers **(PREMIUM)** -You can prevent users that have committed to a merge request from approving it. To -enable this feature: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in GitLab 11.10. +> - Moved to GitLab Premium in 13.9. + +You can prevent users who have committed to a merge request from approving it, +though code authors can still approve. You can enable this feature +[at the instance level](../../admin_area/merge_requests_approvals.md), which +disables changes to this feature at the project level. If you prefer to manage +this feature at the project level, you can: 1. Check the **Prevent MR approvals from users who make commits to the MR.** checkbox. + If this check box is disabled, this feature has been disabled + [at the instance level](../../admin_area/merge_requests_approvals.md). 1. Click **Save changes**. +Read the official Git documentation for an explanation of the +[differences between authors and committers](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History). + #### Require authentication when approving a merge request -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5981) in GitLab 12.0. +> - Moved to GitLab Premium in 13.9. NOTE: To require authentication when approving a merge request, you must enable **Password authentication enabled for web interface** under [sign-in restrictions](../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). -in the Admin area. +in the Admin Area. You can force the approver to enter a password in order to authenticate before adding the approval. This enables an Electronic Signature for approvals such as the one defined diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index 4a596ed6139..646d77391a3 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -17,7 +17,7 @@ then it cannot be merged until its dependency is itself merged. NOTE: Merge requests dependencies are a **PREMIUM** feature, but this restriction is -only enforced for the dependent merge request. A merge request in a **CORE** or +only enforced for the dependent merge request. A merge request in a **FREE** or **STARTER** project can be a dependency of a **PREMIUM** merge request, but not vice-versa. diff --git a/doc/user/project/merge_requests/merge_request_discussion_resolution.md b/doc/user/project/merge_requests/merge_request_discussion_resolution.md deleted file mode 100644 index f8d15f31875..00000000000 --- a/doc/user/project/merge_requests/merge_request_discussion_resolution.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../discussions/index.md' ---- - -This document was moved to [another location](../../discussions/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/merge_when_build_succeeds.md b/doc/user/project/merge_requests/merge_when_build_succeeds.md deleted file mode 100644 index 48d32d2882f..00000000000 --- a/doc/user/project/merge_requests/merge_when_build_succeeds.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -redirect_to: 'merge_when_pipeline_succeeds.md' ---- - -This document was moved to [merge_when_pipeline_succeeds](merge_when_pipeline_succeeds.md). - ->[Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7135) by the "Rename MWBS service to Merge When Pipeline Succeeds" change. - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> 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 b813e4f7d28..d33a8e40aac 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Merge when pipeline succeeds +# Merge when pipeline succeeds **(FREE)** When reviewing a merge request that looks ready to merge but still has a pipeline running, you can set it to merge automatically when the @@ -42,8 +42,12 @@ complete, the merge is blocked until you resolve all existing threads. ## Only allow merge requests to be merged if the pipeline succeeds -You can prevent merge requests from being merged if their pipeline did not succeed -or if there are threads to be resolved. This works for both: +You can prevent merge requests from being merged if: + +- No pipeline ran. +- The pipeline did not succeed. + +This works for both: - GitLab CI/CD pipelines - Pipelines run from an [external CI integration](../integrations/overview.md#integrations-listing) @@ -58,6 +62,7 @@ CI providers with this feature. To enable it, you must: 1. Press **Save** for the changes to take effect. This setting also prevents merge requests from being merged if there is no pipeline. +You should be careful to configure CI/CD so that pipelines run for every merge request. ### Limitations diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md index 99e70f35d6d..a53b5032e1d 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -5,18 +5,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Merge request conflict resolution +# Merge request conflict resolution **(FREE)** Merge conflicts occur when two branches have different changes that cannot be merged automatically. -Git is able to automatically merge changes between branches in most cases, but -there are situations where Git will require your assistance to resolve the +Git can merge changes between branches in most cases, but +occasionally Git requires your assistance to resolve the conflicts manually. Typically, this is necessary when people change the same parts of the same files. -GitLab will prevent merge requests from being merged until all conflicts are -resolved. Conflicts can be resolved locally, or in many cases within GitLab +GitLab prevents merge requests from being merged until all conflicts are +resolved. Conflicts can be resolved locally, or in many cases in GitLab (see [conflicts available for resolution](#conflicts-available-for-resolution) for information on when this is available). @@ -24,35 +24,30 @@ for information on when this is available). NOTE: GitLab resolves conflicts by creating a merge commit in the source branch that -is not automatically merged into the target branch. This allows the merge -commit to be reviewed and tested before the changes are merged, preventing +is not automatically merged into the target branch. The merge +commit can be reviewed and tested before the changes are merged. This prevents unintended changes entering the target branch without review or breaking the build. ## Resolve conflicts: interactive mode -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5479) in GitLab 8.11. - -Clicking this will show a list of files with conflicts, with conflict sections +Clicking **Resolve Conflicts** displays a list of files with conflicts, with conflict sections highlighted:  -Once all conflicts have been marked as using 'ours' or 'theirs', the conflict -can be resolved. This will perform a merge of the target branch of the merge -request into the source branch, resolving the conflicts using the options +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. ## Resolve conflicts: inline editor -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6374) in GitLab 8.13. - -The merge conflict resolution editor allows for more complex merge conflicts, -which require the user to manually modify a file in order to resolve a conflict, -to be solved right form the GitLab interface. Use the **Edit inline** button -to open the editor. Once you're sure about your changes, hit the -**Commit to source branch** button. +Some merge conflicts are more complex, requiring you to manually modify a file to +resolve them. Use the merge conflict resolution editor to resolve complex +conflicts in the GitLab interface. Click **Edit inline** to open the editor. +After you're sure about your changes, click **Commit to source branch**.  @@ -66,13 +61,16 @@ GitLab allows resolving conflicts in a file where all of the below are true: - The file, with conflict markers added, is not over 200 KB in size - The file exists under the same path in both branches -If any file with conflicts in that merge request does not meet all of these -criteria, the conflicts for that merge request cannot be resolved in the UI. +If any file in your merge request containing conflicts can't meet all of these +criteria, you can't resolve the merge conflict in the UI. Additionally, GitLab does not detect conflicts in renames away from a path. For -example, this will not create a conflict: on branch `a`, doing `git mv file1 -file2`; on branch `b`, doing `git mv file1 file3`. Instead, both files will be -present in the branch after the merge request is merged. +example, this does not create a conflict: + +1. On branch `a`, doing `git mv file1 file2` +1. On branch `b`, doing `git mv file1 file3`. + +Instead, both files are present in the branch after the merge request is merged. <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 40a4631694b..d5d0578c07c 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Reverting changes +# Reverting changes **(FREE)** You can use Git's powerful feature to [revert any commit](https://git-scm.com/docs/git-revert "Git revert documentation") by clicking the **Revert** button in merge requests and commit details. 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 e2d6ba9ea1c..94f48fa544f 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 @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Reviewing and managing merge requests **(CORE)** +# Reviewing and managing merge requests **(FREE)** Merge requests are the primary method of making changes to files in a GitLab project. Changes are proposed by [creating and submitting a merge request](creating_merge_requests.md), @@ -13,10 +13,10 @@ which is then reviewed, and accepted (or rejected). ## View project merge requests -View all the merge requests within a project by navigating to **Project > Merge Requests**. +View all the merge requests in a project by navigating to **Project > Merge Requests**. -When you access your project's merge requests, GitLab will present them in a list, -and you can use the tabs available to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists). +When you access your project's merge requests, GitLab displays them in a list. +Use the tabs to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists).  @@ -32,7 +32,7 @@ You can [search and filter the results](../../search/index.md#filtering-issue-an A merge commit is created for every merge, but the branch is only merged if a fast-forward merge is possible. This ensures that if the merge request build -succeeded, the target branch build will also succeed after merging. +succeeded, the target branch build also succeeds after the merge. Navigate to a project's settings, select the **Merge commit with semi-linear history** option under **Merge Requests: Merge method** and save your changes. @@ -80,21 +80,23 @@ Click **Expand file** on any file to view the changes for that file. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229848) in GitLab 13.7. -For larger merge requests it might sometimes be useful to review single files at a time. To enable, -from your avatar on the top-right navigation bar, click **Settings**, and go to **Preferences** on the left -sidebar. Scroll down to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**. -Click **Save changes** to apply. +For larger merge requests, consider reviewing one file at a time. To enable this feature: -From there, when reviewing merge requests' **Changes** tab, you will see only one file at a time. You can then click the buttons **Prev** and **Next** to view the other files changed. +1. In the top-right corner, select your avatar. +1. Select **Preferences**. +1. Scroll to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**. +1. Select **Save changes**. + +After you enable this setting, GitLab displays only one file at a time in the **Changes** tab when you review merge requests. You can click **Prev** and **Next** to view other changed files.  -From [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) onwards, if you want to change +In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) and later, if you want to change this behavior, you can do so from your **User preferences** (as explained above) or directly in a merge request: 1. Go to the merge request's **Changes** tab. -1. Click the cog icon (**{settings}**) to reveal the merge request's settings dropdown. +1. Select the cog icon (**{settings}**) to reveal the merge request's settings dropdown. 1. Select or deselect the checkbox **Show one file at a time** to change the setting accordingly. This change overrides the choice you made in your user preferences and persists until you clear your @@ -104,10 +106,14 @@ browser's cookies or change this behavior again. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. -To seamlessly navigate among commits in a merge request, from the **Commits** tab, click one of -the commits to open the single-commit view. From there, you can navigate among the commits -by clicking the **Prev** and **Next** buttons on the top-right of the page or by using the -<kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. +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 on the top-right of the page. + - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts.  @@ -120,7 +126,7 @@ to expand the entire file.  -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205401) in GitLab 13.1, when viewing a +In GitLab [versions 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/205401), when viewing a merge request's **Changes** tab, if a certain file was only renamed, you can expand it to see the entire content by clicking **Show file contents**. @@ -136,24 +142,60 @@ NOTE: You can append `?w=1` while on the diffs page of a merge request to ignore any whitespace changes. +## Mark files as viewed + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9. +> - It's deployed behind a feature flag, enabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-file-views). **(FREE SELF)** + +When reviewing a merge request with many files multiple times, it may be useful to the reviewer +to focus on new changes and ignore the files that they have already reviewed and don't want to +see anymore unless they are changed again. + +To mark a file as viewed: + +1. Go to the merge request's **Diffs** tab. +1. On the right-top of the file, locate the **Viewed** checkbox. +1. Check it to mark the file as viewed. + +Once checked, the file remains marked for that reviewer unless there are newly introduced +changes to its content or the checkbox is unchecked. + +### Enable or disable file views **(FREE SELF)** + +The file view feature is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to enable it for your instance. + +To enable it: + +```ruby +Feature.enable(:local_file_reviews) +``` + +To disable it: + +```ruby +Feature.disable(:local_file_reviews) +``` + ## Perform inline code reviews > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13950) in GitLab 11.5. -GitLab provides a way of leaving comments in any part of the file being changed -in a Merge Request. To do so, click the **{comment}** **comment** icon in the gutter of the Merge Request diff UI to expand the diff lines and leave a comment, just as you would for a changed line. +In a merge request, you can leave comments in any part of the file being changed. +In the Merge Request Diff UI, click the **{comment}** **comment** icon in the gutter +to expand the diff lines and leave a comment, just as you would for a changed line.  ### Commenting on multiple lines > - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. -> - It's deployed behind a feature flag, enabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/221268) on GitLab 13.3. -> - It's enabled on GitLab.com. -> - It can be disabled or enabled per-project. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-multiline-comments). **(CORE ONLY)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299121) in GitLab 13.9. GitLab provides a way to select which lines of code a comment refers to. After starting a comment a dropdown selector is shown to select the first line that this comment refers to. @@ -169,53 +211,33 @@ above it.  -### Enable or disable multiline comments **(CORE ONLY)** - -The multiline comments feature is under development but 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 opt to enable it for your instance. - -To disable it: - -```ruby -Feature.disable(:multiline_comments) -``` - -To enable it: - -```ruby -Feature.enable(:multiline_comments) -``` - ## Pipeline status in merge requests widgets If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, -you will be able to see: +you can see: - Both pre-merge and post-merge pipelines and the environment information if any. - Which deployments are in progress. -If there's an [environment](../../../ci/environments/index.md) and the application is -successfully deployed to it, the deployed environment and the link to the -Review App will be shown as well. +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 default branch (for example, `main`) is red due to a failed CI pipeline, the `merge` button -When the pipeline fails in a merge request but it can be merged nonetheless, -the **Merge** button will be colored in red. +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 master branch and then triggers a deployment to the staging +is merged into the `master` branch and then triggers a deployment to the staging environment. -Deployments that are ongoing will be shown, as well as the deploying/deployed state +Ongoing deployments are shown, and the state (deploying or deployed) for environments. If it's the first time the branch is deployed, the link -will return a `404` error until done. During the deployment, the stop button will -be disabled. If the pipeline fails to deploy, the deployment information will be hidden. +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.  @@ -223,14 +245,15 @@ 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). +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 -in a per-branch basis. No need to checkout the branch, install and preview locally; -all your changes will be available to preview by anyone with the Review Apps link. +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 @@ -240,21 +263,26 @@ faster to preview proposed modifications. ## Associated features -There is also a large number of features to associated to merge requests: - -| Feature | Description | -|-------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| -| [Bulk editing merge requests](../../project/bulk_editing.md) | Update the attributes of multiple merge requests simultaneously. | -| [Cherry-pick changes](cherry_pick_changes.md) | Cherry-pick any commit in the UI by simply clicking the **Cherry-pick** button in a merged merge requests or a commit. | -| [Fast-forward merge requests](fast_forward_merge.md) | For a linear Git history and a way to accept merge requests without creating merge commits | -| [Find the merge request that introduced a change](versions.md) | When viewing the commit details page, GitLab will link to the merge request(s) containing that commit. | -| [Merge requests versions](versions.md) | Select and compare the different versions of merge request diffs | -| [Resolve conflicts](resolve_conflicts.md) | GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. | -| [Revert changes](revert_changes.md) | Revert changes from any commit from within a merge request. | +These features are associated with merge requests: + +- [Bulk editing merge requests](../../project/bulk_editing.md): + Update the attributes of multiple merge requests simultaneously. +- [Cherry-pick changes](cherry_pick_changes.md): + Cherry-pick any commit in the UI by clicking the **Cherry-pick** button in a merged merge requests or a commit. +- [Fast-forward merge requests](fast_forward_merge.md): + For a linear Git history and a way to accept merge requests without creating merge commits +- [Find the merge request that introduced a change](versions.md): + When viewing the commit details page, GitLab links to the merge request(s) containing that commit. +- [Merge requests versions](versions.md): + Select and compare the different versions of merge request diffs +- [Resolve conflicts](resolve_conflicts.md): + GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. +- [Revert changes](revert_changes.md): + Revert changes from any commit from a merge request. ## Troubleshooting -Sometimes things don't go as expected in a merge request, here are some +Sometimes things don't go as expected in a merge request. Here are some troubleshooting steps. ### Merge request cannot retrieve the pipeline status @@ -264,7 +292,7 @@ This can occur if Sidekiq doesn't pick up the changes fast enough. #### Sidekiq Sidekiq didn't process the CI state change fast enough. Please wait a few -seconds and the status will update automatically. +seconds and the status should update automatically. #### Bug @@ -280,12 +308,9 @@ Merge Request again. ## Tips -Here are some tips that will help you be more efficient with merge requests in +Here are some tips to help you be more efficient with merge requests in the command line. -NOTE: -This section might move in its own document in the future. - ### Copy the branch name for local checkout > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23767) in GitLab 13.4. @@ -294,7 +319,7 @@ The merge request sidebar contains the branch reference for the source branch used to contribute changes for this merge request. To copy the branch reference into your clipboard, click the **Copy branch name** button -(**{copy-to-clipboard}**) in the right sidebar. You can then use it to checkout the branch locally +(**{copy-to-clipboard}**) in the right sidebar. Use it to checkout the branch locally via command line by running `git checkout <branch-name>`. ### Checkout merge requests locally through the `head` ref @@ -303,7 +328,7 @@ A merge request contains all the history from a repository, plus the additional commits added to the branch associated with the merge request. Here's a few ways to checkout a merge request locally. -Please note that you can checkout a merge request locally even if the source +You can checkout a merge request locally even if the source project is a fork (even a private fork) of the target project. This relies on the merge request `head` ref (`refs/merge-requests/:iid/head`) @@ -312,10 +337,10 @@ request via its ID instead of its branch. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223156) in GitLab 13.4, 14 days after a merge request gets closed or merged, the merge request -`head` ref will be deleted. This means that the merge request will not be available +`head` ref is deleted. This means that the merge request is not available for local checkout via the merge request `head` ref anymore. The merge request -can still be re-opened. Also, as long as the merge request's branch -exists, you can still check out the branch as it won't be affected. +can still be re-opened. If the merge request's branch +exists, you can still check out the branch, as it isn't affected. #### Checkout locally by adding a Git alias @@ -334,7 +359,7 @@ from the `origin` remote, do: git mr origin 5 ``` -This will fetch the merge request into a local `mr-origin-5` branch and check +This fetches the merge request into a local `mr-origin-5` branch and check it out. #### Checkout locally by modifying `.git/config` for a given repository diff --git a/doc/user/project/merge_requests/sast.md b/doc/user/project/merge_requests/sast.md deleted file mode 100644 index 11f85749fb7..00000000000 --- a/doc/user/project/merge_requests/sast.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../application_security/sast/index.md' ---- - -This document was moved to [another location](../../application_security/sast/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/sast_docker.md b/doc/user/project/merge_requests/sast_docker.md deleted file mode 100644 index 5d61f2b36e8..00000000000 --- a/doc/user/project/merge_requests/sast_docker.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../application_security/container_scanning/index.md' ---- - -This document was moved to [another location](../../application_security/container_scanning/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 93b85ce8669..1b99b1b5c44 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -5,10 +5,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Squash and merge +# Squash and merge **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1024) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.17. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) from [GitLab Starter](https://about.gitlab.com/pricing/)to GitLab Core in 11.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) from [GitLab Starter](https://about.gitlab.com/pricing/)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. @@ -110,7 +110,6 @@ squashing can itself be considered equivalent to rebasing. > - It's enabled on GitLab.com. > - It can be enabled per project. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-squash-commit-options). **(CORE ONLY)** With Squash Commits Options you can configure the behavior of Squash and Merge for your project. To set it up, navigate to your project's **Settings > General** and expand **Merge requests**. @@ -133,31 +132,6 @@ NOTE: If your project is set to **Do not allow** Squash and Merge, the users still have the option to squash commits locally through the command line and force-push to their remote branch before merging. -### Enable or disable Squash Commit Options **(CORE ONLY)** - -Squash Commit Options 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 -# Instance-wide -Feature.enable(:squash_options) -# or by project -Feature.enable(:squash_options, Project.find(<project ID>)) -``` - -To disable it: - -```ruby -# Instance-wide -Feature.disable(:squash_options) -# or by project -Feature.disable(:squash_options, Project.find(<project ID>)) -``` - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 3960f916f9b..e60f2f712d3 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -52,7 +52,52 @@ Hovering over the coverage bar will provide further information, such as the num of times the line was checked by tests. NOTE: -The Cobertura XML parser currently does not support the `sources` element and ignores it. It is assumed that +A limit of 100 `<source>` nodes for Cobertura format XML files applies. If your Cobertura report exceeds +100 nodes, there can be mismatches or no matches in the Merge Request diff view. + +### Automatic class path correction + +> - [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. + +To make an intelligent guess on the project root relative `class` path, the Cobertura XML parser will attempt to build the +full path by doing following: + +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. + +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: + +```shell +Auth/User.cs +Lib/Utils/User.cs +``` + +And the `sources` from Cobertura XML with paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`: + +```xml +<sources> + <source>/builds/test-org/test-project/Auth</source> + <source>/builds/test-org/test-project/Lib/Utils</source> +</sources> +``` + +The parser will extract `Auth` and `Lib/Utils` from the sources and use these as basis to determine the class path relative to +the project root, combining these extracted sources and the class filename. + +If for example there is a `class` element with the `filename` value of `User.cs`, the parser will take the first candidate path +that matches which is `Auth/User.cs`. + +For each `class` element, the parser will attempt to look for a match for each extracted `source` path up to `100` iterations. If it reaches this limit without finding a matching path in the file tree, the class will not be included in the final coverage report. + +NOTE: +The automatic class path correction only works on `source` paths in the format of `<CI_BUILDS_DIR>/<PROJECT_FULL_PATH>/...`. If `source` will be ignored if the path does not follow this pattern. The parser will assume that the `filename` of a `class` element contains the full path relative to the project root. ## Example test coverage configurations diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 4ad960413ef..8f3ce9186f1 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -64,9 +64,10 @@ 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 the future it will -[replace](https://gitlab.com/gitlab-org/gitlab/-/issues/198458) the -current default comparison. +by selecting **master (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/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md index 7417320eea0..43ab03114fa 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 @@ -5,12 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, concepts --- -# Draft merge requests **(CORE)** +# Draft merge requests **(FREE)** If a merge request is not yet ready to be merged, perhaps due to continued development or open threads, you can prevent it from being accepted before it's ready by flagging -it as a **Draft**. This will disable the "Merge" button, preventing it from -being merged, and it will stay disabled until the "Draft" flag has been removed. +it as a **Draft**. This disables the **Merge** button, preventing it from +being merged. It stays disabled until the **Draft** flag has been removed.  @@ -22,7 +22,7 @@ To run pipelines for merged results, you must [remove the draft status](#removin ## Adding the "Draft" flag to a merge request -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. Support for using **WIP** will be removed in GitLab 14.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. Support for using **WIP** is scheduled for removal in GitLab 14.0. > - **Mark as draft** and **Mark as ready** buttons [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227421) in GitLab 13.5. There are several ways to flag a merge request as a Draft: @@ -30,15 +30,15 @@ There are several ways to flag a merge request as a Draft: - Click the **Mark as draft** button on the top-right corner of the merge request's page. - Add `[Draft]`, `Draft:` or `(Draft)` to the start of the merge request's title. Clicking on **Start the title with Draft:**, under the title box, when editing the merge request's - description will have the same effect. + description has the same effect. - **Deprecated** Add `[WIP]` or `WIP:` to the start of the merge request's title. - **WIP** still works but was deprecated in favor of **Draft**. It will be removed in the next major version (GitLab 14.0). + **WIP** still works but was deprecated in favor of **Draft**. It is scheduled for removal in the next major version (GitLab 14.0). - Add the `/draft` (or `/wip`) [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) in a comment in the merge request. This is a toggle, and can be repeated - to change the status back. Note that any other text in the comment will be discarded. + to change the status back. Note that any other text in the comment is discarded. - Add `draft:`, `Draft:`, `fixup!`, or `Fixup!` to the beginning of a commit message targeting the merge request's source branch. This is not a toggle, and doing it again in another - commit will have no effect. + commit has no effect. ## Removing the "Draft" flag from a merge request @@ -48,10 +48,10 @@ Similar to above, when a Merge Request is ready to be merged, you can remove the - Click the **Mark as ready** button on the top-right corner of the merge request's page. - Remove `[Draft]`, `Draft:` or `(Draft)` from the start of the merge request's title. Clicking on **Remove the Draft: prefix from the title**, under the title box, when editing the merge - request's description, will have the same effect. + request's description, has the same effect. - Add the `/draft` (or `/wip`) [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) in a comment in the merge request. This is a toggle, and can be repeated - to change the status back. Note that any other text in the comment will be discarded. + to change the status back. Note that any other text in the comment is discarded. - Click on the **Resolve Draft status** button near the bottom of the merge request description, next to the **Merge** button (see [image above](#draft-merge-requests)). Must have at least Developer level permissions on the project for the button to @@ -60,8 +60,8 @@ Similar to above, when a Merge Request is ready to be merged, you can remove the ## Including/excluding WIP merge requests when searching When viewing/searching the merge requests list, you can choose to include or exclude -WIP merge requests by adding a "WIP" filter in the search box, and choosing "Yes" -(to include) or "No" (to exclude). +WIP merge requests. Add a **WIP** filter in the search box, and choose **Yes** +to include, or **No** to exclude.  diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index 3e266d054be..7c22b271ec2 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -5,18 +5,17 @@ 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 --- -# Burndown and burnup charts **(STARTER)** +# Burndown and burnup charts **(PREMIUM)** [Burndown](#burndown-charts) and [burnup](#burnup-charts) charts show the progress of completing a milestone.  -## Burndown charts +## Burndown charts **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1540) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.1 for project milestones. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5354) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.8 for group milestones. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6495) to [GitLab Starter](https://about.gitlab.com/pricing/) 11.2 for group milestones. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) [fixed burndown charts](#fixed-burndown-charts) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6495) to GitLab 11.2 for group milestones. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) [fixed burndown charts](#fixed-burndown-charts) in GitLab 13.6. +> - Moved to GitLab Premium in 13.9. Burndown charts show the number of issues over the course of a milestone. @@ -101,10 +100,11 @@ Therefore, when the milestone start date is changed, the number of opened issues change. Reopened issues are considered as having been opened on the day after they were last closed. -## Burnup charts +## Burnup charts **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268350) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) in GitLab 13.6. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268350) in GitLab 13.7. +> - Moved to GitLab Premium in 13.9. Burnup charts show the assigned and completed work for a milestone. diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index acf32bb0f92..fe34dca4959 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -5,7 +5,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Milestones **(CORE)** +# Milestones **(FREE)** Milestones in GitLab are a way to track issues and merge requests created to achieve a broader goal in a certain period of time. @@ -123,10 +123,16 @@ From the project and group issue/merge request list pages, you can [filter](../. ### Filtering in issue boards -- From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [search and filter bar](../../search/index.md#issue-boards). -- From [group issue boards](../issue_board.md#group-issue-boards), you can filter by only group milestones in the [search and filter bar](../../search/index.md#issue-boards). **(PREMIUM)** -- From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards). **(STARTER)** -- From [group issue boards](../issue_board.md#group-issue-boards) you can filter by only group milestones in the [issue board configuration](../issue_board.md#configurable-issue-boards). **(STARTER)** +From [project issue boards](../issue_board.md), you can filter by both group milestones and project +milestones in: + +- [Search and filter bar](../../search/index.md#issue-boards) +- [Issue board configuration](../issue_board.md#configurable-issue-boards) + +From [group issue boards](../issue_board.md#group-issue-boards), you can filter by only group milestones in: + +- [Search and filter bar](../../search/index.md#issue-boards) +- [Issue board configuration](../issue_board.md#configurable-issue-boards) ### Special milestone filters @@ -155,15 +161,17 @@ There are also tabs below these that show the following: - **Participants**: Shows all assignees of issues assigned to the milestone. - **Labels**: Shows all labels that are used in issues assigned to the milestone. -### Project Burndown Charts **(STARTER)** +### Project Burndown Charts -For project milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, showing the progress of completing a milestone. +For project milestones, a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, +showing the progress of completing a milestone.  -### Group Burndown Charts **(STARTER)** +### Group Burndown Charts -For group milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, showing the progress of completing a milestone. +For group milestones, a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, +showing the progress of completing a milestone. ### Milestone sidebar diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index 4910751ece1..585d97c74c2 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -195,7 +195,7 @@ As a user: ### Dependent repositories -The [Job environment variable](../../ci/variables/README.md#predefined-environment-variables) `CI_JOB_TOKEN` can be used to +The [CI/CD variable](../../ci/variables/README.md#predefined-cicd-variables) `CI_JOB_TOKEN` can be used to authenticate any clones of dependent repositories. For example: ```shell diff --git a/doc/user/project/operations/alert_management.md b/doc/user/project/operations/alert_management.md deleted file mode 100644 index e60e7d93d12..00000000000 --- a/doc/user/project/operations/alert_management.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/incident_management/index.md' ---- - -This document was moved to [another location](../../../operations/incident_management/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/dashboard_settings.md b/doc/user/project/operations/dashboard_settings.md deleted file mode 100644 index ef106181acc..00000000000 --- a/doc/user/project/operations/dashboard_settings.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/metrics/dashboards/settings.md' ---- - -This document was moved to [another location](../../../operations/metrics/dashboards/settings.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/error_tracking.md b/doc/user/project/operations/error_tracking.md deleted file mode 100644 index 399ab0d53dc..00000000000 --- a/doc/user/project/operations/error_tracking.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/error_tracking.md' ---- - -This document was moved to [another location](../../../operations/error_tracking.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md deleted file mode 100644 index 03f2cad6d78..00000000000 --- a/doc/user/project/operations/feature_flags.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/feature_flags.md' ---- - -This document was moved to [another location](../../../operations/feature_flags.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/index.md b/doc/user/project/operations/index.md deleted file mode 100644 index d19cf393883..00000000000 --- a/doc/user/project/operations/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/index.md' ---- - -This document was moved to [another location](../../../operations/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/linking_to_an_external_dashboard.md b/doc/user/project/operations/linking_to_an_external_dashboard.md deleted file mode 100644 index ef106181acc..00000000000 --- a/doc/user/project/operations/linking_to_an_external_dashboard.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/metrics/dashboards/settings.md' ---- - -This document was moved to [another location](../../../operations/metrics/dashboards/settings.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/operations/tracing.md b/doc/user/project/operations/tracing.md deleted file mode 100644 index dcf9894f9e1..00000000000 --- a/doc/user/project/operations/tracing.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/tracing.md' ---- - -This document was moved to [another location](../../../operations/tracing.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/maven.md b/doc/user/project/packages/maven.md deleted file mode 100644 index 13b5d69586a..00000000000 --- a/doc/user/project/packages/maven.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../packages/maven_repository/index.md' ---- - -This document was moved to [another location](../../packages/maven_repository/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/maven_packages.md b/doc/user/project/packages/maven_packages.md deleted file mode 100644 index 13b5d69586a..00000000000 --- a/doc/user/project/packages/maven_packages.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../packages/maven_repository/index.md' ---- - -This document was moved to [another location](../../packages/maven_repository/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/maven_repository.md b/doc/user/project/packages/maven_repository.md deleted file mode 100644 index 13b5d69586a..00000000000 --- a/doc/user/project/packages/maven_repository.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../packages/maven_repository/index.md' ---- - -This document was moved to [another location](../../packages/maven_repository/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/packages/npm_registry.md b/doc/user/project/packages/npm_registry.md deleted file mode 100644 index f874b05e7e2..00000000000 --- a/doc/user/project/packages/npm_registry.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../packages/npm_registry/index.md' ---- - -This document was moved to [another location](../../packages/npm_registry/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> 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 aa06a15a8c0..86e34842aaf 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 @@ -19,7 +19,7 @@ GitLab does it for you, out-of-the-box. open source Certificate Authority. WARNING: -This feature covers only certificates for **custom domains**, not the wildcard certificate required to run [Pages daemon](../../../../administration/pages/index.md) **(CORE ONLY)**. Wildcard certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3342). +This feature covers only certificates for **custom domains**, not the wildcard certificate required to run [Pages daemon](../../../../administration/pages/index.md) **(FREE SELF)**. Wildcard certificate generation is tracked in [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3342). ## Requirements @@ -28,7 +28,8 @@ Before you can enable automatic provisioning of an SSL certificate for your doma - Created a [project](../index.md#getting-started) in GitLab containing your website's source code. - Acquired a domain (`example.com`) and added a [DNS entry](index.md) - pointing it to your Pages website. + pointing it to your Pages website. The top-level domain (`.com`) must be a + [public suffix](https://publicsuffix.org/). - [Added your domain to your Pages project](index.md#1-add-a-custom-domain-to-pages) and verified your ownership. - Verified your website is up and running, accessible through your custom 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 e8c6305dbab..d9f57253396 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 @@ -32,7 +32,9 @@ nor credit card transactions, then why do we need secure connections? Back in the 1990s, where HTTPS came out, [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0.2C_2.0_and_3.0) was considered a "special" security measure, necessary just for big companies like banks and shopping sites with financial transactions. +<!-- vale gitlab.Spelling = NO --> Now we have a different picture. [According to Josh Aas](https://letsencrypt.org/2015/10/29/phishing-and-malware.html), Executive Director at [ISRG](https://en.wikipedia.org/wiki/Internet_Security_Research_Group): +<!-- vale gitlab.rulename = YES --> > _We’ve since come to realize that HTTPS is important for almost all websites. It’s important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn’t want its content altered](https://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We’ve also learned that any site not secured by HTTPS [can be used to attack other sites](https://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._ diff --git a/doc/user/project/pages/getting_started/fork_sample_project.md b/doc/user/project/pages/getting_started/fork_sample_project.md deleted file mode 100644 index 2cf118c9066..00000000000 --- a/doc/user/project/pages/getting_started/fork_sample_project.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'pages_forked_sample_project.md' ---- - -This document was moved to [pages_forked_sample_project.md](pages_forked_sample_project.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started/new_or_existing_website.md b/doc/user/project/pages/getting_started/new_or_existing_website.md deleted file mode 100644 index 2fc833fbd34..00000000000 --- a/doc/user/project/pages/getting_started/new_or_existing_website.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'pages_ci_cd_template.md' ---- - -This document was moved to [another location](pages_ci_cd_template.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started/pages_bundled_template.md b/doc/user/project/pages/getting_started/pages_bundled_template.md deleted file mode 100644 index 0dab1f6ee19..00000000000 --- a/doc/user/project/pages/getting_started/pages_bundled_template.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'pages_new_project_template.md' ---- - -This document was moved to [pages_new_project_template.md](pages_new_project_template.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> 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 c7916b7c01e..d9ec2aae2b7 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 @@ -18,7 +18,7 @@ configured to generate a Pages site. To fork a sample project and create a Pages website: 1. View the sample projects by navigating to the [GitLab Pages examples](https://gitlab.com/pages) group. -1. Click the name of the project you want to [fork](../../../../gitlab-basics/fork-project.md). +1. Click the name of the project you want to [fork](../../../../user/project/working_with_projects.md#fork-a-project). 1. In the top right, click the **Fork** button, and then choose a namespace to fork to. 1. Go to your project's **CI/CD > Pipelines** and click **Run pipeline**. GitLab CI/CD builds and deploys your site. @@ -52,5 +52,5 @@ You can take some **optional** further steps:  - - Now go to your SSG's configuration file and change the [base URL](../getting_started_part_one.md#urls-and-baseurls) + - Now go to your SSG's configuration file and change the [base URL](../getting_started_part_one.md#urls-and-base-urls) from `"project-name"` to `""`. The project name setting varies by SSG and may not be in the configuration file. diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md deleted file mode 100644 index 361323a9073..00000000000 --- a/doc/user/project/pages/getting_started_part_four.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'getting_started/pages_from_scratch.md' ---- - -This document was moved to [getting_started/pages_from_scratch.md](getting_started/pages_from_scratch.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 801fe0c7ef0..dee021b8225 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 baseurls +# GitLab Pages domain names, URLs, and base URLs On this document, learn how to name your project for GitLab Pages according to your intended website's URL. @@ -78,7 +78,7 @@ To understand Pages domains clearly, read the examples below. - On your GitLab instance, replace `gitlab.io` above with your Pages server domain. Ask your sysadmin for this information. -## URLs and baseurls +## URLs and base URLs NOTE: The `baseurl` option might be called named differently in some static site generators. diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md deleted file mode 100644 index 9d7f401ca91..00000000000 --- a/doc/user/project/pages/getting_started_part_three.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'custom_domains_ssl_tls_certification/index.md' ---- - -This document was moved to [another location](custom_domains_ssl_tls_certification/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md deleted file mode 100644 index 4b2b186ca28..00000000000 --- a/doc/user/project/pages/getting_started_part_two.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'index.md' ---- - -This document was moved to [another location](index.md#getting-started). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index c9e28bf15c2..6eb06972945 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -103,7 +103,7 @@ optionally secure it with SSL/TLS certificates. If you're using GitLab.com, your website is publicly available to the internet. To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md). -If you're using a self-managed instance (Core, Starter, Premium, or Ultimate), +If you're using a self-managed instance (Free, Premium, or Ultimate), your websites are published on your own server, according to the [Pages settings](../../../administration/pages/index.md) chosen by your sysadmin, who can make them public or internal. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 8380f367212..fbc86abbe66 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -63,7 +63,7 @@ If the case of `404.html`, there are different scenarios. For example: You can configure redirects for your site using a `_redirects` file. To learn more, read the [redirects documentation](redirects.md). -## GitLab Pages Access Control **(CORE)** +## GitLab Pages Access Control **(FREE)** To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md). diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index a2a17a4f2ca..2e0fc87b3df 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -38,7 +38,9 @@ For a demonstration, see [Pages access controls](https://www.youtube.com/watch?v - **Only project members**: Only project members are able to browse the website. - **Everyone with access**: Everyone, both logged into and logged out of GitLab, is able to browse the website, no matter their project membership. -1. Click **Save changes**. +1. Click **Save changes**. Note that your changes may not take effect immediately. GitLab Pages uses + a caching mechanism for efficiency. Your changes may not take effect until that cache is + invalidated, which usually takes less than a minute. The next time someone tries to access your website and the access control is enabled, they're presented with a page to sign into GitLab and verify they diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md deleted file mode 100644 index cf5f33534cd..00000000000 --- a/doc/user/project/pipelines/job_artifacts.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../ci/pipelines/job_artifacts.md' ---- - -This document was moved to [another location](../../../ci/pipelines/job_artifacts.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pipelines/schedules.md b/doc/user/project/pipelines/schedules.md deleted file mode 100644 index 52352a29c5a..00000000000 --- a/doc/user/project/pipelines/schedules.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../ci/pipelines/schedules.md' ---- - -This document was moved to [another location](../../../ci/pipelines/schedules.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md deleted file mode 100644 index f19f28743a8..00000000000 --- a/doc/user/project/pipelines/settings.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../ci/pipelines/settings.md' ---- - -This document was moved to [another location](../../../ci/pipelines/settings.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 5754a3b7a9d..4629c87f41e 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Protected branches +# Protected branches **(FREE)** [Permissions](../permissions.md) in GitLab are fundamentally defined around the idea of having read or write permission to the repository and branches. To impose @@ -13,7 +13,7 @@ further restrictions on certain branches, they can be protected. ## Overview -By default, a protected branch does four simple things: +By default, a protected branch does these things: - It prevents its creation, if not already created, from everybody except users with Maintainer permission. @@ -21,66 +21,69 @@ By default, a protected branch does four simple things: - It prevents **anyone** from force pushing to the branch. - It prevents **anyone** from deleting the branch. -NOTE: -A GitLab administrator is allowed to push to the protected branches. +**Permissions:** -See the [Changelog](#changelog) section for changes over time. +- GitLab administrators are allowed to push to the protected branches. +- Users with [Developer permissions](../permissions.md) are allowed to + create a project in a group, but might not be allowed to initially + push to the [default branch](repository/branches/index.md#default-branch). The default branch protection level is set in the [Admin Area](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection). +See the [Changelog](#changelog) section for changes over time. + ## Configuring protected branches -To protect a branch, you need to have at least Maintainer permission level. Note -that the `master` branch is protected by default. +To protect a branch, you need to have at least Maintainer permission level. +The `master` branch is protected by default. -1. Navigate to your project's **Settings ➔ Repository** +1. In your project, go to **Settings > Repository**. 1. Scroll to find the **Protected branches** section. 1. From the **Branch** dropdown menu, select the branch you want to protect and click **Protect**. In the screenshot below, we chose the `develop` branch.  -1. Once done, the protected branch will appear in the "Protected branches" list. +1. Once done, the protected branch displays in the **Protected branches** list.  ## Using the Allowed to merge and Allowed to push settings -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081) in GitLab 8.11. - In GitLab 8.11 and later, we added another layer of branch protection which provides -more granular management of protected branches. The "Developers can push" -option was replaced by an "Allowed to push" setting which can be set to -allow/prohibit Maintainers and/or Developers to push to a protected branch. +more granular management of protected branches. The **Developers can push** +option was replaced by **Allowed to push**. You can set this value to allow +or prohibit Maintainers and/or Developers to push to a protected branch. -Using the "Allowed to push" and "Allowed to merge" settings, you can control +Using the **Allowed to push** and **Allowed to merge** settings, you can control the actions that different roles can perform with the protected branch. -For example, you could set "Allowed to push" to "No one", and "Allowed to merge" -to "Developers + Maintainers", to require _everyone_ to submit a merge request for +For example, you could set **Allowed to push** to "No one", and **Allowed to merge** +to "Developers + Maintainers", to require everyone to submit a merge request for changes going into the protected branch. This is compatible with workflows like the [GitLab workflow](../../topics/gitlab_flow.md). However, there are workflows where that is not needed, and only protecting from force pushes and branch removal is useful. For those workflows, you can allow everyone with write access to push to a protected branch by setting -"Allowed to push" to "Developers + Maintainers". +**Allowed to push** to "Developers + Maintainers". -You can set the "Allowed to push" and "Allowed to merge" options while creating +You can set the **Allowed to push** and **Allowed to merge** options while creating a protected branch or afterwards by selecting the option you want from the -dropdown list in the "Already protected" area. +dropdown list in the **Already protected** area.  If you don't choose any of those options while creating a protected branch, -they are set to "Maintainers" by default. +they are set to Maintainers by default. -### Allow Deploy Keys to push to a protected branch +### Allow deploy keys to push to a protected branch > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30769) in GitLab 13.7. > - This feature is being selectively deployed in GitLab.com 13.7, and may not be available for all users. +> - This feature is available for all users in GitLab 13.9. You can allow specific machines to access protected branches in your repository with -[Deploy Keys](deploy_keys/index.md). This can be useful for your CI/CD workflow, +[deploy keys](deploy_keys/index.md). This can be useful for your CI/CD workflow, for example. Deploy keys can be selected in the **Allowed to push** dropdown when: @@ -88,7 +91,7 @@ Deploy keys can be selected in the **Allowed to push** dropdown when: - Defining a protected branch. - Updating an existing branch. -Select a deploy key to allow the owner of the key to push to the chosen protected branch, +Select a deploy key to allow the key's owner to push to the chosen protected branch, even if they aren't a member of the related project. The owner of the selected deploy key must have at least read access to the given project. @@ -97,30 +100,26 @@ For a deploy key to be selectable: - It must be [enabled for your project](deploy_keys/index.md#how-to-enable-deploy-keys). - It must have [write access](deploy_keys/index.md#deploy-keys-permissions) to your project repository. -Deploy Keys are not available in the **Allowed to merge** dropdown. - - +Deploy keys are not available in the **Allowed to merge** dropdown. -## Restricting push and merge access to certain users **(STARTER)** + -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.11. +## Restricting push and merge access to certain users **(PREMIUM)** -With GitLab Enterprise Edition you can restrict access to protected branches -by choosing a role (Maintainers, Developers) as well as certain users. From the +With GitLab Premium you can restrict access to protected branches +by choosing a role (Maintainers, Developers) and certain users. From the dropdown menu select the role and/or the users you want to have merge or push access.  -Click **Protect** and the branch will appear in the "Protected branch" list. +Click **Protect** and the branch displays in the **Protected branch** list.  ## Wildcard protected branches -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4665) in GitLab 8.10. - -You can specify a wildcard protected branch, which will protect all branches +You can specify a wildcard protected branch, which protects all branches matching the wildcard. For example: | Wildcard Protected Branch | Matching Branches | @@ -129,15 +128,15 @@ matching the wildcard. For example: | `production/*` | `production/app-server`, `production/load-balancer` | | `*gitlab*` | `gitlab`, `gitlab/staging`, `master/gitlab/production` | -Protected branch settings (like "Developers can push") apply to all matching +Protected branch settings, like **Developers can push**, apply to all matching branches. Two different wildcards can potentially match the same branch. For example, `*-stable` and `production-*` would both match a `production-stable` branch. In that case, if _any_ of these protected branches have a setting like -"Allowed to push", then `production-stable` will also inherit this setting. +"Allowed to push", then `production-stable` also inherit this setting. -If you click on a protected branch's name, you will be presented with a list of +If you click on a protected branch's name, GitLab displays a list of all matching branches:  @@ -151,41 +150,36 @@ When a protected branch or wildcard protected branches are set to Developers (and users with higher [permission levels](../permissions.md)) are allowed to create a new protected branch as long as they are [**Allowed to merge**](#using-the-allowed-to-merge-and-allowed-to-push-settings). -This can only be done via the UI or through the API (to avoid creating protected -branches accidentally from the command line or from a Git client application). +This can only be done by using the UI or through the API, to avoid creating protected +branches accidentally from the command line or from a Git client application. To create a new branch through the user interface: -1. Visit **Repository > Branches**. +1. Go to **Repository > Branches**. 1. Click on **New branch**. -1. Fill in the branch name and select an existing branch, tag, or commit that - the new branch will be based off. Only existing protected branches and commits - that are already in protected branches will be accepted. +1. Fill in the branch name and select an existing branch, tag, or commit to + base the new branch on. Only existing protected branches and commits + that are already in protected branches are accepted. ## Deleting a protected branch -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21393) in GitLab 9.3. - -From time to time, it may be required to delete or clean up branches that are -protected. +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 +branches by using the GitLab web interface: -User with [Maintainer permissions](../permissions.md) and up can manually delete protected -branches via the GitLab web interface: - -1. Visit **Repository > Branches** -1. Click on the delete icon next to the branch you wish to delete -1. In order to prevent accidental deletion, an additional confirmation is - required +1. Go to **Repository > Branches**. +1. Click on the delete icon next to the branch you wish to delete. +1. To prevent accidental deletion, an additional confirmation is required.  -Deleting a protected branch is only allowed via the web interface, not via Git. +Deleting a protected branch is allowed only by using the web interface; not from Git. This means that you can't accidentally delete a protected branch from your command line or a Git client application. -## Protected Branches approval by Code Owners **(PREMIUM)** +## Protected branches approval by Code Owners **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in GitLab Premium 12.4. It is possible to require at least one approval by a [Code Owner](code_owners.md) to a file changed by the @@ -208,7 +202,7 @@ To enable Code Owner's approval to branches already protected:  -When enabled, all merge requests targeting these branches will require approval +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. @@ -224,26 +218,9 @@ for details about the pipelines security model. ## Changelog -**13.5** - -- [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769). - -**11.9** - -- [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) by Developers (and users with higher permission levels) through the API and the user interface. - -**9.2** - -- Allow deletion of protected branches via the web interface ([issue #21393](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21393)). - -**8.11** - -- Allow creating protected branches that can't be pushed to ([merge request !5081](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081)). - -**8.10** - -- Allow developers without push access to merge into a protected branch ([merge request !4892](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4892)). -- Allow specifying protected branches using wildcards ([merge request !4665](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4665)). +- **13.5**: [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769). +- **11.9**: [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) + by Developers (and users with higher permission levels) through the API and the user interface. <!-- ## Troubleshooting diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 7e09c526312..3ea0bb62c0b 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Protected tags +# Protected tags **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10356) in GitLab 9.1. @@ -15,11 +15,13 @@ This feature evolved out of [protected branches](protected_branches.md) ## Overview -Protected tags will prevent anyone from updating or deleting the tag, and will prevent creation of matching tags based on the permissions you have selected. By default, anyone without Maintainer permission will be prevented from creating tags. +Protected tags prevent anyone from updating or deleting the tag, and prevent +creation of matching tags based on the permissions you have selected. By default, +anyone without Maintainer [permissions](../permissions.md) is prevented from creating tags. ## Configuring protected tags -To protect a tag, you need to have at least Maintainer permission level. +To protect a tag, you need to have at least Maintainer [permissions](../permissions.md). 1. Navigate to the project's **Settings > Repository**: @@ -29,17 +31,18 @@ To protect a tag, you need to have at least Maintainer permission level.  -1. From the **Allowed to create** dropdown, select who will have permission to create matching tags and then click **Protect**: +1. From the **Allowed to create** dropdown, select users with permission to create + matching tags, and click **Protect**:  -1. Once done, the protected tag will appear in the **Protected tags** list: +1. After done, the protected tag displays in the **Protected tags** list:  ## Wildcard protected tags -You can specify a wildcard protected tag, which will protect all tags +You can specify a wildcard protected tag, which protects all tags matching the wildcard. For example: | Wildcard Protected Tag | Matching Tags | @@ -52,9 +55,9 @@ matching the wildcard. For example: Two different wildcards can potentially match the same tag. For example, `*-stable` and `production-*` would both match a `production-stable` tag. In that case, if _any_ of these protected tags have a setting like -**Allowed to create**, then `production-stable` will also inherit this setting. +**Allowed to create**, then `production-stable` also inherit this setting. -If you click on a protected tag's name, you will be presented with a list of +If you click on a protected tag's name, GitLab displays a list of all matching tags:  diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 8af4307c013..f94a4075363 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, howto --- -# Push Options +# Push Options **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) in GitLab 11.7. diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 64be3182dab..ac65fabd6a7 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -34,9 +34,9 @@ The following quick actions are applicable to descriptions, discussions and thre | `/assign @user` | ✓ | ✓ | | Assign one user. | | `/assign @user1 @user2` | ✓ | ✓ | | Assign multiple users. **(STARTER)** | | `/assign me` | ✓ | ✓ | | Assign yourself. | -| `/assign_reviewer @user` | | ✓ | | Assign one user as a reviewer. | -| `/assign_reviewer @user1 @user2` | | ✓ | | Assign multiple users as reviewers. **(STARTER)** | -| `/assign_reviewer me` | | ✓ | | Assign yourself as a reviewer. | +| `/assign_reviewer @user` or `/reviewer @user` or `/request_review @user` | | ✓ | | Assign one user as a reviewer. | +| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | | ✓ | | Assign multiple users as reviewers. **(STARTER)** | +| `/assign_reviewer me` or `/reviewer me` or `/request_review me` | | ✓ | | Assign yourself as a reviewer. | | `/award :emoji:` | ✓ | ✓ | ✓ | Toggle emoji award. | | `/child_epic <epic>` | | | ✓ | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). **(ULTIMATE)** | | `/clear_weight` | ✓ | | | Clear weight. **(STARTER)** | @@ -49,7 +49,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/done` | ✓ | ✓ | ✓ | Mark to do as done. | | `/draft` | | ✓ | | Toggle the draft status. | | `/due <date>` | ✓ | | | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | -| `/duplicate <#issue>` | ✓ | | | Close this issue and mark as a duplicate of another issue. **(CORE)** Also, mark both as related. **(STARTER)** | +| `/duplicate <#issue>` | ✓ | | | Close this issue and mark as a duplicate of another issue. **(FREE)** Also, mark both as related. **(STARTER)** | | `/epic <epic>` | ✓ | | | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. **(PREMIUM)** | | `/estimate <<W>w <DD>d <hh>h <mm>m>` | ✓ | ✓ | | Set time estimate. For example, `/estimate 1w 3d 2h 14m`. | | `/iteration *iteration:"iteration name"` | ✓ | | | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). **(STARTER)** | @@ -62,7 +62,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/promote` | ✓ | | | Promote issue to epic. **(PREMIUM)** | | `/publish` | ✓ | | | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906)) **(ULTIMATE)** | | `/reassign @user1 @user2` | ✓ | ✓ | | Replace current assignees with those specified. **(STARTER)** | -| `/rebase` | | ✓ | | Rebase source branch. This will schedule a background task that attempt to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` will be ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab will display a message that a rebase cannot be scheduled. Rebase failures will be displayed with the merge request status. | +| `/rebase` | | ✓ | | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | | `/reassign_reviewer @user1 @user2` | | ✓ | | Replace current reviewers with those specified. **(STARTER)** | | `/relabel ~label1 ~label2` | ✓ | ✓ | ✓ | Replace current labels with those specified. | | `/relate #issue1 #issue2` | ✓ | | | Mark issues as related. **(STARTER)** | @@ -87,8 +87,8 @@ The following quick actions are applicable to descriptions, discussions and thre | `/todo` | ✓ | ✓ | ✓ | Add a to-do item. | | `/unassign @user1 @user2` | ✓ | ✓ | | Remove specific assignees. **(STARTER)** | | `/unassign` | | ✓ | | Remove all assignees. | -| `/unassign_reviewer @user1 @user2` | | ✓ | | Remove specific reviewers. **(STARTER)** | -| `/unassign_reviewer` | | ✓ | | Remove all reviewers. | +| `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | | ✓ | | Remove specific reviewers. **(STARTER)** | +| `/unassign_reviewer` or `/remove_reviewer` | | ✓ | | Remove all reviewers. | | `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | ✓ | ✓ | ✓ | Remove specified labels. | | `/unlabel` or `/remove_label` | ✓ | ✓ | ✓ | Remove all labels. | | `/unlock` | ✓ | ✓ | | Unlock the discussions. | diff --git a/doc/user/project/releases.md b/doc/user/project/releases.md deleted file mode 100644 index 6dd5a6f0b0d..00000000000 --- a/doc/user/project/releases.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'releases/index.md' ---- - -This document was moved to [another location](releases/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 90d7ac0a3c2..b5751797870 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -407,7 +407,7 @@ Here is an example of a release evidence object: } ``` -### Collect release evidence **(PREMIUM ONLY)** +### Collect release evidence **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. @@ -475,6 +475,16 @@ terminal. Read the [Release CLI documentation](https://gitlab.com/gitlab-org/release-cli/-/blob/master/docs/index.md) for details. +## Release Metrics **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259703) in GitLab Premium 13.9. + +Group-level release metrics are available by navigating to **Group > Analytics > CI/CD**. +These metrics include: + +- Total number of releases in the group +- Percentage of projects in the group that have at least one release + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index ffd4b383bcb..4d0cf28593d 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: concepts, howto --- -# Branches +# Branches **(FREE)** A branch is a version of a project's working tree. You create a branch for each set of related changes you make. This keeps each set of changes separate from @@ -53,14 +53,14 @@ the target is the project's **default branch**. The default branch is also initially [protected](../../protected_branches.md#protected-branches) against accidental deletion and forced pushes. -### Custom initial branch name **(CORE ONLY)** +### Custom initial branch name **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221013) in GitLab 13.2. > - It's deployed behind a feature flag, enabled by default. > - It's enabled on GitLab.com. > - It cannot be enabled or disabled per-project. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-custom-initial-branch-name). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-custom-initial-branch-name). **(FREE SELF)** By default, when you create a new project in GitLab, the initial branch is called `master`. For self-managed instances, a GitLab administrator can customize the initial branch name to something @@ -71,7 +71,7 @@ else. This way, every new project created from then on will start from the custo 1. Change the default initial branch to a custom name of your choice. 1. **Save Changes**. -#### Enable or disable custom initial branch name **(CORE ONLY)** +#### Enable or disable custom initial branch name **(FREE SELF)** Setting the default initial branch name is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index 4f996df5fef..df3e24fbf30 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -17,8 +17,8 @@ project.  -For those who prefer to keep their fingers on the keyboard, there is a -[shortcut button](../../shortcuts.md) as well, which you can invoke from _anywhere_ +If you prefer to keep their fingers on the keyboard, use the +[shortcut button](../../shortcuts.md), which you can invoke from anywhere in a project. Press `t` to launch the File search function when in **Issues**, diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index f7da3629c23..1a5e169ec6b 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w disqus_identifier: 'https://docs.gitlab.com/ee/workflow/forking_workflow.html' --- -# Project forking workflow +# Project forking workflow **(FREE)** Whenever possible, it's recommended to work in a common Git repository and use [branching strategies](../../../topics/gitlab_flow.md) to manage your work. However, diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 4322c79daa7..81995291911 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -6,7 +6,7 @@ type: reference, howto description: "Documentation on Git file blame." --- -# Git file blame +# Git file blame **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/commit/39c657930625ddc3ac8a921f01ffc83acadce68f) in GitLab 2.5. diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index 51cc6bb3483..2e27cab4177 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -6,7 +6,7 @@ type: reference, howto description: "Documentation on Git file history." --- -# Git file history +# Git file history **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/blob/9ba1224867665844b117fa037e1465bb706b3685/app/controllers/commits_controller.rb) in GitLab 0.8.0 diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 57e9d814c95..1a46c140507 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: concepts, howto --- -# Signing commits with GPG +# Signing commits with GPG **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9546) in GitLab 9.5. > - Subkeys support was added in GitLab 10.1. @@ -138,27 +138,25 @@ started: gpg --armor --export 30F2B65B9246B6CA ``` -1. Finally, copy the public key and [add it in your profile settings](#adding-a-gpg-key-to-your-account) +1. Finally, copy the public key and [add it in your user settings](#adding-a-gpg-key-to-your-account) ## Adding a GPG key to your account NOTE: -Once you add a key, you cannot edit it, only remove it. In case the paste -didn't work, you'll have to remove the offending key and re-add it. +After you add a key, you cannot edit it, only remove it. In case the paste +didn't work, you have to remove the offending key and re-add it. -You can add a GPG key in your profile's settings: +You can add a GPG key in your user settings: -1. On the upper right corner, click on your avatar and go to your **Settings**. - -  - -1. Navigate to the **GPG keys** tab and paste your _public_ key in the 'Key' - box. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **GPG Keys**. +1. Paste your _public_ key in the **Key** text box.  -1. Finally, click on **Add key** to add it to GitLab. You will be able to see - its fingerprint, the corresponding email address and creation date. +1. Select **Add key** to add it to GitLab. You can see the key's fingerprint, the corresponding + email address, and creation date.  @@ -248,22 +246,24 @@ in case your key has been compromised. To revoke a GPG key: -1. On the upper right corner, click on your avatar and go to your **Settings**. -1. Navigate to the **GPG keys** tab. -1. Click on **Revoke** besides the GPG key you want to delete. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **GPG Keys**. +1. Select **Revoke** next to the GPG key you want to delete. ## Removing a GPG key Removing a key **does not unverify** already signed commits. Commits that were -verified by using this key will stay verified. Only unpushed commits will stay -unverified once you remove this key. To unverify already signed commits, you need +verified by using this key stay verified. Only unpushed commits stay +unverified after you remove this key. To unverify already signed commits, you need to [revoke the associated GPG key](#revoking-a-gpg-key) from your account. To remove a GPG key from your account: -1. On the upper right corner, click on your avatar and go to your **Settings**. -1. Navigate to the **GPG keys** tab. -1. Click on the trash icon besides the GPG key you want to delete. +1. In the top-right corner, select your avatar. +1. Select **Edit profile**. +1. In the left sidebar, select **GPG Keys**. +1. Select the trash icon (**{remove}**) next to the GPG key you want to delete. ## Rejecting commits that are not signed **(PREMIUM)** diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index c4f5d330f63..5a915ebef89 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Repository +# 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. @@ -14,7 +14,7 @@ A repository is part of a [project](../index.md), which has a lot of other featu ## Create a repository To create a new repository, all you need to do is -[create a new project](../../../gitlab-basics/create-project.md) or +[create a new project](../../../user/project/working_with_projects.md#create-a-project) or [fork an existing project](forking_workflow.md). Once you create a new project, you can add new files via UI @@ -43,7 +43,7 @@ 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). 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/README.md) +your code, add a file called [`.gitlab-ci.yml`](../../../ci/quick_start/index.md) to your repository's root. **From the user interface:** @@ -242,13 +242,32 @@ Learn how to [clone a repository through the command line](../../../gitlab-basic Alternatively, clone directly into a code editor as documented below. -### Clone to Apple Xcode +### 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 now be cloned -into Xcode using the new **Open in Xcode** button, located next to the Git URL -used for cloning your project. The button is only shown on macOS. +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 will be cloned onto your computer in a folder of your choice and you'll +be prompted to open in XCode. + +### Clone and open in Visual Studio Code + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220957) in GitLab 13.8. + +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** + +You'll be prompted to select a folder to clone the project into. When VS Code has +successfully cloned your project, it will open the folder. ## Download Source Code @@ -270,6 +289,28 @@ By clicking the download icon, a dropdown will open with links to download the f - **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. + +Depending on the situation, different things apply. + +When [renaming a user](../../profile/index.md#changing-your-username), +[changing a group path](../../group/index.md#changing-a-groups-path) or [renaming 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. +- The redirects are available as long as the original path is not claimed by + another group, user or project. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 91fe9049b53..123df9097f9 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -4,7 +4,7 @@ group: Source Code info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- -# Jupyter Notebook Files +# Jupyter Notebook Files **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2508/) in GitLab 9.1. diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index fb798738160..7847930366a 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -23,107 +23,28 @@ Rewriting repository history is a destructive operation. Make sure to back up yo you begin. The best way back up a repository is to [export the project](../settings/import_export.md#exporting-a-project-and-its-data). -NOTE: -Git LFS files can only be removed by an Administrator using a -[Rake task](../../../raketasks/cleanup.md). Removal of this limitation -[is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/223621). - ## Purge files from repository history -To reduce the size of your repository in GitLab, you must remove references to large files from branches, tags, and +To reduce the size of your repository in GitLab, you must first remove references to large files from branches, tags, *and* other internal references (refs) that are automatically created by GitLab. These refs include: - `refs/merge-requests/*` for merge requests. - `refs/pipelines/*` for [pipelines](../../../ci/troubleshooting.md#fatal-reference-is-not-a-tree-error). - `refs/environments/*` for environments. +- `refs/keep-around/*` are created as hidden refs to prevent commits referenced in the database from being removed -Git doesn't usually download these refs to make cloning and fetch faster, but we can use the `--mirror` option to -download all the advertised refs. - -1. [Install `git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md) - using a supported package manager or from source. - -1. Clone a fresh copy of the repository using `--bare` and `--mirror`: - - ```shell - git clone --bare --mirror https://gitlab.example.com/my/project.git - ``` - -1. Using `git filter-repo`, purge any files from the history of your repository. - - To purge large files, the `--strip-blobs-bigger-than` option can be used: - - ```shell - git filter-repo --strip-blobs-bigger-than 10M - ``` - - To purge large files stored using Git LFS, the `--blob--callback` option can - be used. The example below, uses the callback to read the file size from the - Git LFS pointer, and removes files larger than 10MB. - - ```shell - git filter-repo --blob-callback ' - if blob.data.startswith(b"version https://git-lfs.github.com/spec/v1"): - size_in_bytes = int.from_bytes(blob.data[124:], byteorder="big") - if size_in_bytes > 10*1000: - blob.skip() - ' - ``` - - To purge specific large files by path, the `--path` and `--invert-paths` options can be combined: - - ```shell - git filter-repo --path path/to/big/file.m4v --invert-paths - ``` - - See the - [`git filter-repo` documentation](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html#EXAMPLES) - for more examples and the complete documentation. - -1. Force push your changes to overwrite all branches on GitLab: - - ```shell - git push origin --force 'refs/heads/*' - ``` - - [Protected branches](../protected_branches.md) cause this to fail. To proceed, you must - remove branch protection, push, and then re-enable protected branches. - -1. To remove large files from tagged releases, force push your changes to all tags on GitLab: - - ```shell - git push origin --force 'refs/tags/*' - ``` - - [Protected tags](../protected_tags.md) cause this to fail. To proceed, you must remove tag - protection, push, and then re-enable protected tags. - -1. To prevent dead links to commits that no longer exist, push the `refs/replace` created by `git filter-repo`. - - ```shell - git push origin --force 'refs/replace/*' - ``` - - Refer to the Git [`replace`](https://git-scm.com/book/en/v2/Git-Tools-Replace) documentation for information on how this works. - -1. Run a [repository cleanup](#repository-cleanup). - -NOTE: -Project statistics are cached for performance. You may need to wait 5-10 minutes -to see a reduction in storage utilization. - -## Purge files from GitLab storage - -In addition to the refs mentioned above, GitLab also creates hidden `refs/keep-around/*`to prevent commits being deleted. Hidden refs are not advertised, which means we can't download them using Git, but these refs are included in a project export. +These refs are not automatically downloaded and hidden refs are not advertised, but we can remove these refs using a project export. -To purge files from GitLab storage: +To purge files from a GitLab repository: 1. [Install `git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md) using a supported package manager or from source. 1. Generate a fresh [export from the project](../settings/import_export.html#exporting-a-project-and-its-data) and download it. + This project export contains a backup copy of your repository *and* refs + we can use to purge files from your repository. 1. Decompress the backup using `tar`: @@ -134,7 +55,7 @@ To purge files from GitLab storage: This contains a `project.bundle` file, which was created by [`git bundle`](https://git-scm.com/docs/git-bundle). -1. Clone a fresh copy of the repository from the bundle: +1. Clone a fresh copy of the repository from the bundle using `--bare` and `--mirror` options: ```shell git clone --bare --mirror /path/to/project.bundle @@ -149,7 +70,7 @@ To purge files from GitLab storage: the previous run. You need this file from **every** run. Do the next step every time you run `git filter-repo`. - To purge all large files, the `--strip-blobs-bigger-than` option can be used: + To purge all files larger than 10M, the `--strip-blobs-bigger-than` option can be used: ```shell git filter-repo --strip-blobs-bigger-than 10M @@ -236,14 +157,14 @@ This: - Runs `git gc --prune=30.minutes.ago` against the repository to remove unreferenced objects. Repacking your repository temporarily causes the size of your repository to increase significantly, because the old pack files are not removed until the new pack files have been created. -- Unlinks any unused LFS objects currently attached to your project, freeing up storage space. +- Unlinks any unused LFS objects attached to your project, freeing up storage space. - Recalculates the size of your repository on disk. GitLab sends an email notification with the recalculated repository size after the cleanup has completed. If the repository size does not decrease, this may be caused by loose objects being kept around because they were referenced in a Git operation that happened -in the last 30 minutes. Try re-running these steps once the repository has been +in the last 30 minutes. Try re-running these steps after the repository has been dormant for at least 30 minutes. When using repository cleanup, note: @@ -263,7 +184,7 @@ When using repository cleanup, note: Repository size limits: - Can [be set by an administrator](../../admin_area/settings/account_and_limit_settings.md#account-and-limit-settings) - on self-managed instances. **(STARTER ONLY)** + on self-managed instances. **(PREMIUM SELF)** - Are [set for GitLab.com](../../gitlab_com/index.md#account-and-limit-settings). When a project has reached its size limit, you cannot: diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 4a7f75ba1ac..4d5e4a5ef02 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- -# Repository mirroring +# Repository mirroring **(FREE)** Repository mirroring allows for mirroring of repositories to and from external sources. It can be used to mirror branches, tags, and commits between repositories. It is useful when you want to use @@ -16,8 +16,8 @@ at most once every 5 minutes on GitLab.com with [the limit set by the administra There are two kinds of repository mirroring supported by GitLab: -- [Push](#pushing-to-a-remote-repository): for mirroring a GitLab repository to another location. **(CORE)** -- [Pull](#pulling-from-a-remote-repository): for mirroring a repository from another location to GitLab. **(STARTER)** +- [Push](#pushing-to-a-remote-repository): for mirroring a GitLab repository to another location. **(FREE)** +- [Pull](#pulling-from-a-remote-repository): for mirroring a repository from another location to GitLab. **(PREMIUM)** When the mirror repository is updated, all new branches, tags, and commits will be visible in the project's activity feed. @@ -37,7 +37,7 @@ 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, - and branches will be available in your GitLab instance. **(STARTER)** + and branches will be 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 GitLab repository can push its changes to the old location. @@ -47,10 +47,10 @@ The following are some possible use cases for repository mirroring: GitLab.com repository that's public, allows you to open source specific projects and contribute back to the open source community. -## Pushing to a remote repository **(CORE)** +## Pushing to a remote repository **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/249) in GitLab Enterprise Edition 8.7. -> - [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18715) in 10.8. +> - [Moved to GitLab Free](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18715) in 10.8. > - [LFS support over HTTPS added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40137) in 13.5 For an existing project, you can set up push mirroring as follows: @@ -205,10 +205,11 @@ If it is not working correctly a red `error` tag appears and shows the error mes 1. Fill in the **Password** field with the GitLab personal access token created on the destination GitLab instance. 1. Click the **Mirror repository** button. -## Pulling from a remote repository **(STARTER)** +## Pulling from a remote repository **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51) in GitLab Enterprise Edition 8.2. -> - [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab/-/issues/10871) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.11. +> - [Added Git LFS support](https://gitlab.com/gitlab-org/gitlab/-/issues/10871) in GitLab 11.11. +> - Moved to GitLab Premium in 13.9. You can set up a repository to automatically have its branches, tags, and commits updated from an upstream repository. @@ -262,9 +263,10 @@ Repository mirrors are updated as Sidekiq becomes available to process them. If - Fails (for example, a branch diverged from upstream), it will be attempted again later. Mirrors can fail up to 14 times before they will not be enqueued for update again. -### Overwrite diverged branches **(STARTER)** +### Overwrite diverged branches **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4559) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4559) in GitLab 10.6. +> - Moved to GitLab Premium in 13.9. You can choose to always update your local branches with remote versions, even if they have diverged from the remote. @@ -274,7 +276,9 @@ For mirrored branches, enabling this option results in the loss of local changes To use this option, check the **Overwrite diverged branches** box when creating a repository mirror. -### Trigger pipelines for mirror updates **(STARTER)** +### Trigger pipelines for mirror updates **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. If this option is enabled, pipelines will be triggered when branches or tags are updated from the remote repository. Depending on the activity of the remote @@ -282,9 +286,10 @@ repository, this may greatly increase the load on your CI runners. Only enable this if you know they can handle the load. CI will run using the credentials assigned when you set up pull mirroring. -### Hard failure **(STARTER)** +### Hard failure **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3117) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3117) in GitLab 10.2. +> - Moved to GitLab Premium in 13.9. Once the mirroring process is unsuccessfully retried 14 times in a row, it will get marked as hard failed. This will become visible in either the: @@ -295,9 +300,10 @@ failed. This will become visible in either the: When a project is hard failed, it will no longer get picked up for mirroring. You can resume the project mirroring again by [forcing an update](#forcing-an-update). -### Trigger an update using the API **(STARTER)** +### Trigger an update using the API **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3453) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3453) in GitLab 10.3. +> - Moved to GitLab Premium in 13.9. Pull mirroring uses polling to detect new branches and commits added upstream, often minutes afterwards. If you notify GitLab by [API](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project), @@ -305,19 +311,21 @@ updates will be pulled immediately. For more information, see [Start the pull mirroring process for a Project](../../../api/projects.md#start-the-pull-mirroring-process-for-a-project). -## Mirror only protected branches **(STARTER)** +## Mirror only protected branches **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. Based on the mirror direction that you choose, you can opt to mirror only the [protected branches](../protected_branches.md) from/to your remote repository. For pull mirroring, non-protected branches are not mirrored and can diverge. To use this option, check the **Only mirror protected branches** box when -creating a repository mirror. +creating a repository mirror. **(PREMIUM)** ## SSH authentication -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2551) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.5 for Pull mirroring. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22982) in [GitLab Core](https://about.gitlab.com/pricing/) 11.6 for Push mirroring. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2551) in GitLab 9.5 for Pull mirroring. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22982) in GitLab 11.6 for Push mirroring. SSH authentication is mutual: @@ -332,7 +340,7 @@ If you're mirroring over SSH (that is, using an `ssh://` URL), you can authentic - Password-based authentication, just as over HTTPS. - Public key authentication. This is often more secure than password authentication, - especially when the other repository supports [Deploy Keys](../../../ssh/README.md#deploy-keys). + especially when the other repository supports [deploy keys](../../../ssh/README.md#deploy-keys). To get started: @@ -393,7 +401,7 @@ GitLab generates a 4096-bit RSA key that can be copied by clicking the **Copy SS You then need to add the public SSH key to the other repository's configuration: - If the other repository is hosted on GitLab, you should add the public SSH key - as a [Deploy Key](../../../ssh/README.md#deploy-keys). + as a [deploy key](../../../ssh/README.md#deploy-keys). - If the other repository is hosted elsewhere, you may need to add the key to your user's `authorized_keys` file. Paste the entire public SSH key into the file on its own line and save it. @@ -403,17 +411,19 @@ to generate a new key. You'll have to update the other repository with the new key to keep the mirror running. NOTE: -The generated keys are stored in the GitLab database, not in the filesystem. Therefore, +The generated keys are stored in the GitLab database, not in the file system. Therefore, SSH public key authentication for mirrors cannot be used in a pre-receive hook. -## Forcing an update **(CORE)** +## Forcing an update **(FREE)** While mirrors are scheduled to update automatically, you can always force an update by using the update button which is available on the **Mirroring repositories** section of the **Repository Settings** page.  -## Bidirectional mirroring **(STARTER)** +## Bidirectional mirroring **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. WARNING: Bidirectional mirroring may cause conflicts. @@ -536,7 +546,9 @@ Note that this sample has a few limitations: - The script circumvents the Git hook quarantine environment because the update of `$TARGET_REPO` is seen as a ref update and Git will complain about it. -### Mirroring with Perforce Helix via Git Fusion **(STARTER)** +### Mirroring with Perforce Helix via Git Fusion **(PREMIUM)** + +> Moved to GitLab Premium in 13.9. WARNING: Bidirectional mirroring should not be used as a permanent configuration. Refer to diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index b9477da3937..a9e249bb8c3 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -21,8 +21,8 @@ Choose **New file** from the dropdown. Enter a filename in the **Filename** box. Then, add file content in the editor area. Add a descriptive commit message and choose a branch. The branch field -will default to the branch you were viewing in the file browser. If you enter -a new branch name, a checkbox will appear, allowing you to start a new merge +defaults to the branch you were viewing in the file browser. If you enter +a new branch name, a checkbox displays, allowing you to start a new merge request after you commit the changes. When you are satisfied with your new file, click **Commit Changes** at the bottom. @@ -31,46 +31,45 @@ When you are satisfied with your new file, click **Commit Changes** at the botto ### Shortcuts -You can use handy shortcuts when editing a file through the Web Editor, which are the same as -the Web IDE's. For details, see the documentation for [Command Palette](../web_ide/index.md#command-palette). +You can use shortcuts when editing a file through the Web Editor. It uses the same shortcuts +as the Web IDE. For details, read the documentation for [Command Palette](../web_ide/index.md#command-palette). ### Template dropdowns When starting a new project, there are some common files that the new project -might need too. Therefore a message will be displayed by GitLab to make this -easy for you. +might need. GitLab displays a message to help you:  -When clicking on either `LICENSE` or `.gitignore` and so on, a dropdown will be displayed -to provide you with a template that might be suitable for your project. +When clicking on either `LICENSE` or `.gitignore` and so on, a dropdown displays +to provide you a template that may be suitable for your project:  -The license, changelog, contribution guide, or `.gitlab-ci.yml` file could also -be added through a button on the project page. In the example below, the license +The license, changelog, contribution guide, or `.gitlab-ci.yml` file can also +be added through a button on the project page. In this example, the license has already been created, which creates a link to the license itself.  NOTE: -The **Set up CI/CD** button will not appear on an empty repository. You have to at -least add a file in order for the button to show up. +The **Set up CI/CD** button does not appear on an empty repository. For the button +to display, add a file to your repository. ## Upload a file The ability to create a file is great when the content is text. However, this -doesn't work well for binary data such as images, PDFs, or other file types. In +doesn't work well for binary data such as images, PDFs, or other binary file types. In this case, you need to upload a file. From a project's files page, click the '+' button to the right of the branch -selector. Choose **Upload file** from the dropdown. +selector. Choose **Upload file** from the dropdown:  -Once the upload dialog pops up, there are two ways to upload your file. Either -drag and drop a file on the popup or use the **click to upload** link. A file -preview will appear once you have selected a file to upload. +After the upload dialog pops up, there are two ways to upload your file. Either +drag and drop a file on the popup or use the **click to upload** link. After you +select a file to upload, a file preview displays. Enter a commit message, choose a branch, and click **Upload file** when you are ready. @@ -100,19 +99,22 @@ There are multiple ways to create a branch from the GitLab web interface. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2808) in GitLab 8.6. -If your development workflow dictates to have an issue for every merge -request, you can quickly create a branch directly from the issue to speed the process up. -The new branch, and later its merge request, will be marked as related to this issue. -Once merged, the MR will automatically close the issue. +If your development workflow requires an issue for every merge +request, you can create a branch directly from the issue to speed the process up. +The new branch, and later its merge request, are marked as related to this issue. +Once merged, the merge request closes the issue. You can see a **Create merge request** dropdown below the issue description. -NOTE: -You won't see the **Create merge request** button if there is already a branch with the same -name or a referenced merge request or your project has an active -fork relationship. -If you would like to make this button appear, a possible workaround is to [remove your project's -fork relationship](../settings/index.md#removing-a-fork-relationship). Once removed, the fork -relationship cannot be restored. This project will no longer be able to receive or send merge requests to the source project or other forks. +The **Create merge request** button doesn't display if: + +- A branch with the same name already exists. +- The branch already has a referenced merge request. +- Your project has an active fork relationship. + +To make this button appear, one possible workaround is to +[remove your project's fork relationship](../settings/index.md#removing-a-fork-relationship). +After removal, the fork relationship cannot be restored. This project can no longer +be able to receive or send merge requests to the source project, or other forks.  @@ -120,46 +122,47 @@ This dropdown contains the options **Create merge request and branch** and **Cre  -Once you choose one of these options, a new branch or branch and merge request -will be created based on the default -branch of your project (by default, `master`). The branch name will be based on -the title of the issue, and as a prefix, it will have its internal ID. Thus, the example -screenshot above will create a branch named +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`. +The branch name is based on an internal ID, and the issue title. The example +screenshot above creates a branch named `2-make-static-site-auto-deploy-and-serve`. When you click the **Create branch** button in an empty -repository project, GitLab automatically creates a `master` branch, commits -a blank `README.md` file to it, and creates and redirects you to a new branch -based on the issue title. -If your [project is already configured with a deployment service](../integrations/overview.md), -such as Kubernetes, GitLab takes one step further and prompts you to set up -[auto deploy](../../../topics/autodevops/stages.md#auto-deploy) -by helping you create a `.gitlab-ci.yml` file. +repository project, GitLab performs these actions: + +- Creates a `master` 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,_ + GitLab prompts you to set up [auto deploy](../../../topics/autodevops/stages.md#auto-deploy) + by helping you create a `.gitlab-ci.yml` file. After the branch is created, you can edit files in the repository to fix -the issue. When a merge request is created based on the newly created branch, -the description field will automatically display the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) -`Closes #ID`, where `ID` the ID of the issue. This will close the issue once the +the issue. When a merge request is created based on the newly-created branch, +the description field displays the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) +`Closes #ID`, where `ID` is the ID of the issue. This closes the issue when the merge request is merged. ### Create a new branch from a project's dashboard If you want to make changes to several files before creating a new merge -request, you can create a new branch upfront. From a project's files page, -choose **New branch** from the dropdown. +request, you can create a new branch upfront. - +1. From a project's files page, choose **New branch** from the dropdown. -Enter a new **Branch name**. Optionally, change the **Create from** field -to choose which branch, tag, or commit SHA this new branch will originate from. -This field will autocomplete if you start typing an existing branch or tag. -Click **Create branch** and you will be returned to the file browser on this new -branch. +  - +1. Enter a new **Branch name**. +1. (Optional) Change the **Create from** field to choose which branch, tag, or + commit SHA this new branch originates from. This field autocompletes if you + start typing an existing branch or tag. +1. Click **Create branch** to return to the file browser on this new branch. + +  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 `master`, 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. @@ -167,31 +170,35 @@ modify files. ## Create a new tag -Tags are useful for marking major milestones such as production releases, -release candidates, and more. You can create a tag from a branch or a commit -SHA. From a project's files page, choose **New tag** from the dropdown. +Tags help you mark major milestones such as production releases and +release candidates. You can create a tag from a branch or a commit +SHA: + +1. From a project's files page, choose **New tag** from the dropdown. - +  -Give the tag a name such as `v1.0.0`. Choose the branch or SHA from which you -would like to create this new tag. You can optionally add a message and -release notes. The release notes section supports Markdown format and you can -also upload an attachment. Click **Create tag**, and you will be taken to the tag -list page. +1. Give the tag a name such as `v1.0.0`. +1. Choose the branch or SHA from which you want to create this new tag. +1. (Optional) Add a message and release notes. The release notes section supports + Markdown format. +1. (Optional) Upload an attachment. +1. Click **Create tag**, and GitLab redirects you to the tag list page. - +  ## 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`. Enter -a new branch name in the **Target branch** field. You will notice a checkbox -appear that is labeled **Start a new merge request with these changes**. After -you commit the changes you will be taken to a new merge request form. +trigger a new merge request rather than committing directly to `master`: + +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. +1. Commit your changes, and GitLab redirects you to a new merge request form. - +  -If you'd prefer _not_ to use your primary email address for commits created +If you'd prefer to not use your primary email address for commits created through the web editor, you can choose to use another of your linked email addresses from the **User Settings > Edit Profile** page. diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 639bca0d354..29c1c32145d 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: concepts, howto --- -# Signing commits and tags with X.509 +# Signing commits and tags with X.509 **(FREE)** [X.509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key certificates issued by a public or private Public Key Infrastructure (PKI). diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index c99b0d91523..c7dda81685c 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -23,6 +23,10 @@ When a feature is no longer necessary, you can [archive the related requirement] <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [GitLab 12.10 Introduces Requirements Management](https://www.youtube.com/watch?v=uSS7oUNSEoU). +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a more in-depth walkthrough using a [demonstration project](https://gitlab.com/gitlab-org/requiremeents-mgmt), +see [GitLab Requirements Traceability Walkthrough](https://youtu.be/VIiuTQYFVa0) (Feb 2021). +  ## Create a requirement @@ -260,7 +264,9 @@ For GitLab.com, it is set to 10 MB. ## Export requirements to a CSV file -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290813) in GitLab 13.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290813) in GitLab 13.8. +> - Revised CSV column headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299247) in GitLab 13.9. +> - Ability to select which fields to export [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290823) in GitLab 13.9. You can export GitLab requirements to a [CSV file](https://en.wikipedia.org/wiki/Comma-separated_values) sent to your default notification @@ -275,19 +281,41 @@ Users with Reporter or higher [permissions](../../permissions.md) can export req To export requirements: 1. In a project, go to **Requirements**. -1. Select the **Export as CSV** icon (**{export}**) in the top right. A confirmation modal appears. +1. In the top right, select the **Export as CSV** icon (**{export}**). + + A confirmation modal appears. + +1. Under **Advanced export options**, select which fields to export. + + All fields are selected by default. To exclude a field from being exported, clear the checkbox next to it. + 1. Select **Export requirements**. The exported CSV file is sent to the email address associated with your user. ### Exported CSV file format +<!-- vale gitlab.Spelling = NO --> You can preview the exported CSV file in a spreadsheet editor, such as Microsoft Excel, OpenOffice Calc, or Google Sheets. +<!-- vale gitlab.Spelling = YES --> + +The exported CSV file contains the following headers: + +- In GitLab 13.8: + + - Requirement ID + - Title + - Description + - Author Username + - Latest Test Report State + - Latest Test Report Created At (UTC) -The exported CSV file contains the following columns: +- In GitLab 13.9 and later: -- Requirement ID -- Title -- Description -- Author Username -- Latest Test Report State -- Latest Test Report Created At (UTC) + - Requirement ID + - Title + - Description + - Author + - Author Username + - Created At (UTC) + - State + - State Updated At (UTC) diff --git a/doc/user/project/security_dashboard.md b/doc/user/project/security_dashboard.md deleted file mode 100644 index d9440e8deea..00000000000 --- a/doc/user/project/security_dashboard.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../application_security/security_dashboard/index.md' ---- - -This document was moved to [another location](../application_security/security_dashboard/index.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 76156690fe7..debe5c51d51 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -4,11 +4,9 @@ group: Certify info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Service Desk **(CORE)** +# Service Desk **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/149) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/214839) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215364) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.2. +> Moved to GitLab Free in 13.2. Service Desk is a module that allows your team to connect with any external party through email, without any external tools. @@ -34,7 +32,7 @@ It provides a unique email address for end users to create issues in a project. Follow-up notes can be sent either through the GitLab interface or by email. End users only see the thread through email. -For instance, let's assume you develop a game for iOS or Android. +For example, let's assume you develop a game for iOS or Android. The codebase is hosted in your GitLab instance, built and deployed with GitLab CI/CD. @@ -56,74 +54,99 @@ Here's how Service Desk works for you: ## Configuring Service Desk -NOTE: -Service Desk is enabled on GitLab.com. -You can skip step 1 below; you only need to enable it per project. +Users with Maintainer and higher access in a project can configure Service Desk. + +Service Desk issues are [confidential](issues/confidential_issues.md), so they are +only visible to project members. In GitLab 11.7 we updated the generated email +address format. The older format is still supported, so existing aliases or +contacts still work. + +If you have [templates](description_templates.md) in your repository, you can optionally select +one from the selector menu to append it to all Service Desk issues. -If you have project maintainer access you have the option to set up Service Desk. Follow these steps: +To enable Service Desk in your project: -1. [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. +1. (GitLab self-managed only) [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. We recommend using [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing), - but in GitLab 11.7 and later you can also use [catch-all mailboxes](../../administration/incoming_email.md#catch-all-mailbox). -1. Navigate to your project's **Settings > General** and locate the **Service Desk** section. + but you can also use [catch-all mailboxes](../../administration/incoming_email.md#catch-all-mailbox). +1. In a project, in the left sidebar, go to **Settings > General** and expand the **Service Desk** section. 1. Enable the **Activate Service Desk** toggle. This reveals a unique email address to email issues - to the project. These issues are [confidential](issues/confidential_issues.md), so they are - only visible to project members. Note that in GitLab 11.7, we updated the generated email - address's format. The older format is still supported, however, allowing existing aliases or - contacts to continue working. + to the project. - WARNING: - This email address can be used by anyone to create an issue on this project, regardless - of their access level to your GitLab instance. We recommend **putting this behind an alias** so it can be - changed if needed. We also recommend **[enabling Akismet](../../integration/akismet.md)** on your GitLab - instance to add spam checking to this service. Unblocked email spam would result in many spam - issues being created. +Service Desk is now enabled for this project! To access it in a project, in the left sidebar, select +**Issues > Service Desk**. - If you have [templates](description_templates.md) in your repository, you can optionally select - one from the selector menu to append it to all Service Desk issues. +WARNING: +Anyone in your project can use the Service Desk email address to create an issue in this project, **regardless +of their access level** to your GitLab instance. -Service Desk is now enabled for this project! You should be able to access it from your project's -**Issues** menu. +To improve your project's security, we recommend the following: - +- Put the Service Desk email address behind an alias on your email system so you can change it later. +- [Enable Akismet](../../integration/akismet.md) on your GitLab instance to add spam checking to this service. + Unblocked email spam can result in many spam issues being created. + +The unique internal email address is visible to project members with Maintainer (or higher) +[permission level](../permissions.md) +in your GitLab instance. However, when using an email alias externally, an end user +(issue creator) cannot see the internal email address displayed in the information note. ### Using customized email templates -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/214839) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/215364) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2460) in GitLab Premium 12.7. +> - Moved to GitLab Free in 13.2. An email is sent to the author when: - A user submits a new issue using Service Desk. - A new note is created on a Service Desk issue. -The body of these email messages can be customized by using templates. To create a new customized template, -create a new Markdown (`.md`) file inside the `.gitlab/service_desk_templates/` -directory in your repository. Commit and push to your default branch. +You can customize the body of these email messages with templates. +Save your templates in the `.gitlab/service_desk_templates/` +directory in your repository. + +With Service Desk, you can use templates for: + +- [Thank you emails](#thank-you-email) +- [New note emails](#new-note-email) +- [New Service Desk issues](#new-service-desk-issues) #### Thank you email -The **Thank you email** is the email sent to a user after they submit an issue. -The filename of the template has to be `thank_you.md`. -There are a few placeholders you can use which are automatically replaced in the email: +When a user submits an issue through Service Desk, GitLab sends a **thank you email**. +You must name the template file `thank_you.md`. + +You can use these placeholders to be automatically replaced in each email: - `%{ISSUE_ID}`: issue IID - `%{ISSUE_PATH}`: project path appended with the issue IID -As the Service Desk issues are created as confidential (only project members can see them) -the response email does not provide the issue link. +Because Service Desk issues are created as [confidential](issues/confidential_issues.md) (only project members can see them), +the response email does not contain the issue link. #### New note email -When a user-submitted issue receives a new comment, GitLab sends a **New note email** -to the user. The filename of this template must be `new_note.md`, and you can -use these placeholders in the email: +When a user-submitted issue receives a new comment, GitLab sends a **new note email**. +You must name the template file `new_note.md`. + +You can use these placeholders to be automatically replaced in each email: - `%{ISSUE_ID}`: issue IID - `%{ISSUE_PATH}`: project path appended with the issue IID - `%{NOTE_TEXT}`: note text +#### New Service Desk issues + +You can select one [issue description template](description_templates.md#creating-issue-templates) +**per project** to be appended to every new Service Desk issue's description. +Issue description templates should reside in your repository's `.gitlab/issue_templates/` directory. + +To use a custom issue template with Service Desk, in your project: + +1. [Create a description template](description_templates.md#creating-issue-templates) +1. Go to **Settings > General > Service Desk**. +1. From the dropdown **Template to append to all Service Desk issues**, select your template. + ### Using custom email display name > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7529) in GitLab 12.8. @@ -139,7 +162,7 @@ To edit the custom email display name: ### Using custom email address -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in GitLab Premium 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) in GitLab 13.8. If the `service_desk_email` is configured, then you can create Service Desk @@ -215,7 +238,8 @@ The configuration options are the same as for configuring ## Using Service Desk -There are a few ways Service Desk can be used. +You can use Service Desk to [create an issue](#as-an-end-user-issue-creator) or [respond to one](#as-a-responder-to-the-issue). +In these issues, you can also see our friendly neighborhood [Support Bot](#support-bot-user). ### As an end user (issue creator) diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 27727890383..6f230f1798a 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -18,7 +18,7 @@ The **GitLab import/export** button is displayed if the project import option is See also: - [Project import/export API](../../../api/project_import_export.md) -- [Project import/export administration Rake tasks](../../../administration/raketasks/project_import_export.md) **(CORE ONLY)** +- [Project import/export administration Rake tasks](../../../administration/raketasks/project_import_export.md) **(FREE SELF)** - [Group import/export](../../group/settings/import_export.md) - [Group import/export API](../../../api/group_import_export.md) @@ -180,14 +180,14 @@ all imported projects are given the visibility of `Private`. NOTE: The maximum import file size can be set by the Administrator, default is `0` (unlimited). -As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin Area UI](../../admin_area/settings/account_and_limit_settings.md). +As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin Area UI](../../admin_area/settings/account_and_limit_settings.md). Default [modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to 0 in GitLab 13.8. ### Project import status You can query an import through the [Project import/export API](../../../api/project_import_export.md#import-status). As described in the API documentation, the query may return an import error or exceptions. -### Import large projects **(CORE ONLY)** +### Import large projects **(FREE SELF)** If you have a larger project, consider using a Rake task, as described in our [developer documentation](../../../development/import_project.md#importing-via-a-rake-task). diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 26ef5e2260a..8ab82fe7296 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, index, howto --- -# Project settings +# Project settings **(FREE)** NOTE: Only project maintainers and administrators have the [permissions](../../permissions.md#project-members-permissions) @@ -40,6 +40,26 @@ You can select a framework label to identify that your project has certain compl NOTE: Compliance framework labels do not affect your project settings. +#### Custom compliance frameworks + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276221) 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-custom-compliance-frameworks). **(PREMIUM)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +GitLab 13.9 introduces custom compliance frameworks at the group-level. A group owner can create a compliance framework label +and assign it to any number of projects within that group or subgroups. When this feature is enabled, projects can only +be assigned compliance framework labels that already exist within that group. + +If existing [Compliance frameworks](#compliance-framework) are not sufficient, project and group owners +can now create their own. + +New compliance framework labels can be created and updated using GraphQL. + ### Sharing and permissions For your repository, you can set up features such as public access, repository features, @@ -59,7 +79,7 @@ Use the switches to enable or disable the following features: | **Issues** | ✓ | Activates the GitLab issues tracker | | **Repository** | ✓ | Enables [repository](../repository/) functionality | | **Merge Requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#merge-request-settings) | -| **Forks** | ✓ | Enables [forking](../index.md#fork-a-project) functionality | +| **Forks** | ✓ | Enables [forking](../working_with_projects.md#fork-a-project) functionality | | **Pipelines** | ✓ | Enables [CI/CD](../../../ci/README.md) functionality | | **Container Registry** | | Activates a [registry](../../packages/container_registry/) for your Docker images | | **Git Large File Storage** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs) | @@ -120,7 +140,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/merge_request_approvals.md). **(STARTER)** +- Enable [merge request approvals](../merge_requests/merge_request_approvals.md). - Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). - Enable [merge only when all threads are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved). - Enable [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch) @@ -128,7 +148,7 @@ Set up your project's merge request settings:  -### Service Desk **(STARTER)** +### Service Desk Enable [Service Desk](../service_desk.md) for your project to offer customer support. @@ -201,7 +221,7 @@ To rename a repository: Remember that this can have unintended side effects since everyone with the old URL won't be able to push or pull. Read more about what happens with the -[redirects when renaming repositories](../index.md#redirects-when-changing-repository-paths). +[redirects when renaming repositories](../repository/index.md#redirects-when-changing-repository-paths). #### Transferring an existing project into another namespace @@ -225,7 +245,7 @@ To transfer a project: Once done, you will be taken to the new project's namespace. At this point, read what happens with the -[redirects from the old project to the new one](../index.md#redirects-when-changing-repository-paths). +[redirects from the old project to the new one](../repository/index.md#redirects-when-changing-repository-paths). NOTE: GitLab administrators can use the administration interface to move any project to any @@ -245,8 +265,8 @@ To delete a project: 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 or Silver](https://about.gitlab.com/pricing/) or higher tiers, -group administrators can [configure](../../group/index.md#enabling-delayed-project-removal) projects within a group +- 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#enabling-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). @@ -299,3 +319,22 @@ Add the URL of a Jaeger server to allow your users to [easily access the Jaeger [Add Storage credentials](../../../operations/incident_management/status_page.md#sync-incidents-to-the-status-page) to enable the syncing of public Issues to a [deployed status page](../../../operations/incident_management/status_page.md#create-a-status-page-project). + +### Enable or disable custom compliance frameworks **(PREMIUM)** + +Enabling or disabling custom compliance frameworks is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:ff_custom_compliance_frameworks) +``` + +To disable it: + +```ruby +Feature.disable(:ff_custom_compliance_frameworks) +``` diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 39de9ab9ca2..590f549577e 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -8,13 +8,11 @@ type: reference, howto # Project access tokens NOTE: -Project access tokens are supported for self-managed instances on Core and above. They are also supported on GitLab.com Bronze and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). +Project access tokens are supported for self-managed instances on Free and above. They are also supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2587) in GitLab 13.0. -> - It was [deployed](https://gitlab.com/groups/gitlab-org/-/epics/2587) behind a feature flag, disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/218722) in GitLab 13.3. -> - It's recommended for production use. -> - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in 13.5 for paid groups only. +> - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5 for paid groups only. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in GitLab 13.5. WARNING: This feature might not be available to you. Check the **version history** note above for details. diff --git a/doc/user/project/slash_commands.md b/doc/user/project/slash_commands.md deleted file mode 100644 index 5844861c91e..00000000000 --- a/doc/user/project/slash_commands.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'quick_actions.md' ---- - -This document was moved to [user/project/quick_actions.md](quick_actions.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index 07f122a7828..002eb398406 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -6,11 +6,11 @@ type: reference, how-to description: "The static site editor enables users to edit content on static websites without prior knowledge of the underlying templating language, site architecture or Git commands." --- -# Static Site Editor **(CORE)** +# Static Site Editor **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28758) in GitLab 12.10. > - WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214559) in GitLab 13.0. -> - Non-Markdown content blocks uneditable on the WYSIWYG mode [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216836) in GitLab 13.3. +> - Non-Markdown content blocks not editable on the WYSIWYG mode [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216836) in GitLab 13.3. > - Formatting Markdown [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49052) in GitLab 13.7. Static Site Editor (SSE) enables users to edit content on static websites without @@ -23,8 +23,8 @@ and submit the changes for review. The Static Site Editor allows collaborators to submit changes to static site files seamlessly. For example: -- Non-technical collaborators can easily edit a page directly from the browser; - they don't need to know Git and the details of your project to be able to contribute. +- Non-technical collaborators can edit a page directly from the browser. + They don't need to know Git and the details of your project to contribute. - Recently hired team members can quickly edit content. - Temporary collaborators can jump from project to project and quickly edit pages instead of having to clone or fork every single project they need to submit changes to. @@ -68,11 +68,11 @@ The editor can then navigate to the merge request to assign it to a colleague fo ## Set up your project First, set up the project. Once done, you can use the Static Site Editor to -easily [edit your content](#edit-content). +[edit your content](#edit-content). 1. To get started, create a new project from the [Static Site Editor - Middleman](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman) template. You can either [fork it](../repository/forking_workflow.md#creating-a-fork) - or [create a new project from a template](../../../gitlab-basics/create-project.md#built-in-templates). + or [create a new project from a template](../working_with_projects.md#built-in-templates). 1. Edit the [`data/config.yml`](#static-site-generator-configuration) configuration file to replace `<username>` and `<project-name>` with the proper values for your project's path. @@ -101,7 +101,7 @@ To edit a file: wish to edit the raw Markdown instead, you can toggle the **Markdown** mode in the bottom-right corner. 1. When you're done, click **Submit changes...**. -1. (Optional) Adjust the default title and description of the merge request that will be submitted +1. (Optional) Adjust the default title and description of the merge request, to submit with your changes. Alternatively, select a [merge request template](../../../user/project/description_templates.md#creating-merge-request-templates) from the dropdown menu and edit it accordingly. 1. Click **Submit changes**. @@ -154,9 +154,9 @@ so you can verify the correct image is included and there aren't any references You can embed YouTube videos on the WYSIWYG mode by clicking the video icon (**{live-preview}**). The following URL/ID formats are supported: -- YouTube watch URL (e.g. `https://www.youtube.com/watch?v=0t1DgySidms`) -- YouTube embed URL (e.g. `https://www.youtube.com/embed/0t1DgySidms`) -- YouTube video ID (e.g. `0t1DgySidms`) +- **YouTube watch URLs**: `https://www.youtube.com/watch?v=0t1DgySidms` +- **YouTube embed URLs**: `https://www.youtube.com/embed/0t1DgySidms` +- **YouTube video IDs**: `0t1DgySidms` ### Front matter @@ -164,13 +164,13 @@ The following URL/ID formats are supported: > - Ability to edit page front matter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235921) in GitLab 13.5. Front matter is a flexible and convenient way to define page-specific variables in data files -intended to be parsed by a static site generator. It is commonly used for setting a page's -title, layout template, or author, but can be used to pass any kind of metadata to the +intended to be parsed by a static site generator. Use it to set a page's +title, layout template, or author. You can also pass any kind of metadata to the generator as the page renders out to HTML. Included at the very top of each data file, the -front matter is often formatted as YAML or JSON and requires consistent and accurate syntax. +front matter is often formatted as YAML or JSON, and requires consistent and accurate syntax. To edit the front matter from the Static Site Editor you can use the GitLab regular file editor, -the Web IDE, or easily update the data directly from the WYSIWYG editor: +the Web IDE, or update the data directly from the WYSIWYG editor: 1. Click the **Page settings** button on the bottom-right to reveal a web form with the data you have on the page's front matter. The form is populated with the current data: @@ -181,10 +181,16 @@ the Web IDE, or easily update the data directly from the WYSIWYG editor: 1. When you're done, click **Submit changes...**. 1. Describe your changes (add a commit message). 1. Click **Submit changes**. -1. Click **View merge request** and GitLab will take you there. +1. Click **View merge request** to view it. -Note that support for adding new attributes to the page's front matter from the form is not supported -yet. You can do so by editing the file locally, through the GitLab regular file editor, or through the Web IDE. Once added, the form will load the new fields. +Adding new attributes to the page's front matter from the form is not supported. +To add new attributes: + +- Edit the file locally +- Edit the file with the GitLab regular file editor. +- Edit the file with the Web IDE. + +After adding an attribute, the form loads the new fields. ## Configuration files @@ -206,8 +212,8 @@ use to customize behavior of the Static Site Editor (SSE). If the file does not default values which support a default Middleman project configuration are used. The [Static Site Editor - Middleman](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman) project template generates a file pre-populated with these defaults. -To customize the behavior of the SSE, edit `.gitlab/static-site-editor.yml`'s entries -(described in the table below) according to what works best for your project (respecting YAML syntax). +To customize the behavior of the SSE, edit `.gitlab/static-site-editor.yml`'s entries, +according to your project's needs. Make sure to respect YAML syntax. After the table, see an [example of the SSE configuration file](#gitlabstatic-site-editoryml-example). @@ -224,8 +230,9 @@ image_upload_path: 'source/images' # Relative path to the project's root. Don't ### Static Site Generator configuration The Static Site Editor uses Middleman's configuration file, `data/config.yml` -to customize the behavior of the project itself and to control the **Edit this -page** button, rendered through the file [`layout.erb`](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman/-/blob/master/source/layouts/layout.erb). +to customize the behavior of the project itself. This file also controls the +**Edit this page** button, rendered through the file +[`layout.erb`](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman/-/blob/master/source/layouts/layout.erb). To [configure the project template to your own project](#set-up-your-project), you must replace the `<username>` and `<project-name>` in the `data/config.yml` @@ -236,7 +243,7 @@ the Static Site Editor may use different configuration files or approaches. ## Using Other Static Site Generators -Although Middleman is the only Static Site Generator currently officially supported +Although Middleman is the only Static Site Generator officially supported by the Static Site Editor, you can configure your project's build and deployment to use a different Static Site Generator. In this case, use the Middleman layout as an example, and follow a similar approach to properly render an **Edit this page** diff --git a/doc/user/project/status_page/index.md b/doc/user/project/status_page/index.md deleted file mode 100644 index 513c410a6f9..00000000000 --- a/doc/user/project/status_page/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../../../operations/incident_management/status_page.md' ---- - -This document was moved to [status_page.md](../../../operations/incident_management/status_page.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index c94795578ef..2b0ca38c57c 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -81,7 +81,7 @@ The following time units are available: Default conversion rates are 1mo = 4w, 1w = 5d and 1d = 8h. -### Limit displayed units to hours **(CORE ONLY)** +### Limit displayed units to hours **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29469/) in GitLab 12.1. diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index af8e78afb28..07f46cb94f7 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -5,12 +5,12 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, how-to --- -# Web IDE **(CORE)** +# Web IDE **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Core in 10.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Free in 10.7. -The Web IDE editor makes it faster and easier to contribute changes to your +The Web Integrated Development Environment (IDE) editor makes it faster and easier to contribute changes to your projects by providing an advanced editor with commit staging. ## Open the Web IDE @@ -22,11 +22,11 @@ and from merge requests. ## File finder -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18323) in [GitLab Core](https://about.gitlab.com/pricing/) 10.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18323) in [GitLab Free](https://about.gitlab.com/pricing/) 10.8. The file finder allows you to quickly open files in the current branch by searching for fragments of the file path. The file finder is launched using the keyboard shortcut -<kbd>Cmd</kbd>+<kbd>p</kbd>, <kbd>Ctrl</kbd>+<kbd>p</kbd>, or <kbd>t</kbd> +<kbd>Command</kbd>+<kbd>p</kbd>, <kbd>Control</kbd>+<kbd>p</kbd>, or <kbd>t</kbd> (when editor is not in focus). Type the filename or file path fragments to start seeing results. @@ -102,7 +102,7 @@ based on the [JSON Schema Store](https://www.schemastore.org/json/). The Web IDE has validation for certain files built in. This feature is only supported for the `*.gitlab-ci.yml` files. -#### Enable or disable validation based on predefined schemas **(CORE ONLY)** +#### Enable or disable validation based on predefined schemas **(FREE SELF)** Validation based on predefined schemas is under development and not ready for production use. It is deployed behind a feature flag that is **disabled by default** for self-managed instances, @@ -154,7 +154,7 @@ Each schema entry supports two properties: ## Configure the Web IDE -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23352) in [GitLab Core](https://about.gitlab.com/pricing/) 13.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23352) in [GitLab Free](https://about.gitlab.com/pricing/) 13.1. The Web IDE supports configuration of certain editor settings by using [`.editorconfig` files](https://editorconfig.org/). When opening a file, the @@ -174,7 +174,7 @@ The Web IDE currently supports the following `.editorconfig` settings: ## Commit changes > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Core in 10.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Free in 10.7. > - From [GitLab 12.7 onward](https://gitlab.com/gitlab-org/gitlab/-/issues/33441), files were automatically staged. > - From [GitLab 12.9 onward](https://gitlab.com/gitlab-org/gitlab/-/issues/196609), support for staging files was removed to prevent loss of unstaged data. All your current changes necessarily have to be committed or discarded. @@ -202,7 +202,7 @@ shows you a preview of the merge request diff if you commit your changes. ## View CI job logs -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19279) in [GitLab Core](https://about.gitlab.com/pricing/) 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19279) in [GitLab Free](https://about.gitlab.com/pricing/) 11.0. You can use the Web IDE to quickly fix failing tests by opening the branch or merge request in the Web IDE and opening the logs of the failed @@ -215,7 +215,7 @@ left. ## Switching merge requests -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19318) in [GitLab Core](https://about.gitlab.com/pricing/) 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19318) in [GitLab Free](https://about.gitlab.com/pricing/) 11.0. To switch between your authored and assigned merge requests, click the dropdown in the top of the sidebar to open a list of merge requests. You need to commit or discard all your changes before switching to a different merge @@ -223,7 +223,7 @@ request. ## Switching branches -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20850) in [GitLab Core](https://about.gitlab.com/pricing/) 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20850) in [GitLab Free](https://about.gitlab.com/pricing/) 11.2. To switch between branches of the current project repository, click the dropdown in the top of the sidebar to open a list of branches. @@ -232,8 +232,8 @@ different branch. ## Markdown editing -> - Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18059) in [GitLab Core](https://about.gitlab.com/pricing/) 10.7. -> - Support for pasting images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22822) in [GitLab Core](https://about.gitlab.com/pricing/) 13.1. +> - Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18059) in [GitLab Free](https://about.gitlab.com/pricing/) 10.7. +> - Support for pasting images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22822) in [GitLab Free](https://about.gitlab.com/pricing/) 13.1. When you edit Markdown files in the Web IDE, you can preview your changes by clicking the **Preview Markdown** tab above the file editor. The Markdown preview @@ -246,7 +246,7 @@ added to the filename. ## Live Preview -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19764) in [GitLab Core](https://about.gitlab.com/pricing/) 11.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19764) in [GitLab Free](https://about.gitlab.com/pricing/) 11.2. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/213853) from _Client Side Evaluation_ to _Live Preview_ in GitLab 13.0. You can use the Web IDE to preview JavaScript projects right in the browser. @@ -285,7 +285,7 @@ below. ## Interactive Web Terminals for the Web IDE > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) to GitLab Core in 13.1. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) to GitLab Free in 13.1. WARNING: Interactive Web Terminals for the Web IDE is currently in **Beta**. @@ -307,7 +307,7 @@ to work: This section requires at least a `session_timeout` value (which defaults to 1800 seconds) and a `listen_address` value. If `advertise_address` is not defined, `listen_address` is used. - If you are using a reverse proxy with your GitLab instance, web terminals need to be - [enabled](../../../administration/integration/terminal.md#enabling-and-disabling-terminal-support). **(ULTIMATE ONLY)** + [enabled](../../../administration/integration/terminal.md#enabling-and-disabling-terminal-support). **(ULTIMATE SELF)** If you have the terminal open and the job has finished with its tasks, the terminal blocks the job from finishing for the duration configured in @@ -389,7 +389,7 @@ click **Restart Terminal** to start a new terminal session. ### File syncing to web terminal > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5276) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211686) to GitLab Core in 13.1. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211686) to GitLab Free in 13.1. File changes in the Web IDE can be synced to a running web terminal. This enables users to test their code changes in a preconfigured terminal diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 779179a6665..187fcb5b3f9 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -1,11 +1,11 @@ --- stage: Create -group: Knowledge +group: Editor 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, how-to --- -# Wiki **(CORE)** +# Wiki **(FREE)** A separate system for documentation called Wiki, is built right into each GitLab project. It is enabled by default on all new projects and you can find @@ -184,7 +184,7 @@ Similar to versioned diff file views, you can see the changes made in a given Wi Wiki events (creation, deletion, and updates) are tracked by GitLab and displayed on the [user profile](../../profile/index.md#user-profile), [group](../../group/index.md#view-group-activity), -and [project](../index.md#project-activity) activity pages. +and [project](../working_with_projects.md#project-activity) activity pages. ## Adding and editing wiki pages locally diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md new file mode 100644 index 00000000000..3fe6193c414 --- /dev/null +++ b/doc/user/project/working_with_projects.md @@ -0,0 +1,341 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +--- + +# Working with projects **(FREE)** + +Most work in GitLab is done in a [project](../../user/project/index.md). Files and +code are saved in projects, and most features are in the scope of projects. + +## Explore projects + +You can explore other popular projects available on GitLab. To explore projects: + +1. Click **Projects** in the navigation bar. +1. Click **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 +projects with the largest number of comments in the past month, click **Trending**. + +## Create a project + +To create a project in GitLab: + +1. In your dashboard, click the green **New project** button or use the plus + icon in the navigation bar. This opens the **New project** page. +1. On the **New project** page, choose if you want to: + - Create a [blank project](#blank-projects). + - Create a project using one of the available [project templates](#project-templates). + - [Import a project](../../user/project/import/index.md) from a different repository, + if enabled on your GitLab instance. Contact your GitLab administrator if this is unavailable. + - Run [CI/CD pipelines for external repositories](../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)** + +NOTE: +For a list of words that can't be used as project names see +[Reserved project and group names](../../user/reserved_names.md). + +### Blank projects + +To create a new blank project on the **New project** page: + +1. On the **Blank project** tab, provide the following information: + - The name of your project in the **Project name** field. You can't use + special characters, but you can use spaces, hyphens, underscores, or even + emoji. When adding the name, the **Project slug** auto populates. + The slug is what the GitLab instance uses as the URL path to the project. + If you want a different slug, input the project name first, + then change the slug after. + - The path to your project in the **Project slug** field. This is the URL + path for your project that the GitLab instance uses. If the + **Project name** is blank, it auto populates when you fill in + the **Project slug**. + - The **Project description (optional)** field enables you to enter a + description for your project's dashboard, which helps others + understand what your project is about. Though it's not required, it's a good + idea to fill this in. + - Changing the **Visibility Level** modifies the project's + [viewing and access rights](../../public_access/public_access.md) for users. + - Selecting the **Initialize repository with a README** option creates a + README file so that the Git repository is initialized, has a default branch, and + can be cloned. +1. Click **Create project**. + +### Project templates + +Project templates can pre-populate a new project with the necessary files to get you +started quickly. + +There are two main types of project templates: + +- [Built-in templates](#built-in-templates), sourced from the following groups: + - [`project-templates`](https://gitlab.com/gitlab-org/project-templates) + - [`pages`](https://gitlab.com/pages) +- [Custom project templates](#custom-project-templates), for custom templates + configured by GitLab administrators and users. + +#### Built-in templates + +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. + +To use a built-in template on the **New project** page: + +1. On the **Create from template** tab, select the **Built-in** tab. +1. From the list of available built-in templates, click the: + - **Preview** button to look at the template source itself. + - **Use template** button to start creating the project. +1. Finish creating the project by filling out the project's details. The process is + the same as creating a [blank project](#blank-projects). + +##### Enterprise templates **(ULTIMATE)** + +GitLab is developing Enterprise templates to help you streamline audit management with selected regulatory standards. These templates automatically import issues that correspond to each regulatory requirement. + +To create a new project with an Enterprise template, on the **New project** page: + +1. On the **Create from template** tab, select the **Built-in** tab. +1. From the list of available built-in Enterprise templates, click the: + - **Preview** button to look at the template source itself. + - **Use template** button to start creating the project. +1. Finish creating the project by filling out the project's details. The process is the same as creating a [blank project](#blank-projects). + +Available Enterprise templates include: + +- HIPAA Audit Protocol template ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13756) in GitLab 12.10) + +NOTE: +You can improve the existing built-in templates or contribute new ones in the +[`project-templates`](https://gitlab.com/gitlab-org/project-templates) and +[`pages`](https://gitlab.com/pages) groups by following [these steps](https://gitlab.com/gitlab-org/project-templates/contributing). + +##### Custom project templates **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. + +Creating new projects based on custom project templates is a convenient option for +quickly starting projects. + +Custom projects are available at the [instance-level](../../user/admin_area/custom_project_templates.md) +from the **Instance** tab, or at the [group-level](../../user/group/custom_project_templates.md) +from the **Group** tab, under the **Create from template** tab. + +To use a custom project template on the **New project** page: + +1. On the **Create from template** tab, select the **Instance** tab or the **Group** tab. +1. From the list of available custom templates, click the: + - **Preview** button to look at the template source itself. + - **Use template** button to start creating the project. +1. Finish creating the project by filling out the project's details. The process is + the same as creating a [blank project](#blank-projects). + +## Push to create a new project + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26388) in GitLab 10.5. + +When you create a new repository locally, instead of manually creating a new project in GitLab +and then [cloning the repository](../../gitlab-basics/start-using-git.md#clone-a-repository) +locally, you can directly push it to GitLab to create the new project, all without leaving +your terminal. If you have access rights to the associated namespace, GitLab +automatically creates a new project under that GitLab namespace with its visibility +set to Private by default (you can later change it in the [project's settings](../../public_access/public_access.md#how-to-change-project-visibility)). + +This can be done by using either SSH or HTTPS: + +```shell +## Git push using SSH +git push --set-upstream git@gitlab.example.com:namespace/nonexistent-project.git master + +## Git push using HTTPS +git push --set-upstream https://gitlab.example.com/namespace/nonexistent-project.git master +``` + +You can pass the flag `--tags` to the `git push` command to export existing repository tags. + +Once the push finishes successfully, a remote message indicates +the command to set the remote and the URL to the new project: + +```plaintext +remote: +remote: The private project namespace/nonexistent-project was created. +remote: +remote: To configure the remote, run: +remote: git remote add origin https://gitlab.example.com/namespace/nonexistent-project.git +remote: +remote: To view the project, visit: +remote: https://gitlab.example.com/namespace/nonexistent-project +remote: +``` + +## Fork a project + +A fork is a copy of an original repository that you put in another namespace +where you can experiment and apply changes that you can later decide whether or +not to share, without affecting the original project. + +It takes just a few steps to [fork a project in GitLab](repository/forking_workflow.md#creating-a-fork). + +## Star a project + +You can star a project to make it easier to find projects you frequently use. +The number of stars a project has can indicate its popularity. + +To star a project: + +1. Go to the home page of the project you want to star. +1. In the upper right corner of the page, click **Star**. + +To view your starred projects: + +1. Click **Projects** in the navigation bar. +1. Click **Starred Projects**. +1. GitLab displays information about your starred projects, including: + + - Project description, including name, description, and icon + - Number of times this project has been starred + - Number of times this project has been forked + - Number of open merge requests + - Number of open issues + +## Delete a project + +To delete a project, first navigate to the home page for that project. + +1. Navigate to **Settings > General**. +1. Expand the **Advanced** section. +1. Scroll down to the **Delete project** section. +1. Click **Delete project** +1. Confirm this action by typing in the expected text. + +Projects in personal namespaces are deleted immediately on request. For information on delayed deletion of projects in a group, please see [Enabling delayed project removal](../group/index.md#enabling-delayed-project-removal). + +## Project settings + +Set the project's visibility level and the access levels to its various pages +and perform actions like archiving, renaming or transferring a project. + +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**. + +### Leave a project + +**Leave project** only displays on the project's dashboard +when a project is part of a group (under a +[group namespace](../group/index.md#namespaces)). +If you choose to leave a project you are no longer a project +member, and cannot contribute. + +## Use your project as a Go package + +Any project can be used as a Go package. GitLab responds correctly to `go get` +and `godoc.org` discovery requests, including the +[`go-import`](https://golang.org/cmd/go/#hdr-Remote_import_paths) and +[`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) meta tags. + +Private projects, including projects in subgroups, can be used as a Go package, +but may require configuration to work correctly. GitLab responds correctly +to `go get` discovery requests for projects that *are not* in subgroups, +regardless of authentication or authorization. +[Authentication](#authenticate-go-requests) is required to use a private project +in a subgroup as a Go package. Otherwise, GitLab truncates the path for +private projects in subgroups to the first two segments, causing `go get` to +fail. + +GitLab implements its own Go proxy. This feature must be enabled by an +administrator and requires additional configuration. See [GitLab Go +Proxy](../packages/go_proxy/index.md). + +### Disable Go module features for private projects + +In Go 1.12 and later, Go queries module proxies and checksum databases in the +process of [fetching a +module](../../development/go_guide/dependencies.md#fetching). This can be +selectively disabled with `GOPRIVATE` (disable both), +[`GONOPROXY`](../../development/go_guide/dependencies.md#proxies) (disable proxy +queries), and [`GONOSUMDB`](../../development/go_guide/dependencies.md#fetching) +(disable checksum queries). + +`GOPRIVATE`, `GONOPROXY`, and `GONOSUMDB` are comma-separated lists of Go +modules and Go module prefixes. For example, +`GOPRIVATE=gitlab.example.com/my/private/project` disables queries for that +one project, but `GOPRIVATE=gitlab.example.com` disables queries for *all* +projects on GitLab.com. Go does not query module proxies if the module name or a +prefix of it appears in `GOPRIVATE` or `GONOPROXY`. Go does not query checksum +databases if the module name or a prefix of it appears in `GONOPRIVATE` or +`GONOSUMDB`. + +### Authenticate Go requests + +To authenticate requests to private projects made by Go, use a [`.netrc` +file](https://ec.haxx.se/usingcurl-netrc.html) and a [personal access +token](../profile/personal_access_tokens.md) in the password field. **This only +works if your GitLab instance can be accessed with HTTPS.** The `go` command +does not transmit credentials over insecure connections. This authenticates +all HTTPS requests made directly by Go, but does not authenticate requests made +through Git. + +For example: + +```plaintext +machine gitlab.example.com +login <gitlab_user_name> +password <personal_access_token> +``` + +NOTE: +On Windows, Go reads `~/_netrc` instead of `~/.netrc`. + +### Authenticate Git fetches + +If a module cannot be fetched from a proxy, Go falls back to using Git (for +GitLab projects). Git uses `.netrc` to authenticate requests. You can also +configure Git to either: + +- Embed specific credentials in the request URL. +- Use SSH instead of HTTPS, as Go always uses HTTPS to fetch Git repositories. + +```shell +# Embed credentials in any request to GitLab.com: +git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com" + +# Use SSH instead of HTTPS: +git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com" +``` + +## Access project page with project ID + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53671) in GitLab 11.8. + +To quickly access a project from the GitLab UI using the project ID, +visit the `/projects/:id` URL in your browser or other tool accessing the project. + +## Project's landing page + +The project's landing page shows different information depending on +the project's visibility settings and user permissions. + +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) + 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 + visitor sees the list of files and directories of the repository. + +For users without permissions to view the project's code, GitLab displays: + +- The wiki homepage, if any. +- The list of issues in the project. diff --git a/doc/user/search/advanced_global_search.md b/doc/user/search/advanced_global_search.md index 1898bdf06a9..2d1a05cd966 100644 --- a/doc/user/search/advanced_global_search.md +++ b/doc/user/search/advanced_global_search.md @@ -5,9 +5,10 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Advanced Search **(STARTER)** +# Advanced Search **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109) in GitLab [Starter](https://about.gitlab.com/pricing/) 8.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109) in GitLab 8.4. +> - [Moved](../../subscriptions/bronze_starter.md) to GitLab Premium in 13.9. NOTE: Advanced Search (powered by Elasticsearch) is enabled for Bronze and above on GitLab.com since 2020-07-10. diff --git a/doc/user/search/advanced_search_syntax.md b/doc/user/search/advanced_search_syntax.md index e3501be8e8e..19f7305124e 100644 --- a/doc/user/search/advanced_search_syntax.md +++ b/doc/user/search/advanced_search_syntax.md @@ -5,12 +5,10 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference --- -# Advanced Search Syntax **(STARTER)** +# Advanced Search Syntax **(PREMIUM)** -> - Introduced in [GitLab Enterprise Starter](https://about.gitlab.com/pricing/) 9.2 - -NOTE: -Advanced Search (powered by Elasticsearch) is enabled for Bronze and above on GitLab.com since 2020-07-10. +> - Introduced in [GitLab](https://about.gitlab.com/pricing/) 9.2. +> - [Moved](../../subscriptions/bronze_starter.md) to GitLab Premium in 13.9. Use advanced queries for more targeted search results. diff --git a/doc/user/search/img/search_history.gif b/doc/user/search/img/search_history.gif Binary files differdeleted file mode 100644 index 4cfa48ee0ab..00000000000 --- a/doc/user/search/img/search_history.gif +++ /dev/null diff --git a/doc/user/search/index.md b/doc/user/search/index.md index d229c27b608..ffd331248be 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -9,16 +9,14 @@ type: index, reference, howto ## Issues and merge requests -To search through issues and merge requests in multiple projects, you can use the **Issues** or **Merge Requests** links -in the top-right part of your screen. +To search through issues and merge requests in multiple projects, use the **Issues** or **Merge Requests** links +in the top-right part of your screen. These instructions are valid for both. -Both of them work in the same way, therefore, the following notes are valid for both. - -The number displayed on their right represents the number of issues and merge requests assigned to you. +The number displayed on their right represents the number of issues and merge requests assigned to you:  -When you click **Issues**, the opened issues assigned to you are shown straight away: +When you click **Issues**, GitLab shows the opened issues assigned to you:  @@ -30,7 +28,7 @@ You can also filter the results using the search and filter field, as described ### Issues and MRs assigned to you or created by you GitLab shows shortcuts to issues and merge requests created by you or assigned to you -on the search field on the top-right of your screen: +in the search field in the upper right corner:  @@ -38,7 +36,7 @@ on the search field on the top-right of your screen: > - Filtering by Epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195704) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. > - Filtering by child Epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9029) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. -> - Filtering by Iterations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6. +> - Filtering by Iterations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6. [Moved](../../subscriptions/bronze_starter.md) to GitLab Premium in 13.9. Follow these steps to filter the **Issues** and **Merge Requests** list pages in projects and groups: @@ -101,32 +99,34 @@ You can filter the **Issues** list to individual instances by their ID. For exam  -### Filtering merge requests by approvers **(STARTER)** +### Filtering merge requests by approvers **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9468) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9468) in GitLab 11.9. +> - [Moved](../../subscriptions/bronze_starter.md) to GitLab Premium in 13.9. To filter merge requests by an individual approver, you can type (or select from the dropdown) **Approver** and select the user.  -### Filtering merge requests by "approved by" **(STARTER)** +### Filtering merge requests by "approved by" **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30335) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30335) in GitLab 13.0. +> - [Moved](../../subscriptions/bronze_starter.md) to GitLab Premium in 13.9. To filter merge requests already approved by a specific individual, you can type (or select from the dropdown) **Approved-By** and select the user.  -### Filtering merge requests by reviewer **(CORE)** +### Filtering merge requests by reviewer **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47605) in GitLab 13.7. To filter review requested merge requests for a specific individual, you can type (or select from the dropdown) **Reviewer** and select the user. -### Filtering merge requests by environment or deployment date **(CORE)** +### Filtering merge requests by environment or deployment date **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44041) in GitLab 13.6. @@ -156,15 +156,16 @@ using the filter functionality, you can start typing characters to bring up relevant users or other attributes. For performance optimization, there is a requirement of a minimum of three -characters to begin your search. For example, if you want to search for -issues that have the assignee "Simone Presley", you must type at -least "Sim" before autocomplete gives any relevant results. +characters to begin your search. To search for issues with the assignee `Simone Presley`, +you must type at least `Sim` before autocomplete displays results. ## Search history -You can view recent searches by clicking on the little arrow-clock icon, which is to the left of the search input. Click the search entry to run that search again. This feature is available for issues and merge requests. Searches are stored locally in your browser. +Search history is available for issues and merge requests, and is stored locally +in your browser. To run a search from history: - +1. In the top menu, click **Issues** or **Merge requests**. +1. To the left of the search bar, click **Recent searches**, and select a search from the list. ## Removing search filters @@ -174,7 +175,7 @@ To delete filter tokens one at a time, the <kbd>⌥</kbd> (Mac) / <kbd>Control</ ## Filtering with multiple filters of the same type -Some filters can be added multiple times. These include but are not limited to assignees and labels. When you filter with these multiple filters of the same type, the AND logic is applied. For example, if you were filtering `assignee:@sam assignee:@sarah`, your results include only entries whereby the assignees are assigned to both Sam and Sarah are returned. +Some filters can be added multiple times. These include but are not limited to assignees and labels. When you filter with these multiple filters of the same type, the `AND` logic is applied. For example, if you were filtering `assignee:@sam assignee:@sarah`, your results include only entries whereby the assignees are assigned to both Sam and Sarah are returned.  @@ -192,8 +193,8 @@ You can search through your projects from the left menu, by clicking the menu ba On the field **Filter by name**, type the project or group name you want to find, and GitLab filters them for you as you type. -You can also look for the projects you [starred](../project/index.md#star-a-project) (**Starred projects**), and **Explore** all -public and internal projects available in GitLab.com, from which you can filter by visibility, +You can also look for the projects you [starred](../project/working_with_projects.md#star-a-project) (**Starred projects**). +You can **Explore** all public and internal projects available in GitLab.com, from which you can filter by visibility, through **Trending**, best rated with **Most stars**, or **All** of them. You can also sort them by **Name**, **Last created**, **Oldest created**, **Last updated**, @@ -217,7 +218,7 @@ and sort them by **Last created**, **Oldest created**, **Last updated**, or **Ol From an [Issue Board](../../user/project/issue_board.md), you can filter issues by **Author**, **Assignee**, **Milestone**, and **Labels**. You can also filter them by name (issue title), from the field **Filter by name**, which is loaded as you type. -When you want to search for issues to add to lists present in your Issue Board, click +To search for issues to add to lists present in your Issue Board, click the button **Add issues** on the top-right of your screen, opening a modal window from which you can, besides filtering them by **Name**, **Author**, **Assignee**, **Milestone**, and **Labels**, select multiple issues to add to a list of your choice: @@ -226,10 +227,14 @@ and **Labels**, select multiple issues to add to a list of your choice: ## Shortcut -GitLab shows a shortcut on the search field on the top-right of the project's dashboard to -quickly access issues and merge requests created or assigned to you in that project: +To view issues and merge requests created or assigned to you in a project: + +1. Go to your project. +1. In the top navigation bar, click the search box to display a list of issues and + merge requests. +1. Select your desired issue or merge request: - +  ### Autocomplete suggestions @@ -246,7 +251,7 @@ You can also type in this search bar to see autocomplete suggestions for: ## Basic search -The Basic search in GitLab is a global search service that allows you to search +The Basic search in GitLab enables you to search across the entire GitLab instance, in a group, or in a single project. Basic search is backed by the database and allows searching in: @@ -288,14 +293,14 @@ redirected to the commit result and given the option to return to the search res  -## Advanced Search **(STARTER)** +## Advanced Search **(PREMIUM)** Leverage Elasticsearch for faster, more advanced code search across your entire GitLab instance. [Learn how to use the Advanced Search.](advanced_global_search.md) -## Advanced Search Syntax **(STARTER)** +## Advanced Search Syntax **(PREMIUM)** Use advanced queries for more targeted search results. @@ -307,7 +312,7 @@ Use advanced queries for more targeted search results. > - 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-search-project-settings). **(CORE ONLY)** +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-search-project-settings). **(FREE SELF)** WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -318,7 +323,7 @@ appear highlighted in the sections that match the search term.  -### Enable or disable Search project settings **(CORE ONLY)** +### Enable or disable Search project settings **(FREE SELF)** Search project settings is under development and not ready for production use. It is deployed behind a feature flag that is **disabled by default**. diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index 282e3296735..014555cffed 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -35,6 +35,7 @@ These shortcuts are available in most areas of GitLab | <kbd>Shift</kbd> + <kbd>m</kbd> | Go to your Merge requests page.| | <kbd>Shift</kbd> + <kbd>t</kbd> | Go to your To-Do List page. | | <kbd>p</kbd> + <kbd>b</kbd> | Show/hide the Performance Bar. | +| <kbd>g</kbd> + <kbd>x</kbd> | Toggle between [GitLab](https://gitlab.com/) and [GitLab Next](https://next.gitlab.com/) (GitLab SaaS only). | Additionally, the following shortcuts are available when editing text in text fields, for example comments, replies, issue descriptions, and merge request descriptions: @@ -42,10 +43,10 @@ for example comments, replies, issue descriptions, and merge request description | Keyboard Shortcut | Description | | ---------------------------------------------------------------------- | ----------- | | <kbd>↑</kbd> | Edit your last comment. You must be in a blank text field below a thread, and you must already have at least one comment in the thread. | -| <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd> | Toggle Markdown preview, when editing text in a text field that has **Write** and **Preview** tabs at the top. | -| <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>b</kbd> | Bold the selected text (surround it with `**`). | -| <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>i</kbd> | Italicize the selected text (surround it with `_`). | -| <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>k</kbd> | Add a link (surround the selected text with `[]()`). | +| <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd> | Toggle Markdown preview, when editing text in a text field that has **Write** and **Preview** tabs at the top. | +| <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>b</kbd> | Bold the selected text (surround it with `**`). | +| <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>i</kbd> | Italicize the selected text (surround it with `_`). | +| <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>k</kbd> | Add a link (surround the selected text with `[]()`). | NOTE: The shortcuts for editing in text fields are always enabled, even when @@ -104,7 +105,7 @@ These shortcuts are available when browsing the files in a project (navigate to | <kbd>↑</kbd> | Move selection up. | | <kbd>↓</kbd> | Move selection down. | | <kbd>enter</kbd> | Open selection. | -| <kbd>esc</kbd> | Go back to file list screen (only while searching for files, **Repository > Files** then click on **Find File**). | +| <kbd>Escape</kbd> | Go back to file list screen (only while searching for files, **Repository > Files** then click on **Find File**). | | <kbd>y</kbd> | Go to file permalink (only while viewing a file). | ### Web IDE @@ -113,8 +114,8 @@ These shortcuts are available when editing a file with the [Web IDE](project/web | Keyboard Shortcut | Description | | ------------------------------------------------------- | ----------- | -| <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>p</kbd> | Search for, and then open another file for editing. | -| <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>Enter</kbd> | Commit (when editing the commit message). | +| <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>p</kbd> | Search for, and then open another file for editing. | +| <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>Enter</kbd> | Commit (when editing the commit message). | ### Repository Graph @@ -145,7 +146,7 @@ These shortcuts are available when using a [filtered search input](search/index. | Keyboard Shortcut | Description | | ----------------------------------------------------- | ----------- | | <kbd>⌘</kbd> (Mac) + <kbd>⌫</kbd> | Clear entire search filter. | -| <kbd>⌥</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>⌫</kbd> | Clear one token at a time. | +| <kbd>⌥</kbd> (Mac) / <kbd>Control</kbd> + <kbd>⌫</kbd> | Clear one token at a time. | ## Epics **(ULTIMATE)** diff --git a/doc/user/snippets.md b/doc/user/snippets.md index af499221da6..e919e73f404 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -65,8 +65,8 @@ have version control enabled by default. This means that all snippets get their own underlying repository initialized with a `master` branch at the moment the snippet is created. Whenever a change to the snippet is saved, a -new commit to the master branch is recorded. Commit messages are automatically -generated. The snippet's repository has only one branch (master) by default, deleting +new commit to the `master` branch is recorded. Commit messages are automatically +generated. The snippet's repository has only one branch (`master`) by default, deleting it or creating other branches is not supported. Existing snippets are automatically migrated in 13.0. Their current @@ -75,14 +75,14 @@ content is saved as the initial commit to the snippets' repository. ### Filenames Snippets support syntax highlighting based on the filename and -extension provided for them. While it is possible to submit a snippet +extension provided for them. While you can submit a snippet without specifying a filename and extension, it needs a valid name so the content can be created as a file in the snippet's repository. -In case the user does not attribute a filename and extension to a snippet, -GitLab automatically adds a filename in the format `snippetfile<x>.txt` +If you don't attribute a filename and extension to a snippet, +GitLab adds a filename in the format `snippetfile<x>.txt` where `<x>` represents a number added to the file, starting with 1. This -number increases incrementally when more snippets without an attributed +number increments when more snippets without an attributed filename are added. When upgrading from an earlier version of GitLab to 13.0, existing snippets @@ -96,14 +96,15 @@ direct or embedded links to the snippet. > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2829) in GitLab 13.5. -GitLab Snippets support multiple files in one single snippet. It can be very handy +GitLab Snippets support multiple files in one single snippet. This is helpful when your code snippet is composed of multiple parts or when they relate to a certain context. For example: - A snippet that includes a script and its output. - A snippet that includes HTML, CSS, and JS code. - A snippet with a `docker-compose.yml` file and its associated `.env` file. -- A `gulpfile.js` file coupled with a `package.json` file, which together can be used to bootstrap a project and manage its dependencies. +- A `gulpfile.js` file coupled with a `package.json` file, which together can be + used to bootstrap a project and manage its dependencies. Snippets support between 1 and 10 files. They can be managed via Git (because they're [versioned](#versioned-snippets) by a Git repository), through the [Snippets API](../api/snippets.md), or in the GitLab UI. @@ -135,7 +136,7 @@ button above the snippet content to copy the URL of your choice. This allows you to have a local copy of the snippet's repository and make changes as needed. You can commit those changes and push them to the remote -master branch. +`master` branch. ### Reduce snippets repository size @@ -148,15 +149,15 @@ see the documentation on [reducing repository size](../user/project/repository/r ### Limitations - Binary files are not supported. -- Creating or deleting branches is not supported. Only a default *master* branch is used. +- Creating or deleting branches is not supported. Only a default `master` branch is used. - Git tags are not supported in snippet repositories. - Snippets' repositories are limited to 10 files. Attempting to push more -than 10 files results in an error. -- Revisions are not *yet* visible to the user on the GitLab UI, but -it's planned to be added in future iterations. See the [revisions tab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/39271) -for updates. + than 10 files results in an error. +- Revisions are not visible to the user on the GitLab UI, but this feature is planned + in future iterations. See the [revisions tab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/39271) + for updates. - The [maximum size for a snippet](../administration/snippets/index.md#snippets-content-size-limit) -is 50 MB, by default. + is 50 MB, by default. - Git LFS is not supported. ## Discover snippets @@ -168,10 +169,10 @@ dashboard of your GitLab instance via the top navigation. For GitLab.com you can navigate to an [overview]((https://gitlab.com/dashboard/snippets)) that shows snippets you created and allows you to explore all snippets. -If you want to discover snippets that belong to a specific project, you can navigate +To discover snippets that belong to a specific project, navigate to the Snippets page via the left side navigation on the project page. -Project snippets are enabled and available by default, but they can -be disabled by navigating to your project's **Settings**, expanding +Project snippets are enabled and available by default. You can +disable them by navigating to your project's **Settings**, expanding **Visibility, project features, permissions** and scrolling down to **Snippets**. From there, you can toggle to disable them or select a different visibility level from the dropdown menu. @@ -181,7 +182,7 @@ different visibility level from the dropdown menu. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/12910) in GitLab 9.2. With GitLab Snippets you engage in a conversation about that piece of code, -facilitating the collaboration among users. +encouraging user collaboration. ## Downloading snippets @@ -207,20 +208,23 @@ To embed a snippet, first make sure that: - In **Project > Settings > Permissions**, the snippets permissions are set to **Everyone with access** -After the above conditions are met, the "Embed" section appears in your -snippet where you can simply click on the "Copy" button. This copies a one-line -script that you can add to any website or blog post. - -Here's how an example code looks like: +After the above conditions are met, the **Embed** section appears in your +snippet. Click the **Copy** button to copy a one-line +script that you can add to any website or blog post. For example: ```html <script src="https://gitlab.com/namespace/project/snippets/SNIPPET_ID.js"></script> ``` -Here's how an embedded snippet looks like: +Here's what an embedded snippet looks like: <script src="https://gitlab.com/gitlab-org/gitlab-foss/snippets/1717978.js"></script> -Embedded snippets are displayed with a header that shows the filename if it's defined, -the snippet size, a link to GitLab, and the actual snippet content. Actions in -the header allow users to see the snippet in raw format and download it. +Embedded snippets are displayed with a header that shows: + +- The filename, if defined. +- The snippet size. +- A link to GitLab. +- The actual snippet content. + +Actions in the header enable users to see the snippet in raw format, and download it. diff --git a/doc/user/todos.md b/doc/user/todos.md index 27a849719c5..57ab7d4d888 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -5,7 +5,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab To-Do List **(CORE)** +# GitLab To-Do List **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2817) in GitLab 8.5. diff --git a/doc/user/upgrade_email_bypass.md b/doc/user/upgrade_email_bypass.md index e50b6959a70..183ce5e4312 100644 --- a/doc/user/upgrade_email_bypass.md +++ b/doc/user/upgrade_email_bypass.md @@ -116,7 +116,7 @@ LDAP Users remain confirmed if all of the following conditions are met: - The ["User email confirmation at sign-up" option](../security/user_email_confirmation.md) is set to false. - The first sign-in is based on user LDAP credentials. -- The user has added and verified [a secondary email address](profile/index.md#profile-settings) some time later. +- The user has added and verified [a secondary email address](profile/index.md#user-settings) some time later. NOTE: Confirmation timestamps (primary vs. secondary) are different. @@ -124,6 +124,6 @@ Confirmation timestamps (primary vs. secondary) are different. Users remain unconfirmed by the background migration if any of the following conditions are met: - They [create an account through GitLab](profile/account/create_accounts.md). -- They [swap their primary email address](profile/index.md#profile-settings) and verify it. +- They [swap their primary email address](profile/index.md#user-settings) and verify it. - If they have two email addresses with the same `confirmed_at` timestamp due to the linked [security issue](https://gitlab.com/gitlab-org/gitlab/-/issues/121664). - [LDAP is introduced](../administration/auth/ldap/index.md), and users' primary email address matches that in LDAP. diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index 8662efc03a7..16ba2582101 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -1,13 +1,13 @@ --- type: howto stage: Fulfillment -group: Provision +group: Utilization 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 --- # Storage usage quota -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/13294) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/13294) in GitLab 12.0. > - Moved to GitLab Free. A project's repository has a free storage quota of 10 GB. When a project's repository reaches @@ -32,11 +32,11 @@ namespace to trigger a recalculation. A stacked bar graph shows the proportional storage used for the namespace, including a total per storage item. Click on each project's title to see a breakdown per storage item. -## Storage usage statistics **(BRONZE ONLY)** +## Storage usage statistics > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247831) in GitLab 13.7. > - It's [deployed behind a feature flag](../user/feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. +> - It's enabled on GitLab SaaS. > - It's recommended for production use. WARNING: |
