diff options
Diffstat (limited to 'doc/user')
436 files changed, 4914 insertions, 3306 deletions
diff --git a/doc/user/abuse_reports.md b/doc/user/abuse_reports.md index 155f45f087f..935fca8209f 100644 --- a/doc/user/abuse_reports.md +++ b/doc/user/abuse_reports.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Abuse reports @@ -38,8 +38,8 @@ To report abuse from a user's comment: 1. Complete an abuse report. 1. Click the **Send report** button. -NOTE: **Note:** -A URL to the reported user's comment will be pre-filled in the abuse report's +NOTE: +A URL to the reported user's comment is pre-filled in the abuse report's **Message** field. ## Reporting abuse through a user's issue or merge request @@ -58,8 +58,8 @@ With the **Report abuse** button displayed, to submit an abuse report: 1. Submit an abuse report. 1. Click the **Send report** button. -NOTE: **Note:** -A URL to the reported user's issue or merge request will be pre-filled +NOTE: +A URL to the reported user's issue or merge request is pre-filled in the abuse report's **Message** field. ## Managing abuse reports diff --git a/doc/user/account/security.md b/doc/user/account/security.md index 8a8edc23529..d9db3a25c00 100644 --- a/doc/user/account/security.md +++ b/doc/user/account/security.md @@ -3,3 +3,6 @@ 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 index 42a66becc50..b085611f747 100644 --- a/doc/user/account/two_factor_authentication.md +++ b/doc/user/account/two_factor_authentication.md @@ -3,3 +3,6 @@ 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 4c346d7dfe8..62f3bd3625c 100644 --- a/doc/user/admin_area/abuse_reports.md +++ b/doc/user/admin_area/abuse_reports.md @@ -1,7 +1,7 @@ --- stage: Manage group: Access -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -73,7 +73,7 @@ page:  -NOTE: **Note:** +NOTE: Users can be [blocked](../../api/users.md#block-user) and [unblocked](../../api/users.md#unblock-user) using the GitLab API. diff --git a/doc/user/admin_area/activating_deactivating_users.md b/doc/user/admin_area/activating_deactivating_users.md index 96b39ae7116..1bca1751d2e 100644 --- a/doc/user/admin_area/activating_deactivating_users.md +++ b/doc/user/admin_area/activating_deactivating_users.md @@ -1,7 +1,7 @@ --- stage: Manage group: Access -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -43,7 +43,7 @@ Please note that for the deactivation option to be visible to an admin, the user Users can also be deactivated using the [GitLab API](../../api/users.md#deactivate-user). -NOTE: **Note:** +NOTE: A deactivated user does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). ## Activating a user @@ -61,9 +61,9 @@ To do this: Users can also be activated using the [GitLab API](../../api/users.md#activate-user). -NOTE: **Note:** +NOTE: Activating a user changes the user's state to active and consumes a [seat](../../subscriptions/self_managed/index.md#billable-users). -TIP: **Tip:** +NOTE: A deactivated user can also activate their account themselves by simply logging back in via the UI. diff --git a/doc/user/admin_area/analytics/convdev.md b/doc/user/admin_area/analytics/convdev.md index 3ffda3f4400..d0f3a34e15e 100644 --- a/doc/user/admin_area/analytics/convdev.md +++ b/doc/user/admin_area/analytics/convdev.md @@ -3,3 +3,6 @@ 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 d1f80e63c04..8f629fd4250 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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)** @@ -9,20 +9,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [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. -NOTE: **Note:** -Your GitLab instance's [usage ping](../settings/usage_statistics.md#usage-ping) must be activated in order to use this feature. - The DevOps Report gives you an overview of your entire instance's adoption of [Concurrent DevOps](https://about.gitlab.com/topics/concurrent-devops/) from planning to monitoring. To see DevOps Report, go to **Admin Area > Analytics > DevOps Report**. -## DevOps Score +## DevOps Score **(CORE)** -DevOps Score displays the usage of GitLab's major features on your instance over -the last 30 days, averaged over the number of active users in that time period. It also -provides a Lead score per feature, which is calculated based on GitLab's analysis +NOTE: +Your GitLab instance's [usage ping](../settings/usage_statistics.md#usage-ping) must be activated in order to use this feature. + +The DevOps Score tab displays the usage of major GitLab features on your instance over +the last 30 days, averaged over the number of billable users in that time period. It also +provides a Lead score per feature, which is calculated based on GitLab analysis of top-performing instances based on [usage ping data](../settings/usage_statistics.md#usage-ping) that GitLab has collected. Your score is compared to the lead score of each feature and then expressed as a percentage at the bottom of said feature. Your overall **DevOps Score** is an average of your feature scores. You can use this score to compare your DevOps status to other organizations. @@ -32,6 +32,48 @@ Your overall **DevOps Score** is an average of your feature scores. You can use The page also provides helpful links to articles and GitLab docs, to help you improve your scores. -Usage ping data is aggregated on GitLab's servers for analysis. Your usage +Usage ping data is aggregated on GitLab servers for analysis. Your usage information is **not sent** to any other GitLab instances. If you have just started using GitLab, it may take a few weeks for data to be collected before this feature is available. + +## DevOps Adoption **(ULTIMATE)** + +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247112) in GitLab 13.7. + +The DevOps Adoption tab shows you which segments of your organization are using the most essential features of GitLab: + +- Issues +- Merge Requests +- Approvals +- Runners +- Pipelines +- 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. + +DevOps Adoption allows you to: + +- Verify whether you are getting the return on investment that you expected from GitLab. +- Identify specific groups that are lagging in their adoption of GitLab so you can help them along in their DevOps journey. +- Find the groups that have adopted certain features and can provide guidance to other groups on how to use those features. + + + +### Disable or enable DevOps Adoption + +DevOps Adoption is deployed behind a feature flag that is **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(:devops_adoption_feature) +``` + +To enable it: + +```ruby +Feature.enable(:devops_adoption_feature) +``` 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 differnew file mode 100644 index 00000000000..0f1f16bead6 --- /dev/null +++ b/doc/user/admin_area/analytics/img/dev_ops_adoption_v13_7.png diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md index 3d53cd73dd2..098d758e42a 100644 --- a/doc/user/admin_area/analytics/index.md +++ b/doc/user/admin_area/analytics/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Instance-level analytics diff --git a/doc/user/admin_area/analytics/instance_statistics.md b/doc/user/admin_area/analytics/instance_statistics.md new file mode 100644 index 00000000000..44fd04198b1 --- /dev/null +++ b/doc/user/admin_area/analytics/instance_statistics.md @@ -0,0 +1,5 @@ +--- +redirect_to: 'usage_trends.md' +--- + +This document was moved to [another location](usage_trends.md). diff --git a/doc/user/admin_area/analytics/usage_trends.md b/doc/user/admin_area/analytics/usage_trends.md index cf12f1f24c6..aeb577b8183 100644 --- a/doc/user/admin_area/analytics/usage_trends.md +++ b/doc/user/admin_area/analytics/usage_trends.md @@ -1,7 +1,7 @@ --- stage: Manage -group: Value Stream 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/#designated-technical-writers +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)** @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - It's enabled on GitLab.com. > - It's recommended for production use. -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. Usage Trends gives you an overview of how much data your instance contains, and how quickly this volume is changing over time. diff --git a/doc/user/admin_area/analytics/user_cohorts.md b/doc/user/admin_area/analytics/user_cohorts.md index c9b62e258ae..1d2d0029860 100644 --- a/doc/user/admin_area/analytics/user_cohorts.md +++ b/doc/user/admin_area/analytics/user_cohorts.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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)** diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index 23a6de38e17..b7f5afe7b70 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto disqus_identifier: 'https://docs.gitlab.com/ee/customization/branded_login_page.html' --- @@ -16,15 +16,15 @@ section. By default, the navigation bar has the GitLab logo, but this can be customized with any image desired. It is optimized for images 28px high (any width), but any image can be -used (less than 1MB) and it will automatically be resized. +used (less than 1MB) and it is automatically resized.  Once you select and upload an image, click **Update appearance settings** at the bottom of the page to activate it in the GitLab instance. -NOTE: **Note:** -GitLab pipeline emails will also display the custom logo. +NOTE: +GitLab pipeline emails also display the custom logo. ## Favicon @@ -45,7 +45,7 @@ of the page to activate it in the GitLab instance. > - [Added](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55057) to [GitLab Core](https://about.gitlab.com/pricing/) 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 will appear on all projects and pages of the +of your GitLab instance. These messages appear on all projects and pages of the instance, including the sign in / sign up page. The default color is white text on an orange background, but this can be customized by clicking on **Customize colors**. @@ -69,7 +69,7 @@ and logo. You can make full use of [Markdown](../markdown.md) in the description  The optimal size for the logo is 640x360px, but any image can be used (below 1MB) -and it will be resized automatically. The logo image will appear between the title and +and it is resized automatically. The logo image appears between the title and the description, on the left of the sign-up page.  @@ -78,7 +78,7 @@ After you add a message, click **Update appearance settings** at the bottom of t to activate it in the GitLab instance. You can also click on the **Sign-in page** button, to review the saved appearance settings: -NOTE: **Note:** +NOTE: You can add also add a [customized help message](settings/help_page.md) below the sign in message or add [a Sign in text message](settings/sign_in_restrictions.md#sign-in-information). ## New project pages @@ -88,12 +88,12 @@ You can make full use of [Markdown](../markdown.md) in the description:  -The message will be displayed below the **New Project** message, on the left side +The message is displayed below the **New Project** message, on the left side of the **New project page**. After you add a message, click **Update appearance settings** at the bottom of the page to activate it in the GitLab instance. You can also click on the **New project page** -button, which will bring you to the new project page so you can review the change. +button, which brings you to the new project page so you can review the change.  diff --git a/doc/user/admin_area/approving_users.md b/doc/user/admin_area/approving_users.md index 430ad4f8899..af4d4e86e69 100644 --- a/doc/user/admin_area/approving_users.md +++ b/doc/user/admin_area/approving_users.md @@ -1,7 +1,7 @@ --- stage: Manage group: Access -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- diff --git a/doc/user/admin_area/blocking_unblocking_users.md b/doc/user/admin_area/blocking_unblocking_users.md index 989182db423..1dba9e5adda 100644 --- a/doc/user/admin_area/blocking_unblocking_users.md +++ b/doc/user/admin_area/blocking_unblocking_users.md @@ -1,7 +1,7 @@ --- stage: Manage group: Access -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -32,7 +32,7 @@ Personal projects, and group and user history of the blocked user are left intac Users can also be blocked using the [GitLab API](../../api/users.md#block-user). -NOTE: **Note:** +NOTE: A blocked user does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). ## Unblocking a user @@ -46,6 +46,6 @@ A blocked user can be unblocked from the Admin Area. To do this: Users can also be unblocked using the [GitLab API](../../api/users.md#unblock-user). -NOTE: **Note:** +NOTE: Unblocking a user changes the user's state to active and consumes a [seat](../../subscriptions/self_managed/index.md#billable-users). diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index 0bbdf5bc5e7..c96c57a99eb 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -47,13 +47,13 @@ The available placeholders are: - `{{username}}` - `{{instance_id}}` -If the user is not signed in, user related values will be empty. +If the user is not signed in, user related values are empty.  Broadcast messages can be managed using the [broadcast messages API](../../api/broadcast_messages.md). -NOTE: **Note:** +NOTE: If more than one banner message is active at one time, they are displayed in a stack in order of creation. If more than one notification message is active at one time, only the newest is shown. @@ -70,12 +70,12 @@ To add a broadcast message: 1. Select a date for the message to start and end. 1. Click the **Add broadcast message** button. -NOTE: **Note:** +NOTE: The **Background color** field expects the value to be a hexadecimal code because the form uses the [color_field](https://api.rubyonrails.org/v6.0.3.4/classes/ActionView/Helpers/FormHelper.html#method-i-color_field) helper method, which generates the proper HTML to render. -NOTE: **Note:** +NOTE: Once a broadcast message has expired, it is no longer displayed in the UI but is still listed in the list of broadcast messages. User can also dismiss a broadcast message if the option **Dismissable** is set. @@ -89,7 +89,7 @@ To edit a broadcast message: 1. From the list of broadcast messages, click the appropriate button to edit the message. 1. After making the required changes, click the **Update broadcast message** button. -TIP: **Tip:** +NOTE: Expired messages can be made active again by changing their end date. ## Deleting a broadcast message @@ -103,7 +103,7 @@ To delete a broadcast message: Once deleted, the broadcast message is removed from the list of broadcast messages. -NOTE: **Note:** +NOTE: Broadcast messages can be deleted while active. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index fc04f9786b6..70bb070b13e 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -1,7 +1,7 @@ --- stage: Manage group: Access -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index e148c5f063e..a9bc2ecf324 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- @@ -20,10 +20,10 @@ available to the user if they have access to them. For example: - Private projects will be available only if the user is a member of the project. Repository and database information that are copied over to each new project are -identical to the data exported with -[GitLab's Project Import/Export](../project/settings/import_export.md). +identical to the data exported with the +[GitLab Project Import/Export](../project/settings/import_export.md). -NOTE: **Note:** +NOTE: To set project templates at a group level, see [Custom group-level project templates](../group/custom_project_templates.md). @@ -37,7 +37,7 @@ source for an entire GitLab instance by: 1. Selecting a group to use. 1. Pressing **Save changes**. -NOTE: **Note:** +NOTE: Projects below subgroups of the template group are **not** supported. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md index b9bd94e65be..b5fcab58535 100644 --- a/doc/user/admin_area/diff_limits.md +++ b/doc/user/admin_area/diff_limits.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 --- @@ -20,10 +20,10 @@ shown. Patches greater than 10% of this size will be automatically collapsed, and a link to expand the diff will be presented. -NOTE: **Note:** +NOTE: Merge requests and branch comparison views will be affected. -CAUTION: **Caution:** +WARNING: This setting is experimental. An increased maximum will increase resource consumption of your instance. Keep this in mind when adjusting the maximum. diff --git a/doc/user/admin_area/geo_nodes.md b/doc/user/admin_area/geo_nodes.md index 28738ed52f3..81e987d25d6 100644 --- a/doc/user/admin_area/geo_nodes.md +++ b/doc/user/admin_area/geo_nodes.md @@ -1,7 +1,7 @@ --- stage: Enablement group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -64,7 +64,7 @@ which is used by users. Internal URL does not need to be a private address. Internal URL defaults to External URL, but you can customize it under **Admin Area > Geo > Nodes**. -CAUTION: **Warning:** +WARNING: We recommend using an HTTPS connection while configuring the Geo nodes. To avoid breaking communication between **primary** and **secondary** nodes when using HTTPS, customize your Internal URL to point to a load balancer with TLS diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index fd8c72ad081..40cb6bd0853 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- @@ -14,7 +14,7 @@ To access the Admin Area, either: - Click the Admin Area icon (**{admin}**). - Visit `/admin` on your self-managed instance. -NOTE: **Note:** +NOTE: Only admin users can access the Admin Area. ## Admin Area sections @@ -24,7 +24,7 @@ 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 logs](#audit-log). | +| **{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). | | **{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. | @@ -37,7 +37,7 @@ The Admin Area is made up of the following sections: | **{lock}** Credentials **(ULTIMATE ONLY)** | 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's appearance](appearance.md). | +| **{appearance}** Appearance | Customize [GitLab appearance](appearance.md). | | **{settings}** Settings | Modify the [settings](settings/index.md) for your GitLab instance. | ## Admin Dashboard @@ -94,7 +94,7 @@ The list of projects can be sorted by: A user can choose to hide or show archived projects in the list. -In the **Filter by name** field, type the project name you want to find, and GitLab will filter +In the **Filter by name** field, type the project name you want to find, and GitLab filters them as you type. Select from the **Namespace** dropdown to filter only projects in that namespace. @@ -322,6 +322,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 Log **(PREMIUM ONLY)** +### Audit Events **(PREMIUM ONLY)** -The **Audit Log** page lists changes made within the GitLab server. With this information you can control, analyze, and track every change. +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 3c35276b843..cc9735df9d6 100644 --- a/doc/user/admin_area/labels.md +++ b/doc/user/admin_area/labels.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 --- diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index 2b0496b381a..d7710c362e5 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -1,7 +1,7 @@ --- stage: Growth group: Conversion -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -32,7 +32,7 @@ is locked. ## Uploading your license -The very first time you visit your GitLab EE installation signed in as an admin, +The very first time you visit your GitLab EE installation signed in as an administrator, you should see a note urging you to upload a license with a link that takes you to **Admin Area > License**. @@ -75,7 +75,7 @@ You can also specify a custom location and filename for the license: gitlab_rails['initial_license_file'] = "/path/to/license/file" ``` -CAUTION: **Caution:** +WARNING: These methods only add a license at the time of installation. Use the **{admin}** **Admin Area** in the web user interface to renew or upgrade licenses. @@ -94,13 +94,13 @@ You can review the license details at any time in the **License** section of the ## Notification before the license expires One month before the license expires, a message informing about the expiration -date is displayed to GitLab admins. Make sure that you update your +date is displayed to GitLab administrators. Make sure that you update your license, otherwise you miss all the paid features if your license expires. ## What happens when your license expires In case your license expires, GitLab locks down some features like Git pushes, -and issue creation, and displays a message to all admins to inform of the expired license. +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 diff --git a/doc/user/admin_area/merge_requests_approvals.md b/doc/user/admin_area/merge_requests_approvals.md index fb9ca21a214..5264f3b770b 100644 --- a/doc/user/admin_area/merge_requests_approvals.md +++ b/doc/user/admin_area/merge_requests_approvals.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- diff --git a/doc/user/admin_area/monitoring/dev_ops_report.md b/doc/user/admin_area/monitoring/dev_ops_report.md index 9ad9830ed59..2cc9f153de3 100644 --- a/doc/user/admin_area/monitoring/dev_ops_report.md +++ b/doc/user/admin_area/monitoring/dev_ops_report.md @@ -3,3 +3,6 @@ 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 88c98248435..3c08a330b13 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts, howto --- @@ -55,7 +55,7 @@ GET /-/health Example request: ```shell -curl 'https://gitlab.example.com/-/health' +curl "https://gitlab.example.com/-/health" ``` Example response: @@ -70,7 +70,7 @@ The readiness probe checks whether the GitLab instance is ready to accept traffic via Rails Controllers. The check by default does validate only instance-checks. -If the `all=1` parameter is specified, the check will also validate +If the `all=1` parameter is specified, the check also validates the dependent services (Database, Redis, Gitaly etc.) and gives a status for each. @@ -82,7 +82,7 @@ GET /-/readiness?all=1 Example request: ```shell -curl 'https://gitlab.example.com/-/readiness' +curl "https://gitlab.example.com/-/readiness" ``` Example response: @@ -97,7 +97,7 @@ Example response: } ``` -On failure, the endpoint will return a `503` HTTP status code. +On failure, the endpoint returns a `503` HTTP status code. This check does hit the database and Redis if authenticated via `token`. @@ -105,7 +105,7 @@ This check is being exempt from Rack Attack. ## Liveness -DANGER: **Warning:** +WARNING: In GitLab [12.4](https://about.gitlab.com/upcoming-releases/) the response body of the Liveness check was changed to match the example below. @@ -121,12 +121,12 @@ GET /-/liveness Example request: ```shell -curl 'https://gitlab.example.com/-/liveness' +curl "https://gitlab.example.com/-/liveness" ``` Example response: -On success, the endpoint will return a `200` HTTP status code, and a response like below. +On success, the endpoint returns a `200` HTTP status code, and a response like below. ```json { @@ -134,13 +134,13 @@ On success, the endpoint will return a `200` HTTP status code, and a response li } ``` -On failure, the endpoint will return a `503` HTTP status code. +On failure, the endpoint returns a `503` HTTP status code. This check is being exempt from Rack Attack. ## Access token (Deprecated) -NOTE: **Note:** +NOTE: Access token has been deprecated in GitLab 9.4 in favor of [IP whitelist](#ip-whitelist). An access token needs to be provided while accessing the probe endpoints. The current @@ -155,7 +155,7 @@ The access token can be passed as a URL parameter: https://gitlab.example.com/-/readiness?token=ACCESS_TOKEN ``` -NOTE: **Note:** +NOTE: In case the database or Redis service are inaccessible, the probe endpoints response is not guaranteed to be correct. You should switch to [IP whitelist](#ip-whitelist) from deprecated access token to avoid it. 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 97c74483cc3..bc266216714 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +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 --- @@ -13,7 +13,7 @@ You can change the maximum file size for attachments in comments and replies in Navigate to **Admin Area (wrench icon) > Settings > General**, then expand **Account and Limit**. From here, you can increase or decrease by changing the value in `Maximum attachment size (MB)`. -NOTE: **Note:** +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 details. @@ -30,11 +30,30 @@ You can change the maximum file size for imports in GitLab. Navigate to **Admin Area (wrench icon) > Settings > General**, then expand **Account and Limit**. From here, you can increase or decrease by changing the value in `Maximum import size (MB)`. -NOTE: **Note:** +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 details. +## Personal Access Token prefix + +You can set a global prefix for all generated Personal Access Tokens. + +A prefix can help you identify PATs visually, as well as with automation tools. + +### Setting a prefix + +Only a GitLab administrator can set the prefix, which is a global setting applied +to any PAT generated in the system by any user: + +1. Navigate to **Admin Area > Settings > General**. +1. Expand the **Account and limit** section. +1. Fill in the **Personal Access Token prefix** field. +1. Click **Save changes**. + +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)** > [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). @@ -71,7 +90,7 @@ These settings can be found within: 1. From the Group's homepage, navigate to **Settings > General**. 1. Fill in the **Repository size limit (MB)** field in the **Naming, visibility** section. 1. Click **Save changes**. -- GitLab's global settings: +- GitLab global settings: 1. From the Dashboard, navigate to **Admin Area > Settings > General**. 1. Expand the **Account and limit** section. 1. Fill in the **Size limit per repository (MB)** field. @@ -81,13 +100,13 @@ 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. -NOTE: **Note:** +NOTE: The repository size limit includes repository files and LFS, but does not include artifacts, uploads, wiki, packages, or snippets. For details on manually purging files, see [reducing the repository size using Git](../../project/repository/reducing_the_repo_size_using_git.md). -NOTE: **Note:** +NOTE: For GitLab.com repository size limits, see [accounts and limit settings](../../gitlab_com/index.md#account-and-limit-settings). ## Troubleshooting @@ -182,5 +201,5 @@ To do this: 1. Navigate to **Admin Area > Settings > General**, then expand **Account and Limit**. 1. Check the **Prevent users from changing their profile name** checkbox. -NOTE: **Note:** +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) diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index b4867d33644..ef2eb046c21 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -1,7 +1,7 @@ --- stage: Verify group: Continuous Integration -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 +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 --- @@ -62,7 +62,7 @@ To change it at the: 1. Change the value of **maximum artifacts size (in MB)**. 1. Click **Save changes** for the changes to take effect. -NOTE: **Note:** +NOTE: The setting at all levels is only available to GitLab administrators. ## Default artifacts expiration **(CORE ONLY)** @@ -80,7 +80,7 @@ This setting is set per job and can be overridden in [`.gitlab-ci.yml`](../../../ci/yaml/README.md#artifactsexpire_in). To disable the expiration, set it to `0`. The default unit is in seconds. -NOTE: **Note:** +NOTE: Any changes to this setting will apply to new artifacts only. The expiration time will not be updated for artifacts created before this setting was changed. The administrator may need to manually search for and expire previously-created @@ -172,7 +172,7 @@ but commented out to help encourage others to add to it in the future. --> ## Required pipeline configuration **(PREMIUM ONLY)** -CAUTION: **Caution:** +WARNING: This feature is being re-evaluated in favor of a different [compliance solution](https://gitlab.com/gitlab-org/gitlab/-/issues/34830). We recommend that users who haven't yet implemented this feature wait for diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index d956364b3ea..4ebfac57715 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -2,10 +2,9 @@ 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/#designated-technical-writers +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)** You can customize some of the content in emails sent from your GitLab instance. @@ -18,7 +17,7 @@ The logo in the header of some emails can be customized, see the [logo customiza > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5031) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.7. -The additional text will appear at the bottom of any email and can be used for +The additional text appears at the bottom of any email and can be used for legal/auditing/compliance reasons. 1. Go to **Admin Area > Settings > Preferences** (`/admin/application_settings/preferences`). @@ -37,10 +36,10 @@ In order to change this option: 1. Go to **Admin Area > Settings > Preferences** (`/admin/application_settings/preferences`). 1. Expand the **Email** section. -1. Enter the desire hostname in the **Custom hostname (for private commit emails)** field. -1. Click **Save changes**. +1. Enter the desired hostname in the **Custom hostname (for private commit emails)** field. +1. Select **Save changes**. -NOTE: **Note:** +NOTE: Once the hostname gets configured, every private commit email using the previous hostname, will not get 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 80bca6f5b2c..18ae7e6f05a 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- @@ -17,30 +17,30 @@ authorization with your own defined service. ## Overview -Once the external service is configured and enabled, when a project is accessed, -a request is made to the external service with the user information and project -classification label assigned to the project. When the service replies with a -known response, the result is cached for 6 hours. +After the external service is configured and enabled, when a project is +accessed, a request is made to the external service with the user information +and project classification label assigned to the project. When the service +replies with a known response, the result is cached for six hours. -If the external authorization is enabled, GitLab will further block pages and +If the external authorization is enabled, GitLab further blocks pages and functionality that render cross-project data. That includes: - Most pages under Dashboard (Activity, Milestones, Snippets, Assigned merge requests, Assigned issues, To-Do List). - Under a specific group (Activity, Contribution analytics, Issues, Issue boards, Labels, Milestones, Merge requests). -- Global and Group search will be disabled. +- Global and Group search are disabled. This is to prevent performing to many requests at once to the external authorization service. Whenever access is granted or denied this is logged in a log file called -`external-policy-access-control.log`. -Read more about logs GitLab keeps in the [omnibus documentation](https://docs.gitlab.com/omnibus/settings/logs.html). +`external-policy-access-control.log`. Read more about the logs GitLab keeps in +the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/logs.html). ## Configuration -The external authorization service can be enabled by an admin on the GitLab's +The external authorization service can be enabled by an administrator on the GitLab **Admin Area > Settings > General** page:  @@ -48,7 +48,7 @@ The external authorization service can be enabled by an admin on the GitLab's The available required properties are: - **Service URL**: The URL to make authorization requests to. When leaving the - URL blank, cross project features will remain available while still being able + URL blank, cross project features remain available while still being able to specify classification labels for projects. - **External authorization request timeout**: The timeout after which an authorization request is aborted. When a request times out, access is denied @@ -58,19 +58,21 @@ The available required properties are: - **Client authentication key**: Private key for the certificate when authentication is required for the external authorization service, this is encrypted when stored. -- **Client authentication key password**: Passphrase to use for the private key when authenticating with the external service this is encrypted when stored. +- **Client authentication key password**: Passphrase to use for the private key + when authenticating with the external service this is encrypted when stored. - **Default classification label**: The classification label to use when requesting authorization if no specific label is defined on the project When using TLS Authentication with a self signed certificate, the CA certificate -needs to be trusted by the OpenSSL installation. When using GitLab installed using -Omnibus, learn to install a custom CA in the -[omnibus documentation](https://docs.gitlab.com/omnibus/settings/ssl.html). Alternatively learn where to install -custom certificates using `openssl version -d`. +needs to be trusted by the OpenSSL installation. When using GitLab installed +using Omnibus, learn to install a custom CA in the +[Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/ssl.html). +Alternatively, learn where to install custom certificates by using +`openssl version -d`. ## How it works -When GitLab requests access, it will send a JSON POST request to the external +When GitLab requests access, it sends a JSON POST request to the external service with this body: ```json @@ -85,14 +87,17 @@ service with this body: } ``` -The `user_ldap_dn` is optional and is only sent when the user is logged in +The `user_ldap_dn` is optional and is only sent when the user is signed in through LDAP. -`identities` will contain the details of all the identities associated with the user. This will be an empty array if there are no identities associated with the user. +`identities` contains the details of all the identities associated with the +user. This is an empty array if there are no identities associated with the +user. When the external authorization service responds with a status code 200, the user is granted access. When the external service responds with a status code -401 or 403, the user is denied access. In any case, the request is cached for 6 hours. +401 or 403, the user is denied access. In any case, the request is cached for +six hours. When denying access, a `reason` can be optionally specified in the JSON body: @@ -102,20 +107,20 @@ When denying access, a `reason` can be optionally specified in the JSON body: } ``` -Any other status code than 200, 401 or 403 will also deny access to the user, but the -response will not be cached. +Any other status code than 200, 401 or 403 also deny access to the user, but the +response isn't cached. If the service times out (after 500ms), a message "External Policy Server did -not respond" will be displayed. +not respond" is displayed. ## Classification labels You can use your own classification label in the project's **Settings > General > General project settings** page in the "Classification label" box. When no classification label is specified on a project, the default -label defined in the [global settings](#configuration) will be used. +label defined in the [global settings](#configuration) is used. -The label will be shown on all project pages in the upper right corner. +The label is shown on all project pages in the upper right corner.  diff --git a/doc/user/admin_area/settings/gitaly_timeouts.md b/doc/user/admin_area/settings/gitaly_timeouts.md index cac05678a1a..d196dc1730e 100644 --- a/doc/user/admin_area/settings/gitaly_timeouts.md +++ b/doc/user/admin_area/settings/gitaly_timeouts.md @@ -1,7 +1,7 @@ --- stage: Create group: Gitaly -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" +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 --- diff --git a/doc/user/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md index c0237c3da73..1ac54bdc037 100644 --- a/doc/user/admin_area/settings/help_page.md +++ b/doc/user/admin_area/settings/help_page.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -13,7 +13,7 @@ to go for help. You can customize and display this information on the GitLab ser ## Adding a help message to the help page -You can add a help message, which will be shown on the GitLab `/help` page (e.g., +You can add a help message, which is shown on the GitLab `/help` page (e.g., <https://gitlab.com/help>) in a new section at the top of the `/help` page: 1. Navigate to **Admin Area > Settings > Preferences**, then expand **Help page**. @@ -27,7 +27,7 @@ You can add a help message, which will be shown on the GitLab `/help` page (e.g. ## Adding a help message to the login page **(STARTER)** -You can add a help message, which will be shown on the GitLab login page in a new section +You can add a help message, which is shown on the GitLab login page in a new section titled `Need Help?`, located below the login page message: 1. Navigate to **Admin Area > Settings > Preferences**, then expand **Help page**. diff --git a/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png b/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png Binary files differindex 53dc0e4ac87..5056e8354a9 100644 --- a/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png +++ b/doc/user/admin_area/settings/img/user_and_ip_rate_limits.png diff --git a/doc/user/admin_area/settings/import_export_rate_limits.md b/doc/user/admin_area/settings/import_export_rate_limits.md index 92cb2a1a109..c6b965c18d3 100644 --- a/doc/user/admin_area/settings/import_export_rate_limits.md +++ b/doc/user/admin_area/settings/import_export_rate_limits.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Project/Group Import/Export rate limits diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 21d495de5b7..a7641ec22ca 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index --- @@ -34,7 +34,8 @@ Access the default page for admin area settings by navigating to **Admin Area > | Option | Description | | ------ | ----------- | | [Elasticsearch](../../../integration/elasticsearch.md#enabling-advanced-search) | Elasticsearch integration. Elasticsearch AWS IAM. | -| [PlantUML](../../../administration/integration/plantuml.md#gitlab) | Allow rendering of PlantUML diagrams in AsciiDoc documents. | +| [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). | | [Third party offers](third_party_offers.md) | Control the display of third party offers. | | [Snowplow](../../../development/product_analytics/snowplow.md) | Configure the Snowplow integration. | @@ -63,8 +64,8 @@ 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 will be run after the project's own configuration. | -| [Package Registry](continuous_integration.md#package-registry-configuration) | Settings related to the use and experience of using GitLab's Package Registry. Note there are [risks involved](../../packages/container_registry/index.md#use-with-external-container-registries) in enabling some of these settings. | +| [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. | +| [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 @@ -98,7 +99,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | Option | Description | | ------ | ----------- | -| Geo | Geo allows you to replicate your GitLab instance to other geographical locations. Redirects to **Admin Area > Geo > Settings**, and will no longer be available at **Admin Area > Settings > Geo** in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/36896). | +| Geo | Geo allows you to replicate your GitLab instance to other geographical locations. Redirects to **Admin Area > Geo > Settings** are no longer available at **Admin Area > Settings > Geo** in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/36896). | ## Preferences @@ -111,6 +112,6 @@ Access the default page for admin area settings by navigating to **Admin Area > | [Gitaly timeouts](gitaly_timeouts.md) | Configure Gitaly timeouts. | | Localization | [Default first day of the week](../../profile/preferences.md) and [Time tracking](../../project/time_tracking.md#limit-displayed-units-to-hours). | -NOTE: **Note:** +NOTE: You can change the [Default first day of the week](../../profile/preferences.md) for the entire GitLab instance in the **Localization** section of **Admin Area > Settings > Preferences**. diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index 20f2812bc39..42fa7fe6f54 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +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 --- diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index c09bb6f3c67..fe4e84b98ac 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Project integration management @@ -26,7 +26,7 @@ Only the complete settings for an integration can be inherited. Per-field inheri 1. Select an integration. 1. Enter configuration details and click **Save changes**. -CAUTION: **Caution:** +WARNING: This may affect all or most of the groups and projects on your GitLab instance. Please review the details below. @@ -59,7 +59,7 @@ integration on all non-configured groups and projects by default. 1. Select an integration. 1. Enter configuration details and click **Save changes**. -CAUTION: **Caution:** +WARNING: This may affect all or most of the subgroups and projects belonging to the group. Please review the details below. If this is the first time you are setting up group-level settings for an integration: diff --git a/doc/user/admin_area/settings/protected_paths.md b/doc/user/admin_area/settings/protected_paths.md index bb6fff9650d..870735f5be7 100644 --- a/doc/user/admin_area/settings/protected_paths.md +++ b/doc/user/admin_area/settings/protected_paths.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- 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 cf23ea12ef4..484bb7b0a14 100644 --- a/doc/user/admin_area/settings/push_event_activities_limit.md +++ b/doc/user/admin_area/settings/push_event_activities_limit.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +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 --- diff --git a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md index 3f8ef7c9d01..30cc64ccaa0 100644 --- a/doc/user/admin_area/settings/rate_limit_on_issues_creation.md +++ b/doc/user/admin_area/settings/rate_limit_on_issues_creation.md @@ -2,7 +2,7 @@ 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/#designated-technical-writers +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 issue creation 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 96cd71033d0..9ffd46e9ba6 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 @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- @@ -12,7 +12,7 @@ type: reference This setting allows you to rate limit the requests to raw endpoints, defaults to `300` requests per minute. It can be modified in **Admin Area > Settings > Network > Performance Optimization**. -For example, requests over `300` per minute to `https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/controllers/application_controller.rb` will be blocked. Access to the raw file will be released after 1 minute. +For example, requests over `300` per minute to `https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/controllers/application_controller.rb` are blocked. Access to the raw file is released after 1 minute.  diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 7ab1d396e8b..92ad8eced95 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- @@ -25,9 +25,9 @@ You can restrict the password authentication for web interface and Git over HTTP ## Two-factor authentication -When this feature enabled, all users will have to use the [two-factor authentication](../../profile/account/two_factor_authentication.md). +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 will be allowed +Once the two-factor authentication is configured as mandatory, the users are allowed to skip forced configuration of two-factor authentication for the configurable grace period in hours. @@ -44,13 +44,13 @@ see [Email notification for unknown sign-ins](../../profile/unknown_sign_in_noti ## Sign-in information -All users that are not logged-in will be redirected to the page represented by the configured -"Home page URL" if value is not empty. +All users that are not logged in are redirected to the page represented by the configured +**Home page URL** if value is not empty. -All users will be redirect to the page represented by the configured "After sign out path" +All users are redirected to the page represented by the configured **After sign out path** after sign out if value is not empty. -In the Sign-in restrictions section, scroll to the "Sign-in text" text box. You can add a +In the **Sign-in restrictions** section, scroll to the **Sign-in text** field. You can add a custom message for your users in Markdown format. For example, if you include the following information in the noted text box: @@ -61,7 +61,7 @@ For example, if you include the following information in the noted text box: To access this text box, navigate to Admin Area > Settings > General, and expand the "Sign-in restrictions" section. ``` -Your users will see the "Custom sign-in text" when they navigate to the sign-in screen for your +Your users see the **Custom sign-in text** when they navigate to the sign-in screen for your GitLab instance:  diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index 5ea034ff4d2..213c8c4116a 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- @@ -51,10 +51,13 @@ To enforce confirmation of the email address used for new sign ups: > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4315) in GitLab 13.6. -When the number of users reaches the user cap, any user who is added or requests access must be +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 their account. +If an administrator increases or removes the user cap, the users in pending approval state will be +automatically approved in a background job. + ## Soft email confirmation > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47003) in GitLab 12.2. @@ -63,7 +66,7 @@ their account. > - 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). -CAUTION: **Warning:** +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 diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index 95c32af5716..b6826035116 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- @@ -29,7 +29,7 @@ To enforce acceptance of a Terms of Service and Privacy Policy:  For each update to the terms, a new version is stored. When a user accepts or declines the terms, -GitLab will record which version they accepted or declined. +GitLab records which version they accepted or declined. ## New users @@ -37,28 +37,28 @@ When this feature is enabled, a checkbox is added to the sign-up form.  -This checkbox will be required during sign up. +This checkbox is required during sign up. Users can review the terms entered in the admin panel before -accepting. The page will be opened in a new window so they can +accepting. The page is opened in a new window so they can continue their registration afterwards. ## Accepting terms When this feature is enabled, the users that have not accepted the -terms of service will be presented with a screen where they can either +terms of service are presented with a screen where they can either accept or decline the terms.  -If the user accepts the terms, they will be directed to where they -were going. After a sign-in or sign-up this will most likely be the +If the user accepts the terms, they are directed to where they +were going. After a sign-in or sign-up this is most likely the dashboard. If the user was already logged in when the feature was turned on, -they will be asked to accept the terms on their next interaction. +they are asked to accept the terms on their next interaction. -If a user declines the terms, they will be signed out. +If a user declines the terms, they are signed out. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index f0e53115cb1..84511339842 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index d4080b3921a..02b1428177f 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -1,13 +1,13 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Usage statistics **(CORE ONLY)** -GitLab Inc. will periodically collect information about your instance in order +GitLab Inc. periodically collects information about your instance in order to perform various actions. All statistics are opt-out. You can enable/disable them in the @@ -22,7 +22,7 @@ If your GitLab instance is behind a proxy, set the appropriate [proxy configurat ## Version Check **(CORE ONLY)** -If enabled, version check will inform you if a new version is available and the +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`) for all signed in users, and on the admin pages. The statuses are: @@ -37,10 +37,10 @@ GitLab Inc. collects your instance's version and hostname (through the HTTP referer) as part of the version check. No other information is collected. This information is used, among other things, to identify to which versions -patches will need to be backported, making sure active GitLab instances remain +patches must be backported, making sure active GitLab instances remain secure. -If you disable version check, this information will not be collected. Enable or +If you disable version check, this information isn't collected. Enable or disable the version check in **Admin Area > Settings > Metrics and profiling > Usage statistics**. ### Request flow example @@ -65,8 +65,8 @@ See [Usage Ping guide](../../../development/product_analytics/usage_ping.md). ## Instance-level statistics **(CORE ONLY)** -Once usage ping is enabled, GitLab will gather data from other instances and -will be able to show [usage statistics](../analytics/index.md) +After usage ping is enabled, GitLab gathers data from other instances and +can show [usage statistics](../analytics/index.md) of your instance to your admins in **Admin Area > Analytics**. <!-- ## Troubleshooting 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 af3e0c5b63b..3f0d75dc682 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 @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- @@ -53,12 +53,70 @@ users to not set that header and bypass the GitLab rate limiter. Note that the bypass only works if the header is set to `1`. Requests that bypassed the rate limiter because of the bypass header -will be marked with `"throttle_safelist":"throttle_bypass_header"` in +are marked with `"throttle_safelist":"throttle_bypass_header"` in [`production_json.log`](../../../administration/logs.md#production_jsonlog). To disable the bypass mechanism, make sure the environment variable `GITLAB_THROTTLE_BYPASS_HEADER` is unset or empty. +## Allowing specific users to bypass authenticated request rate limiting + +Similarly to the bypass header described above, it is possible to allow +a certain set of users to bypass the rate limiter. This only applies +to authenticated requests: with unauthenticated requests, by definition +GitLab does not know who the user is. + +The allowlist is configured as a comma-separated list of user IDs in +the `GITLAB_THROTTLE_USER_ALLOWLIST` environment variable. If you want +users 1, 53 and 217 to bypass the authenticated request rate limiter, +the allowlist configuration would be `1,53,217`. + +- For [Omnibus](https://docs.gitlab.com/omnibus/settings/environment-variables.html), + set `'GITLAB_THROTTLE_USER_ALLOWLIST' => '1,53,217'` in `gitlab_rails['env']`. +- For source installations, set `export GITLAB_THROTTLE_USER_ALLOWLIST=1,53,217` + in `/etc/default/gitlab`. + +Requests that bypassed the rate limiter because of the user allowlist +are marked with `"throttle_safelist":"throttle_user_allowlist"` in +[`production_json.log`](../../../administration/logs.md#production_jsonlog). + +At application startup, the allowlist is logged in [`auth.log`](../../../administration/logs.md#authlog). + +## Trying out throttling settings before enforcing them + +> [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/629) in GitLab 13.6. + +Trying out throttling settings can be done by setting the +`GITLAB_THROTTLE_DRY_RUN` environment variable to a comma-separated +list of throttle names. + +The possible names are: + +- `throttle_unauthenticated` +- `throttle_authenticated_api` +- `throttle_authenticated_web` +- `throttle_unauthenticated_protected_paths` +- `throttle_authenticated_protected_paths_api` +- `throttle_authenticated_protected_paths_web` + +For example: trying out throttles for all authenticated requests to +non-protected paths could be done by setting +`GITLAB_THROTTLE_DRY_RUN='throttle_authenticated_web,throttle_authenticated_api'`. + +To enable the dry-run mode for all throttles, the variable can be set +to `*`. + +Setting a throttle to dry-run mode will log a message to the +[`auth.log`](../../../administration/logs.md#authlog) when it would +hit the limit, while letting the request continue as normal. The log +message will contain an `env` field set to `track`. The `matched` +field will contain the name of throttle that was hit. + +It is important to set the environment variable **before** enabling +the rate limiting in the settings. The settings in the admin panel +take effect immediately, while setting the environment variable +requires a restart of all the Puma processes. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues 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 3740dc95c12..fe1841e7020 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +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 --- @@ -43,7 +43,7 @@ To do this: 1. Uncheck the **Allow owners to manage default branch protection per group** checkbox. -NOTE: **Note:** +NOTE: GitLab administrators can still update the default branch protection of a group. ## Default project creation protection @@ -74,7 +74,7 @@ To ensure only admin users can delete projects: 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. -CAUTION: **Warning:** +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. @@ -151,7 +151,7 @@ For more details, see [Exporting a project and its data](../../../user/project/s > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4696) in GitLab 8.10. -With GitLab's access restrictions, you can select with which protocols users can communicate with +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 @@ -180,7 +180,7 @@ When only one protocol is enabled: On top of these UI restrictions, GitLab will deny all Git actions on the protocol not selected. -CAUTION: **Important:** +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. @@ -208,7 +208,7 @@ To specify a custom Git clone URL for HTTP(S): 1. Enter a root URL for **Custom Git clone URL for HTTP(S)**. 1. Click on **Save changes**. -NOTE: **Note:** +NOTE: SSH clone URLs can be customized in `gitlab.rb` by setting `gitlab_rails['gitlab_ssh_host']` and other related settings. diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md index ec0153ac3b6..a95501c0bde 100644 --- a/doc/user/admin_area/user_cohorts.md +++ b/doc/user/admin_area/user_cohorts.md @@ -3,3 +3,6 @@ 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/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index dc956765794..745774480b0 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -1,8 +1,8 @@ --- description: "Learn how long your open merge requests have spent in code review, and what distinguishes the longest-running." # Up to ~200 chars long. They will be displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here. stage: Manage -group: Value Stream 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/#designated-technical-writers +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 --- @@ -16,7 +16,7 @@ enables you to: 1. Take action on individual merge requests. 1. Reduce overall cycle time. -NOTE: **Note:** +NOTE: Initially, no data appears. Data is populated as users comment on open merge requests. ## Overview @@ -37,7 +37,7 @@ The table is sorted by: ## Use cases -This feature is designed for [development team leaders](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#delaney-development-team-lead) +This feature is designed for [development team leaders](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#delaney-development-team-lead) and others who want to understand broad code review dynamics, and identify patterns to explain them. You can use Code Review Analytics to: diff --git a/doc/user/analytics/cycle_analytics.md b/doc/user/analytics/cycle_analytics.md index 9d1cc508f63..5c235f6708b 100644 --- a/doc/user/analytics/cycle_analytics.md +++ b/doc/user/analytics/cycle_analytics.md @@ -3,3 +3,6 @@ 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/img/issues_created_per_month_v12_8.png b/doc/user/analytics/img/issues_created_per_month_v12_8.png Binary files differnew file mode 100644 index 00000000000..fccfa949779 --- /dev/null +++ b/doc/user/analytics/img/issues_created_per_month_v12_8.png diff --git a/doc/user/analytics/img/issues_table_v13_1.png b/doc/user/analytics/img/issues_table_v13_1.png Binary files differnew file mode 100644 index 00000000000..3e8a729a884 --- /dev/null +++ b/doc/user/analytics/img/issues_table_v13_1.png diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 29df25d76af..adfd09d8526 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -1,7 +1,7 @@ --- stage: Manage -group: Value Stream 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/#designated-technical-writers +group: Optimize +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Analytics diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md new file mode 100644 index 00000000000..0aa135ab88d --- /dev/null +++ b/doc/user/analytics/issue_analytics.md @@ -0,0 +1,45 @@ +--- +type: reference +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 +--- + +# Issue Analytics **(PREMIUM)** + +> - [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 +prior. + +To access the chart, navigate to your project sidebar and select **{chart}** **Analytics > Issue Analytics**. + +Hover over each bar to see the total number of issues. + +To narrow the scope of issues included in the graph, enter your criteria in the +**Search or filter results...** field. Criteria from the following list can be typed in or selected from a menu: + +- Author +- Assignee +- Milestone +- Label +- My reaction +- Weight + +You can change the total number of months displayed by setting a URL parameter. +For example, `https://gitlab.com/groups/gitlab-org/-/issues_analytics?months_back=15` +shows a total of 15 months for the chart in the GitLab.org group. + + + +## Drill into the information + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196547) in GitLab 13.1. + +You can examine details of individual issues by browsing the table +located below the chart. + +The chart displays the top 100 issues based on the global page filters. + + diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 5402d9a20a0..c0fe19f1f16 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -1,8 +1,8 @@ --- description: "Merge Request Analytics help you understand the efficiency of your code review process, and the productivity of your team." # Up to ~200 chars long. They will be displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here. stage: Manage -group: Value Stream 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/#designated-technical-writers +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)** @@ -23,7 +23,7 @@ To access Merge Request Analytics, from your project's menu, go to **Analytics > ## Use cases -This feature is designed for [development team leaders](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#delaney-development-team-lead) +This feature is designed for [development team leaders](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#delaney-development-team-lead) and others who want to understand broad patterns in code review and productivity. You can use Merge Request Analytics to expose when your team is most and least productive, and @@ -36,7 +36,7 @@ Merge Request Analytics could be used when: ## Visualizations and data -The following visualizations and data are available, representing all merge requests that were merged in the past 12 months. +The following visualizations and data are available, representing all merge requests that were merged in the given date range. ### Throughput chart @@ -46,7 +46,25 @@ The throughput chart shows the number of merge requests merged per month. ### Throughput table -Data table displaying a maximum of the 100 most recent merge requests merged for the time period. +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232651) in GitLab 13.3. + +The Throughput table displays the most recent merge requests merged in the date range. The +table displays up to 20 merge requests at a time. If there are more than 20 merge requests, +you can paginate to them. For each merge request, you can review the following data: + +- Title (as a link to the merge request itself) +- ID +- Pipeline status +- Label count +- Comment count +- Approval count (if approved) +- Date merged +- Time to merge +- Milestone +- Commit count +- Pipeline count +- Line change counts +- Assignees  @@ -68,6 +86,17 @@ To filter results: 1. Click on the filter bar. 1. Select a parameter to filter by. 1. Select a value from the autocompleted results, or enter search text to refine the results. +1. Hit the "Return" key. + +## Date range + +The date range is set to the past 12 months by default. You can modify the date range by changing the "From" and/or "To" values that appear alongside the filter bar. After changing either value, the data displayed on the page will update automatically. + +## Tip: Bookmark preferred settings + +You can bookmark preferred filters and date ranges. After you have applied a change to the +filter bar or the date range, you'll see that information in the URL. You can create a +bookmark for those preferred settings in your browser. ## Permissions diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index da3fe00a901..633d7b35087 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -1,7 +1,7 @@ --- stage: Manage -group: Value Stream 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/#designated-technical-writers +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 --- # Productivity Analytics **(PREMIUM)** diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index 3fc5478d466..f77070ea943 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -1,7 +1,7 @@ --- stage: Manage -group: Value Stream 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/#designated-technical-writers +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 --- # Repository Analytics @@ -23,7 +23,7 @@ The feature requires: You can find Repository Analytics in the project's sidebar. To access the page, go to **{chart}** **Analytics > Repository**. -NOTE: **Note:** +NOTE: Without a Git commit in the default branch, the menu item won't be visible. ### Charts diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index 244e37ba3ab..b5aecff5180 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -1,10 +1,10 @@ --- stage: Manage -group: Value Stream 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/#designated-technical-writers +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 +# Value Stream Analytics **(CORE)** > - 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. @@ -21,13 +21,10 @@ to uncover, triage, and identify the root cause of slowdowns in the software dev For information on how to contribute to the development of Value Stream Analytics, see our [contributor documentation](../../development/value_stream_analytics.md). -## Project Level Value Stream Analytics **(CORE)** +Project-level Value Stream Analytics is available via **Project > Analytics > Value Stream**. -Project Level Value Stream Analytics is available via **Project > Analytics > Value Stream**. - -## Group Level Value Stream Analytics **(PREMIUM)** - -From GitLab 12.9, group level Value Stream Analytics is available via **Group > Analytics > Value Stream**. +NOTE: +[Group-level Value Stream Analytics](../group/value_stream_analytics) is also available. ## Default stages @@ -46,38 +43,15 @@ The stages tracked by Value Stream Analytics by default represent the [GitLab fl - **Staging** (Continuous Deployment) - Time between merging and deploying to production -## Filter the analytics data - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 13.3 - -GitLab provides the ability to filter analytics based on the following parameters: - -- Milestones (Group level) -- Labels (Group level) -- Author -- Assignees - -To filter results: - -1. Select a group. -1. Click on the filter bar. -1. Select a parameter to filter by. -1. Select a value from the autocompleted results, or type to refine the results. - - - -NOTE: **Note:** -Filtering is available only for group-level Value Stream Analytics. - ### Date ranges -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36300) in GitLab 10.0. -GitLab provides the ability to filter analytics based on a date range. To filter results: +GitLab provides the ability to filter analytics based on a date range. To filter results, select one of these options: -1. Select a group. -1. Optionally select a project. -1. Select a date range using the available date pickers. +1. Last 7 days +1. Last 30 days (default) +1. Last 90 days ## How Time metrics are measured @@ -86,9 +60,8 @@ The "Time" metrics near the top of the page are measured as follows: - **Lead time**: median time from issue created to issue closed. - **Cycle time**: median time from first commit to issue closed. -Note: A commit is associated with an issue by [crosslinking](../project/issues/crosslinking_issues.md) in the commit message or by manually linking the merge request containing the commit. - - +NOTE: +A commit is associated with an issue by [crosslinking](../project/issues/crosslinking_issues.md) in the commit message or by manually linking the merge request containing the commit. ## How the stages are measured @@ -103,31 +76,30 @@ Each stage of Value Stream Analytics is further described in the table below. | **Stage** | **Description** | | --------- | --------------- | -| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whatever comes first. The label will be tracked only if it already has an [Issue Board list](../project/issue_board.md) created for it. | -| Plan | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. The very first commit of the branch is the one that triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch needs to contain the related issue number (e.g., `#42`). If none of the commits in the branch mention the related issue number, it is not considered to the measurement time of the stage. | -| Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR) related to that commit. The key to keep the process tracked is to include the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) to the description of the merge request (for example, `Closes #xxx`, where `xxx` is the number of the issue related to this merge request). If the closing pattern is not present, then the calculation takes the creation time of the first commit in the merge request as the start time. | -| Test | Measures the median time to run the entire pipeline for that project. It's related to the time GitLab CI/CD takes to run every job for the commits pushed to that merge request defined in the previous stage. It is basically the start->finish time for all pipelines. | -| Review | Measures the median time taken to review the merge request that has a closing issue pattern, between its creation and until it's merged. | -| Staging | Measures the median time between merging the merge request with a closing issue pattern until the very first deployment to a [production environment](#how-the-production-environment-is-identified). If there isn't a production environment, this is not tracked. | +| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whichever comes first. The label is tracked only if it already includes an [Issue Board list](../project/issue_board.md) created for it. | +| Plan | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. That first branch commit triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch must include the related issue number (such as `#42`). If the issue number is *not* included in a commit, that data is not included in the measurement time of the stage. | +| Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR). The process is tracked with the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) in the description of the merge request. For example, if the issue is closed with `Closes #xxx`, it's assumed that `xxx` is issue number for the merge request). If there is no closing pattern, the start time is set to the create time of the first commit. | +| Test | Essentially the start to finish time for all pipelines. Measures the median time to run the entire pipeline for that project. Related to the time required by GitLab CI/CD to run every job for the commits pushed to that merge request, as defined in the previous stage. | +| Review | Measures the median time taken to review merge requests with a closing issue pattern, from creation to merge. | +| Staging | Measures the median time between merging the merge request (with a closing issue pattern) to the first deployment to a [production environment](#how-the-production-environment-is-identified). Data not collected without a production environment. | How this works, behind the scenes: -1. Issues and merge requests are grouped together in pairs, such that for each - `<issue, merge request>` pair, the merge request has the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) - for the corresponding issue. All other issues and merge requests are **not** - considered. -1. Then the `<issue, merge request>` pairs are filtered out by last XX days (specified - by the UI - default is 90 days). So it prohibits these pairs from being considered. -1. For the remaining `<issue, merge request>` pairs, we check the information that - we need for the stages, like issue creation date, merge request merge time, - etc. +1. Issues and merge requests are grouped in pairs, where the merge request has the + [closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) + for the corresponding issue. Issue/merge request pairs without closing patterns are + **not** included. +1. Issue/merge request pairs are filtered by the last XX days, specified through the UI + (default = 90 days). Pairs outside the filtered range are not included. +1. For the remaining pairs, review information needed for stages, including + issue creation date, merge request merge time, and so on. -To sum up, anything that doesn't follow [GitLab flow](../../topics/gitlab_flow.md) will not be tracked and the -Value Stream Analytics dashboard will not present any data for: +In short, the Value Stream Analytics dashboard tracks data related to [GitLab flow](../../topics/gitlab_flow.md). It does not include data for: - Merge requests that do not close an issue. -- Issues not labeled with a label present in the Issue Board or for issues not assigned a milestone. -- Staging stage, if the project has no [production environment](#how-the-production-environment-is-identified). +- Issues that do not include labels present in the Issue Board +- Issues without a milestone. +- Staging stages, in projects without a [production environment](#how-the-production-environment-is-identified). ## How the production environment is identified @@ -165,8 +137,7 @@ environments is configured. 1. Now that the merge request is merged, a deployment to the `production` environment starts and finishes at 19:30 (stop of **Staging** stage). -From the above example you can conclude the time it took each stage to complete -as long as their total time: +From the above example we see the time used for each stage: - **Issue**: 2h (11:00 - 09:00) - **Plan**: 1h (12:00 - 11:00) @@ -175,203 +146,20 @@ as long as their total time: - **Review**: 5h (19:00 - 14:00) - **Staging**: 30min (19:30 - 19:00) -A few notes: - -- In the above example we demonstrated that it doesn't matter if your first - commit doesn't mention the issue number, you can do this later in any commit - of the branch you are working on. -- You can see that the **Test** stage is not calculated to the overall time of - the cycle since it is included in the **Review** process (every MR should be - tested). -- The example above was just **one cycle** of the seven stages. Add multiple - cycles, calculate their median time and the result is what the dashboard of - Value Stream Analytics is showing. - -## Customizable Value Stream Analytics **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12196) in GitLab 12.9. - -The default stages are designed to work straight out of the box, but they might not be suitable for -all teams. Different teams use different approaches to building software, so some teams might want -to customize their Value Stream Analytics. - -GitLab allows users to create multiple value streams, hide default stages and create custom stages that align better to their development workflow. - -NOTE: **Note:** -Customizability is [only available for group-level](https://gitlab.com/gitlab-org/gitlab/-/issues/35823#note_272558950) Value Stream Analytics. - -### Stage path - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210315) in GitLab 13.0. - -Stages are visually depicted as a horizontal process flow. Selecting a stage will update the -the content below the value stream. - -This is disabled by default. If you have a self-managed instance, an -administrator can [open a Rails console](../../administration/troubleshooting/navigating_gitlab_via_rails_console.md) -and enable it with the following command: - -```ruby -Feature.enable(:value_stream_analytics_path_navigation) -``` - -### Adding a stage - -In the following example we're creating a new stage that measures and tracks issues from creation -time until they are closed. - -1. Navigate to your group's **Analytics > Value Stream**. -1. Click the **Add a stage** button. -1. Fill in the new stage form: - - Name: Issue start to finish. - - Start event: Issue created. - - End event: Issue closed. -1. Click the **Add stage** button. - - - -The new stage is persisted and it will always show up on the Value Stream Analytics page for your -group. - -If you want to alter or delete the stage, you can easily do that for customized stages by: - -1. Hovering over the stage. -1. Clicking the vertical ellipsis (**{ellipsis_v}**) button that appears. - - - -Creating a custom stage requires specifying two events: - -- A start. -- An end. - -Be careful to choose a start event that occurs *before* your end event. For example, consider a -stage that: - -- Started when an issue is added to a board. -- Ended when the issue is created. - -This stage would not work because the end event has already happened when the start event occurs. -To prevent such invalid stages, the UI prohibits incompatible start and end events. After you select -the start event, the stop event dropdown will only list the compatible events. - -### Re-ordering stages - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196698) in GitLab 12.10. - -Once a custom stage has been added, you can "drag and drop" stages to rearrange their order. These changes are automatically saved to the system. - -### Label based stages +More information: -The pre-defined start and end events can cover many use cases involving both issues and merge requests. - -For supporting more complex workflows, use stages based on group labels. These events are based on -labels being added or removed. In particular, [scoped labels](../project/labels.md#scoped-labels) -are useful for complex workflows. - -In this example, we'd like to measure more accurate code review times. The workflow is the following: - -- When the code review starts, the reviewer adds `workflow::code_review_start` label to the merge request. -- When the code review is finished, the reviewer adds `workflow::code_review_complete` label to the merge request. - -Creating a new stage called "Code Review": - - - -### Hiding unused stages - -Sometimes certain default stages are not relevant to a team. In this case, you can easily hide stages -so they no longer appear in the list. To hide stages: - -1. Add a custom stage to activate customizability. -1. Hover over the default stage you want to hide. -1. Click the vertical ellipsis (**{ellipsis_v}**) button that appears and select **Hide stage**. - -To recover a default stage that was previously hidden: - -1. Click **Add a stage** button. -1. In the top right corner open the **Recover hidden stage** dropdown. -1. Select a stage. - -### Creating a value stream - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221202) in GitLab 13.3 - -A default value stream is readily available for each group. You can create additional value streams based on the different areas of work that you would like to measure. - -Once created, a new value stream includes the [seven stages](#default-stages) that follow -[GitLab workflow](../../topics/gitlab_flow.md) -best practices. You can customize this flow by adding, hiding or re-ordering stages. - -To create a value stream: - -1. Navigate to your group's **Analytics > Value Stream**. -1. Click the Value stream dropdown and select **Create new Value Stream** -1. Fill in a name for the new Value Stream -1. Click the **Create Value Stream** button. - - - -### Deleting a value stream - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221205) in GitLab 13.4. - -To delete a custom value stream: - -1. Navigate to your group's **Analytics > Value Stream**. -1. Click the Value stream dropdown and select the value stream you would like to delete. -1. Click the **Delete (name of value stream)**. -1. Click the **Delete** button to confirm. - - - -### Disabling custom value streams - -Custom value streams are enabled by default. If you have a self-managed instance, an -administrator can open a Rails console and disable them with the following command: - -```ruby -Feature.disable(:value_stream_analytics_create_multiple_value_streams) -``` - -## Days to completion chart - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21631) in GitLab 12.6. -> - [Chart median line removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235455) in GitLab 13.4. - -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 -from within the chart itself. - -The chart data is limited to the last 500 items. - -### Disabling chart - -This chart is enabled by default. If you have a self-managed instance, an -administrator can open a Rails console and disable it with the following command: - -```ruby -Feature.disable(:cycle_analytics_scatterplot_enabled) -``` - -## Type of work - Tasks by type chart - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32421) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. - -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 -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 -select up to a total of 15 labels. +- The above example specifies the issue number in a latter commit. The process + still collects analytics data for that issue. +- The time required in the **Test** stage is not included in the overall time of + the cycle. It is included in the **Review** process, as every MR should be + tested. +- The example above illustrates only **one cycle** of the multiple stages. Value + Stream Analytics, on its dashboard, shows the calculated median elapsed time + for these issues. ## Permissions -The current permissions on the Project Value Stream Analytics dashboard are: +The current permissions on the Project-level Value Stream Analytics dashboard are: - Public projects - anyone can access. - Internal projects - any authenticated user can access. @@ -379,9 +167,6 @@ The current permissions on the Project Value Stream Analytics dashboard are: You can [read more about permissions](../../user/permissions.md) in general. -For Value Stream Analytics functionality introduced in GitLab 12.3 and later, -users must have Reporter access or above. - ## More resources Learn more about Value Stream Analytics in the following resources: diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 57c5f8bc1fa..09e38d5048f 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Fuzz Testing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -139,7 +139,7 @@ This is a minimal configuration for API Fuzzing. From here you can: - [Add authentication](#authentication). - Learn how to [handle false positives](#handling-false-positives). -DANGER: **Warning:** +WARNING: **NEVER** run fuzz testing against a production server. Not only can it perform *any* function that the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting data. Only run fuzzing against a test server. @@ -147,7 +147,7 @@ data. Only run fuzzing against a test server. ### HTTP Archive (HAR) The [HTTP Archive format (HAR)](http://www.softwareishard.com/blog/har-12-spec/) -is an archive file format for logging HTTP transactions. When used with GitLab's API fuzzer, HAR +is an archive file format for logging HTTP transactions. When used with the GitLab API fuzzer, HAR must contain records of calling the web API to test. The API fuzzer extracts all the requests and uses them to perform testing. @@ -155,10 +155,10 @@ You can use various tools to generate HAR files: - [Fiddler](https://www.telerik.com/fiddler): Web debugging proxy - [Insomnia Core](https://insomnia.rest/): API client -- [Chrome](https://www.google.com/chrome): Browser +- [Chrome](https://www.google.com/chrome/): Browser - [Firefox](https://www.mozilla.org/en-US/firefox/): Browser -DANGER: **Warning:** +WARNING: HAR files may contain sensitive information such as authentication tokens, API keys, and session cookies. We recommend that you review the HAR file contents before adding them to a repository. @@ -230,7 +230,7 @@ This is a minimal configuration for API Fuzzing. From here you can: - [Add authentication](#authentication). - Learn how to [handle false positives](#handling-false-positives). -DANGER: **Warning:** +WARNING: **NEVER** run fuzz testing against a production server. Not only can it perform *any* function that the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting data. Only run fuzzing against a test server. @@ -243,11 +243,11 @@ developers and testers use to call various types of APIs. The API definitions for use with API Fuzzing. When exporting, make sure to select a supported version of Postman Collection: v2.0 or v2.1. -When used with GitLab's API fuzzer, Postman Collections must contain definitions of the web API to +When used with the GitLab API fuzzer, Postman Collections must contain definitions of the web API to test with valid data. The API fuzzer extracts all the API definitions and uses them to perform testing. -DANGER: **Warning:** +WARNING: Postman Collection files may contain sensitive information such as authentication tokens, API keys, and session cookies. We recommend that you review the Postman Collection file contents before adding them to a repository. @@ -321,7 +321,7 @@ This is a minimal configuration for API Fuzzing. From here you can: - [Add authentication](#authentication). - Learn how to [handle false positives](#handling-false-positives). -DANGER: **Warning:** +WARNING: **NEVER** run fuzz testing against a production server. Not only can it perform *any* function that the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting data. Only run fuzzing against a test server. @@ -488,24 +488,24 @@ increases as the numbers go up. To use a configuration file, add it to your repo | 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). | -|[`FUZZAPI_HTTP_USERNAME`](#http-basic-authentication) |Username for HTTP authentication. | -|[`FUZZAPI_HTTP_PASSWORD`](#http-basic-authentication) |Password for HTTP authentication. | +| `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. | <!--|[`FUZZAPI_D_TARGET_IMAGE`](#target-container) |API target docker image | |[`FUZZAPI_D_TARGET_ENV`](#target-container) |Docker environment options | -|[`FUZZAPI_D_TARGET_VOLUME`](#target-container)|Docker volume options | +|[`FUZZAPI_D_TARGET_VOLUME`](#target-container) | Docker volume options | |[`FUZZAPI_D_TARGET_PORTS`](#target-container) |Docker port options | | `FUZZAPI_D_WORKER_IMAGE` |Custom worker docker image | | `FUZZAPI_D_WORKER_ENV` |Custom worker docker environment options | @@ -720,45 +720,43 @@ Repeat this configuration for each profile as needed. ## Running your first scan -When configured correctly, a CI/CD pipeline contains a `Fuzz` stage and a `apifuzzer_fuzz` job. The -job only fails when an invalid configuration is provided. During normal operation, the job always -succeeds even if faults are identified during fuzz testing. +When configured correctly, a CI/CD pipeline contains a `fuzz` stage and an `apifuzzer_fuzz` or +`apifuzzer_fuzz_dnd` job. The job only fails when an invalid configuration is provided. During +normal operation, the job always succeeds even if faults are identified during fuzz testing. -Faults are displayed on the **Tests** pipeline tab with the suite name **API-Fuzzing**. The **Name** -field on the **Tests** page includes the fuzz-tested operation and parameter. The **Trace** field -contains a writeup of the identified fault. This writeup contains information on what the fuzzer -tested and how it detected something wrong. +Faults are displayed on the **Security** pipeline tab with the suite name. When testing against the +repositories default branch, the fuzzing faults are also shown on the Security & Compliance's +Vulnerability Report page. To prevent an excessive number of reported faults, the API fuzzing scanner limits the number of -faults it reports to one per parameter. - -### Fault Writeup - -The faults that API fuzzing finds aren't associated with a specific vulnerability type. They require -investigation to determine what type of issue they are and if they should be fixed. See -[handling false positives](#handling-false-positives) for information about configuration changes -you can make to limit the number of false positives reported. - -This table contains a description of fields in an API fuzzing fault writeup. - -| Writeup Item | Description | -|:-------------|:------------| -| Operation | The operation tested. | -| Parameter | The field modified. This can be a path segment, header, query string, or body element. | -| Endpoint | The endpoint being tested. | -| Check | Check module producing the test. Checks can be turned on and off. | -| Assert | Assert module that detected a failure. Assertions can be configured and turned on and off. | -| CWE | Fuzzing faults always have the same CWE. | -| OWASP | Fuzzing faults always have the same OWASP ID. | -| Exploitability | Fuzzing faults always have an `unknown` exploitability. | -| Impact | Fuzzing faults always have an `unknown` risk impact. | -| Description | Verbose description of what the check did. Includes the original parameter value and the modified (mutated) value. | -| Detection | Why a failure was detected and reported. This is related to the Assert that was used. | -| Original Request | The original, unmodified HTTP request. Useful when reviewing the actual request to see what changes were made. | -| Actual Request | The request that produced the failure. This request has been modified in some way by the Check logic. | -| Actual Response | The response to the actual request. | -| Recorded Request | An unmodified request. | -| Recorded Response | The response to the unmodified request. You can compare this with the actual request when triaging this fault. | +faults it reports. + +## Viewing fuzzing faults + +The API Fuzzing analyzer produces a JSON report that is collected and used +[to populate the faults into GitLab vulnerability screens](../index.md#view-details-of-an-api-fuzzing-vulnerability). +Fuzzing faults show up as vulnerabilities with a severity of Unknown. + +The faults that API fuzzing finds require manual investigation and aren't associated with a specific +vulnerability type. They require investigation to determine if they are a security issue, and if +they should be fixed. See [handling false positives](#handling-false-positives) +for information about configuration changes you can make to limit the number of false positives +reported. + +For additional information, see +[View details of an API Fuzzing vulnerability](../index.md#view-details-of-an-api-fuzzing-vulnerability). + +### Security Dashboard + +Fuzzing faults show up as vulnerabilities with a severity of Unknown. The Security Dashboard is a +good place to get an overview of all the security vulnerabilities in your groups, projects and +pipelines. For more information, see the [Security Dashboard documentation](../security_dashboard/index.md). + +### Interacting with the vulnerabilities + +Fuzzing faults show up as vulnerabilities with a severity of Unknown. +Once a fault is found, you can interact with it. Read more on how to +[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). ## Handling False Positives diff --git a/doc/user/application_security/compliance_dashboard/index.md b/doc/user/application_security/compliance_dashboard/index.md index d9af9d66c36..383d2bf2df7 100644 --- a/doc/user/application_security/compliance_dashboard/index.md +++ b/doc/user/application_security/compliance_dashboard/index.md @@ -3,3 +3,6 @@ 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/configuration/index.md b/doc/user/application_security/configuration/index.md index ead34ca227e..fe21fdc1f15 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Security Configuration **(ULTIMATE)** diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index eef15a9c424..9bde2c28972 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Protect group: Container Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Container Scanning **(ULTIMATE)** @@ -14,7 +14,7 @@ vulnerabilities. By including an extra job in your pipeline that scans for those displays them in a merge request, you can use GitLab to audit your Docker-based apps. By default, container scanning in GitLab is based on [Clair](https://github.com/quay/clair) and [Klar](https://github.com/optiopay/klar), which are open-source tools for vulnerability static analysis in -containers. [GitLab's Klar analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar/) +containers. The GitLab [Klar analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar/) scans the containers and serves as a wrapper for Clair. To integrate security scanners other than Clair and Klar into GitLab, see @@ -43,6 +43,7 @@ To enable container scanning in your pipeline, you need the following: or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. - Docker `18.09.03` or higher installed on the same computer as the runner. If you're using the shared runners on GitLab.com, then this is already the case. +- An image matching [Clair's list of supported distributions](https://quay.github.io/claircore/). - [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): @@ -211,7 +212,7 @@ container_scanning: GIT_STRATEGY: fetch ``` -CAUTION: **Deprecated:** +WARNING: GitLab 13.0 and later doesn't support [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic). When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. @@ -298,7 +299,7 @@ For details on saving and transporting Docker images as a file, see Docker's doc It can be worthwhile to set up a [scheduled pipeline](../../../ci/pipelines/schedules.md) to build a new version of the vulnerabilities database on a preset schedule. Automating -this with a pipeline means you won't have to do it manually each time. You can use the following +this with a pipeline means you do not have to do it manually each time. You can use the following `.gitlab-yml.ci` as a template: ```yaml @@ -318,7 +319,7 @@ build_latest_vulnerabilities: - docker push $CI_REGISTRY/namespace/clair-vulnerabilities-db ``` -The above template works for a GitLab Docker registry running on a local installation, however, if you're using a non-GitLab Docker registry, you'll need to change the `$CI_REGISTRY` value and the `docker login` credentials to match the details of your local registry. +The above template works for a GitLab Docker registry running on a local installation, however, if you're using a non-GitLab Docker registry, you need to change the `$CI_REGISTRY` value and the `docker login` credentials to match the details of your local registry. ## Running the standalone container scanning tool diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 4c5afcee3d0..0a5a0c3a565 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Fuzz Testing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- diff --git a/doc/user/application_security/cve_id_request.md b/doc/user/application_security/cve_id_request.md index 94cacf2882f..bc0c1e52626 100644 --- a/doc/user/application_security/cve_id_request.md +++ b/doc/user/application_security/cve_id_request.md @@ -2,14 +2,14 @@ type: tutorial stage: Secure group: Vulnerability Research -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # CVE ID Requests > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. -As part of [GitLab's role as a CVE Numbering Authority](https://about.gitlab.com/security/cve) +As part of [our role as a CVE Numbering Authority](https://about.gitlab.com/security/cve/) ([CNA](https://cve.mitre.org/cve/cna.html)), you may request [CVE](https://cve.mitre.org/index.html) identifiers from GitLab to track vulnerabilities found within your project. @@ -33,7 +33,7 @@ If the following conditions are met, a **Request CVE ID** button appears in your ## Submitting a CVE ID Request Clicking the **Request CVE ID** button in the issue sidebar takes you to the new issue page for -[GitLab's CVE project](https://gitlab.com/gitlab-org/cves). +the [GitLab CVE project](https://gitlab.com/gitlab-org/cves).  diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 2f1ed2faf90..f4401fa6445 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -1,7 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -15,7 +15,7 @@ deployed, your application is exposed to a new category of possible attacks, such as cross-site scripting or broken authentication flaws. This is where Dynamic Application Security Testing (DAST) comes into place. -NOTE: **Note:** +NOTE: The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) explains how 4 of the top 6 attacks were application based. Download it to learn how to protect your organization. @@ -91,12 +91,22 @@ 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. Add it in an `environment_url.txt` file at the root of your project. - This is great for testing in dynamic environments. In order to run DAST against - an app dynamically created during a GitLab CI/CD pipeline, have the app - persist its domain in an `environment_url.txt` file, and DAST - automatically parses that file to find its scan target. - You can see an [example](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml) - of this in our Auto DevOps CI YAML. + This is useful for testing in dynamic environments. To run DAST against an application + dynamically created during a GitLab CI/CD pipeline, a job that runs prior to the DAST scan must + persist the application's domain in an `environment_url.txt` file. DAST automatically parses the + `environment_url.txt` file to find its scan target. + + For example, in a job that runs prior to DAST, you could include code that looks similar to: + + ```yaml + script: + - echo http://${CI_PROJECT_ID}-${CI_ENVIRONMENT_SLUG}.domain.com > environment_url.txt + artifacts: + paths: [environment_url.txt] + when: always + ``` + + You can see an example of this in our [Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml) file. If both values are set, the `DAST_WEBSITE` value takes precedence. @@ -161,8 +171,9 @@ headers whose values you want masked. For details on how to mask headers, see It's also possible to authenticate the user before performing the DAST checks. -**Important:** It is highly recommended that you configure the scanner to authenticate to the application, -or it will not be able to check most of the application for security risks, as most +NOTE: +We highly recommended that you configure the scanner to authenticate to the application, +otherwise it cannot check most of the application for security risks, as most of your application is likely not accessible without authentication. It is also recommended that you periodically confirm the scanner's authentication is still working as this tends to break over time due to authentication changes to the application. @@ -183,6 +194,8 @@ variables: DAST_AUTH_URL: https://example.com/sign-in DAST_USERNAME_FIELD: session[user] # the name of username field at the sign-in HTML form DAST_PASSWORD_FIELD: session[password] # the name of password field at the sign-in HTML form + DAST_SUBMIT_FIELD: login # the `id` or `name` of the element that when clicked will submit the login form or the password form of a multi-page login process + DAST_FIRST_SUBMIT_FIELD: next # the `id` or `name` of the element that when clicked will submit the username form of a multi-page login process DAST_AUTH_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between ``` @@ -191,7 +204,7 @@ The results are saved as a that you can later download and analyze. Due to implementation limitations, we always take the latest DAST artifact available. -DANGER: **Warning:** +WARNING: **NEVER** run an authenticated scan against a production server. When an authenticated scan is run, it may perform *any* function that the authenticated user can. This includes actions like modifying and deleting data, submitting forms, and following links. @@ -486,8 +499,8 @@ variables: 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 will use `DAST_WEBSITE` to build the URLs to scan -- Spidering is disabed when `DAST_PATHS` or `DAST_PATHS_FILE` are defined +- `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 greater than this, use `DAST_PATHS_FILE`. @@ -498,7 +511,7 @@ To perform a [full scan](#full-scan) on the listed paths, use the `DAST_FULL_SCA ### Customizing the DAST settings -CAUTION: **Deprecation:** +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. @@ -529,7 +542,7 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `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` will be reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | +| `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_USERNAME` | string | The username to authenticate to in the website. | | `DAST_PASSWORD` | string | The password to authenticate to in the website. | @@ -551,7 +564,9 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `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 within `/zap/wrk`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | +| `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` | @@ -720,7 +735,7 @@ To delete an existing site profile: 1. From your project's home page, go to **Security & Compliance > Configuration**. 1. Click **Manage** in the **DAST Profiles** row. -1. Click **{remove}** in the row of the profile to delete. +1. Click **{remove}** (Delete profile) in the row of the profile to delete. ## Scanner profile @@ -762,7 +777,7 @@ 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}** in the scanner profile's row. +1. Click **{remove}** (Delete profile) in the scanner profile's row. ## On-demand scans @@ -780,7 +795,7 @@ An on-demand DAST scan: ### Run an on-demand DAST scan -NOTE: **Note:** +NOTE: You must have permission to run an on-demand DAST scan against a protected branch. The default branch is automatically protected. For more information, see [Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). @@ -812,7 +827,7 @@ Click **View details** to view the web console output which includes the list of ### JSON -CAUTION: **Caution:** +WARNING: The JSON report artifacts are not a public API of DAST and their format is expected to change in the future. The DAST tool always emits a JSON report file called `gl-dast-report.json` and @@ -821,8 +836,8 @@ sample reports can be found in the There are two formats of data in the JSON report that are used side by side: -- The proprietary ZAP format that will be eventually deprecated. -- A common format that will be the default in the future. +- The proprietary ZAP format, which is planned to be deprecated. +- A common format that is planned to the default in the future. ### Other formats diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index ddd059707d4..d5f4ce9cc6a 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -2,14 +2,14 @@ type: reference, howto stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Dependency List **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10075) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. -The Dependency list allows you to see your project's dependencies, and key +The dependency list allows you to see your project's dependencies, and key details about them, including their known vulnerabilities. To see it, navigate to **Security & Compliance > Dependency List** in your project's sidebar. This information is sometimes referred to as a Software Bill of Materials or SBoM / BOM. @@ -55,13 +55,14 @@ dependencies, but the UI only shows one of the shortest paths. Dependency Paths are supported for the following package managers: - [NuGet](https://www.nuget.org/) +- [Yarn 1.x](https://classic.yarnpkg.com/lang/en/) ## Licenses > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10536) in GitLab Ultimate 12.3. If the [License Compliance](../../compliance/license_compliance/index.md) CI job is configured, -the [discovered licenses](../../compliance/license_compliance/index.md#supported-languages-and-package-managers) will be displayed on this page. +the [discovered licenses](../../compliance/license_compliance/index.md#supported-languages-and-package-managers) are displayed on this page. ## Downloading the Dependency List diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index 40189235e64..1079a75e32f 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -2,7 +2,7 @@ type: reference, howto stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Dependency Scanning Analyzers **(ULTIMATE)** diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 1b164c9cecd..07774f51958 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -2,14 +2,14 @@ type: reference, howto stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Dependency Scanning **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5105) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7. -GitLab's Dependency Scanning feature can automatically find security vulnerabilities in your +The Dependency Scanning feature can automatically find security vulnerabilities in your dependencies while you're developing and testing your applications. For example, dependency scanning lets you know if your application uses an external (open source) library that is known to be vulnerable. You can then take action to protect your application. @@ -46,7 +46,7 @@ To run dependency scanning jobs, by default, you need GitLab Runner with the [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. If you're using the shared runners on GitLab.com, this is enabled by default. -CAUTION: **Caution:** +WARNING: If you use your own runners, make sure your installed version of Docker is **not** `19.03.0`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. @@ -64,7 +64,7 @@ The following languages and dependency managers are supported: | [Conan](https://conan.io/) | C, C++ | [`conan.lock`](https://docs.conan.io/en/latest/versioning/lockfiles.html) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | [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/) | JavaScript | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js/) | +| [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), [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/) | Python | `setup.py`, `requirements.txt`, `requirements.pip`, `requires.txt`, `Pipfile` | [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) | @@ -123,7 +123,7 @@ configuration, the last mention of the variable takes precedence. ### Overriding dependency scanning jobs -CAUTION: **Deprecation:** +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. @@ -141,6 +141,16 @@ gemnasium-dependency_scanning: DS_REMEDIATE: "false" ``` +To override the `dependencies: []` attribute, add an override job as above, targeting this attribute: + +```yaml +include: + - template: Dependency-Scanning.gitlab-ci.yml + +gemnasium-dependency_scanning: + dependencies: ["build"] +``` + ### Available variables Dependency scanning can be [configured](#customizing-the-dependency-scanning-settings) @@ -173,7 +183,7 @@ The following variables are used for configuring specific analyzers (used for a | `PIP_REQUIREMENTS_FILE` | `gemnasium-python` | | Pip requirements file to be scanned. | | `DS_PIP_VERSION` | `gemnasium-python` | | Force the install of a specific pip version (example: `"19.3"`), otherwise the pip installed in the Docker image is used. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12811) in GitLab 12.7) | | `DS_PIP_DEPENDENCY_PATH` | `gemnasium-python` | | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12412) in GitLab 12.2) | -| `DS_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)| +| `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. | @@ -356,10 +366,10 @@ 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 will 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 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). - This advisory database is constantly being updated, so you will need to periodically sync your local copy with GitLab's. + 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. @@ -510,3 +520,8 @@ uses the [`rules:exists`](../../../ci/yaml/README.md#rulesexists) syntax. This directive is limited to 10000 checks and always returns `true` after reaching this number. Because of this, and depending on the number of files in your repository, a dependency 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 +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`). diff --git a/doc/user/application_security/img/security_widget_v13_6.png b/doc/user/application_security/img/security_widget_v13_6.png Binary files differdeleted file mode 100644 index 2dd44909dfe..00000000000 --- a/doc/user/application_security/img/security_widget_v13_6.png +++ /dev/null diff --git a/doc/user/application_security/img/security_widget_v13_7.png b/doc/user/application_security/img/security_widget_v13_7.png Binary files differnew file mode 100644 index 00000000000..fb1eaf9a2be --- /dev/null +++ b/doc/user/application_security/img/security_widget_v13_7.png diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 30852d1bbcd..417ce70665c 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -1,7 +1,7 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +stage: secure +group: secure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -92,7 +92,7 @@ rules: ## Security Scanning with Auto DevOps -When [Auto DevOps](../../topics/autodevops/) is enabled, all GitLab Security scanning tools will be configured using default settings. +When [Auto DevOps](../../topics/autodevops/) is enabled, all GitLab Security scanning tools are configured using default settings. - [Auto SAST](../../topics/autodevops/stages.md#auto-sast) - [Auto Secret Detection](../../topics/autodevops/stages.md#auto-secret-detection) @@ -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` (GitLab's own 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. | @@ -127,19 +127,21 @@ with this approach, however, and there is a > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4393) in GitLab Core 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)** -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. Merge requests which have run security scans let you know that the generated -reports are available to download. +reports are available to download. To download a report, click on the +**Download results** dropdown, and select the desired report. - + ## Interacting with the vulnerabilities @@ -199,6 +201,43 @@ authorization credentials. By default, content of specific headers are masked in reports. You can specify the list of all headers to be masked. For details, see [Hide sensitive information](dast/index.md#hide-sensitive-information). +### View details of an API Fuzzing vulnerability + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.7. + +Faults detected by API Fuzzing occur in the live web application, and require manual investigation +to determine if they are vulnerabilities. Fuzzing faults are included as vulnerabilities with a +severity of Unknown. To facilitate investigation of the fuzzing faults, detailed information is +provided about the HTTP messages sent and received along with a description of the modification(s) +made. + +Follow these steps to view details of a fuzzing fault: + +1. You can view faults in a project, or a merge request: + + - In a project, go to the project's **{shield}** **Security & Compliance > Vulnerability Report** + page. This page shows all vulnerabilities from the default branch only. + - In a merge request, go the merge request's **Security** section and click the **Expand** + button. API Fuzzing faults are available in a section labeled + **API Fuzzing detected N potential vulnerabilities**. Click the title to display the fault + details. + +1. Click the fault's title to display the fault's details. The table below describes these details. + +| Field | Description | +|:-----------------|:------------------------------------------------------------------ | +| Description | Description of the fault including what was modified. | +| Project | Namespace and project in which the vulnerability was detected. | +| Method | HTTP method used to detect the vulnerability. | +| URL | URL at which the vulnerability was detected. | +| Request | The HTTP request that caused the fault. | +| Unmodified Response | Response from an unmodified request. This is what a normal working response looks like. | +| Actual Response | Response received from fuzzed request. | +| Evidence | How we determined a fault occurred. | +| Identifiers | The fuzzing check used to find this fault. | +| Severity | Severity of the finding is always Unknown. | +| Scanner Type | Scanner used to perform testing. | + ### Dismissing a vulnerability To dismiss a vulnerability, you must set its status to Dismissed. This dismisses the vulnerability @@ -225,11 +264,11 @@ vulnerability as you learn more over time. > Introduced 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 will select that individual vulnerability. +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 will deselect all the vulnerabilities in the list. +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. -Pressing the "Dismiss Selected" button will dismiss all the selected vulnerabilities at once, with the reason you chose. +Pressing the "Dismiss Selected" button dismisses all the selected vulnerabilities at once, with the reason you chose.  diff --git a/doc/user/application_security/license_compliance/index.md b/doc/user/application_security/license_compliance/index.md index ed81eb8ca10..4c598d851a9 100644 --- a/doc/user/application_security/license_compliance/index.md +++ b/doc/user/application_security/license_compliance/index.md @@ -3,3 +3,6 @@ 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 index df44041600b..bd67fca529f 100644 --- a/doc/user/application_security/license_management/index.md +++ b/doc/user/application_security/license_management/index.md @@ -3,3 +3,6 @@ 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 35582aa20ed..14ca27cdabe 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Offline environments @@ -34,7 +34,7 @@ must come in through physical media (USB drive, hard drive, writeable DVD, etc.) ## Overview -GitLab scanners generally will connect to the internet to download the +GitLab scanners usually connect to the internet to download the latest sets of signatures, rules, and patches. A few extra steps are necessary to configure the tools to function properly by using resources available on your local network. @@ -73,7 +73,7 @@ hosting the latest versions of that dependency or image. ### Scanner signature and rule updates -When connected to the internet, some scanners will reference public databases +When connected to the internet, some scanners reference public databases for the latest sets of signatures and rules to check against. Without connectivity, this is not possible. Depending on the scanner, you must therefore disable these automatic update checks and either use the databases that they came @@ -131,7 +131,7 @@ a bastion, and used only for this specific project. #### Scheduling the updates -By default, this project's pipeline will run only once, when the `.gitlab-ci.yml` is added to the +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 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. @@ -139,7 +139,7 @@ example, you can set this up to download and store the Docker images every week. Some images can be updated more frequently than others. For example, the [vulnerability database](https://hub.docker.com/r/arminc/clair-db/tags) for Container Scanning is updated daily. To update this single image, create a new Scheduled Pipeline that runs daily and set `SECURE_BINARIES_ANALYZERS` to `clair-vulnerabilities-db`. Only -this job will be triggered, and the image will be updated daily and made available in the project +this job is triggered, and the image is updated daily and made available in the project registry. #### Using the secure bundle created diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 4cbd4496dea..15412473ab1 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -1,7 +1,7 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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)** diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 49e194a9319..fb3bc256e11 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -1,15 +1,16 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- # Static Application Security Testing (SAST) -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. +> - [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. -NOTE: **Note:** +NOTE: The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) explains how 4 of the top 6 attacks were application based. Download it to learn how to protect your organization. @@ -50,16 +51,16 @@ To run SAST jobs, by default, you need GitLab Runner with the [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. If you're using the shared runners on GitLab.com, this is enabled by default. -CAUTION: **Caution:** +WARNING: Our SAST jobs require a Linux container type. Windows containers are not yet supported. -CAUTION: **Caution:** +WARNING: If you use your own runners, make sure the Docker version installed is **not** `19.03.0`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. ## Supported languages and frameworks -GitLab SAST supports a variety of languages, package managers, and frameworks. Our SAST security scanners also feature automatic language detection which works even for mixed-language projects. If any supported language is detected in project source code we will automatically run the appropriate SAST analyzers. +GitLab SAST supports a variety of languages, package managers, and frameworks. Our SAST security scanners also feature automatic language detection which works even for mixed-language projects. If any supported language is detected in project source code we automatically run the appropriate SAST analyzers. You can also [view our language roadmap](https://about.gitlab.com/direction/secure/static-analysis/sast/#language-support) and [request other language support by opening an issue](https://gitlab.com/groups/gitlab-org/-/epics/297). @@ -93,6 +94,31 @@ Note that the Java analyzers can also be used for variants like the [Grails](https://grails.org/), and the [Maven wrapper](https://github.com/takari/maven-wrapper). +### Multi-project support + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4895) in GitLab 13.7. + +GitLab SAST can scan repositories that contain multiple projects. All projects must be in the same +language. + +The following analyzers have multi-project support: + +- Bandit +- ESLint +- Gosec +- Kubesec +- NodeJsScan +- MobSF +- PMD +- Security Code Scan +- 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). + ### 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. @@ -188,7 +214,7 @@ the pipeline configuration, the last mention of the variable takes precedence. ### Overriding SAST jobs -CAUTION: **Deprecation:** +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. @@ -330,13 +356,13 @@ variables: If your project requires custom build configurations, it can be preferable to avoid compilation during your SAST execution and instead pass all job artifacts from an -earlier stage within the pipeline. This is the current strategy when requiring +earlier stage in the pipeline. This is the current strategy when requiring 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 -analyzer and compilation will be skipped: +analyzer and compilation is skipped: ```yaml image: maven:3.6-jdk-8-alpine @@ -379,7 +405,10 @@ SAST can be [configured](#customizing-the-sast-settings) using environment varia #### 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. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. + +To control the verbosity of logs, set the `SECURE_LOG_LEVEL` environment variable. Messages of this +logging level or higher are output. From highest to lowest severity, the logging levels are: @@ -392,7 +421,7 @@ 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 within the SAST environment. +of CA certs that you want to trust in the SAST environment. #### Docker images @@ -410,8 +439,8 @@ Some analyzers make it possible to filter out vulnerabilities under a given thre | 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 will also match patterns. | -| `SEARCH_MAX_DEPTH` | 4 | Maximum number of directories traversed when searching for source code files. | +| `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. | @@ -424,7 +453,7 @@ 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` will scan. If dependencies are defined, `helm dependency build` should be ran in a `before_script` to fetch the necessary dependencies. | +| `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. | @@ -451,15 +480,20 @@ all [custom environment variables](../../../ci/variables/README.md#custom-enviro to the underlying SAST analyzer images if [the SAST vendored template](#configuration) is used. -CAUTION: **Caution:** +WARNING: Variables having names starting with these prefixes are **not** propagated to the SAST Docker container and/or analyzer containers: `DOCKER_`, `CI`, `GITLAB_`, `FF_`, `HOME`, `PWD`, `OLDPWD`, `PATH`, `SHLVL`, `HOSTNAME`. ### Experimental features -Receive early access to experimental features. +You can receive early access to experimental features. Experimental features might be added, +removed, or promoted to regular features at any time. + +Experimental features available are: + +- Enable scanning of iOS and Android apps using the [MobSF analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf/). -Currently, this will enable scanning of iOS and Android apps via the [MobSF analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf/). +#### Enable experimental features To enable experimental features, add the following to your `.gitlab-ci.yml` file: @@ -571,7 +605,7 @@ Once a vulnerability is found, you can interact with it. Read more on how to ## Vulnerabilities database -Vulnerabilities contained within the vulnerability database can be searched +Vulnerabilities contained in the vulnerability database can be searched and viewed at the [GitLab vulnerability advisory database](https://advisories.gitlab.com). ### Vulnerabilities database update diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 5eba0fa44ba..8f57e2c5535 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Secret Detection @@ -40,19 +40,26 @@ The [default ruleset provided by Gitleaks](https://gitlab.com/gitlab-org/securit - Cloud services: - Amazon Web Services (AWS) - Google Cloud Platform (GCP) -Encryption keys: + - Heroku API +- Encryption keys: - PKCS8 - RSA - SSH - PGP + - DSA + - EC - Social media platforms: - Facebook API - Twitter API - Cloud SaaS vendors: - GitHub API - Slack Token + - Slack Webhook - Stripe API + - Twilio API - Generic API key strings starting with `api-` +- Password in URL +- U.S. Social Security Number ## Requirements @@ -61,10 +68,10 @@ To run Secret Detection jobs, by default, you need GitLab Runner with the [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. If you're using the shared runners on GitLab.com, this is enabled by default. -CAUTION: **Caution:** +WARNING: Our Secret Detection jobs expect a Linux container type. Windows containers are not supported. -CAUTION: **Caution:** +WARNING: If you use your own runners, make sure the Docker version installed is **not** `19.03.0`. See [troubleshooting information](../sast#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. @@ -102,7 +109,7 @@ begins with a dollar sign (`$`), as this likely indicates the password is an env For example, `https://username:$password@example.com/path/to/repo` isn't detected, while `https://username:password@example.com/path/to/repo` is. -NOTE: **Note:** +NOTE: You don't have to configure Secret Detection manually as shown in this section if you're using [Auto Secret Detection](../../../topics/autodevops/stages.md#auto-secret-detection) provided by [Auto DevOps](../../../topics/autodevops/index.md). @@ -115,7 +122,7 @@ Add the following to your `.gitlab-ci.yml` file: ```yaml include: - - template: Secret-Detection.gitlab-ci.yml + - template: Security/Secret-Detection.gitlab-ci.yml ``` The included template creates Secret Detection jobs in your CI/CD pipeline and scans @@ -130,13 +137,13 @@ always take the latest Secret Detection artifact available. > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4639) in GitLab 13.6. -Upon detection of a secret, GitLab supports post processing hooks. These can be used to take actions like notifying the cloud service who issued the secret. The cloud provider can confirm the credentials and take remediation actions like revoking or reissuing a new secret and notifying the creator of the secret. Post-processing workflows vary by supported cloud providers. +Upon detection of a secret, GitLab supports post processing hooks. These can be used to take actions like notifying the cloud service who issued the secret. The cloud provider can confirm the credentials and take remediation actions like revoking or reissuing a new secret and notifying the creator of the secret. Post-processing workflows vary by supported cloud providers. GitLab currently supports post-processing for following service providers: - Amazon Web Services (AWS) -Third party cloud and SaaS providers can [express integration interest by filling out this form](https://forms.gle/wWpvrtLRK21Q2WJL9). Learn more about the [technical details of post-processing secrets](https://gitlab.com/groups/gitlab-org/-/epics/4639). +Third party cloud and SaaS providers can [express integration interest by filling out this form](https://forms.gle/wWpvrtLRK21Q2WJL9). Learn more about the [technical details of post-processing secrets](https://gitlab.com/groups/gitlab-org/-/epics/4639). ### Customizing settings @@ -153,7 +160,7 @@ override the `secret_detection` job with the `SECRET_DETECTION_HISTORIC_SCAN` va ```yaml include: - - template: Secret-Detection.gitlab-ci.yml + - template: Security/Secret-Detection.gitlab-ci.yml secret_detection: variables: @@ -163,7 +170,7 @@ secret_detection: Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable takes precedence. -CAUTION: **Deprecation:** +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. @@ -252,6 +259,27 @@ We have created a [short video walkthrough](https://youtu.be/wDtc_K00Y0A) showca <iframe src="https://www.youtube.com/embed/wDtc_K00Y0A" frameborder="0" allowfullscreen="true"> </iframe> </figure> +## Running Secret Detection in an offline environment + +For self-managed GitLab instances in an environment with limited, restricted, or intermittent access +to external resources through the internet, some adjustments are required for the Secret Detection job to +run successfully. For more information, see [Offline environments](../offline_deployments/index.md). + +### Requirements for offline Secret Detection + +To use Secret Detection in an offline environment, you need: + +- GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). +- A Docker Container Registry with locally available copy of Secret Detection [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. +- Configure certificate checking of packages (optional). + +GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), +meaning the runner tries to pull Docker images from the GitLab container registry even if a local +copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) +in an offline environment if you prefer using only locally available Docker images. However, we +recommend keeping the pull policy setting to `always` if not in an offline environment, as this +enables the use of updated scanners in your CI/CD pipelines. + ### Make GitLab Secret Detection analyzer image available inside your Docker registry Import the following default Secret Detection analyzer images from `registry.gitlab.com` into your @@ -278,8 +306,46 @@ 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 + +Add the following configuration to your `.gitlab-ci.yml` file. You must replace +`SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry: + +```yaml +include: + - template: Security/Secret-Detection.gitlab-ci.yml + +variables: + SECURE_ANALYZERS_PREFIX: "localhost:5000/analyzers" +``` + +The Secret Detection job should now use local copies of the Secret Detection analyzer to scan your code and generate +security reports without requiring internet access. + ## Troubleshooting ### Getting warning message `gl-secret-detection-report.json: no matching files` For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). + +### 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. + +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: + +```plaintext +ERRO[2020-11-18T18:05:52Z] object not found +[ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ Couldn't run the gitleaks command: exit status 2 +[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`: + +```yaml +secret_detection: + variables: + GIT_DEPTH: 100 +``` diff --git a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png Binary files differdeleted file mode 100644 index 0310ef3ea0a..00000000000 --- a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..cd8dbed48fc --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_7.png diff --git a/doc/user/application_security/security_dashboard/img/vulnerability_details_create_issue_v13_7.png b/doc/user/application_security/security_dashboard/img/vulnerability_details_create_issue_v13_7.png Binary files differnew file mode 100644 index 00000000000..b9b228c9430 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/vulnerability_details_create_issue_v13_7.png diff --git a/doc/user/application_security/security_dashboard/img/vulnerability_page_v13_1.png b/doc/user/application_security/security_dashboard/img/vulnerability_page_v13_1.png Binary files differdeleted file mode 100644 index 9cf95b197fe..00000000000 --- a/doc/user/application_security/security_dashboard/img/vulnerability_page_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 9f402cea9dc..2750aa81872 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -2,7 +2,7 @@ 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/#designated-technical-writers +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)** @@ -87,7 +87,7 @@ 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, -you will see the number of failures clearly indicated. The failure notification takes you directly to +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, @@ -142,7 +142,7 @@ Next to the timeline chart is a list of projects, grouped and sorted by the seve | B | One or more "low" | | A | Zero vulnerabilities | -Projects with no vulnerability tests configured will not appear in the list. Additionally, dismissed +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. @@ -192,7 +192,7 @@ You can export all your vulnerabilities in CSV (comma separated values) format b 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: **Note:** +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. @@ -225,12 +225,12 @@ are discovered. To ensure the information on the Security Dashboard is regularly updated, [configure a scheduled pipeline](../../../ci/pipelines/schedules.md) to run a -daily security scan. This will update the information displayed on the Security +daily security scan. This updates the information displayed on the Security Dashboard regardless of how often the default branch is updated. That way, reports are created even if no code change happens. -CAUTION: **Warning:** +WARNING: Running Dependency Scanning from a scheduled pipeline might result in false negatives if your project doesn't have a lock file and isn't configured for Continuous Delivery. A lock file is a file that lists all transient dependencies and keeps track of their exact versions. The false negative @@ -249,7 +249,7 @@ to configure daily security scans. 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: @@ -264,7 +264,7 @@ 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: diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index f975de213ef..e046b18b2a4 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -1,20 +1,20 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- -# Secure and Defend terminology +# Secure and Protect terminology -This terminology list for GitLab Secure and Defend aims to: +This terminology list for GitLab Secure and Protect aims to: - Promote a ubiquitous language for discussing application security. -- Improve the effectiveness of communication regarding GitLab's application security features. +- Improve the effectiveness of communication regarding GitLab application security features. - Get new contributors up to speed faster. -This document defines application security terms in the specific context of GitLab's Secure and -Defend products. Terms may therefore have different meanings outside of GitLab Secure and Defend. +This document defines application security terms in the specific context of GitLab Secure and +Protect features. Terms may therefore have different meanings outside that context. ## Terms @@ -24,7 +24,7 @@ Software that performs a scan. The scan analyzes an attack surface for vulnerabi a report containing findings. Reports adhere to the [Secure report format](#secure-report-format). Analyzers integrate into GitLab using a CI job. The report produced by the analyzer is published as -an artifact once the job is complete. GitLab ingests this report, allowing users to visualize and +an artifact after the job is complete. GitLab ingests this report, allowing users to visualize and manage found vulnerabilities. For more information, see [Security Scanner Integration](../../../development/integrations/secure.md). Many GitLab analyzers follow a standard approach using Docker to run a wrapped scanner. For example, @@ -74,7 +74,7 @@ or creating a merge request. ### Finding -An asset that has the potential to be vulnerable, identified within a project by an analyzer. Assets +An asset that has the potential to be vulnerable, identified in a project by an analyzer. Assets include but are not restricted to source code, binary packages, containers, dependencies, networks, applications, and infrastructure. @@ -98,9 +98,9 @@ A finding's primary identifier is a value unique to that finding. The external t of the finding's [first identifier](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/v2.4.0-rc1/dist/sast-report-format.json#L228) combine to create the value. -Examples of primary identifiers include ZAP's `PluginID`, or `CVE` for Klar. Note that the -identifier must be stable. Subsequent scans must return the same value for the same finding, even if -the location has slightly changed. +Examples of primary identifiers include `PluginID` for OWASP Zed Attack Proxy (ZAP), or `CVE` for +Klar. Note that the identifier must be stable. Subsequent scans must return the same value for the +same finding, even if the location has slightly changed. ### Report finding diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index f85d4f0140c..f7bd201aba9 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Protect group: Container Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Threat Monitoring **(ULTIMATE)** @@ -101,7 +101,7 @@ reflected upon refresh. Enforcement status changes are deployed directly to a deployment namespace of the selected environment. By default, the network policy list contains predefined policies in a -disabled state. Once enabled,a predefined policy deploys to the +disabled state. Once enabled, a predefined policy deploys to the selected environment's deployment platform and you can manage it like the regular policies. diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 95bb1ff1a67..705964dba66 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -2,7 +2,7 @@ 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/#designated-technical-writers +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 @@ -37,7 +37,7 @@ the following values: |-----------|------------------------------------------------------------------------------------------------------------------| | 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 will not be resolved | +| 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 | A timeline shows you when the vulnerability status has changed @@ -47,9 +47,9 @@ and allows you to comment on a change. You can create an issue for a vulnerability by selecting the **Create issue** button. -This creates a [confidential issue](../../project/issues/confidential_issues.md) in the -project the vulnerability came from and pre-populates it with useful information from -the vulnerability report. After the issue is created, GitLab redirects you to the +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. ## Link issues to the vulnerability diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index 4bd15c7922d..546746af535 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -48,13 +48,10 @@ monospaced font: and lines breaks will be preserved. ``` -An admonition paragraph grabs the reader's attention: +Admonition paragraphs grab the reader's attention: -```plaintext -NOTE: This is a brief reference, please read the full documentation at https://asciidoctor.org/docs/. - -TIP: Lists can be indented. Leading whitespace is not significant. -``` +- `NOTE: This is a brief reference, please read the full documentation at https://asciidoctor.org/docs/.` +- `TIP: Lists can be indented. Leading whitespace is not significant.` ### Text Formatting @@ -440,6 +437,36 @@ graph LR ---- ``` +#### Kroki + +Kroki supports more than a dozen diagram libraries. +To make Kroki available in GitLab, a GitLab administrator needs to enable it first. +Read more in the [Kroki integration](../administration/integration/kroki.md) page. + +Once Kroki is enabled, you can create a wide variety of diagrams in AsciiDoc and Markdown documents. +Here's an example using a GraphViz diagram: + +**AsciiDoc** + +```plaintext +[graphviz] +.... +digraph G { + Hello->World +} +.... +``` + +**Markdown** + +````markdown +```graphviz +digraph G { + Hello->World +} +``` +```` + #### PlantUML To make PlantUML available in GitLab, a GitLab administrator needs to enable it first. diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md index 47249a44bc1..4ece94447bc 100644 --- a/doc/user/award_emojis.md +++ b/doc/user/award_emojis.md @@ -1,10 +1,10 @@ --- 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/#designated-technical-writers +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 +# Award emoji **(CORE)** > - [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 @@ -46,7 +46,7 @@ celebrate an accomplishment or agree with an opinion. To: - Add an award emoji, click the smile in the top right of the comment and pick an emoji from the dropdown. -- Remove an award emoji, click the emoji again and the vote will be removed. +- Remove an award emoji, click the emoji again.  diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 74c679d9bb9..5963485aebc 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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)** @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/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). -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. The [GitLab Kubernetes Agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) @@ -56,6 +56,12 @@ There are several components that work in concert for the Agent to accomplish Gi These repositories might be the same GitLab project or separate projects. +NOTE: +GitLab recommends you use the same GitLab project for the agent configuration +and manifest repositories. Our backlog contains issues for adding support for +[private manifest repositories outside of the configuration project](https://gitlab.com/gitlab-org/gitlab/-/issues/220912) and +[group level agents](https://gitlab.com/gitlab-org/gitlab/-/issues/283885). + For more details, please refer to our [full architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture) in the Agent project. ## Get started with GitOps and the GitLab Agent @@ -82,8 +88,8 @@ Upgrade your agent installations together with GitLab upgrades. To decide which 1. Open the [GITLAB_KAS_VERSION](https://gitlab.com/gitlab-org/gitlab/-/blob/master/GITLAB_KAS_VERSION) file from the GitLab Repository, which contains the latest `agentk` version associated with the `master` branch. 1. Change the `master` branch and select the Git tag associated with your version. For instance, you could change it to GitLab [v13.5.3-ee release](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.5.3-ee/GITLAB_KAS_VERSION) -The available `agentk` versions can be found in -[its container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/eyJuYW1lIjoiZ2l0bGFiLW9yZy9jbHVzdGVyLWludGVncmF0aW9uL2dpdGxhYi1hZ2VudC9hZ2VudGsiLCJ0YWdzX3BhdGgiOiIvZ2l0bGFiLW9yZy9jbHVzdGVyLWludGVncmF0aW9uL2dpdGxhYi1hZ2VudC9yZWdpc3RyeS9yZXBvc2l0b3J5LzEyMjMyMDUvdGFncz9mb3JtYXQ9anNvbiIsImlkIjoxMjIzMjA1LCJjbGVhbnVwX3BvbGljeV9zdGFydGVkX2F0IjpudWxsfQ==). +The available `agentk` and `kas` versions can be found in +[the container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/). ### Install the Kubernetes Agent Server @@ -93,7 +99,7 @@ chart](https://gitlab.com/gitlab-org/charts/gitlab). If you don't already have GitLab installed, please refer to our [installation documentation](https://docs.gitlab.com/ee/install/README.html). -NOTE: **Note:** +NOTE: GitLab plans to include the KAS on [GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/3834). #### Install with Omnibus @@ -161,23 +167,9 @@ gitops: ``` GitLab [versions 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) also -supports manifest projects containing multiple directories (or subdirectories) -of YAML files. To use multiple YAML files, specify a `paths` attribute: - -```yaml -gitops: - manifest_projects: - - id: "path-to/your-manifest-project-number1" - paths: - # Read all .yaml files from team1/app1 directory. - # See https://github.com/bmatcuk/doublestar#about and - # https://pkg.go.dev/github.com/bmatcuk/doublestar/v2#Match for globbing rules. - - glob: '/team1/app1/*.yaml' - # Read all .yaml files from team2/apps and all subdirectories - - glob: '/team2/apps/**/*.yaml' - # If 'paths' is not specified or is an empty list, the configuration below is used - - glob: '/**/*.{yaml,yml,json}' -``` +supports manifest projects containing +multiple directories (or subdirectories) of YAML files. For more information see our +documentation on the [Kubernetes Agent configuration respository](repository.md). ### Create an Agent record in GitLab @@ -223,7 +215,7 @@ the Agent in subsequent steps. You can create an Agent record either: } ``` - NOTE: **Note:** + NOTE: GraphQL only displays the token one time after creating it. If you are new to using the GitLab GraphQL API, refer to the @@ -257,11 +249,14 @@ example [`resources.yml` file](#example-resourcesyml-file) in the following ways The agent can use the WebSockets or gRPC protocols to connect to the Agent Server. Select the option appropriate for your cluster configuration and GitLab architecture: - The `wss` scheme (an encrypted WebSockets connection) is specified by default - after you install `gitlab-kas` sub-chart or enable `kas` for Omnibus GitLab. - In this case, you must set `wss://GitLab.host.tld:443/-/kubernetes-agent` as + after you install the `gitlab-kas` sub-chart, or enable `gitlab-kas` for Omnibus GitLab. + When using the sub-chart, you must set `wss://kas.host.tld:443` as + `kas-address`, where `host.tld` is the domain you've setup for your GitLab installation. + When using Omnibus GitLab, you must set `wss://GitLab.host.tld:443/-/kubernetes-agent` as `kas-address`, where `GitLab.host.tld` is your GitLab hostname. - - Specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent`) + - When using the sub-chart, specify the `ws` scheme (such as `ws://kas.host.tld:80`) to use an unencrypted WebSockets connection. + When using the Omnibus GitLab, specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent`). - Specify the `grpc` scheme if both Agent and Server are installed in one cluster. In this case, you may specify `kas-address` value as `grpc://gitlab-kas.<your-namespace>:5005`) to use gRPC directly, where `gitlab-kas` @@ -270,6 +265,10 @@ example [`resources.yml` file](#example-resourcesyml-file) in the following ways Follow the [Support TLS for gRPC communication issue](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) for progress updates. + - When deploying KAS through the [GitLab chart](https://docs.gitlab.com/charts/), it's possible to customize the `kas-address` for `wss` and `ws` schemes to whatever you need. + Check the [chart's KAS Ingress docs](https://docs.gitlab.com/charts/charts/gitlab/kas/#ingress) + to learn more about it. + - In the near future, Omnibus GitLab intends to provision `gitlab-kas` under a sub-domain by default, instead of the `/-/kubernetes-agent` path. Please follow [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5784) for details. - If you defined your own secret name, replace `gitlab-agent-token` with your secret name in the `secretName:` section. @@ -317,7 +316,8 @@ spec: args: - --token-file=/config/token - --kas-address - - wss://gitlab.host.tld:443/-/kubernetes-agent + - wss://kas.host.tld:443 # change this line for the one below if using Omnibus GitLab + # - wss://gitlab.host.tld:443/-/kubernetes-agent volumeMounts: - name: token-volume mountPath: /config @@ -392,9 +392,12 @@ subjects: In a previous step, you configured a `config.yaml` to point to the GitLab projects the Agent should synchronize. In each of those projects, you must create a `manifest.yaml` file for the Agent to monitor. You can auto-generate this `manifest.yaml` with a -templating engine or other means. Only public projects are supported as -manifest projects. Support for private projects is planned in the issue -[Agent authorization for private manifest projects](https://gitlab.com/gitlab-org/gitlab/-/issues/220912). +templating engine or other means. + +The agent is authorized to download manifests for the configuration +project, and public projects. Support for other private projects is +planned in the issue [Agent authorization for private manifest +projects](https://gitlab.com/gitlab-org/gitlab/-/issues/220912). Each time you commit and push a change to this file, the Agent logs the change: @@ -548,7 +551,7 @@ issue is in progress, directly edit the deployment with the `kubectl edit deployment gitlab-kas` command, and change `--listen-websocket=true` to `--listen-websocket=false`. After running that command, you should be able to use `grpc://gitlab-kas.<YOUR-NAMESPACE>:5005`. -#### Agent logs - Decompressor is not installed for grpc-encoding +### Agent logs - Decompressor is not installed for grpc-encoding ```plaintext {"level":"warn","time":"2020-11-05T05:25:46.916Z","msg":"GetConfiguration.Recv failed","error":"rpc error: code = Unimplemented desc = grpc: Decompressor is not installed for grpc-encoding \"gzip\""} diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md new file mode 100644 index 00000000000..b71bbc29ef9 --- /dev/null +++ b/doc/user/clusters/agent/repository.md @@ -0,0 +1,96 @@ +--- +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/#designated-technical-writers +--- + +# Kubernetes Agent configuration repository **(PREMIUM ONLY)** + +> - [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). + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +The [GitLab Kubernetes Agent integration](index.md) supports hosting your configuration for +multiple GitLab Kubernetes Agents in a single repository. These agents can be running +in the same cluster or in multiple clusters, and potentially with more than one Agent per cluster. + +The Agent bootstraps with the GitLab installation URL and an authentication token, +and you provide the rest of the configuration in your repository, following +Infrastructure as Code (IaaC) best practices. + +A minimal repository layout looks like this, with `my_agent_1` as the name +of your Agent: + +```plaintext +|- .gitlab + |- agents + |- my_agent_1 + |- config.yaml +``` + +## Synchronize manifest projects + +Your `config.yaml` file contains a `gitops` section, which contains a `manifest_projects` +section. Each `id` in the `manifest_projects` section is the path to a Git repository +with Kubernetes resource definitions in YAML or JSON format. The Agent monitors +each project you declare, and when the project changes, GitLab deploys the changes +using the Agent. + +To use multiple YAML files, specify a `paths` attribute in the `gitops` section. + +By default, the Agent monitors all +[Kubernetes object types](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields). +You can exclude some types of resources from monitoring. This enables you to reduce +the permissions needed by the GitOps feature, through `resource_exclusions`. + +To enable a specific named resource, first use `resource_inclusions` to enable desired resources. +The following file excerpt includes specific `api_groups` and `kinds`. The `resource_exclusions` +which follow excludes all other `api_groups` and `kinds`: + +```yaml +gitops: + # Manifest projects are watched by the agent. Whenever a project changes, + # GitLab deploys the changes using the agent. + manifest_projects: + # No authentication mechanisms are currently supported. + # The `id` is a path to a Git repository with Kubernetes resource definitions + # in YAML or JSON format. + - id: gitlab-org/cluster-integration/gitlab-agent + # Holds the only API groups and kinds of resources that gitops will monitor. + # Inclusion rules are evaluated first, then exclusion rules. + # If there is still no match, resource is monitored. + # Resources: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields + # Groups: https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-groups-and-versioning + resource_inclusions: + - api_groups: + - apps + kinds: + - '*' + - api_groups: + - '' + kinds: + - 'ConfigMap' + # Holds the API groups and kinds of resources to exclude from gitops watch. + # Inclusion rules are evaluated first, then exclusion rules. + # If there is still no match, resource is monitored. + resource_exclusions: + - api_groups: + - '*' + kinds: + - '*' + # Namespace to use if not set explicitly in object manifest. + default_namespace: my-ns + # Paths inside of the repository to scan for manifest files. + # Directories with names starting with a dot are ignored. + paths: + # Read all .yaml files from team1/app1 directory. + # See https://github.com/bmatcuk/doublestar#about and + # https://pkg.go.dev/github.com/bmatcuk/doublestar/v2#Match for globbing rules. + - glob: '/team1/app1/*.yaml' + # Read all .yaml files from team2/apps and all subdirectories + - glob: '/team2/apps/**/*.yaml' + # If 'paths' is not specified or is an empty list, the configuration below is used + - glob: '/**/*.{yaml,yml,json}' +``` diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 67a53fa773f..53be7e995d5 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 @@ -10,595 +10,16 @@ GitLab provides **GitLab Managed Apps** for various applications which can be added directly to your configured cluster. These applications are needed for [Review Apps](../../ci/review_apps/index.md) and [deployments](../../ci/environments/index.md) when using [Auto DevOps](../../topics/autodevops/index.md). -You can install them after you [create a cluster](../project/clusters/add_remove_clusters.md). GitLab provides -GitLab Managed Apps that can installed with [one-click](#install-with-one-click) or [using CI/CD](#install-using-gitlab-cicd-alpha). +You can install them after you [create a cluster](../project/clusters/add_remove_clusters.md). +GitLab provides GitLab Managed Apps [using CI/CD](#install-using-gitlab-cicd). +GitLab Managed Apps with [one-click installations](#install-with-one-click) +have been deprecated, and are scheduled for removal in GitLab 14.0. -## Install with one click - -Applications managed by GitLab are installed onto the `gitlab-managed-apps` -namespace. This namespace: - -- Is different from the namespace used for project deployments. -- Is created once. -- Has a non-configurable name. - -To view a list of available applications to install for a: - -- [Project-level cluster](../project/clusters/index.md), navigate to your project's - **Operations > Kubernetes**. -- [Group-level cluster](../group/clusters/index.md), navigate to your group's - **Kubernetes** page. - -You can install the following applications with one click: - -- [Helm](#helm) -- [Ingress](#ingress) -- [cert-manager](#cert-manager) -- [Prometheus](#prometheus) -- [GitLab Runner](#gitlab-runner) -- [JupyterHub](#jupyterhub) -- [Knative](#knative) -- [Crossplane](#crossplane) -- [Elastic Stack](#elastic-stack) -- [Fluentd](#fluentd) - -With the exception of Knative, the applications are installed in a dedicated -namespace called `gitlab-managed-apps`. - -Some applications are installable only for a project-level cluster. -Support for installing these applications in a group-level cluster is -planned for future releases. -For updates, see the [issue tracking progress](https://gitlab.com/gitlab-org/gitlab/-/issues/24411). - -CAUTION: **Caution:** -If you have an existing Kubernetes cluster with Helm already installed, -you should be careful as GitLab cannot detect it. In this case, installing -Helm with the applications results in the cluster having it twice, which -can lead to confusion during deployments. - -In GitLab versions 11.6 and greater, Helm is upgraded to the latest version -supported by GitLab before installing any of the applications. - -### Helm - -> - Introduced in GitLab 10.2 for project-level clusters. -> - Introduced in GitLab 11.6 for group-level clusters. -> - [Uses a local Tiller](https://gitlab.com/gitlab-org/gitlab/-/issues/209736) in GitLab 13.2 and later. -> - [Uses Helm 3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46267) for clusters created with GitLab 13.6 and later. - -[Helm](https://helm.sh/docs/) is a package manager for Kubernetes and is -used to install the GitLab-managed apps. GitLab runs each `helm` command -in a pod within the `gitlab-managed-apps` namespace inside the cluster. - -- For clusters created on GitLab 13.6 and newer, GitLab uses Helm 3 to manage - applications. -- For clusters created on versions of GitLab prior to 13.6, GitLab uses - Helm 2 with a local [Tiller](https://v2.helm.sh/docs/glossary/#tiller) server. - Prior to [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/209736), - GitLab used an in-cluster Tiller server in the `gitlab-managed-apps` - namespace. You can safely remove this server after upgrading to GitLab 13.2 - or newer. - -GitLab's Helm integration does not support installing applications behind a proxy, -but a [workaround](../../topics/autodevops/index.md#install-applications-behind-a-proxy) -is available. - -#### Upgrade a cluster to Helm 3 - -GitLab does not currently offer a way to migrate existing application management -on existing clusters from Helm 2 to Helm 3. To migrate a cluster to Helm 3: - -1. Uninstall all applications on your cluster. -1. [Remove the cluster integration](../project/clusters/add_remove_clusters.md#removing-integration). -1. [Re-add the cluster](../project/clusters/add_remove_clusters.md#existing-kubernetes-cluster) as - an existing cluster. - -### cert-manager - -> Introduced in GitLab 11.6 for project- and group-level clusters. - -[cert-manager](https://cert-manager.io/docs/) is a native Kubernetes certificate -management controller that helps with issuing certificates. Installing -cert-manager on your cluster issues a certificate by [Let's Encrypt](https://letsencrypt.org/) -and ensures that certificates are valid and up-to-date. - -The chart used to install this application depends on the version of GitLab used. In: - -- GitLab 12.3 and newer, the [`jetstack/cert-manager`](https://github.com/jetstack/cert-manager) - chart is used with a [`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/cert_manager/values.yaml) - file. -- GitLab 12.2 and older, the [`stable/cert-manager`](https://github.com/helm/charts/tree/master/stable/cert-manager) - chart was used. - -If you installed cert-manager prior to GitLab 12.3, Let's Encrypt -[blocks requests](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753) -from older versions of `cert-manager`. To resolve this: - -1. [Back up any additional configuration](https://cert-manager.io/docs/tutorials/backup/). -1. Uninstall cert-manager. -1. Install cert-manager again. - -### GitLab Runner - -> - Introduced in GitLab 10.6 for project-level clusters. -> - Introduced in GitLab 11.10 for group-level clusters. - -[GitLab Runner](https://docs.gitlab.com/runner/) is the open source project that -is used to run your jobs and send the results back to GitLab. It's used in -conjunction with [GitLab CI/CD](../../ci/README.md), the open-source continuous -integration service included with GitLab that coordinates the jobs. - -If the project is on GitLab.com, [shared runners](../gitlab_com/index.md#shared-runners) -are available. You don't have to deploy one if they are enough for your -needs. If a project-specific runner is desired, or there are no shared runners, -you can deploy one. - -The deployed runner is set as **privileged**. Root access to the underlying -server is required to build Docker images, so it's the default. Be sure to read -the [security implications](../project/clusters/index.md#security-implications) -before deploying one. - -The [`runner/gitlab-runner`](https://gitlab.com/gitlab-org/charts/gitlab-runner) -chart is used to install this application, using -[a preconfigured `values.yaml`](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/blob/master/values.yaml) -file. Customizing the installation by modifying this file is not supported. This -also means you cannot modify `config.toml` file for this Runner. If you want to -have that possibility and still deploy Runner in Kubernetes, consider using the -[Cluster management project](management_project.md) or installing Runner manually -via [GitLab Runner Helm Chart](https://docs.gitlab.com/runner/install/kubernetes.html). - -### Ingress - -> - Introduced in GitLab 10.2 for project-level clusters. -> - Introduced in GitLab 11.6 for group-level clusters. - -[Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) -provides load balancing, SSL termination, and name-based virtual hosting -out of the box. It acts as a web proxy for your applications and is useful -if you want to use [Auto DevOps](../../topics/autodevops/index.md) or deploy your own web apps. - -The Ingress Controller installed is -[Ingress-NGINX](https://kubernetes.io/docs/concepts/services-networking/ingress/), -which is supported by the Kubernetes community. - -With the following procedure, a load balancer must be installed in your cluster -to obtain the endpoint. You can use either -Ingress, or Knative's own load balancer ([Istio](https://istio.io)) if using Knative. - -To publish your web application, you first need to find the endpoint, which is either an IP -address or a hostname associated with your load balancer. - -To install it, click on the **Install** button for Ingress. GitLab attempts -to determine the external endpoint and it should be available within a few minutes. - -#### Determining the external endpoint automatically - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17052) in GitLab 10.6. - -After you install Ingress, the external endpoint should be available within a few minutes. - -TIP: **Tip:** -This endpoint can be used for the -[Auto DevOps base domain](../../topics/autodevops/index.md#auto-devops-base-domain) -using the `KUBE_INGRESS_BASE_DOMAIN` environment variable. - -If the endpoint doesn't appear and your cluster runs on Google Kubernetes Engine: - -1. [Examine your Kubernetes cluster](https://console.cloud.google.com/kubernetes) - on Google Kubernetes Engine to ensure there are no errors on its nodes. -1. Ensure you have enough [Quotas](https://console.cloud.google.com/iam-admin/quotas) - on Google Kubernetes Engine. For more information, see - [Resource Quotas](https://cloud.google.com/compute/quotas). -1. Review [Google Cloud's Status](https://status.cloud.google.com/) for service - disruptions. - -The [`stable/nginx-ingress`](https://github.com/helm/charts/tree/master/stable/nginx-ingress) -chart is used to install this application with a -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/ingress/values.yaml) -file. - -After installing, you may see a `?` for **Ingress IP Address** depending on the -cloud provider. For EKS specifically, this is because the ELB is created -with a DNS name, not an IP address. If GitLab is still unable to -determine the endpoint of your Ingress or Knative application, you can -[determine it manually](#determining-the-external-endpoint-manually). - -#### Determining the external endpoint manually - -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 will incur 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. - -#### Using a static IP - -By default, an ephemeral external IP address is associated to the cluster's load -balancer. If you associate the ephemeral IP with your DNS and the IP changes, -your apps won't be reachable, and you'd have to change the DNS record again. -To avoid that, change it into a static reserved IP. - -Read how to [promote an ephemeral external IP address in GKE](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip). - -#### Pointing your DNS at the external endpoint - -After you have set up the external endpoint, associate it with a -[wildcard DNS record](https://en.wikipedia.org/wiki/Wildcard_DNS_record) (such -as `*.example.com.`) to reach your apps. If your external endpoint is an IP -address, use an A record. If your external endpoint is a hostname, use a CNAME -record. - -#### Web Application Firewall (ModSecurity) - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21966) in GitLab 12.7. - -A Web Application Firewall (WAF) examines traffic being sent or received, -and can block malicious traffic before it reaches your application. The benefits -of a WAF are: - -- Real-time security monitoring for your application. -- Logging of all your HTTP traffic to the application. -- Access control for your application. -- Highly configurable logging and blocking rules. - -By default, GitLab provides you with a WAF known as [`ModSecurity`](https://www.modsecurity.org/), -which is a toolkit for real-time web application monitoring, logging, and access -control. GitLab's offering applies the [OWASP's Core Rule Set](https://www.modsecurity.org/CRS/Documentation/), -which provides generic attack detection capabilities. - -This feature: - -- Runs in "Detection-only mode" unless configured otherwise. -- Is viewable by checking your Ingress controller's `modsec` log for rule violations. - For example: - - ```shell - kubectl -n gitlab-managed-apps logs -l app=nginx-ingress,component=controller -c modsecurity-log -f - ``` - -To enable WAF, switch its respective toggle to the enabled position when installing or updating [Ingress application](#ingress). - -If this is your first time using GitLab's WAF, we recommend you follow the -[quick start guide](../../topics/web_application_firewall/quick_start_guide.md). - -There is a small performance overhead by enabling ModSecurity. If this is -considered significant for your application, you can disable ModSecurity's -rule engine for your deployed application in any of the following ways: - -1. Set the [deployment variable](../../topics/autodevops/index.md) - `AUTO_DEVOPS_MODSECURITY_SEC_RULE_ENGINE` to `Off` to prevent ModSecurity - from processing any requests for the given application or environment. -1. Switch its respective toggle to the disabled position, and then apply changes - by selecting **Save changes** to reinstall Ingress with the recent changes. - - - -##### Logging and blocking modes - -To help you tune your WAF rules, you can globally set your WAF to either -*Logging* or *Blocking* mode: - -- *Logging mode*: Allows traffic matching the rule to pass, and logs the event. -- *Blocking mode*: Prevents traffic matching the rule from passing, and logs the event. - -To change your WAF's mode: - -1. If you haven't already done so, [install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md). -1. Navigate to **Operations > Kubernetes**. -1. In **Applications**, scroll to **Ingress**. -1. Under **Global default**, select your desired mode. -1. Select **Save changes**. - -##### WAF version updates - -Enabling, disabling, or changing the logging mode for **ModSecurity** is only -allowed within same version of [Ingress](#ingress) due to limitations in -[Helm](https://helm.sh/) which might be overcome in future releases. - -**ModSecurity** user interface controls are disabled if the version deployed -differs from the one available in GitLab, while actions at the [Ingress](#ingress) -level, such as uninstalling, can still be performed: - - - -Update [Ingress](#ingress) to the most recent version to take advantage of bug -fixes, security fixes, and performance improvements. To update the -[Ingress application](#ingress), you must first uninstall it, and then re-install -it as described in [Install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md). - -##### Viewing Web Application Firewall traffic - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14707) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. - -You can view Web Application Firewall traffic by navigating to your project's -**Security & Compliance > Threat Monitoring** page. From there, you can see -tracked over time: - -- The total amount of traffic to your application. -- The proportion of traffic that's considered anomalous by the Web Application - Firewall's default [OWASP ruleset](https://www.modsecurity.org/CRS/Documentation/). - -If a significant percentage of traffic is anomalous, investigate it for potential threats -by [examining the Web Application Firewall logs](#web-application-firewall-modsecurity). - - - -### JupyterHub - -> - Introduced in GitLab 11.0 for project-level clusters. -> - Introduced in GitLab 12.3 for group and instance-level clusters. - -[JupyterHub](https://jupyterhub.readthedocs.io/en/stable/) is a multi-user service -for managing notebooks across a team. [Jupyter Notebooks](https://jupyter-notebook.readthedocs.io/en/latest/) -provide a web-based interactive programming environment used for data analysis, -visualization, and machine learning. - -The [`jupyter/jupyterhub`](https://jupyterhub.github.io/helm-chart/) -chart is used to install this application with a -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/jupyter/values.yaml) -file. - -Authentication is enabled only for [project members](../project/members/index.md) -for project-level clusters and group members for group-level clusters with -[Developer or higher](../permissions.md) access to the associated project or group. - -GitLab uses a [custom Jupyter image](https://gitlab.com/gitlab-org/jupyterhub-user-image/blob/master/Dockerfile) -that installs additional useful packages on top of the base Jupyter. Ready-to-use -DevOps Runbooks built with Nurtch's [Rubix library](https://github.com/Nurtch/rubix) -are also available. - -More information on creating executable runbooks can be found in -[our Runbooks documentation](../project/clusters/runbooks/index.md#configure-an-executable-runbook-with-gitlab). -Ingress must be installed and have an IP address assigned before -JupyterHub can be installed. - -#### Jupyter Git Integration - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28783) in GitLab 12.0 for project-level clusters. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/32512) in GitLab 12.3 for group and instance-level clusters. - -When installing JupyterHub onto your Kubernetes cluster, -[JupyterLab's Git extension](https://github.com/jupyterlab/jupyterlab-git) -is provisioned and configured using the authenticated user's: - -- Name. -- Email. -- Newly created access token. - -JupyterLab's Git extension enables full version control of your notebooks, and -issuance of Git commands within Jupyter. You can issue Git commands through the -**Git** tab on the left panel, or through Jupyter's command-line prompt. - -JupyterLab's Git extension stores the user token in the JupyterHub DB in encrypted -format, and in the single user Jupyter instance as plain text, because -[Git requires storing credentials as plain text](https://git-scm.com/docs/git-credential-store) -Potentially, if a nefarious user finds a way to read from the file system in the -single-user Jupyter instance, they could retrieve the token. - - - -You can clone repositories from the files tab in Jupyter: - - - -### Knative - -> - Introduced in GitLab 11.5 for project-level clusters. -> - Introduced in GitLab 12.3 for group- and instance-level clusters. - -[Knative](https://cloud.google.com/knative/) provides a platform to -create, deploy, and manage serverless workloads from a Kubernetes -cluster. It's used in conjunction with, and includes -[Istio](https://istio.io) to provide an external IP address for all -programs hosted by Knative. - -The [`knative/knative`](https://storage.googleapis.com/triggermesh-charts) -chart is used to install this application. - -During installation, you must enter a wildcard domain where your applications -will be exposed. Configure your DNS server to use the external IP address for that -domain. Applications created and installed are accessible as -`<program_name>.<kubernetes_namespace>.<domain_name>`, which requires -your Kubernetes cluster to have -[RBAC enabled](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). - -### Prometheus - -> - Introduced in GitLab 10.4 for project-level clusters. -> - Introduced in GitLab 11.11 for group-level clusters. - -[Prometheus](https://prometheus.io/docs/introduction/overview/) is an -open-source monitoring and alerting system useful to supervise your -deployed applications. - -GitLab is able to monitor applications by using the -[Prometheus integration](../project/integrations/prometheus.md). Kubernetes container CPU and -memory metrics are collected, and response metrics are also retrieved -from NGINX Ingress. - -The [`stable/prometheus`](https://github.com/helm/charts/tree/master/stable/prometheus) -chart is used to install this application with a -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/prometheus/values.yaml) -file. - -To enable monitoring, install Prometheus into the cluster with the **Install** -button. - -### Crossplane - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34702) in GitLab 12.5 for project-level clusters. - -[Crossplane](https://crossplane.github.io/docs/v0.9/) is a multi-cloud control plane useful for -managing applications and infrastructure across multiple clouds. It extends the -Kubernetes API using: - -- Custom resources. -- Controllers that watch those custom resources. - -Crossplane allows provisioning and lifecycle management of infrastructure components -across cloud providers in a uniform manner by abstracting cloud provider-specific -configurations. - -The Crossplane GitLab-managed application: - -- Installs Crossplane with a provider of choice on a Kubernetes cluster attached to the - project repository. -- Can then be used to provision infrastructure or managed applications such as - PostgreSQL (for example, CloudSQL from GCP or RDS from AWS) and other services - required by the application with the Auto DevOps pipeline. - -[`alpha/crossplane`](https://github.com/crossplane/crossplane/tree/v0.4.1/cluster/charts/crossplane) chart v0.4.1 is used to -install Crossplane using the -[`values.yaml`](https://github.com/crossplane/crossplane/blob/master/cluster/charts/crossplane/values.yaml.tmpl) -file. - -For information about configuring Crossplane installed on the cluster, see -[Crossplane configuration](crossplane.md). - -### Elastic Stack - -> Introduced in GitLab 12.7 for project- and group-level clusters. - -[Elastic Stack](https://www.elastic.co/elastic-stack) is a complete end-to-end -log analysis solution which helps in deep searching, analyzing and visualizing the logs -generated from different machines. - -GitLab can gather logs from pods in your cluster. Filebeat runs as a DaemonSet -on each node in your cluster, and ships container logs to Elasticsearch for -querying. GitLab then connects to Elasticsearch for logs, instead of the -Kubernetes API, giving you access to more advanced querying capabilities. Log -data is deleted after 30 days, using [Curator](https://www.elastic.co/guide/en/elasticsearch/client/curator/5.5/about.html). - -The Elastic Stack cluster application is intended as a log aggregation solution -and is not related to our [Advanced Search](../search/advanced_global_search.md) -functionality, which uses a separate Elasticsearch cluster. - -To enable log shipping: - -1. Ensure your cluster contains at least three nodes of instance types larger - than `f1-micro`, `g1-small`, or `n1-standard-1`. -1. Navigate to **Operations > Kubernetes**. -1. In **Kubernetes Cluster**, select a cluster. -1. In the **Applications** section, find **Elastic Stack**, and then select - **Install**. - -The [`gitlab/elastic-stack`](https://gitlab.com/gitlab-org/charts/elastic-stack) -chart is used to install this application with a -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/elastic_stack/values.yaml) -file. The chart deploys three identical Elasticsearch pods which can't be -colocated, and each requires one CPU and 2 GB of RAM, making them -incompatible with clusters containing fewer than three nodes, or consisting of -`f1-micro`, `g1-small`, `n1-standard-1`, or `*-highcpu-2` instance types. - -#### Optional: deploy Kibana to perform advanced queries - -If you are an advanced user and have direct access to your Kubernetes cluster using `kubectl` and `helm`, you can deploy Kibana manually. - -The following assumes that `helm` has been [initialized](https://v2.helm.sh/docs/helm/) with `helm init`. - -Save the following to `kibana.yml`: - -```yaml -elasticsearch: - enabled: false - -filebeat: - enabled: false - -kibana: - enabled: true - elasticsearchHosts: http://elastic-stack-elasticsearch-master.gitlab-managed-apps.svc.cluster.local:9200 -``` - -Then install it on your cluster: - -```shell -helm repo add gitlab https://charts.gitlab.io -helm install --name kibana gitlab/elastic-stack --values kibana.yml -``` - -To access Kibana, forward the port to your local machine: - -```shell -kubectl port-forward svc/kibana-kibana 5601:5601 -``` - -Then, you can visit Kibana at `http://localhost:5601`. - -### Fluentd - -> Introduced in GitLab 12.10 for project- and group-level clusters. - -[Fluentd](https://www.fluentd.org/) is an open source data collector, which enables -you to unify the data collection and consumption to better use and understand -your data. Fluentd sends logs in syslog format. - -To enable Fluentd: - -1. Navigate to **Operations > Kubernetes** and click - **Applications**. Enter a host, port, and protocol - for sending the WAF logs with syslog. -1. Provide the host domain name or URL in **SIEM Hostname**. -1. Provide the host port number in **SIEM Port**. -1. Select a **SIEM Protocol**. -1. Select at least one of the available logs (such as WAF or Cilium). -1. Click **Save changes**. - - - -### Future apps - -Interested in contributing a new GitLab managed app? Visit the -[development guidelines page](../../development/kubernetes.md#gitlab-managed-apps) -to get started. - -## Install using GitLab CI/CD (alpha) +## Install using GitLab CI/CD > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20822) in GitLab 12.6. -CAUTION: **Warning:** +WARNING: This is an _alpha_ feature, and is subject to change at any time without prior notice. @@ -664,14 +85,15 @@ applications you have configured. In case of pipeline failure, the output of the [Helm Tiller](https://v2.helm.sh/docs/install/#running-tiller-locally) binary is saved as a [CI job artifact](../../ci/pipelines/job_artifacts.md). +#### Usage in GitLab versions earlier than 13.5 + For GitLab versions 13.5 and below, the Ingress, Fluentd, Prometheus, -and Sentry apps are fetched from the central Helm [stable -repository](https://kubernetes-charts.storage.googleapis.com/), which -will be [deleted](https://github.com/helm/charts#deprecation-timeline) -on November 13, 2020. This will cause the installation CI/CD pipeline to +and Sentry apps are fetched from the central Helm +[stable repository](https://kubernetes-charts.storage.googleapis.com/). This repository +[was deleted](https://github.com/helm/charts#deprecation-timeline) +on November 13, 2020. This causes the installation CI/CD pipeline to fail. Upgrade to GitLab 13.6, or alternatively, you can -use the following `.gitlab-ci.yml`, which has been tested on GitLab -13.5: +use the following `.gitlab-ci.yml`, which has been tested on GitLab 13.5: ```yaml include: @@ -738,7 +160,7 @@ for the available configuration options. Support for installing the Ingress managed application is provided by the GitLab Configure group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). +[Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). ### Install cert-manager using GitLab CI/CD @@ -782,7 +204,7 @@ Support for installing the Cert Manager managed application is provided by the GitLab Configure group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). +[Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). ### Install Sentry using GitLab CI/CD @@ -809,7 +231,7 @@ for the available configuration options. We recommend you pay close attention to the following configuration options: - `email`. Needed to invite users to your Sentry instance and to send error emails. -- `user`. Where you can set the login credentials for the default admin user. +- `user`. Where you can set the login credentials for the default administrator user. - `postgresql`. For a PostgreSQL password that can be used when running future updates. When upgrading, it's important to provide the existing PostgreSQL password (given @@ -851,7 +273,7 @@ Support for installing the Sentry managed application is provided by the GitLab Health group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Health group](https://about.gitlab.com/handbook/product/product-categories/#health-group). +[Health group](https://about.gitlab.com/handbook/product/categories/#health-group). ### Install PostHog using GitLab CI/CD @@ -867,8 +289,8 @@ posthog: You can customize the installation of PostHog by defining `.gitlab/managed-apps/posthog/values.yaml` in your cluster management project. Refer to the -[Configuration section of the PostHog chart's README](https://github.com/PostHog/charts/tree/master/charts/posthog) -for the available configuration options. +[Configuration section](https://github.com/PostHog/charts/tree/master/charts/posthog) +of the PostHog chart's README for the available configuration options. You must provide a PostgreSQL password in `postgresql.postgresqlPassword` to avoid authentication errors. Read the @@ -922,13 +344,13 @@ prometheus: You can customize the installation of Prometheus by defining `.gitlab/managed-apps/prometheus/values.yaml` in your cluster management project. Refer to the -[Configuration section of the Prometheus chart's README](https://github.com/helm/charts/tree/master/stable/prometheus#configuration) -for the available configuration options. +[Configuration section](https://github.com/helm/charts/tree/master/stable/prometheus#configuration) +of the Prometheus chart's README for the available configuration options. Support for installing the Prometheus managed application is provided by the GitLab APM group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the [APM group](https://about.gitlab.com/handbook/product/product-categories/#apm-group). +least 2 people from the [APM group](https://about.gitlab.com/handbook/product/categories/#apm-group). ### Install GitLab Runner using GitLab CI/CD @@ -966,7 +388,7 @@ Support for installing the GitLab Runner managed application is provided by the GitLab Runner group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Runner group](https://about.gitlab.com/handbook/product/product-categories/#runner-group). +[Runner group](https://about.gitlab.com/handbook/product/categories/#runner-group). ### Install Cilium using GitLab CI/CD @@ -977,7 +399,8 @@ support for [NetworkPolicy](https://kubernetes.io/docs/concepts/services-network resources. For more information, see [Network Policies](../../topics/autodevops/stages.md#network-policy). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see the [Container Network Security Demo for GitLab 12.8](https://www.youtube.com/watch?v=pgUEdhdhoUI). +For an overview, see the +[Container Network Security Demo for GitLab 12.8](https://www.youtube.com/watch?v=pgUEdhdhoUI). Enable Cilium in the `.gitlab/managed-apps/config.yaml` file to install it: @@ -1008,14 +431,14 @@ You can check Cilium's installation status on the cluster management page: - [Group-level cluster](../group/clusters/index.md): Navigate to your group's **Kubernetes** page. -CAUTION: **Caution:** +WARNING: Installation and removal of the Cilium requires a **manual** [restart](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-gke/#restart-unmanaged-pods) of all affected pods in all namespaces to ensure that they are [managed](https://docs.cilium.io/en/v1.8/operations/troubleshooting/#ensure-managed-pod) by the correct networking plugin. -NOTE: **Note:** +NOTE: Major upgrades might require additional setup steps. For more information, see the official [upgrade guide](https://docs.cilium.io/en/v1.8/operations/upgrade/). @@ -1050,9 +473,9 @@ agent: enabled: false ``` -The [Hubble](https://github.com/cilium/hubble) monitoring daemon is -enabled by default and it's set to collect per namespace flow -metrics. This metrics are accessible on the [Threat Monitoring](../application_security/threat_monitoring/index.md) +The [Hubble](https://github.com/cilium/hubble) monitoring daemon is enabled by default +and it's set to collect per namespace flow metrics. This metrics are accessible on the +[Threat Monitoring](../application_security/threat_monitoring/index.md) dashboard. You can disable Hubble by adding the following to `.gitlab/managed-apps/cilium/values.yaml`: @@ -1078,7 +501,7 @@ Support for installing the Cilium managed application is provided by the GitLab Container Security group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). +[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). ### Install Falco using GitLab CI/CD @@ -1103,7 +526,7 @@ management project. Refer to the [Falco chart](https://github.com/falcosecurity/charts/tree/master/falco) for the available configuration options. -CAUTION: **Caution:** +WARNING: By default eBPF support is enabled and Falco uses an [eBPF probe](https://falco.org/docs/event-sources/drivers/#using-the-ebpf-probe) to pass system calls to user space. If your cluster doesn't support this, you can @@ -1120,8 +543,8 @@ isn't pre-compiled, you may need to manually prepare the kernel module or eBPF p [`driverkit`](https://github.com/falcosecurity/driverkit#against-a-kubernetes-cluster) and install it on each cluster node. -By default, Falco is deployed with a limited set of rules. To add more rules, add the following to -`.gitlab/managed-apps/falco/values.yaml` (you can get examples from +By default, Falco is deployed with a limited set of rules. To add more rules, add +the following to `.gitlab/managed-apps/falco/values.yaml` (you can get examples from [Cloud Native Security Hub](https://securityhub.dev/)): ```yaml @@ -1174,7 +597,7 @@ Support for installing the Falco managed application is provided by the GitLab Container Security group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). +[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). ### Install Vault using GitLab CI/CD @@ -1256,12 +679,12 @@ server: } ``` -Once you have successfully installed Vault, you must +After you have successfully installed Vault, you must [initialize the Vault](https://learn.hashicorp.com/tutorials/vault/getting-started-deploy#initializing-the-vault) and obtain the initial root token. You need access to your Kubernetes cluster that Vault has been deployed into in order to do this. To initialize the Vault, get a shell to one of the Vault pods running inside Kubernetes (typically this is done -by using the `kubectl` command line tool). Once you have a shell into the pod, +by using the `kubectl` command line tool). After you have a shell into the pod, run the `vault operator init` command: ```shell @@ -1276,7 +699,7 @@ Support for installing the Vault managed application is provided by the GitLab Release Management group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Release Management group](https://about.gitlab.com/handbook/product/product-categories/#release-management-group). +[Release Management group](https://about.gitlab.com/handbook/product/categories/#release-management-group). ### Install JupyterHub using GitLab CI/CD @@ -1333,7 +756,7 @@ Support for installing the JupyterHub managed application is provided by the Git If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). +[Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). ### Install Elastic Stack using GitLab CI/CD @@ -1361,7 +784,7 @@ management project. Refer to the [chart](https://gitlab.com/gitlab-org/charts/elastic-stack) for all available configuration options. -NOTE: **Note:** +NOTE: In this alpha implementation of installing Elastic Stack through CI, reading the environment logs through Elasticsearch is unsupported. This is supported if [installed with the UI](#elastic-stack). @@ -1369,7 +792,7 @@ environment logs through Elasticsearch is unsupported. This is supported if Support for installing the Elastic Stack managed application is provided by the GitLab APM group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the [APM group](https://about.gitlab.com/handbook/product/product-categories/#apm-group). +least 2 people from the [APM group](https://about.gitlab.com/handbook/product/categories/#apm-group). ### Install Crossplane using GitLab CI/CD @@ -1394,8 +817,9 @@ we set for this chart. You can customize the installation of Crossplane by defining `.gitlab/managed-apps/crossplane/values.yaml` file in your cluster management project. Refer to the -[chart](https://github.com/crossplane/crossplane/tree/master/cluster/charts/crossplane#configuration) for the -available configuration options. Note that this link points to the documentation for the current development release, which may differ from the version you have installed. +[chart](https://github.com/crossplane/crossplane/tree/master/cluster/charts/crossplane#configuration) +for the available configuration options. Note that this link points to the documentation +for the current development release, which may differ from the version you have installed. Support for the Crossplane managed application is provided by the Crossplane team. If you run into issues, @@ -1419,8 +843,8 @@ You can also review the default values set for this chart in the You can customize the installation of Fluentd by defining `.gitlab/managed-apps/fluentd/values.yaml` file in your cluster management project. Refer to the -[configuration chart for the current development release of Fluentd](https://github.com/helm/charts/tree/master/stable/fluentd#configuration) -for all available configuration options. +[configuration chart](https://github.com/helm/charts/tree/master/stable/fluentd#configuration) +for the current development release of Fluentd for all available configuration options. The configuration chart link points to the current development release, which may differ from the version you have installed. To ensure compatibility, switch @@ -1430,7 +854,7 @@ Support for installing the Fluentd managed application is provided by the GitLab Container Security group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). +[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). ### Install Knative using GitLab CI/CD @@ -1459,11 +883,12 @@ Support for installing the Knative managed application is provided by the GitLab Configure group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). +[Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). #### Knative Metrics -GitLab provides [Invocation Metrics](../project/clusters/serverless/index.md#invocation-metrics) for your functions. To collect these metrics, you must have: +GitLab provides [Invocation Metrics](../project/clusters/serverless/index.md#invocation-metrics) +for your functions. To collect these metrics, you must have: 1. Knative and Prometheus managed applications installed on your cluster. 1. Manually applied the custom metrics on your cluster by running the following command: @@ -1520,7 +945,8 @@ podAnnotations: ``` The only information to be changed here is the profile name which is `profile-one` -in this example. Refer to the [AppArmor tutorial](https://kubernetes.io/docs/tutorials/clusters/apparmor/#securing-a-pod) +in this example. Refer to the +[AppArmor tutorial](https://kubernetes.io/docs/tutorials/clusters/apparmor/#securing-a-pod) for more information on how AppArmor is integrated in Kubernetes. #### Using PodSecurityPolicy in your deployments @@ -1563,13 +989,600 @@ Support for installing the AppArmor managed application is provided by the GitLab Container Security group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). +[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). ## Browse applications logs > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36769) in GitLab 13.2. -Logs produced by pods running **GitLab Managed Apps** can be browsed using [**Log Explorer**](../project/clusters/kubernetes_pod_logs.md). +Logs produced by pods running **GitLab Managed Apps** can be browsed using +[**Log Explorer**](../project/clusters/kubernetes_pod_logs.md). + +## Install with one click + +WARNING: +The one click installation method is scheduled for removal in GitLab 14.0. The removal +of this feature from GitLab does not affect installed applications to avoid breaking +changes. Following GitLab 14.0, users can take ownership of already installed applications +using our documentation. + +Applications managed by GitLab are installed onto the `gitlab-managed-apps` +namespace. This namespace: + +- Is different from the namespace used for project deployments. +- Is created once. +- Has a non-configurable name. + +To view a list of available applications to install for a: + +- [Project-level cluster](../project/clusters/index.md), navigate to your project's + **Operations > Kubernetes**. +- [Group-level cluster](../group/clusters/index.md), navigate to your group's + **Kubernetes** page. + +You can install the following applications with one click: + +- [Helm](#helm) +- [Ingress](#ingress) +- [cert-manager](#cert-manager) +- [Prometheus](#prometheus) +- [GitLab Runner](#gitlab-runner) +- [JupyterHub](#jupyterhub) +- [Knative](#knative) +- [Crossplane](#crossplane) +- [Elastic Stack](#elastic-stack) +- [Fluentd](#fluentd) + +With the exception of Knative, the applications are installed in a dedicated +namespace called `gitlab-managed-apps`. + +Some applications are installable only for a project-level cluster. +Support for installing these applications in a group-level cluster is +planned for future releases. +For updates, see the [issue tracking progress](https://gitlab.com/gitlab-org/gitlab/-/issues/24411). + +WARNING: +If you have an existing Kubernetes cluster with Helm already installed, +you should be careful as GitLab cannot detect it. In this case, installing +Helm with the applications results in the cluster having it twice, which +can lead to confusion during deployments. + +In GitLab versions 11.6 and greater, Helm is upgraded to the latest version +supported by GitLab before installing any of the applications. + +### Helm + +> - Introduced in GitLab 10.2 for project-level clusters. +> - Introduced in GitLab 11.6 for group-level clusters. +> - [Uses a local Tiller](https://gitlab.com/gitlab-org/gitlab/-/issues/209736) in GitLab 13.2 and later. +> - [Uses Helm 3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46267) for clusters created with GitLab 13.6 and later. +> - [Offers legacy Tiller removal](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47457) in GitLab 13.7 and later. + +[Helm](https://helm.sh/docs/) is a package manager for Kubernetes and is +used to install the GitLab-managed apps. GitLab runs each `helm` command +in a pod in the `gitlab-managed-apps` namespace inside the cluster. + +- For clusters created on GitLab 13.6 and newer, GitLab uses Helm 3 to manage + applications. +- For clusters created on versions of GitLab prior to 13.6, GitLab uses Helm 2 + with a local [Tiller](https://v2.helm.sh/docs/glossary/#tiller) server. Prior + to [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/209736), GitLab + used an in-cluster Tiller server in the `gitlab-managed-apps` namespace. You + can safely uninstall the server from the GitLab application page if you have + previously installed it. This doesn't affect your other applications. + +The GitLab Helm integration does not support installing applications behind a proxy, +but a [workaround](../../topics/autodevops/index.md#install-applications-behind-a-proxy) +is available. + +#### Upgrade a cluster to Helm 3 + +GitLab does not offer a way to migrate existing application management +on existing clusters from Helm 2 to Helm 3. To migrate a cluster to Helm 3: + +1. Uninstall all applications on your cluster. +1. [Remove the cluster integration](../project/clusters/add_remove_clusters.md#removing-integration). +1. [Re-add the cluster](../project/clusters/add_remove_clusters.md#existing-kubernetes-cluster) as + an existing cluster. + +### cert-manager + +> Introduced in GitLab 11.6 for project- and group-level clusters. + +[cert-manager](https://cert-manager.io/docs/) is a native Kubernetes certificate +management controller that helps with issuing certificates. Installing +cert-manager on your cluster issues a certificate by [Let's Encrypt](https://letsencrypt.org/) +and ensures that certificates are valid and up-to-date. + +The chart used to install this application depends on the version of GitLab used. In: + +- GitLab 12.3 and newer, the [`jetstack/cert-manager`](https://github.com/jetstack/cert-manager) + chart is used with a + [`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/cert_manager/values.yaml) + file. +- GitLab 12.2 and older, the + [`stable/cert-manager`](https://github.com/helm/charts/tree/master/stable/cert-manager) + chart was used. + +If you installed cert-manager prior to GitLab 12.3, Let's Encrypt +[blocks requests](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753) +from older versions of `cert-manager`. To resolve this: + +1. [Back up any additional configuration](https://cert-manager.io/docs/tutorials/backup/). +1. Uninstall cert-manager. +1. Install cert-manager again. + +### GitLab Runner + +> - Introduced in GitLab 10.6 for project-level clusters. +> - Introduced in GitLab 11.10 for group-level clusters. + +[GitLab Runner](https://docs.gitlab.com/runner/) is the open source project that +is used to run your jobs and send the results back to GitLab. It's used in +conjunction with [GitLab CI/CD](../../ci/README.md), the open-source continuous +integration service included with GitLab that coordinates the jobs. + +If the project is on GitLab.com, [shared runners](../gitlab_com/index.md#shared-runners) +are available. You don't have to deploy one if they are enough for your +needs. If a project-specific runner is desired, or there are no shared runners, +you can deploy one. + +The deployed runner is set as **privileged**. Root access to the underlying +server is required to build Docker images, so it's the default. Be sure to read +the [security implications](../project/clusters/index.md#security-implications) +before deploying one. + +The [`runner/gitlab-runner`](https://gitlab.com/gitlab-org/charts/gitlab-runner) +chart is used to install this application, using +[a preconfigured `values.yaml`](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/blob/master/values.yaml) +file. Customizing the installation by modifying this file is not supported. This +also means you cannot modify `config.toml` file for this Runner. If you want to +have that possibility and still deploy Runner in Kubernetes, consider using the +[Cluster management project](management_project.md) or installing Runner manually +via [GitLab Runner Helm Chart](https://docs.gitlab.com/runner/install/kubernetes.html). + +### Ingress + +> - Introduced in GitLab 10.2 for project-level clusters. +> - Introduced in GitLab 11.6 for group-level clusters. + +[Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) +provides load balancing, SSL termination, and name-based virtual hosting +out of the box. It acts as a web proxy for your applications and is useful +if you want to use [Auto DevOps](../../topics/autodevops/index.md) or deploy your own web apps. + +The Ingress Controller installed is +[Ingress-NGINX](https://kubernetes.io/docs/concepts/services-networking/ingress/), +which is supported by the Kubernetes community. + +With the following procedure, a load balancer must be installed in your cluster +to obtain the endpoint. You can use either +Ingress, or Knative's own load balancer ([Istio](https://istio.io)) if using Knative. + +To publish your web application, you first need to find the endpoint, which is either an IP +address or a hostname associated with your load balancer. + +To install it, click on the **Install** button for Ingress. GitLab attempts +to determine the external endpoint and it should be available in a few minutes. + +#### Determining the external endpoint automatically + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17052) in GitLab 10.6. + +After you install Ingress, the external endpoint should be available in a few minutes. + +NOTE: +This endpoint can be used for the +[Auto DevOps base domain](../../topics/autodevops/index.md#auto-devops-base-domain) +using the `KUBE_INGRESS_BASE_DOMAIN` environment variable. + +If the endpoint doesn't appear and your cluster runs on Google Kubernetes Engine: + +1. [Examine your Kubernetes cluster](https://console.cloud.google.com/kubernetes) + on Google Kubernetes Engine to ensure there are no errors on its nodes. +1. Ensure you have enough [Quotas](https://console.cloud.google.com/iam-admin/quotas) + on Google Kubernetes Engine. For more information, see + [Resource Quotas](https://cloud.google.com/compute/quotas). +1. Review [Google Cloud's Status](https://status.cloud.google.com/) for service + disruptions. + +The [`stable/nginx-ingress`](https://github.com/helm/charts/tree/master/stable/nginx-ingress) +chart is used to install this application with a +[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/ingress/values.yaml) +file. + +After installing, you may see a `?` for **Ingress IP Address** depending on the +cloud provider. For EKS specifically, this is because the ELB is created +with a DNS name, not an IP address. If GitLab is still unable to +determine the endpoint of your Ingress or Knative application, you can +[determine it manually](#determining-the-external-endpoint-manually). + +#### Determining the external endpoint manually + +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. + +#### Using a static IP + +By default, an ephemeral external IP address is associated to the cluster's load +balancer. If you associate the ephemeral IP with your DNS and the IP changes, +your apps aren't reachable, and you'd have to change the DNS record again. +To avoid that, change it into a static reserved IP. + +Read how to [promote an ephemeral external IP address in GKE](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip). + +#### Pointing your DNS at the external endpoint + +After you have set up the external endpoint, associate it with a +[wildcard DNS record](https://en.wikipedia.org/wiki/Wildcard_DNS_record) (such +as `*.example.com.`) to reach your apps. If your external endpoint is an IP +address, use an A record. If your external endpoint is a hostname, use a CNAME +record. + +#### Web Application Firewall (ModSecurity) + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21966) in GitLab 12.7. + +A Web Application Firewall (WAF) examines traffic being sent or received, +and can block malicious traffic before it reaches your application. The benefits +of a WAF are: + +- Real-time security monitoring for your application. +- Logging of all your HTTP traffic to the application. +- Access control for your application. +- Highly configurable logging and blocking rules. + +By default, GitLab provides you with a WAF known as [`ModSecurity`](https://www.modsecurity.org/), +which is a toolkit for real-time web application monitoring, logging, and access +control. GitLab applies the [OWASP's Core Rule Set](https://www.modsecurity.org/CRS/Documentation/), +which provides generic attack detection capabilities. + +This feature: + +- Runs in "Detection-only mode" unless configured otherwise. +- Is viewable by checking your Ingress controller's `modsec` log for rule violations. + For example: + + ```shell + kubectl -n gitlab-managed-apps logs -l app=nginx-ingress,component=controller -c modsecurity-log -f + ``` + +To enable WAF, switch its respective toggle to the enabled position when installing +or updating [Ingress application](#ingress). + +If this is your first time using the GitLab WAF, we recommend you follow the +[quick start guide](../../topics/web_application_firewall/quick_start_guide.md). + +There is a small performance overhead by enabling ModSecurity. If this is +considered significant for your application, you can disable ModSecurity's +rule engine for your deployed application in any of the following ways: + +1. Set the [deployment variable](../../topics/autodevops/index.md) + `AUTO_DEVOPS_MODSECURITY_SEC_RULE_ENGINE` to `Off` to prevent ModSecurity + from processing any requests for the given application or environment. +1. Switch its respective toggle to the disabled position, and then apply changes + by selecting **Save changes** to reinstall Ingress with the recent changes. + + + +##### Logging and blocking modes + +To help you tune your WAF rules, you can globally set your WAF to either +*Logging* or *Blocking* mode: + +- *Logging mode*: Allows traffic matching the rule to pass, and logs the event. +- *Blocking mode*: Prevents traffic matching the rule from passing, and logs the event. + +To change your WAF's mode: + +1. If you haven't already done so, + [install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md). +1. Navigate to **Operations > Kubernetes**. +1. In **Applications**, scroll to **Ingress**. +1. Under **Global default**, select your desired mode. +1. Select **Save changes**. + +##### WAF version updates + +Enabling, disabling, or changing the logging mode for **ModSecurity** is only +allowed in same version of [Ingress](#ingress) due to limitations in +[Helm](https://helm.sh/) which might be overcome in future releases. + +The **ModSecurity** user interface controls are disabled if the version deployed +differs from the one available in GitLab. However, actions at the [Ingress](#ingress) +level, such as uninstalling, can still be performed: + + + +Update [Ingress](#ingress) to the most recent version to take advantage of bug +fixes, security fixes, and performance improvements. To update the +[Ingress application](#ingress), you must first uninstall it, and then re-install +it as described in [Install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md). + +##### Viewing Web Application Firewall traffic + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14707) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. + +You can view Web Application Firewall traffic by navigating to your project's +**Security & Compliance > Threat Monitoring** page. From there, you can see +tracked over time: + +- The total amount of traffic to your application. +- The proportion of traffic that's considered anomalous by the Web Application + Firewall's default [OWASP ruleset](https://www.modsecurity.org/CRS/Documentation/). + +If a significant percentage of traffic is anomalous, investigate it for potential threats +by [examining the Web Application Firewall logs](#web-application-firewall-modsecurity). + + + +### JupyterHub + +> - Introduced in GitLab 11.0 for project-level clusters. +> - Introduced in GitLab 12.3 for group and instance-level clusters. + +[JupyterHub](https://jupyterhub.readthedocs.io/en/stable/) is a multi-user service +for managing notebooks across a team. [Jupyter Notebooks](https://jupyter-notebook.readthedocs.io/en/latest/) +provide a web-based interactive programming environment used for data analysis, +visualization, and machine learning. + +The [`jupyter/jupyterhub`](https://jupyterhub.github.io/helm-chart/) +chart is used to install this application with a +[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/jupyter/values.yaml) +file. + +Authentication is enabled only for [project members](../project/members/index.md) +for project-level clusters and group members for group-level clusters with +[Developer or higher](../permissions.md) access to the associated project or group. + +GitLab uses a [custom Jupyter image](https://gitlab.com/gitlab-org/jupyterhub-user-image/blob/master/Dockerfile) +that installs additional relevant packages on top of the base Jupyter. Ready-to-use +DevOps Runbooks built with Nurtch's [Rubix library](https://github.com/Nurtch/rubix) +are also available. + +More information on creating executable runbooks can be found in +[our Runbooks documentation](../project/clusters/runbooks/index.md#configure-an-executable-runbook-with-gitlab). +Ingress must be installed and have an IP address assigned before +JupyterHub can be installed. + +#### Jupyter Git Integration + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28783) in GitLab 12.0 for project-level clusters. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/32512) in GitLab 12.3 for group and instance-level clusters. + +When installing JupyterHub onto your Kubernetes cluster, +[JupyterLab's Git extension](https://github.com/jupyterlab/jupyterlab-git) +is provisioned and configured using the authenticated user's: + +- Name. +- Email. +- Newly created access token. + +JupyterLab's Git extension enables full version control of your notebooks, and +issuance of Git commands in Jupyter. You can issue Git commands through the +**Git** tab on the left panel, or through Jupyter's command-line prompt. + +JupyterLab's Git extension stores the user token in the JupyterHub DB in encrypted +format, and in the single user Jupyter instance as plain text, because +[Git requires storing credentials as plain text](https://git-scm.com/docs/git-credential-store) +Potentially, if a nefarious user finds a way to read from the file system in the +single-user Jupyter instance, they could retrieve the token. + + + +You can clone repositories from the files tab in Jupyter: + + + +### Knative + +> - Introduced in GitLab 11.5 for project-level clusters. +> - Introduced in GitLab 12.3 for group- and instance-level clusters. + +[Knative](https://cloud.google.com/knative/) provides a platform to +create, deploy, and manage serverless workloads from a Kubernetes +cluster. It's used in conjunction with, and includes +[Istio](https://istio.io) to provide an external IP address for all +programs hosted by Knative. + +The [`knative/knative`](https://storage.googleapis.com/triggermesh-charts) +chart is used to install this application. + +During installation, you must enter a wildcard domain where your applications +are exposed. Configure your DNS server to use the external IP address for that +domain. Applications created and installed are accessible as +`<program_name>.<kubernetes_namespace>.<domain_name>`, which requires +your Kubernetes cluster to have +[RBAC enabled](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). + +### Prometheus + +> - Introduced in GitLab 10.4 for project-level clusters. +> - Introduced in GitLab 11.11 for group-level clusters. + +[Prometheus](https://prometheus.io/docs/introduction/overview/) is an +open-source monitoring and alerting system you can use to supervise your +deployed applications. + +GitLab is able to monitor applications by using the +[Prometheus integration](../project/integrations/prometheus.md). Kubernetes container CPU and +memory metrics are collected, and response metrics are also retrieved +from NGINX Ingress. + +The [`stable/prometheus`](https://github.com/helm/charts/tree/master/stable/prometheus) +chart is used to install this application with a +[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/prometheus/values.yaml) +file. + +To enable monitoring, install Prometheus into the cluster with the **Install** +button. + +### Crossplane + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34702) in GitLab 12.5 for project-level clusters. + +[Crossplane](https://crossplane.github.io/docs/v0.9/) is a multi-cloud control plane +to help you manage applications and infrastructure across multiple clouds. It extends the +Kubernetes API using: + +- Custom resources. +- Controllers that watch those custom resources. + +Crossplane allows provisioning and lifecycle management of infrastructure components +across cloud providers in a uniform manner by abstracting cloud provider-specific +configurations. + +The Crossplane GitLab-managed application: + +- Installs Crossplane with a provider of choice on a Kubernetes cluster attached to the + project repository. +- Can then be used to provision infrastructure or managed applications such as + PostgreSQL (for example, CloudSQL from GCP or RDS from AWS) and other services + required by the application with the Auto DevOps pipeline. + +[`alpha/crossplane`](https://github.com/crossplane/crossplane/tree/v0.4.1/cluster/charts/crossplane) chart v0.4.1 is used to +install Crossplane using the +[`values.yaml`](https://github.com/crossplane/crossplane/blob/master/cluster/charts/crossplane/values.yaml.tmpl) +file. + +For information about configuring Crossplane installed on the cluster, see +[Crossplane configuration](crossplane.md). + +### Elastic Stack + +> Introduced in GitLab 12.7 for project- and group-level clusters. + +[Elastic Stack](https://www.elastic.co/elastic-stack) is a complete end-to-end +log analysis solution which helps in deep searching, analyzing and visualizing the logs +generated from different machines. + +GitLab can gather logs from pods in your cluster. Filebeat runs as a DaemonSet +on each node in your cluster, and ships container logs to Elasticsearch for +querying. GitLab then connects to Elasticsearch for logs, instead of the +Kubernetes API, giving you access to more advanced querying capabilities. Log +data is deleted after 30 days, using [Curator](https://www.elastic.co/guide/en/elasticsearch/client/curator/5.5/about.html). + +The Elastic Stack cluster application is intended as a log aggregation solution +and is not related to our [Advanced Search](../search/advanced_global_search.md) +functionality, which uses a separate Elasticsearch cluster. + +To enable log shipping: + +1. Ensure your cluster contains at least three nodes of instance types larger + than `f1-micro`, `g1-small`, or `n1-standard-1`. +1. Navigate to **Operations > Kubernetes**. +1. In **Kubernetes Cluster**, select a cluster. +1. In the **Applications** section, find **Elastic Stack**, and then select + **Install**. + +The [`gitlab/elastic-stack`](https://gitlab.com/gitlab-org/charts/elastic-stack) +chart is used to install this application with a +[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/elastic_stack/values.yaml) +file. The chart deploys three identical Elasticsearch pods which can't be +colocated, and each requires one CPU and 2 GB of RAM, making them +incompatible with clusters containing fewer than three nodes, or consisting of +`f1-micro`, `g1-small`, `n1-standard-1`, or `*-highcpu-2` instance types. + +#### Optional: deploy Kibana to perform advanced queries + +If you are an advanced user and have direct access to your Kubernetes cluster +using `kubectl` and `helm`, you can deploy Kibana manually. The following assumes +that `helm` has been [initialized](https://v2.helm.sh/docs/helm/) with `helm init`. + +Save the following to `kibana.yml`: + +```yaml +elasticsearch: + enabled: false + +filebeat: + enabled: false + +kibana: + enabled: true + elasticsearchHosts: http://elastic-stack-elasticsearch-master.gitlab-managed-apps.svc.cluster.local:9200 +``` + +Then install it on your cluster: + +```shell +helm repo add gitlab https://charts.gitlab.io +helm install --name kibana gitlab/elastic-stack --values kibana.yml +``` + +To access Kibana, forward the port to your local machine: + +```shell +kubectl port-forward svc/kibana-kibana 5601:5601 +``` + +Then, you can visit Kibana at `http://localhost:5601`. + +### Fluentd + +> Introduced in GitLab 12.10 for project- and group-level clusters. + +[Fluentd](https://www.fluentd.org/) is an open source data collector, which enables +you to unify the data collection and consumption to better use and understand +your data. Fluentd sends logs in syslog format. + +To enable Fluentd: + +1. Navigate to **Operations > Kubernetes** and click + **Applications**. Enter a host, port, and protocol + for sending the WAF logs with syslog. +1. Provide the host domain name or URL in **SIEM Hostname**. +1. Provide the host port number in **SIEM Port**. +1. Select a **SIEM Protocol**. +1. Select at least one of the available logs (such as WAF or Cilium). +1. Click **Save changes**. + + ## Upgrading applications diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md index f13be15c6bc..d1df5642514 100644 --- a/doc/user/clusters/cost_management.md +++ b/doc/user/clusters/cost_management.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 cost management **(ULTIMATE)** @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Cluster cost management provides insights into cluster resource usage. GitLab provides an example [`kubecost-cost-model`](https://gitlab.com/gitlab-examples/kubecost-cost-model/) -project that uses GitLab's Prometheus integration and +project that uses the GitLab Prometheus integration and [Kubecost's `cost-model`](https://github.com/kubecost/cost-model) to provide cluster cost insights within GitLab: @@ -28,7 +28,7 @@ permissions in a project or group. need to change this value if you use a non-managed Prometheus. - Adds the necessary annotations to the deployment manifest to be scraped by GitLab-managed Prometheus. - - Changes the Google Pricing API access key to GitLab's access key. + - Changes the Google Pricing API access key to the GitLab access key. - Contains definitions for a custom GitLab Metrics dashboard to show the cost insights. 1. Connect GitLab with Prometheus, depending on your configuration: - *If Prometheus is already configured,* navigate to **Settings > Integrations > Prometheus** @@ -58,7 +58,7 @@ file or creating similar dashboard configuration files. To learn more, read abou #### Available metrics -Metrics contain both instance and node labels. The instance label will be deprecated in a future version. +Metrics contain both instance and node labels. The instance label is scheduled for deprecation in a future version. - `node_cpu_hourly_cost` - Hourly cost per vCPU on this node. - `node_gpu_hourly_cost` - Hourly cost per GPU on this node. diff --git a/doc/user/clusters/crossplane.md b/doc/user/clusters/crossplane.md index 8463917f2f3..c1ef798f5a8 100644 --- a/doc/user/clusters/crossplane.md +++ b/doc/user/clusters/crossplane.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index 3ab20c5466e..be4ac8151e4 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 Environments **(PREMIUM)** diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index f7241444a6b..55f507fb318 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -1,12 +1,12 @@ --- 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/#designated-technical-writers +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 (alpha) +# Cluster management project -CAUTION: **Warning:** +WARNING: This is an _alpha_ feature, and it is subject to change at any time without prior notice. @@ -20,13 +20,13 @@ privileges. This can be useful for: -- Creating pipelines to install cluster-wide applications into your cluster, see [Install using GitLab CI/CD (alpha)](applications.md#install-using-gitlab-cicd-alpha) for details. +- Creating pipelines to install cluster-wide applications into your cluster, see [Install using GitLab CI/CD (alpha)](applications.md#install-using-gitlab-cicd) for details. - Any jobs that require `cluster-admin` privileges. ## Permissions -Only the management project will receive `cluster-admin` privileges. All -other projects will continue to receive [namespace scoped `edit` level privileges](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). +Only the management project receives `cluster-admin` privileges. All +other projects continue to receive [namespace scoped `edit` level privileges](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). Management projects are restricted to the following: @@ -92,7 +92,7 @@ to a management project: | Production | `production` | The following environments set in -[`.gitlab-ci.yml`](../../ci/yaml/README.md) will deploy to the +[`.gitlab-ci.yml`](../../ci/yaml/README.md) deploy to the Development, Staging, and Production cluster respectively. ```yaml diff --git a/doc/user/compliance/compliance_dashboard/index.md b/doc/user/compliance/compliance_dashboard/index.md index 151c61b50d8..f1dfc431f25 100644 --- a/doc/user/compliance/compliance_dashboard/index.md +++ b/doc/user/compliance/compliance_dashboard/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Compliance Dashboard **(ULTIMATE)** @@ -19,7 +19,7 @@ To access the Compliance Dashboard for a group, navigate to **{shield}** **Secur  -NOTE: **Note:** +NOTE: The Compliance Dashboard shows only the latest MR on each project. ## Use cases @@ -81,6 +81,6 @@ To download the Chain of Custody report, navigate to **{shield}** **Security & C You can generate a commit-specific Chain of Custody report for a given commit SHA. To do so, select the dropdown next to the **List of all merge commits** button at the top of the Compliance Dashboard. -NOTE: **Note:** +NOTE: The Chain of Custody report download is a CSV file, with a maximum size of 15 MB. The remaining records are truncated when this limit is reached. diff --git a/doc/user/compliance/index.md b/doc/user/compliance/index.md index d0e73b47358..d31f877c418 100644 --- a/doc/user/compliance/index.md +++ b/doc/user/compliance/index.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Compliance **(ULTIMATE)** diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 65c009f947f..f78b6115623 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Secure group: Composition Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # License Compliance **(ULTIMATE)** @@ -19,21 +19,21 @@ in your existing `.gitlab-ci.yml` file or by implicitly using [Auto License Compliance](../../../topics/autodevops/stages.md#auto-license-compliance) that is provided by [Auto DevOps](../../../topics/autodevops/index.md). -GitLab checks the License Compliance report, compares the licenses between the -source and target branches, and shows the information right on the merge request. -Denied licenses will be clearly visible with an `x` red icon next to them -as well as new licenses which need a decision from you. In addition, you can -[manually allow or deny](#policies) -licenses in your project's license compliance policy section. If GitLab detects a denied license -in a new commit, GitLab blocks any merge requests containing that commit and instructs the developer -to remove the license. +The [License Finder](https://github.com/pivotal/LicenseFinder) scan tool runs as part of the CI/CD +pipeline, and detects the licenses in use. GitLab checks the License Compliance report, compares the +licenses between the source and target branches, and shows the information right on the merge +request. Denied licenses are indicated by a `x` red icon next to them as well as new licenses that +need a decision from you. In addition, you can [manually allow or deny](#policies) licenses in your +project's license compliance policy section. If a denied license is detected in a new commit, +GitLab blocks any merge requests containing that commit and instructs the developer to remove the +license. -NOTE: **Note:** +NOTE: If the license compliance report doesn't have anything to compare to, no information -will be displayed in the merge request area. That is the case when you add the +is displayed in the merge request area. That is the case when you add the `license_scanning` job in your `.gitlab-ci.yml` for the first time. -Consecutive merge requests will have something to compare to and the license -compliance report will be shown properly. +Consecutive merge requests have something to compare to and the license +compliance report is shown properly.  @@ -51,36 +51,33 @@ You can view and modify existing policies from the [policies](#policies) tab. The following languages and package managers are supported. -| Language | Package managers | Notes | Scan Tool | -|------------|------------------|-------|-----------| -| JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/) | | [License Finder](https://github.com/pivotal/LicenseFinder) | -| Go | [Godep](https://github.com/tools/godep), [go mod](https://github.com/golang/go/wiki/Modules) | | [License Finder](https://github.com/pivotal/LicenseFinder) | -| Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | | [License Finder](https://github.com/pivotal/LicenseFinder) | -| .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`. | [License Finder](https://github.com/pivotal/LicenseFinder) | -| 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). | [License Finder](https://github.com/pivotal/LicenseFinder) | -| Ruby | [gem](https://rubygems.org/) | | [License Finder](https://github.com/pivotal/LicenseFinder)| +Java 8 and Gradle 1.x projects are not supported. The minimum supported version of Maven is 3.2.5. -NOTE: **Note:** -Java 8 and Gradle 1.x projects are not supported. -The minimum supported version of Maven is 3.2.5. +| Language | Package managers | Notes | +|------------|----------------------------------------------------------------------------------------------|-------| +| 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`. | +| 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/) | | ### Experimental support -The following languages and package managers are [supported experimentally](https://github.com/pivotal/LicenseFinder#experimental-project-types), -which means that the reported licenses might be incomplete or inaccurate. - -| Language | Package managers | Scan Tool | -|------------|-------------------------------------------------------------------|----------------------------------------------------------| -| JavaScript | [Yarn](https://yarnpkg.com/)|[License Finder](https://github.com/pivotal/LicenseFinder)| -| Go | go get, gvt, glide, dep, trash, govendor |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Erlang | [Rebar](https://www.rebar3.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage) | | [License Finder](https://github.com/pivotal/LicenseFinder) | -| Objective-C, Swift | [CocoaPods](https://cocoapods.org/) v0.39 and below |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Elixir | [Mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| C++/C | [Conan](https://conan.io/) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Scala | [sbt](https://www.scala-sbt.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| Rust | [Cargo](https://crates.io) |[License Finder](https://github.com/pivotal/LicenseFinder)| -| PHP | [Composer](https://getcomposer.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +The following languages and package managers are [supported experimentally](https://github.com/pivotal/LicenseFinder#experimental-project-types). +The reported licenses might be incomplete or inaccurate. + +| Language | Package managers | +|------------|---------------------------------------------------------------------------------------------------------------| +| JavaScript | [Yarn](https://yarnpkg.com/) | +| 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) | +| C++/C | [Conan](https://conan.io/) | +| Scala | [sbt](https://www.scala-sbt.org/) | +| Rust | [Cargo](https://crates.io) | +| PHP | [Composer](https://getcomposer.org/) | ## Requirements @@ -109,12 +106,12 @@ include: The included template creates a `license_scanning` job in your CI/CD pipeline and scans your dependencies to find their licenses. -NOTE: **Note:** +NOTE: Before GitLab 12.8, the `license_scanning` job was named `license_management`. GitLab 13.0 removes the `license_management` job, so you must migrate to the `license_scanning` job and use the new `License-Scanning.gitlab-ci.yml` template. -The results will be saved as a +The results are saved as a [License Compliance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportslicense_scanning) that you can later download and analyze. Due to implementation limitations, we always take the latest License Compliance artifact available. Behind the scenes, the @@ -160,7 +157,7 @@ in the project automated setup, like the download and installation of a certific For that, a `LICENSE_MANAGEMENT_SETUP_CMD` environment variable can be passed to the container, with the required commands to run before the license detection. -If present, this variable will override the setup step necessary to install all the packages +If present, this variable overrides the setup step necessary to install all the packages of your application (e.g.: for a project with a `Gemfile`, the setup step could be `bundle install`). @@ -179,7 +176,7 @@ directory of your project. ### Overriding the template -CAUTION: **Deprecation:** +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. @@ -274,13 +271,13 @@ to specify its location. ### 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 If you have a private NPM registry you can use the -[`registry`](https://docs.npmjs.com/using-npm/config#registry) +[`registry`](https://docs.npmjs.com/using-npm/config/#registry) setting to specify its location. For example: @@ -294,7 +291,7 @@ registry = https://npm.example.com You can supply a custom root certificate to complete TLS verification by using the `ADDITIONAL_CA_CERT_BUNDLE` [environment variable](#available-variables). -To disable TLS verification you can provide the [`strict-ssl`](https://docs.npmjs.com/using-npm/config#strict-ssl) +To disable TLS verification you can provide the [`strict-ssl`](https://docs.npmjs.com/using-npm/config/#strict-ssl) setting. For example: @@ -454,7 +451,7 @@ if a GitLab remote is specified in the `.conan/remotes.json` file. To override the default credentials specify a [`CONAN_LOGIN_USERNAME_{REMOTE_NAME}`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name) matching the name of the remote specified in the `.conan/remotes.json` file. -NOTE: **Note:** +NOTE: [MSBuild](https://github.com/mono/msbuild#microsoftbuild-msbuild) projects aren't supported. The `license_scanning` image ships with [Mono](https://www.mono-project.com/) and [MSBuild](https://github.com/mono/msbuild#microsoftbuild-msbuild). Additional setup may be required to build packages for this project configuration. @@ -616,7 +613,7 @@ To use License Compliance in an offline environment, you need: - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). - Docker Container Registry with locally available copies of License Compliance [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. -NOTE: **Note:** +NOTE: GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), meaning the runner tries to pull Docker images from the GitLab container registry even if a local copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) @@ -695,7 +692,7 @@ requirements must be met: [supported languages and package managers](#supported-languages-and-package-managers). Once everything is set, navigate to **Security & Compliance > License Compliance** -in your project's sidebar, and you'll see the licenses displayed, where: +in your project's sidebar, and the licenses are displayed, where: - **Name:** The name of the license. - **Component:** The components which have this license. @@ -708,8 +705,8 @@ in your project's sidebar, and you'll see the licenses displayed, where: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22465) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. Policies allow you to specify licenses that are `allowed` or `denied` in a project. If a `denied` -license is newly committed it will disallow a merge request and instruct the developer to remove it. -Note, the merge request will not be able to be merged until the `denied` license is removed. +license is newly committed it blocks the merge request and instructs the developer to remove it. +Note, the merge request is not able to be merged until the `denied` license is removed. You may add a [`License-Check` approval rule](#enabling-license-approvals-within-a-project), which enables a designated approver that can approve and then merge a merge request with `denied` license. @@ -771,7 +768,7 @@ specify the desired version by adding a or using the appropriate [`ASDF_<tool>_VERSION`](https://asdf-vm.com/#/core-configuration?id=environment-variables) environment variable to activate the appropriate version. -For example, the following `.tool-versions` file will activate version `12.16.3` of [Node.js](https://nodejs.org/) +For example, the following `.tool-versions` file activates version `12.16.3` of [Node.js](https://nodejs.org/) and version `2.7.2` of [Ruby](https://www.ruby-lang.org/). ```plaintext @@ -828,5 +825,5 @@ $ docker run -it --entrypoint='' registry.gitlab.com/gitlab-org/security-product root@6abb70e9f193:~# ``` -NOTE: **Note:** +NOTE: Selecting a custom version of [Mono](https://www.mono-project.com/) or [.NET Core](https://dotnet.microsoft.com/download/dotnet-core) is currently not supported. diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index d3576ea33fe..945c082bba9 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -31,7 +31,7 @@ You can also reply to a comment notification email to reply to the comment if creates another standard comment. Replying to a threaded comment creates a reply in the thread. Email replies support [Markdown](../markdown.md) and [quick actions](../project/quick_actions.md), just as if you replied from the web. -NOTE: **Note:** +NOTE: There is a limit of 5,000 comments for every object, for example: issue, epic, and merge request. ## Resolvable comments and threads @@ -85,7 +85,7 @@ Threads created this way will only appear in the original merge request and not when navigating to that commit under your project's **Repository > Commits** page. -TIP: **Tip:** +NOTE: When a link of a commit reference is found in a thread inside a merge request, it will be automatically converted to a link in the context of the current merge request. @@ -206,7 +206,7 @@ top-level resolvable threads are not automatically resolved. You can add comments and threads to a particular commit under your project's **Repository > Commits**. -CAUTION: **Attention:** +WARNING: Threads created this way will be lost if the commit ID changes after a force push. @@ -248,7 +248,7 @@ After you click on the image, a comment form will be displayed that would be the of your thread. Once you save your comment, you will see a new badge displayed on top of your image. This badge represents your thread. -NOTE: **Note:** +NOTE: This thread badge is typically associated with a number that is only used as a visual reference for each thread. In the merge request thread tab, this badge will be indicated with a comment icon since each thread will render a new @@ -444,7 +444,7 @@ to 4 lines _below_ the commented line, with the suggested change.  -NOTE: **Note:** +NOTE: Suggestions covering multiple lines are limited to 100 lines _above_ and 100 lines _below_ the commented diff line, allowing up to 200 changed lines per suggestion. @@ -491,13 +491,13 @@ For example, to customize the commit message to output **Addresses user_1's review**, set the custom text to `Addresses %{username}'s review`. -NOTE: **Note:** +NOTE: Custom commit messages for each applied Suggestion (and for batch Suggestions) will be introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381). ### Batch Suggestions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/#alpha). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). > - It was deployed behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) on GitLab 13.2. > - It's enabled on GitLab.com. diff --git a/doc/user/feature_flags.md b/doc/user/feature_flags.md index c134b7c083c..9a601871349 100644 --- a/doc/user/feature_flags.md +++ b/doc/user/feature_flags.md @@ -18,7 +18,7 @@ may be unavailable to you. In this case, you'll see a warning like this in the feature documentation: -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Review the **version history** note on this page for details. diff --git a/doc/user/feature_highlight.md b/doc/user/feature_highlight.md index 31eb0e6375d..8d452d2caf0 100644 --- a/doc/user/feature_highlight.md +++ b/doc/user/feature_highlight.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Feature highlight @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/16379) in GitLab 10.5 Feature highlights are represented by a pulsing blue dot. Hovering over the dot -will display more information. +displays more information. They are used to emphasize a certain feature and make something more visible to the user. You can dismiss any feature highlight permanently by clicking the "Got it" link diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 54f14c71c93..7aafa52799d 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -1,18 +1,18 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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.com settings -In this page you will find information about the settings that are used on +This page contains information about the settings that are used on [GitLab.com](https://about.gitlab.com/pricing/). ## SSH host keys fingerprints Below are the fingerprints for GitLab.com's SSH host keys. The first time you connect -to a GitLab.com repository, you'll see one of these keys in the output. +to a GitLab.com repository, one of these keys is displayed in the output. | Algorithm | MD5 (deprecated) | SHA256 | | --------- | --- | ------- | @@ -37,7 +37,7 @@ gitlab.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAA GitLab.com sends emails from the `mg.gitlab.com` domain via [Mailgun](https://www.mailgun.com/) and has its own dedicated IP address (`192.237.158.143`). -NOTE: **Note:** +NOTE: The IP address for `mg.gitlab.com` is subject to change at any time. ## Backups @@ -50,7 +50,7 @@ Projects can be backed up in their entirety by exporting them either [through th With exports, be sure to take note of [what is and is not](../project/settings/import_export.md#exported-contents), included in a project export. -Since GitLab is built on Git, you can back up **just** the repository of a project by [cloning](../../gitlab-basics/start-using-git.md#clone-a-repository) it to another machine. Similarly, if you need to back up just the wiki of a repository it can also be cloned and all files uploaded to that wiki will come with it [if they were uploaded after 2020-08-22](../project/wiki/index.md#creating-a-new-wiki-page). +Since GitLab is built on Git, you can back up **just** the repository of a project by [cloning](../../gitlab-basics/start-using-git.md#clone-a-repository) it to another machine. Similarly, if you need to back up just the wiki of a repository it can also be cloned and all files uploaded to that wiki are included [if they were uploaded after 2020-08-22](../project/wiki/index.md#creating-a-new-wiki-page). ## Alternative SSH port @@ -84,7 +84,7 @@ Below are the settings for [GitLab Pages](https://about.gitlab.com/stages-devops | TLS certificates support | yes | no | | Maximum size (compressed) | 1G | 100M | -NOTE: **Note:** +NOTE: The maximum size of your Pages site is regulated by the artifacts maximum size which is part of [GitLab CI/CD](#gitlab-cicd). @@ -116,7 +116,7 @@ or over the repository size limit, you can [reduce your repository size with Git | [Repository size including LFS](../admin_area/settings/account_and_limit_settings.md) | 10 GB | Unlimited | | Maximum import size | 5 GB | 50 MB | -NOTE: **Note:** +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. ## IP range @@ -144,27 +144,26 @@ A limit of: GitLab offers Linux and Windows shared runners hosted on GitLab.com for executing your pipelines. -NOTE: **Note:** +NOTE: Shared runners provided by GitLab are **not** configurable. Consider [installing your own runner](https://docs.gitlab.com/runner/install/) if you have specific configuration needs. ### Linux shared runners -Linux shared runners on GitLab.com run in [autoscale mode](https://docs.gitlab.com/runner/configuration/autoscale.html) and are powered by Google Cloud Platform. -Autoscaling means reduced waiting times to spin up CI/CD jobs, and isolated VMs for each project, -thus maximizing security. They're free to use for public open source projects and limited -to 400 CI minutes per month per group for private projects. More minutes -[can be purchased](../../subscriptions/gitlab_com/index.md#purchase-additional-ci-minutes), if -needed. Read about all [GitLab.com plans](https://about.gitlab.com/pricing/). +Linux shared runners on GitLab.com run in autoscale mode and are powered by Google Cloud Platform. + +Autoscaling means reduced queue times to spin up CI/CD jobs, and isolated VMs for each project, thus maximizing security. These shared runners are available for users and customers on GitLab.com. + +GitLab offers 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. All your CI/CD jobs run on [n1-standard-1 instances](https://cloud.google.com/compute/docs/machine-types) with 3.75GB of RAM, CoreOS and the latest Docker Engine installed. Instances provide 1 vCPU and 25GB of HDD disk space. The default region of the VMs is US East1. Each instance is used only for one job, this ensures any sensitive data left on the system can't be accessed by other people their CI jobs. -The `gitlab-shared-runners-manager-X.gitlab.com` fleet of runners are dedicated for GitLab projects as well as community forks of them. They use a slightly larger machine type (n1-standard-2) and have a bigger SSD disk size. They will not run untagged jobs and unlike the general fleet of shared runners, the instances are re-used up to 40 times. +The `gitlab-shared-runners-manager-X.gitlab.com` fleet of runners are dedicated for GitLab projects as well as community forks of them. They use a slightly larger machine type (n1-standard-2) and have a bigger SSD disk size. They don't run untagged jobs and unlike the general fleet of shared runners, the instances are re-used up to 40 times. Jobs handled by the shared runners on GitLab.com (`shared-runners-manager-X.gitlab.com`), -**will be timed out after 3 hours**, regardless of the timeout configured in a +**time out after 3 hours**, regardless of the timeout configured in a project. Check the issues [4010](https://gitlab.com/gitlab-com/infrastructure/-/issues/4010) and [4070](https://gitlab.com/gitlab-com/infrastructure/-/issues/4070) for the reference. Below are the shared runners settings. @@ -200,7 +199,7 @@ directory. The full contents of our `config.toml` are: -NOTE: **Note:** +NOTE: Settings that are not public are shown as `X`. **Google Cloud Platform** @@ -294,7 +293,7 @@ You can follow our work towards this goal in the The full contents of our `config.toml` are: -NOTE: **Note:** +NOTE: Settings that aren't public are shown as `X`. ```toml @@ -396,19 +395,19 @@ test: - The average provisioning time for a new Windows VM is 5 minutes. This means that you may notice slower build start times on the Windows shared runner fleet during the beta. In a future - release we will update the autoscaler to enable - the pre-provisioning of virtual machines. This will significantly reduce + release we intend to update the autoscaler to enable + the pre-provisioning of virtual machines. This is intended to significantly reduce the time it takes to provision a VM on the Windows fleet. You can follow along in the [related issue](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/-/issues/32). - The Windows shared runner fleet may be unavailable occasionally for maintenance or updates. - The Windows shared runner virtual machine instances do not use the - GitLab Docker executor. This means that you will not be able to specify + GitLab Docker executor. This means that you can't specify [`image`](../../ci/yaml/README.md#image) or [`services`](../../ci/yaml/README.md#services) in your pipeline configuration. - For the beta release, we have included a set of software packages in the base VM image. If your CI job requires additional software that's - not included in this list, then you will need to add installation + not included in this list, then you must add installation commands to [`before_script`](../../ci/yaml/README.md#before_script) or [`script`](../../ci/yaml/README.md#script) to install the required software. Note that each job runs on a new VM instance, so the installation of additional software packages needs to be repeated for @@ -434,7 +433,7 @@ and the following environment variables: | `SIDEKIQ_MEMORY_KILLER_SHUTDOWN_WAIT` | - | `30` | | `SIDEKIQ_LOG_ARGUMENTS` | `1` | `1` | -NOTE: **Note:** +NOTE: The `SIDEKIQ_MEMORY_KILLER_MAX_RSS` setting is `16000000` on Sidekiq import nodes and Sidekiq export nodes. @@ -506,54 +505,42 @@ Web front-ends: ## GitLab.com-specific rate limits -NOTE: **Note:** +NOTE: See [Rate limits](../../security/rate_limits.md) for administrator documentation. -IP blocks usually happen when GitLab.com receives unusual traffic from a single -IP address that the system views as potentially malicious based on rate limit -settings. After the unusual traffic ceases, the IP address will be automatically -released depending on the type of block, as described below. +When a request is rate limited, GitLab responds with a `429` status +code. The client should wait before attempting the request again. There +are also informational headers with this response detailed in [rate +limiting responses](#rate-limiting-responses). -If you receive a `403 Forbidden` error for all requests to GitLab.com, please -check for any automated processes that may be triggering a block. For -assistance, contact [GitLab Support](https://support.gitlab.com/hc/en-us) -with details, such as the affected IP address. +The following table describes the rate limits for GitLab.com, both before and +after the limits change in January, 2021: -### HAProxy API throttle +| 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 | -GitLab.com responds with HTTP status code `429` to API requests that exceed 10 -requests -per second per IP address. - -The following example headers are included for all API requests: - -```plaintext -RateLimit-Limit: 600 -RateLimit-Observed: 6 -RateLimit-Remaining: 594 -RateLimit-Reset: 1563325137 -RateLimit-ResetTime: Wed, 17 Jul 2019 00:58:57 GMT -``` +More details are available on the rate limits for [protected +paths](#protected-paths-throttle) and [raw +endpoints](../../user/admin_area/settings/rate_limits_on_raw_endpoints.md). -Source: +### Rate limiting responses -- Search for `rate_limit_http_rate_per_minute` and `rate_limit_sessions_per_second` in [GitLab.com's current HAProxy settings](https://gitlab.com/gitlab-cookbooks/gitlab-haproxy/blob/master/attributes/default.rb). +The [`Retry-After` +header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) +indicates when the client should retry. -### Pagination response headers - -For performance reasons, if a query returns more than 10,000 records, GitLab -doesn't return the following headers: - -- `x-total`. -- `x-total-pages`. -- `rel="last"` `link`. +Rate limits applied by HAProxy (instead of Cloudflare or the +GitLab application) have `RateLimit-Reset` and `RateLimit-ResetTime` +headers. -### Rack Attack initializer - -Details of rate limits enforced by [Rack Attack](../../security/rack_attack.md). - -#### Protected paths throttle +### Protected paths throttle GitLab.com responds with HTTP status code `429` to POST requests at protected paths that exceed 10 requests per **minute** per IP address. @@ -569,6 +556,18 @@ Retry-After: 60 See [Protected Paths](../admin_area/settings/protected_paths.md) for more details. +### IP blocks + +IP blocks can occur when GitLab.com receives unusual traffic from a single +IP address that the system views as potentially malicious, based on rate limit +settings. After the unusual traffic ceases, the IP address is automatically +released depending on the type of block, as described in a following section. + +If you receive a `403 Forbidden` error for all requests to GitLab.com, +check for any automated processes that may be triggering a block. For +assistance, contact [GitLab Support](https://support.gitlab.com/hc/en-us) +with details, such as the affected IP address. + #### Git and container registry failed authentication ban GitLab.com responds with HTTP status code `403` for 1 hour, if 30 failed @@ -586,13 +585,14 @@ This limit: No response headers are provided. -### Admin Area settings +### Pagination response headers -GitLab.com: +For performance reasons, if a query returns more than 10,000 records, GitLab +doesn't return the following headers: -- Has [rate limits on raw endpoints](../../user/admin_area/settings/rate_limits_on_raw_endpoints.md) - set to the default. -- Does not have the user and IP rate limits settings enabled. +- `x-total`. +- `x-total-pages`. +- `rel="last"` `link`. ### Visibility settings @@ -612,6 +612,13 @@ 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 diff --git a/doc/user/group/bulk_editing/index.md b/doc/user/group/bulk_editing/index.md index ec1e81bac2d..8db9c7fd76c 100644 --- a/doc/user/group/bulk_editing/index.md +++ b/doc/user/group/bulk_editing/index.md @@ -1,19 +1,19 @@ --- 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/#designated-technical-writers +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 --- # Bulk editing issues, epics, and merge requests at the group level **(PREMIUM)** -NOTE: **Note:** +NOTE: Bulk editing issues and merge requests is also available at the **project level**. For more details, see [Bulk editing issues and merge requests at the project level](../../project/bulk_editing.md). If you want to update attributes across multiple issues, epics, or merge requests in a group, you can do it by bulk editing them, that is, editing them together. -NOTE: **Note:** +NOTE: Only the items visible on the current page are selected for bulk editing (up to 20).  @@ -22,7 +22,7 @@ Only the items visible on the current page are selected for bulk editing (up to > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7249) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. -NOTE: **Note:** +NOTE: You need a permission level of [Reporter or higher](../../permissions.md) to manage issues. When bulk editing issues in a group, you can edit the following attributes: @@ -46,7 +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: **Note:** +NOTE: You need a permission level of [Reporter or higher](../../permissions.md) to manage epics. When bulk editing epics in a group, you can edit their labels. @@ -63,7 +63,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: **Note:** +NOTE: You need a permission level of [Developer or higher](../../permissions.md) to 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 1a62d67e468..ea7629d1f10 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -2,7 +2,7 @@ type: reference 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/#designated-technical-writers +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 @@ -58,11 +58,11 @@ differentiate the new cluster from your other clusters. > - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26565) in GitLab 11.11. You can choose to allow GitLab to manage your cluster for you. If GitLab manages -your cluster, resources for your projects will be automatically created. See the +your cluster, resources for your projects are automatically created. See the [Access controls](../../project/clusters/add_remove_clusters.md#access-controls) section for details on which resources GitLab creates for you. -For clusters not managed by GitLab, project-specific resources won't be created +For clusters not managed by GitLab, project-specific resources aren't created automatically. If you're using [Auto DevOps](../../../topics/autodevops/index.md) for deployments with a cluster not managed by GitLab, you must ensure: @@ -97,7 +97,7 @@ To clear the cache: Domains at the cluster level permit support for multiple domains per [multiple Kubernetes clusters](#multiple-kubernetes-clusters) When specifying a domain, -this will be automatically set as an environment variable (`KUBE_INGRESS_BASE_DOMAIN`) during +this is automatically set as an environment variable (`KUBE_INGRESS_BASE_DOMAIN`) during the [Auto DevOps](../../../topics/autodevops/index.md) stages. The domain should have a wildcard DNS configured to the Ingress IP address. diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index cf55a1f688b..0dbd7af1214 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -1,8 +1,8 @@ --- type: reference stage: Manage -group: Value Stream 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/#designated-technical-writers +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)** diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index bbff82811bf..a59b1f2e9b2 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Custom group-level project templates **(PREMIUM)** @@ -20,7 +20,7 @@ To use a custom project template for a new project you need to: 1. Edit your group's settings to look to your 'templates' subgroup for templates: 1. In the left-hand menu, click **{settings}** **Settings > General**. - NOTE: **Note:** + NOTE: If you don't have access to the group's settings, you may not have sufficient privileges (for example, you may need developer or higher permissions). 1. Scroll to **Custom project templates** and click **Expand**. If no **Custom project templates** section displays, make sure you've created a subgroup, and added a project (repository) to it. @@ -56,7 +56,7 @@ gitlab.com/acmeco/ Users can configure a GitLab group that serves as template source under a group's **Settings > General > Custom project templates**. -NOTE: **Note:** +NOTE: GitLab administrators can [set project templates for an entire GitLab instance](../admin_area/custom_project_templates.md). @@ -66,11 +66,11 @@ available to every signed-in user, if all enabled [project features](../project/ However, private projects will be available only if the user is a member of the project. -NOTE: **Note:** +NOTE: Only direct subgroups can be set as the template source. Projects of nested subgroups of a selected template source cannot be used. Repository and database information that are copied over to each new project are -identical to the data exported with [GitLab's Project Import/Export](../project/settings/import_export.md). +identical to the data exported with the [GitLab Project Import/Export](../project/settings/import_export.md). <!-- ## Troubleshooting diff --git a/doc/user/group/dependency_proxy/index.md b/doc/user/group/dependency_proxy/index.md index f735ec0214f..c4feed24132 100644 --- a/doc/user/group/dependency_proxy/index.md +++ b/doc/user/group/dependency_proxy/index.md @@ -3,3 +3,6 @@ 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/img/new_epic_form_v13.2.png b/doc/user/group/epics/img/new_epic_form_v13.2.png Binary files differdeleted file mode 100644 index ac1450ae111..00000000000 --- a/doc/user/group/epics/img/new_epic_form_v13.2.png +++ /dev/null diff --git a/doc/user/group/epics/img/new_epic_from_groups_v13.2.png b/doc/user/group/epics/img/new_epic_from_groups_v13.2.png Binary files differdeleted file mode 100644 index bb75605af60..00000000000 --- a/doc/user/group/epics/img/new_epic_from_groups_v13.2.png +++ /dev/null diff --git a/doc/user/group/epics/img/new_epic_from_groups_v13.7.png b/doc/user/group/epics/img/new_epic_from_groups_v13.7.png Binary files differnew file mode 100644 index 00000000000..3607d5c7a3f --- /dev/null +++ b/doc/user/group/epics/img/new_epic_from_groups_v13.7.png diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index e98c4b416fe..c76b07481b2 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -2,7 +2,7 @@ type: reference, howto 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/#designated-technical-writers +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 --- # Epics **(PREMIUM)** @@ -10,20 +10,24 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.2. > - Single-level Epics [were moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8. -Epics let you manage your portfolio of projects more efficiently by tracking groups of issues that -share a theme across projects and milestones. +Epics let you manage your portfolio of projects more efficiently by tracking groups of [issues](../../project/issues/index.md) +that share a theme across projects and milestones. An epic's page contains the following tabs: -- **Epics and Issues**: epics and issues added to this epic. Child epics, and their issues, are - shown in a tree view. - - Click the chevron (**>**) next to a parent epic to reveal the child epics and issues. - - Hover over the total counts to see a breakdown of open and closed items. +- **Issues**: issues added to this epic. +- **Epics and Issues**: epics and issues added to this epic. + Appears instead of the **Issues** tab if you have access to [multi-level epics](#multi-level-child-epics). + Child epics and their issues are shown in a tree view. - NOTE: **Note:** - The number provided here includes all epics associated with this project. The number includes epics for which users may not yet have permission. + - To reveal the child epics and issues, select the chevron (**>**) next to a parent epic. + - To see a breakdown of open and closed items, hover over the total counts. -- **Roadmap**: a roadmap view of child epics which have start and due dates. + The number provided here includes all epics associated with this project. The number includes + epics for which users may not yet have permission. + +- [**Roadmap**](#roadmap-in-epics): a roadmap view of child epics which have start and due dates. + Appears if you have access to [multi-level epics](#multi-level-child-epics).  @@ -75,14 +79,10 @@ to: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199184) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. > - The health status of a closed issue [is hidden](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3 or later. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7. Report or respond to the health of issues and epics by setting a red, amber, or green [health status](../../project/issues/index.md#health-status), which then appears on your Epic tree. -### Disable Issue health status in Epic tree - -This feature comes with a feature flag enabled by default. For steps to disable it, see -[Disable issue health status](../../project/issues/index.md#disable-issue-health-status). - ## Multi-level child epics **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8333) in GitLab Ultimate 11.7. @@ -92,7 +92,7 @@ New child epics appear at the top of the list of epics in the **Epics and Issues When you add an epic that's already linked to a parent epic, the link to its current parent is removed. -An epic can have multiple child epics up to the maximum depth of five. +An epic can have multiple child epics up to the maximum depth of seven. See [Manage multi-level child epics](manage_epics.md#manage-multi-level-child-epics) for steps to create, move, reorder, or delete child epics. @@ -101,35 +101,18 @@ steps to create, move, reorder, or delete child epics. To set a **Start date** and **Due date** for an epic, select one of the following: -- **Fixed**: Enter a fixed value. -- **From milestones**: Inherit a dynamic value from the milestones that are assigned to the epic's issues. - Note that GitLab 12.5 replaced this option with **Inherited**. -- **Inherited**: Inherit a dynamic value from the epic's issues, child epics, and milestones ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones**). - -### From milestones - -> [Replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 by **Inherited**. - -If you select **From milestones** for the start date, GitLab automatically sets the date to be earliest -start date across all milestones that are assigned to the issues that belong to the epic. -If you select **From milestones** for the due date, GitLab sets the date to be the latest due date across -all milestones that are assigned to those issues. - -These are dynamic dates which are recalculated if any of the following occur: - -- Milestones are re-assigned to the issues. -- Milestone dates change. -- Issues are added or removed from the epic. +- **Fixed**: enter a fixed value. +- **Inherited**: inherit a dynamic value from the epic's issues, child epics, and milestones. ### Inherited > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones**. -If you select: +If you select **Inherited**: -- **Inherited** for the start date, GitLab will scan all child epics and issues assigned to the epic, - and will set the start date to match the earliest found start date or milestone. -- **Inherited** for the due date, GitLab will set the due date to match the latest due date or +- For the **start date**: GitLab scans all child epics and issues assigned to the epic, + and sets the start date to match the earliest found start date or milestone. +- For the **due date**: GitLab sets the due date to match the latest due date or milestone found among its child epics and issues. These are dynamic dates and recalculated if any of the following occur: @@ -143,7 +126,7 @@ Because the epic's dates can inherit dates from its children, the start date and If the start date of a child epic on the lowest level changes, that becomes the earliest possible start date for its parent epic. The parent epic's start date then reflects this change and propagates upwards to the top epic. -## Roadmap in epics +## Roadmap in epics **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7327) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.10. diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index 5895b611bb3..9cc7a35bc32 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -2,7 +2,7 @@ type: howto 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/#designated-technical-writers +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 --- <!-- When adding a new h2 section here, remember to mention it in index.md#manage-epics --> @@ -14,42 +14,28 @@ to them. ## Create an epic -A paginated list of epics is available in each group from where you can create -a new epic. The list of epics includes also epics from all subgroups of the -selected group. From your group page: +> - 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. -### Create an epic from the epic list +To create an epic in the group you're in: -To create an epic from the epic list, in a group: +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 anywhere, in the top menu, select **New...** (**{plus-square}**) **> New epic**. -1. Go to **{epic}** **Epics**. -1. Select **New epic**. -1. Enter a descriptive title. -1. Select **Create epic**. +  -### Access the New Epic form +1. Fill in these fields: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211533) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. + - Title + - Description + - [Confidentiality checkbox](#make-an-epic-confidential) + - Labels + - Start date + - Due date -There are two ways to get to the New Epic form and create an epic in the group you're in: - -- From an epic in your group, select **New Epic**. -- From anywhere, in the top menu, select **plus** (**{plus-square}**) **> New epic**. - -  - -### Elements of the New Epic form - -When you're creating a new epic, these are the fields you can fill in: - -- Title -- Description -- Confidentiality checkbox -- Labels -- Start date -- Due date - - +1. Select **Create epic**. You are taken to view the newly created epic. ## Edit an epic @@ -79,7 +65,7 @@ You can edit multiple epics at once. To learn how to do it, visit ## Delete an epic -NOTE: **Note:** +NOTE: To delete an epic, you need to be an [Owner](../../permissions.md#group-members-permissions) of a group/subgroup. When editing the description of an epic, select the **Delete** button to delete the epic. @@ -130,7 +116,7 @@ that of Issues and Merge Requests) based on following parameters:  To search, go to the list of epics and select the field **Search or filter results**. -It will display a dropdown menu, from which you can add an author. You can also enter plain +It displays a dropdown menu, from which you can add an author. You can also enter plain text to search by epic title or description. When done, press <kbd>Enter</kbd> on your keyboard to filter the list. @@ -155,7 +141,7 @@ The sort option and order is saved and used wherever you browse epics, including If you're working on items that contain private information, you can make an epic confidential. -NOTE: **Note:** +NOTE: A confidential epic can only contain confidential issues and confidential child epics. To make an epic confidential: @@ -211,7 +197,7 @@ To create an issue from an epic: ### Remove an issue from an epic You can remove issues from an epic when you're on the epic's details page. -After you remove an issue from an epic, the issue will no longer be associated with this epic. +After you remove an issue from an epic, the issue is no longer associated with this epic. To remove an issue from an epic: @@ -253,8 +239,8 @@ To move an issue to another epic: If you have the necessary [permissions](../../permissions.md) to close an issue and create an epic in the immediate parent group, you can promote an issue to an epic with the `/promote` [quick action](../../project/quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). -Only issues from projects that are in groups can be promoted. When attempting to promote a confidential -issue, a warning will display. Promoting a confidential issue to an epic will make all information +Only issues from projects that are in groups can be promoted. When you attempt to promote a confidential +issue, a warning is displayed. Promoting a confidential issue to an epic makes all information related to the issue public as epics are public to group members. When the quick action is executed: @@ -262,7 +248,7 @@ When the quick action is executed: - An epic is created in the same group as the project of the issue. - Subscribers of the issue are notified that the epic was created. -The following issue metadata will be copied to the epic: +The following issue metadata is copied to the epic: - Title, description, activity/comment thread. - Upvotes/downvotes. @@ -277,7 +263,7 @@ You can create a spreadsheet template to manage a pattern of consistently repeat <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an introduction to epic templates, see [GitLab Epics and Epic Template Tip](https://www.youtube.com/watch?v=D74xKFNw8vg). -For more on epic templates, see [Epic Templates - Repeatable sets of issues](https://about.gitlab.com/handbook/marketing/product-marketing/getting-started/104/). +For more on epic templates, see [Epic Templates - Repeatable sets of issues](https://about.gitlab.com/handbook/marketing/strategic-marketing/getting-started/104/). ## Manage multi-level child epics **(ULTIMATE)** diff --git a/doc/user/group/img/add_new_members_v13_6.png b/doc/user/group/img/add_new_members_v13_6.png Binary files differdeleted file mode 100644 index 4255eeb72c7..00000000000 --- a/doc/user/group/img/add_new_members_v13_6.png +++ /dev/null diff --git a/doc/user/group/img/add_new_members_v13_7.png b/doc/user/group/img/add_new_members_v13_7.png Binary files differnew file mode 100644 index 00000000000..7e06bdf8fd1 --- /dev/null +++ b/doc/user/group/img/add_new_members_v13_7.png 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 differnew file mode 100644 index 00000000000..769953b1355 --- /dev/null +++ b/doc/user/group/img/group_code_coverage_analytics_v13_7.png diff --git a/doc/user/group/img/group_members_filter_2fa_disabled_13_7.png b/doc/user/group/img/group_members_filter_2fa_disabled_13_7.png Binary files differnew file mode 100644 index 00000000000..8336103bad1 --- /dev/null +++ b/doc/user/group/img/group_members_filter_2fa_disabled_13_7.png diff --git a/doc/user/group/img/group_members_filter_2fa_enabled_13_7.png b/doc/user/group/img/group_members_filter_2fa_enabled_13_7.png Binary files differnew file mode 100644 index 00000000000..eb27906b583 --- /dev/null +++ b/doc/user/group/img/group_members_filter_2fa_enabled_13_7.png diff --git a/doc/user/group/img/group_members_filter_direct_13_7.png b/doc/user/group/img/group_members_filter_direct_13_7.png Binary files differnew file mode 100644 index 00000000000..c1b2d996e59 --- /dev/null +++ b/doc/user/group/img/group_members_filter_direct_13_7.png diff --git a/doc/user/group/img/group_members_filter_inherited_13_7.png b/doc/user/group/img/group_members_filter_inherited_13_7.png Binary files differnew file mode 100644 index 00000000000..f75990f9da8 --- /dev/null +++ b/doc/user/group/img/group_members_filter_inherited_13_7.png diff --git a/doc/user/group/img/group_members_search_13_7.png b/doc/user/group/img/group_members_search_13_7.png Binary files differnew file mode 100644 index 00000000000..21f36fc75f8 --- /dev/null +++ b/doc/user/group/img/group_members_search_13_7.png diff --git a/doc/user/group/img/group_members_sort_13_7.png b/doc/user/group/img/group_members_sort_13_7.png Binary files differnew file mode 100644 index 00000000000..5d307da649a --- /dev/null +++ b/doc/user/group/img/group_members_sort_13_7.png diff --git a/doc/user/group/img/group_storage_usage_quota.png b/doc/user/group/img/group_storage_usage_quota.png Binary files differdeleted file mode 100644 index c5d81ad7a8b..00000000000 --- a/doc/user/group/img/group_storage_usage_quota.png +++ /dev/null diff --git a/doc/user/group/img/manual_permissions_v13_6.png b/doc/user/group/img/manual_permissions_v13_6.png Binary files differdeleted file mode 100644 index 6d26061b049..00000000000 --- a/doc/user/group/img/manual_permissions_v13_6.png +++ /dev/null diff --git a/doc/user/group/img/manual_permissions_v13_7.png b/doc/user/group/img/manual_permissions_v13_7.png Binary files differnew file mode 100644 index 00000000000..fcea0121915 --- /dev/null +++ b/doc/user/group/img/manual_permissions_v13_7.png diff --git a/doc/user/group/index.md b/doc/user/group/index.md index e09c685147a..a0884461da1 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Access -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Groups @@ -130,7 +130,7 @@ give a user access to all projects in the group with one action. Add members to a group by navigating to the group's dashboard and clicking **Members**. - + Select the [permission level](../permissions.md#permissions), and add the new member. You can also set the expiring date for that user; this is the date on which they will no longer have access to your group. @@ -211,6 +211,88 @@ To remove a member from a group: 1. (Optional) Select the **Also unassign this user from related issues and merge requests** checkbox. 1. Click **Remove member**. +## Filter and sort members in a group + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) in GitLab 12.6. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/228675) in GitLab 13.7. +> - 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-the-ability-to-filter-and-sort-group-members). **(CORE ONLY)** + +The following sections illustrate how you can filter and sort members in a group. To view these options, +navigate to your desired group, go to **Members**, and include the noted search terms. + +### Membership filter + +By default, inherited and direct members are displayed. The [membership](subgroups/index.md#membership) filter can be used to display only inherited or only direct members. + +#### Only display inherited members + +Include `Membership` `=` `Inherited` in the search text box. + + + +#### Only display direct members + +Include `Membership` `=` `Direct` in the search text box. + + + +### 2FA filter + +[Owner](../permissions.md#group-members-permissions) permissions required. + +By default, members with 2FA enabled and disabled are displayed. The 2FA filter can be used to display only members with 2FA enabled or only members with 2FA disabled. + +#### Only display members with 2FA enabled + +Include `2FA` `=` `Enabled` in the search text box. + + + +#### Only display members with 2FA disabled + +Include `2FA` `=` `Disabled` 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. + + + +### Enable or disable improvements to the ability to filter and sort group members **(CORE ONLY)** + +Group member filtering and sorting 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(:group_members_filtered_search) +# For a single group +Feature.disable(:group_members_filtered_search, Group.find(<group id>)) +``` + +To enable them: + +```ruby +# For the instance +Feature.enable(:group_members_filtered_search) +# For a single group +Feature.enable(:group_members_filtered_search, Group.find(<group id>)) +``` + ## Changing the default branch protection of a group > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7583) in GitLab 12.9. @@ -226,7 +308,7 @@ To change this setting for a specific group: To change this setting globally, see [Default branch protection](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection). -NOTE: **Note:** +NOTE: In [GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can choose to [disable group owners from updating the default branch protection](../admin_area/settings/visibility_and_access_controls.md#disable-group-owners-from-updating-default-branch-protection). ## Add projects to a group @@ -342,7 +424,7 @@ Group links can be created using either a CN or a filter. These group links are For more information on the administration of LDAP and group sync, refer to the [main LDAP documentation](../../administration/auth/ldap/index.md#group-sync). -NOTE: **Note:** +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)** @@ -377,7 +459,7 @@ In GitLab [8.15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/822) and 1. Select the pencil icon in the row for the user you are editing. 1. Select the brown `Edit permissions` button in the modal. - + Now you will be able to edit the user's permissions from the **Members** page. @@ -404,7 +486,7 @@ and above. There are a few limitations compared to project wikis: -- Local Git access is not supported yet. +- Git LFS is not supported. - Group wikis are not included in global search, group exports, backups, 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 @@ -482,12 +564,12 @@ To change your group path (group URL): 1. Enter a new name under **Change group URL**. 1. Click **Change group URL**. -CAUTION: **Caution:** +WARNING: It is currently not possible to rename a namespace if it contains a project with [Container Registry](../packages/container_registry/index.md) tags, because the project cannot be moved. -TIP: **Tip:** +NOTE: If you want to retain ownership over the original namespace and protect the URL redirects, then instead of changing a group's path or renaming a username, you can create a new group and transfer projects to it. @@ -716,7 +798,7 @@ To enable delayed deletion of projects: 1. Expand the **Permissions, LFS, 2FA** section, and check **Enable delayed project removal**. 1. Click **Save changes**. -NOTE: **Note:** +NOTE: The group setting for delayed deletion is not inherited by sub-groups and has to be individually defined for each group. #### Prevent project forking outside group **(PREMIUM)** @@ -747,20 +829,6 @@ To enable prevent project forking: - **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. -#### Storage usage quota **(STARTER)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/13294) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.0. - -A group owner can check the aggregated storage usage for all the projects in a group, sub-groups included, in the **Storage** tab of the **Usage Quotas** page available to the group page settings list. - - - -The total usage of the storage is updated if any relevant event that -will affect its value is triggered (e.g., a commit push). -For performance reasons, we may delay the update up to 1 hour and 30 minutes. - -If your namespace shows `N/A` as the total storage usage, you can trigger a recalculation by pushing a commit to any project in that namespace. - #### Group push rules **(STARTER)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34370) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.8. @@ -794,10 +862,21 @@ With [GitLab Issue Analytics](issues_analytics/index.md), you can see a bar char ## Repositories analytics **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. +> - [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: + + + ## Dependency Proxy Use GitLab as a [dependency proxy](../packages/dependency_proxy/index.md) for upstream Docker images. diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index 50dfb0e5ccd..b559e6806e9 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -1,8 +1,8 @@ --- type: reference, howto stage: Manage -group: Value Stream 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/#designated-technical-writers +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 --- # Insights **(ULTIMATE)** @@ -40,7 +40,7 @@ more details about the `.gitlab/insights.yml` configuration file. If you have access to view a group, then you have access to view their Insights. -NOTE: **Note:** +NOTE: Issues or merge requests that you don't have access to (because you don't have access to the project they belong to, or because they are confidential) are filtered out of the Insights charts. diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index dea1eaba819..269be19f759 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -1,20 +1,19 @@ --- type: reference stage: Manage -group: Value Stream 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/#designated-technical-writers +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 --- # Issue Analytics **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7478) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9 at the project level. 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 prior. -To access the chart, navigate to your group or project sidebar and select **{chart}** **Analytics > Issue Analytics**. +To access the chart, navigate to your group sidebar and select **{chart}** **Analytics > Issue Analytics**. Hover over each bar to see the total number of issues. diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 90050e217ee..a06c7a8f325 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -2,7 +2,7 @@ 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/#designated-technical-writers +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)** @@ -38,7 +38,7 @@ From there you can create a new iteration or click an iteration to get a more de ## Create an iteration -NOTE: **Note:** +NOTE: You need Developer [permissions](../../permissions.md) or higher to create an iteration. To create an iteration: @@ -52,7 +52,7 @@ To create an iteration: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218277) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2. -NOTE: **Note:** +NOTE: You need Developer [permissions](../../permissions.md) or higher to edit an iteration. To edit an iteration, click the three-dot menu (**{ellipsis_v}**) > **Edit iteration**. @@ -71,17 +71,16 @@ To learn how to add an issue to an iteration, see the steps in 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. +The report also shows a breakdown of total issues in an iteration. +Open iteration reports show a summary of completed, unstarted, and in-progress issues. +Closed iteration reports show the total number of issues completed by the due date. + To view an iteration report, go to the iterations list page and click an iteration's title. ### Iteration burndown and burnup charts > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222750) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. -> - It was deployed behind a feature flag, disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45492) on GitLab 13.6. -> - 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-iteration-charts). **(STARTER ONLY)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/269972) in [GitLab Starter](https://about.gitlab.com/pricing/) 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). @@ -113,30 +112,6 @@ Feature.disable(:group_iterations) Feature.disable(:group_iterations, Group.find(<group ID>)) ``` -## Disable iteration charts **(STARTER ONLY)** - -GitLab iteration charts 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) -can disable it for your instance. `:iteration_charts` can be enabled or disabled per-group. - -To enable it: - -```ruby -# Instance-wide -Feature.enable(:iteration_charts) -# or by group -Feature.enable(:iteration_charts, Group.find(<group ID>)) -``` - -To disable it: - -```ruby -# Instance-wide -Feature.disable(:iteration_charts) -# or by group -Feature.disable(:iteration_charts, Group.find(<group ID>)) -``` - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index fe5e7979592..fc4fb0236de 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -2,14 +2,14 @@ type: reference stage: Verify group: Testing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Repositories Analytics **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. ## Latest project test coverage list @@ -25,7 +25,9 @@ To see the latest code coverage for each project in your group: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. -You can get a CSV of the code coverage data for all of the projects in your group. This report has a maximum of 1000 records. To get the report: +You can get a CSV of the code coverage data for all of the projects in your group. This report has a maximum of 1000 records. The code coverage data is from the default branch in each project. + +To get the report: 1. Go to your group's **Analytics > Repositories** page 1. Click **Download historic test coverage data (.csv)**, @@ -44,6 +46,9 @@ For each day that a coverage report was generated by a job in a project's pipeli If the project's code coverage was calculated more than once in a day, we will take the last value from that day. +NOTE: +[In GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/270102), group code coverage data is taken from the configured [default branch](../../project/repository/branches/index.md#default-branch). In earlier versions, it is taken from the `master` branch. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index f9d49c1236e..32abc676352 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -2,7 +2,7 @@ type: reference 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/#designated-technical-writers +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 --- # Roadmap **(PREMIUM)** diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md index 50f062bafa9..15dd91bece2 100644 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ b/doc/user/group/saml_sso/group_managed_accounts.md @@ -2,12 +2,12 @@ type: reference, howto stage: Manage group: Access -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 Managed Accounts **(PREMIUM)** -CAUTION: **Caution:** +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 diff --git a/doc/user/group/saml_sso/img/saml_group_links_nav_v13_6.png b/doc/user/group/saml_sso/img/saml_group_links_nav_v13_6.png Binary files differnew file mode 100644 index 00000000000..c1980b24a6d --- /dev/null +++ b/doc/user/group/saml_sso/img/saml_group_links_nav_v13_6.png diff --git a/doc/user/group/saml_sso/img/saml_group_links_v13_6.png b/doc/user/group/saml_sso/img/saml_group_links_v13_6.png Binary files differnew file mode 100644 index 00000000000..c78b77b8fcf --- /dev/null +++ b/doc/user/group/saml_sso/img/saml_group_links_v13_6.png diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 94d2c9afb24..62431747911 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Access -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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)** @@ -38,13 +38,15 @@ GitLab.com uses the SAML NameID to identify users. The NameID element: - Must be unique to each user. - Must be a persistent value that will never change, such as a randomly generated unique user ID. - Is case sensitive. The NameID must match exactly on subsequent login attempts, so should not rely on user input that could change between upper and lower case. -- Should not be an email address or username. We strongly recommend against these as it is hard to guarantee they will never change, for example when a person's name changes. Email addresses are also case-insensitive, which can result in users being unable to sign in. +- Should not be an email address or username. We strongly recommend against these as it's hard to + guarantee it doesn't ever change, for example, when a person's name changes. Email addresses are + also case-insensitive, which can result in users being unable to sign in. The relevant field name and recommended value for supported providers are in the [provider specific notes](#providers). appropriate corresponding field. -CAUTION: **Warning:** -Once users have signed into GitLab using the SSO SAML setup, changing the `NameID` will break the configuration and potentially lock users out of the GitLab group. +WARNING: +Once users have signed into GitLab using the SSO SAML setup, changing the `NameID` breaks the configuration and potentially locks users out of the GitLab group. #### NameID Format @@ -56,11 +58,11 @@ GitLab provides metadata XML that can be used to configure your Identity Provide 1. Navigate to the group and click **Settings > SAML SSO**. 1. Copy the provided **GitLab metadata URL**. -1. Follow your Identity Provider's documentation and paste the metadata URL when it is requested. +1. Follow your Identity Provider's documentation and paste the metadata URL when it's requested. ## Configuring GitLab -Once you've set up your identity provider to work with GitLab, you'll need to configure GitLab to use it for authentication: +After you set up your identity provider to work with GitLab, you must configure GitLab to use it for authentication: 1. Navigate to the group's **Settings > SAML SSO**. 1. Find the SSO URL from your Identity Provider and enter it the **Identity provider single sign-on URL** field. @@ -71,7 +73,7 @@ Once you've set up your identity provider to work with GitLab, you'll need to co  -NOTE: **Note:** +NOTE: Please note that the certificate [fingerprint algorithm](#additional-providers-and-setup-options) must be in SHA1. When configuring the identity provider, use a secure signature algorithm. ### SSO enforcement @@ -79,18 +81,18 @@ Please note that the certificate [fingerprint algorithm](#additional-providers-a - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5291) in GitLab 11.8. - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9255) in GitLab 11.11 with ongoing enforcement in the GitLab UI. -With this option enabled, users must go through your group's GitLab single sign-on URL. They may also be added via SCIM, if configured. Users cannot be added manually, and may only access project/group resources via the UI by signing in through the SSO URL. +With this option enabled, users must go through your group's GitLab single sign-on URL. They may also be added via SCIM, if configured. Users can't be added manually, and may only access project/group resources via the UI by signing in through the SSO URL. -However, users will not be prompted to sign in through SSO on each visit. GitLab will check whether a user has authenticated through SSO, and will only prompt the user to sign in via SSO if the session has expired. +However, users are not prompted to sign in through SSO on each visit. GitLab checks whether a user has authenticated through SSO, and only prompts the user to sign in via SSO if the session has expired. You can see more information about how long a session is valid in our [user profile documentation](../../profile/#why-do-i-keep-getting-signed-out). We intend to add a similar SSO requirement for [Git and API activity](https://gitlab.com/gitlab-org/gitlab/-/issues/9152). -When SSO enforcement is enabled for a group, users cannot share a project in the group outside the top-level group, even if the project is forked. +When SSO enforcement is enabled for a group, users can't share a project in the group outside the top-level group, even if the project is forked. ## Providers -NOTE: **Note:** +NOTE: GitLab is unable to provide support for IdPs that are not listed here. | Provider | Documentation | @@ -190,31 +192,77 @@ If the information you need isn't listed above you may wish to check our [troubl ## User access and management +> [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/268142) in GitLab 13.7. + Once Group SSO is configured and enabled, users can access the GitLab.com group through the identity provider's dashboard. If [SCIM](scim_setup.md) is configured, please see the [user access and linking setup section on the SCIM page](scim_setup.md#user-access-and-linking-setup). -When a user tries to sign in with Group SSO, they will need an account that's configured with one of the following: +When a user tries to sign in with Group SSO, GitLab attempts to find or create a user based on the following: -- [SCIM](scim_setup.md). -- [Group-managed accounts](group_managed_accounts.md). -- A GitLab.com account. +- Find an existing user with a matching SAML identity. This would mean the user either had their account created by [SCIM](scim_setup.md) or they have previously signed in with the group's SAML IdP. +- If there is no conflicting user with the same email address, create a new account automatically. +- If there is a conflicting user with the same email address, redirect the user to the sign-in page to: + - Create a new account with another email address. + - Sign-in to their existing account to link the SAML identity. ### Linking SAML to your existing GitLab.com account 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 are signing in to. A group Admin 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. Locate and visit the **GitLab single sign-on URL** for the group you're signing in to. A group Admin 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. Enter your credentials on the Identity Provider if prompted. -1. You will be 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. +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. -On subsequent visits, you should be able to go [sign in to GitLab.com with SAML](#signing-in-to-gitlabcom-with-saml) or by visiting links directly. If the **enforce SSO** option is turned on, you will be redirected to sign in through the identity provider. +On subsequent visits, you should be able to go [sign in to GitLab.com with SAML](#signing-in-to-gitlabcom-with-saml) or by visiting links directly. If the **enforce SSO** option is turned on, you are then redirected to sign in through the identity provider. ### 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. You will be signed in to GitLab.com and redirected to the group. +1. You are then signed in to GitLab.com and redirected to the group. + +### Configure user settings from SAML response + +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263661) in GitLab 13.7. + +GitLab allows setting certain user attributes based on values from the SAML response. +This affects users created on first sign-in via Group SAML. Existing users' +attributes are not affected regardless of the values sent in the SAML response. + +#### Supported user attributes + +- `can_create_group` - 'true' or 'false' to indicate whether the user can create + new groups. Default is `true`. +- `projects_limit` - The total number of personal projects a user can create. + A value of `0` means the user cannot create new projects in their personal + namespace. Default is `10000`. + +#### Example SAML response + +You can find SAML responses in the developer tools or console of your browser, +in base64-encoded format. Use the base64 decoding tool of your choice to +convert the information to XML. An example SAML response is shown here. + +```xml + <saml2:AttributeStatement> + <saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.email</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.firstName</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.lastName</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="can_create_group" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">true</saml2:AttributeValue> + </saml2:Attribute> + <saml2:Attribute Name="projects_limit" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> + <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">10</saml2:AttributeValue> + </saml2:Attribute> + </saml2:AttributeStatement> +``` ### Role @@ -238,10 +286,53 @@ Users can unlink SAML for a group from their profile page. This can be helpful i - You no longer want a group to be able to sign you in to GitLab.com. - Your SAML NameID has changed and so GitLab can no longer find your user. -For example, to unlink the `MyOrg` account, the following **Disconnect** button will be available under **Profile > Accounts**: +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. + +For example, to unlink the `MyOrg` account, the following **Disconnect** button is available under **Profile > Accounts**:  +## Group Sync + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a demo of Group Sync using Azure, see [Demo: SAML Group Sync](https://youtu.be/Iqvo2tJfXjg). + +When the SAML response includes a user and their group memberships from the SAML identity provider, +GitLab uses that information to automatically manage that user's GitLab group memberships. + +Ensure your SAML identity provider sends an attribute statement named `Groups` or `groups` like the following: + +```xml +<saml:AttributeStatement> + <saml:Attribute Name="Groups"> + <saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue> + <saml:AttributeValue xsi:type="xs:string">Product Managers</saml:AttributeValue> + </saml:Attribute> +</saml:AttributeStatement> +``` + +When SAML SSO is enabled for the top-level group, `Maintainer` and `Owner` level users +see a new menu item in group **Settings -> SAML Group Links**. Each group (parent or subgroup) can specify +one or more group links to map a SAML identity provider group name to a GitLab access level. + + + +To link the SAML `Freelancers` group in the attribute statement example above: + +1. Enter `Freelancers` in the `SAML Group Name` field. +1. Choose the desired `Access Level`. +1. **Save** the group link. +1. Repeat to add additional group links if desired. + + + +If a user is a member of multiple SAML groups mapped to the same GitLab group, +the user gets the highest access level from the groups. For example, if one group +is linked as `Guest` and another `Maintainer`, a user in both groups gets `Maintainer` +access. + ## Glossary | Term | Description | @@ -250,7 +341,7 @@ For example, to unlink the `MyOrg` account, the following **Disconnect** button | 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. | | SSO | Single Sign On. | -| Assertion consumer service URL | The callback on GitLab where users will be redirected after successfully authenticating with the identity provider. | +| 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". | | Certificate fingerprint | Used to confirm that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. | diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 7c089a289c6..40c036e1fc0 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -2,7 +2,7 @@ type: howto, reference stage: Manage group: Access -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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)** @@ -13,7 +13,7 @@ System for Cross-domain Identity Management (SCIM), is an open standard that ena automation of user provisioning. When SCIM is provisioned for a GitLab group, membership of that group is synchronized between GitLab and the identity provider. -GitLab's [SCIM API](../../../api/scim.md) implements part of [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644). +The GitLab [SCIM API](../../../api/scim.md) implements part of [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644). ## Features @@ -92,14 +92,14 @@ You can then test the connection by clicking on **Test Connection**. If the conn 1. Save your changes. For reference, you can view [an example configuration in the troubleshooting reference](../../../administration/troubleshooting/group_saml_scim.md#azure-active-directory). - NOTE: **Note:** + NOTE: If you used a unique identifier **other than** `objectId`, be sure to map it to `externalId`. 1. Below the mapping list click on **Show advanced options > Edit attribute list for AppName**. 1. Ensure the `id` is the primary and required field, and `externalId` is also required. - NOTE: **Note:** + NOTE: `username` should neither be primary nor required as we don't support that field on GitLab SCIM yet. @@ -108,15 +108,15 @@ You can then test the connection by clicking on **Test Connection**. If the conn  - NOTE: **Note:** + NOTE: You can control what is actually synced by selecting the `Scope`. For example, `Sync only assigned users and groups` only syncs the users assigned to the application (`Users and groups`), otherwise, it syncs the whole Active Directory. Once enabled, the synchronization details and any errors appears on the -bottom of the **Provisioning** screen, together with a link to the audit logs. +bottom of the **Provisioning** screen, together with a link to the audit events. -CAUTION: **Warning:** +WARNING: Once synchronized, changing the field mapped to `id` and `externalId` may cause a number of errors. These include provisioning errors, duplicate users, and may prevent existing users from accessing the GitLab group. ### Okta configuration steps @@ -132,7 +132,7 @@ configuration. Otherwise, the Okta SCIM app may not work properly. 1. If you see an **Admin** button in the top right, click the button. This will ensure you are in the Admin area. - TIP: **Tip:** + NOTE: If you're using the Developer Console, click **Developer Console** in the top bar and select **Classic UI**. Otherwise, you may not see the buttons described in the following steps: @@ -194,7 +194,7 @@ provider or users list for the specific app. Upon the next sync, the user is deprovisioned, which means that the user is removed from the group. -NOTE: **Note:** +NOTE: Deprovisioning does not delete the user account. ```mermaid @@ -240,7 +240,7 @@ To see how the `external_uid` compares to the value returned as the SAML NameId, Whether the value was changed or you need to map to a different field, ensure `id`, `externalId`, and `NameId` all map to the same field. -If GitLab's `externalId` doesn't match the SAML NameId, it will need to be updated in order for the user to log in. Ideally your identity provider will be configured to do such an update, but in some cases it may be unable to do so, such as when looking up a user fails due to an ID change. +If the GitLab `externalId` doesn't match the SAML NameId, it needs to be updated in order for the user to sign in. Ideally your identity provider is configured to do such an update, but in some cases it may be unable to do so, such as when looking up a user fails due to an ID change. Be cautious if you revise the fields used by your SCIM identity provider, typically `id` and `externalId`. We use these IDs to look up users. If the identity provider does not know the current values for these fields, @@ -262,6 +262,15 @@ Individual users can follow the instructions in the ["SAML authentication failed 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). +### The SCIM app is throwing `"User has already been taken","status":409` error message + +Changing the SAML or SCIM configuration or provider can cause the following problems: + +| Problem | Solution | +|------------------------------------------------------------------------------|--------------------| +| SAML and SCIM identity mismatch. | First [verify that the user's SAML NameId matches the SCIM externalId](#how-do-i-verify-users-saml-nameid-matches-the-scim-externalid) and then [update or fix the mismatched SCIM externalId and SAML NameId](#update-or-fix-mismatched-scim-externalid-and-saml-nameid). | +| SCIM identity mismatch between GitLab and the Identify Provider SCIM app. | You can confirm whether you're hitting the error because of your SCIM identity mismatch between your SCIM app and GitLab.com by using [SCIM API](../../../api/scim.md#update-a-single-saml-user) which shows up in the `id` key and compares it with the user `externalId` in the SCIM app. You can use the same [SCIM API](../../../api/scim.md#update-a-single-saml-user) to update the SCIM `id` for the user on GitLab.com. | + ### Azure #### How do I verify my SCIM configuration is correct? @@ -283,7 +292,7 @@ When testing the connection, you may encounter an error: **You appear to have en #### (Field) can't be blank sync error -When checking the Audit Logs for the Provisioning, you can sometimes see the +When checking the Audit Events for the Provisioning, you can sometimes see the error `Namespace can't be blank, Name can't be blank, and User can't be blank.` This is likely caused because not all required fields (such as first name and last name) are present for all users being mapped. diff --git a/doc/user/group/security_dashboard/index.md b/doc/user/group/security_dashboard/index.md index c59198df081..3feccf2e342 100644 --- a/doc/user/group/security_dashboard/index.md +++ b/doc/user/group/security_dashboard/index.md @@ -3,3 +3,6 @@ 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 77cb862a49d..2aee8706194 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Group Import/Export @@ -55,7 +55,7 @@ The following items are **not** exported: - Runner tokens - SAML discovery tokens -NOTE: **Note:** +NOTE: For more details on the specific data persisted in a group export, see the [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/import_export/group/import_export.yml) file. @@ -75,7 +75,7 @@ For more details on the specific data persisted in a group export, see the 1. Alternatively, you can come back to the project settings and download the file from there by clicking **Download export**, or generate a new file by clicking **Regenerate export**. -NOTE: **Note:** +NOTE: The maximum import file size can be set by the Administrator, default is 50MB. 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). @@ -121,10 +121,12 @@ For example: ## Rate Limits -To help avoid abuse, users are rate limited to: +To help avoid abuse, by default, users are rate limited to: | Request Type | Limit | | ---------------- | ---------------------------------------- | -| Export | 30 groups every 5 minutes | -| Download export | 10 downloads per group every 10 minutes | -| Import | 30 groups every 5 minutes | +| Export | 6 groups per minute | +| Download export | 1 download per group per minute | +| Import | 6 groups per minute | + +Please note that GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) from the defaults. diff --git a/doc/user/group/subgroups/img/group_members.png b/doc/user/group/subgroups/img/group_members.png Binary files differdeleted file mode 100644 index 830ccafa794..00000000000 --- a/doc/user/group/subgroups/img/group_members.png +++ /dev/null diff --git a/doc/user/group/subgroups/img/group_members_13_7.png b/doc/user/group/subgroups/img/group_members_13_7.png Binary files differnew file mode 100644 index 00000000000..ab22bcb932c --- /dev/null +++ b/doc/user/group/subgroups/img/group_members_13_7.png diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 268014a3cd2..8af075fc0c0 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto, concepts --- @@ -109,16 +109,16 @@ To create a subgroup:  -1. Click the **Create group** button and you will be taken to the new group's +1. Click the **Create group** button to be redirected to the new group's dashboard page. Follow the same process to create any subsequent groups. ## Membership -When you add a member to a subgroup, they inherit the membership and permission -level from the parent group(s). This model allows access to nested groups if you -have membership in one of its parents. +When you add a member to a group, that member is also added to all subgroups. +Permission level is inherited from the group’s parent. This model allows access to +subgroups if you have membership in one of its parents. Jobs for pipelines in subgroups can use [runners](../../../ci/runners/README.md) registered to the parent group(s). This means secrets configured for the parent group are available to subgroup jobs. @@ -131,49 +131,41 @@ the **Members** page of the group the member was added. You can tell if a member has inherited the permissions from a parent group by looking at the group's **Members** page. - + From the image above, we can deduce the following things: - There are 5 members that have access to the group `four`. -- User0 is a Reporter and has inherited their permissions from group `one` +- User 0 is a Reporter and has inherited their permissions from group `one` which is above the hierarchy of group `four`. -- User1 is a Developer and has inherited their permissions from group +- User 1 is a Developer and has inherited their permissions from group `one/two` which is above the hierarchy of group `four`. -- User2 is a Developer and has inherited their permissions from group +- User 2 is a Developer and has inherited their permissions from group `one/two/three` which is above the hierarchy of group `four`. -- For User3 there is no indication of a parent group, therefore they belong to +- For User 3 the **Source** column indicates **Direct member**, therefore they belong to group `four`, the one we're inspecting. - Administrator is the Owner and member of **all** subgroups and for that reason, - as with User3, there is no indication of an ancestor group. + as with User 3, the **Source** column indicates **Direct member**. -[From](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) GitLab 12.6, you can filter -this list using dropdown on the right side: - - - -- **Show only direct members** displays only Administrator and User3, since these are - the only users that belong to group `four`, which is the one we're inspecting. -- **Show only inherited members** displays User0, User1 and User2, no matter which group - above the hierarchy is the source of inherited permissions. +Members can be [filtered by inherited or direct membership](../index.md#membership-filter). ### Overriding the ancestor group membership -NOTE: **Note:** +NOTE: You must be an Owner of a group to be able to add members to it. -NOTE: **Note:** +NOTE: A user's permissions in a subgroup cannot be lower than in any of its ancestor groups. Therefore, you cannot reduce a user's permissions in a subgroup with respect to its ancestor groups. To override a user's membership of an ancestor group (the first group they were added to), add the user to the new subgroup again with a higher set of permissions. -For example, if User0 was first added to group `group-1/group-1-1` with Developer -permissions, then they will inherit those permissions in every other subgroup -of `group-1/group-1-1`. To give them Maintainer access to `group-1/group-1-1/group1-1-1`, +For example, if User 1 was first added to group `one/two` with Developer +permissions, then they inherit those permissions in every other subgroup +of `one/two`. To give them Maintainer access to group `one/two/three/four`, you would add them again in that group as Maintainer. Removing them from that group, -the permissions will fallback to those of the ancestor group. +the permissions fall back to those of the ancestor group. ## Mentioning subgroups diff --git a/doc/user/analytics/img/delete_value_stream_v13.4.png b/doc/user/group/value_stream_analytics/img/delete_value_stream_v13.4.png Binary files differindex c97fcb76343..c97fcb76343 100644 --- a/doc/user/analytics/img/delete_value_stream_v13.4.png +++ b/doc/user/group/value_stream_analytics/img/delete_value_stream_v13.4.png diff --git a/doc/user/analytics/img/label_based_stage_vsm_v12_9.png b/doc/user/group/value_stream_analytics/img/label_based_stage_vsm_v12_9.png Binary files differindex 84ce33aece5..84ce33aece5 100644 --- a/doc/user/analytics/img/label_based_stage_vsm_v12_9.png +++ b/doc/user/group/value_stream_analytics/img/label_based_stage_vsm_v12_9.png diff --git a/doc/user/analytics/img/new_value_stream_v13_3.png b/doc/user/group/value_stream_analytics/img/new_value_stream_v13_3.png Binary files differindex bc8502e85a6..bc8502e85a6 100644 --- a/doc/user/analytics/img/new_value_stream_v13_3.png +++ b/doc/user/group/value_stream_analytics/img/new_value_stream_v13_3.png diff --git a/doc/user/analytics/img/new_vsm_stage_v12_9.png b/doc/user/group/value_stream_analytics/img/new_vsm_stage_v12_9.png Binary files differindex dbef25d33ed..dbef25d33ed 100644 --- a/doc/user/analytics/img/new_vsm_stage_v12_9.png +++ b/doc/user/group/value_stream_analytics/img/new_vsm_stage_v12_9.png diff --git a/doc/user/analytics/img/vsa_filter_bar_v13.3.png b/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13.3.png Binary files differindex 506765f63cb..506765f63cb 100644 --- a/doc/user/analytics/img/vsa_filter_bar_v13.3.png +++ b/doc/user/group/value_stream_analytics/img/vsa_filter_bar_v13.3.png diff --git a/doc/user/analytics/img/vsa_time_metrics_v13_0.png b/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_0.png Binary files differindex 799a81584a0..799a81584a0 100644 --- a/doc/user/analytics/img/vsa_time_metrics_v13_0.png +++ b/doc/user/group/value_stream_analytics/img/vsa_time_metrics_v13_0.png diff --git a/doc/user/analytics/img/vsm_stage_list_v12_9.png b/doc/user/group/value_stream_analytics/img/vsm_stage_list_v12_9.png Binary files differindex 3b50dd48543..3b50dd48543 100644 --- a/doc/user/analytics/img/vsm_stage_list_v12_9.png +++ b/doc/user/group/value_stream_analytics/img/vsm_stage_list_v12_9.png diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md new file mode 100644 index 00000000000..0f9afdef995 --- /dev/null +++ b/doc/user/group/value_stream_analytics/index.md @@ -0,0 +1,375 @@ +--- +type: reference +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/#designated-technical-writers +--- + +# Value Stream Analytics **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196455) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9 at the group level. + +Value Stream Analytics measures the time spent to go from an +[idea to production](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) +(also known as cycle time) for each of your projects or groups. Value Stream Analytics displays the median time +spent in each stage defined in the process. + +Value Stream Analytics can help you quickly determine the velocity of a given +group. It points to bottlenecks in the development process, enabling management +to uncover, triage, and identify the root cause of slowdowns in the software development life cycle. + +For information on how to contribute to the development of Value Stream Analytics, see our [contributor documentation](../../../development/value_stream_analytics.md). + +Group-level Value Stream Analytics is available via **Group > Analytics > Value Stream**. + +[Project-level Value Stream Analytics](../../analytics/value_stream_analytics.md) is also available. + +## Default stages + +The stages tracked by Value Stream Analytics by default represent the [GitLab flow](../../../topics/gitlab_flow.md). These stages can be customized in Group Level Value Stream Analytics. + +- **Issue** (Tracker) + - Time to schedule an issue (by milestone or by adding it to an issue board) +- **Plan** (Board) + - Time to first commit +- **Code** (IDE) + - Time to create a merge request +- **Test** (CI) + - Time it takes GitLab CI/CD to test your code +- **Review** (Merge Request/MR) + - Time spent on code review +- **Staging** (Continuous Deployment) + - Time between merging and deploying to production + +## Filter the analytics data + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 13.3 + +GitLab provides the ability to filter analytics based on the following parameters: + +- Milestones (Group level) +- Labels (Group level) +- Author +- Assignees + +To filter results: + +1. Select a group. +1. Click on the filter bar. +1. Select a parameter to filter by. +1. Select a value from the autocompleted results, or type to refine the results. + + + +### Date ranges + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 12.4. + +GitLab provides the ability to filter analytics based on a date range. To filter results: + +1. Select a group. +1. Optionally select a project. +1. Select a date range using the available date pickers. + +## How Time metrics are measured + +The "Time" metrics near the top of the page are measured as follows: + +- **Lead time**: median time from issue created to issue closed. +- **Cycle time**: median time from first commit to issue closed. + +A commit is associated with an issue by [crosslinking](../../project/issues/crosslinking_issues.md) in the commit message or by manually linking the merge request containing the commit. + + + +## How the stages are measured + +Value Stream Analytics records stage time and data based on the project issues with the +exception of the staging stage, where only data deployed to +production are measured. + +Specifically, if your CI is not set up and you have not defined a [production environment](#how-the-production-environment-is-identified), then you will not have any +data for this stage. + +Each stage of Value Stream Analytics is further described in the table below. + +| **Stage** | **Description** | +| --------- | --------------- | +| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whatever comes first. The label will be tracked only if it already has an [Issue Board list](../../project/issue_board.md) created for it. | +| Plan | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. The very first commit of the branch is the one that triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch needs to contain the related issue number (e.g., `#42`). If none of the commits in the branch mention the related issue number, it is not considered to the measurement time of the stage. | +| Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR) related to that commit. The key to keep the process tracked is to include the [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically) to the description of the merge request (for example, `Closes #xxx`, where `xxx` is the number of the issue related to this merge request). If the closing pattern is not present, then the calculation takes the creation time of the first commit in the merge request as the start time. | +| Test | Measures the median time to run the entire pipeline for that project. It's related to the time GitLab CI/CD takes to run every job for the commits pushed to that merge request defined in the previous stage. It is basically the start->finish time for all pipelines. | +| Review | Measures the median time taken to review the merge request that has a closing issue pattern, between its creation and until it's merged. | +| Staging | Measures the median time between merging the merge request with a closing issue pattern until the very first deployment to a [production environment](#how-the-production-environment-is-identified). If there isn't a production environment, this is not tracked. | + +How this works, behind the scenes: + +1. Issues and merge requests are grouped together in pairs, such that for each + `<issue, merge request>` pair, the merge request has the [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically) + for the corresponding issue. All other issues and merge requests are **not** + considered. +1. Then the `<issue, merge request>` pairs are filtered out by last XX days (specified + by the UI - default is 90 days). So it prohibits these pairs from being considered. +1. For the remaining `<issue, merge request>` pairs, we check the information that + we need for the stages, like issue creation date, merge request merge time, + etc. + +To sum up, anything that doesn't follow [GitLab flow](../../../topics/gitlab_flow.md) will not be tracked and the +Value Stream Analytics dashboard will not present any data for: + +- Merge requests that do not close an issue. +- Issues not labeled with a label present in the Issue Board or for issues not assigned a milestone. +- Staging stage, if the project has no [production environment](#how-the-production-environment-is-identified). + +## How the production environment is identified + +Value Stream Analytics identifies production environments by looking for project [environments](../../../ci/yaml/README.md#environment) with a name matching any of these patterns: + +- `prod` or `prod/*` +- `production` or `production/*` + +These patterns are not case-sensitive. + +You can change the name of a project environment in your GitLab CI/CD configuration. + +## Example workflow + +Below is a simple fictional workflow of a single cycle that happens in a +single day through all noted stages. Note that if a stage does not include a start +and a stop time, its data is not included in the median time. It is assumed that +milestones are created and a CI for testing and setting environments is configured. +a start and a stop mark, it is not measured and hence not calculated in the median +time. It is assumed that milestones are created and CI for testing and setting +environments is configured. + +1. Issue is created at 09:00 (start of **Issue** stage). +1. Issue is added to a milestone at 11:00 (stop of **Issue** stage / start of + **Plan** stage). +1. Start working on the issue, create a branch locally and make one commit at + 12:00. +1. Make a second commit to the branch which mentions the issue number at 12.30 + (stop of **Plan** stage / start of **Code** stage). +1. Push branch and create a merge request that contains the [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically) + in its description at 14:00 (stop of **Code** stage / start of **Test** and + **Review** stages). +1. The CI starts running your scripts defined in [`.gitlab-ci.yml`](../../../ci/yaml/README.md) and + takes 5min (stop of **Test** stage). +1. Review merge request, ensure that everything is OK and merge the merge + request at 19:00. (stop of **Review** stage / start of **Staging** stage). +1. Now that the merge request is merged, a deployment to the `production` + environment starts and finishes at 19:30 (stop of **Staging** stage). + +From the above example you can conclude the time it took each stage to complete +as long as their total time: + +- **Issue**: 2h (11:00 - 09:00) +- **Plan**: 1h (12:00 - 11:00) +- **Code**: 2h (14:00 - 12:00) +- **Test**: 5min +- **Review**: 5h (19:00 - 14:00) +- **Staging**: 30min (19:30 - 19:00) + +A few notes: + +- In the above example we demonstrated that it doesn't matter if your first + commit doesn't mention the issue number, you can do this later in any commit + of the branch you are working on. +- You can see that the **Test** stage is not calculated to the overall time of + the cycle since it is included in the **Review** process (every MR should be + tested). +- The example above was just **one cycle** of the seven stages. Add multiple + cycles, calculate their median time and the result is what the dashboard of + Value Stream Analytics is showing. + +## Customizable Stages + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12196) in GitLab 12.9. + +The default stages are designed to work straight out of the box, but they might not be suitable for +all teams. Different teams use different approaches to building software, so some teams might want +to customize their Value Stream Analytics. + +GitLab allows users to create multiple value streams, hide default stages and create custom stages that align better to their development workflow. + +### Stage path + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210315) in GitLab 13.0. + +Stages are visually depicted as a horizontal process flow. Selecting a stage will update the +the content below the value stream. + +This is disabled by default. If you have a self-managed instance, an +administrator can [open a Rails console](../../../administration/troubleshooting/navigating_gitlab_via_rails_console.md) +and enable it with the following command: + +```ruby +Feature.enable(:value_stream_analytics_path_navigation) +``` + +### Adding a stage + +In the following example we're creating a new stage that measures and tracks issues from creation +time until they are closed. + +1. Navigate to your group's **Analytics > Value Stream**. +1. Click the **Add a stage** button. +1. Fill in the new stage form: + - Name: Issue start to finish. + - Start event: Issue created. + - End event: Issue closed. +1. Click the **Add stage** button. + + + +The new stage is persisted and it will always show up on the Value Stream Analytics page for your +group. + +If you want to alter or delete the stage, you can easily do that for customized stages by: + +1. Hovering over the stage. +1. Clicking the vertical ellipsis (**{ellipsis_v}**) button that appears. + + + +Creating a custom stage requires specifying two events: + +- A start. +- An end. + +Be careful to choose a start event that occurs *before* your end event. For example, consider a +stage that: + +- Started when an issue is added to a board. +- Ended when the issue is created. + +This stage would not work because the end event has already happened when the start event occurs. +To prevent such invalid stages, the UI prohibits incompatible start and end events. After you select +the start event, the stop event dropdown will only list the compatible events. + +### Re-ordering stages + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196698) in GitLab 12.10. + +Once a custom stage has been added, you can "drag and drop" stages to rearrange their order. These changes are automatically saved to the system. + +### Label based stages + +The pre-defined start and end events can cover many use cases involving both issues and merge requests. + +For supporting more complex workflows, use stages based on group labels. These events are based on +labels being added or removed. In particular, [scoped labels](../../project/labels.md#scoped-labels) +are useful for complex workflows. + +In this example, we'd like to measure more accurate code review times. The workflow is the following: + +- When the code review starts, the reviewer adds `workflow::code_review_start` label to the merge request. +- When the code review is finished, the reviewer adds `workflow::code_review_complete` label to the merge request. + +Creating a new stage called "Code Review": + + + +### Hiding unused stages + +Sometimes certain default stages are not relevant to a team. In this case, you can easily hide stages +so they no longer appear in the list. To hide stages: + +1. Add a custom stage to activate customizability. +1. Hover over the default stage you want to hide. +1. Click the vertical ellipsis (**{ellipsis_v}**) button that appears and select **Hide stage**. + +To recover a default stage that was previously hidden: + +1. Click **Add a stage** button. +1. In the top right corner open the **Recover hidden stage** dropdown. +1. Select a stage. + +### Creating a value stream + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221202) in GitLab 13.3 + +A default value stream is readily available for each group. You can create additional value streams based on the different areas of work that you would like to measure. + +Once created, a new value stream includes the [seven stages](#default-stages) that follow +[GitLab workflow](../../../topics/gitlab_flow.md) +best practices. You can customize this flow by adding, hiding or re-ordering stages. + +To create a value stream: + +1. Navigate to your group's **Analytics > Value Stream**. +1. Click the Value stream dropdown and select **Create new Value Stream** +1. Fill in a name for the new Value Stream +1. Click the **Create Value Stream** button. + + + +### Deleting a value stream + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221205) in GitLab 13.4. + +To delete a custom value stream: + +1. Navigate to your group's **Analytics > Value Stream**. +1. Click the Value stream dropdown and select the value stream you would like to delete. +1. Click the **Delete (name of value stream)**. +1. Click the **Delete** button to confirm. + + + +### Disabling custom value streams + +Custom value streams are enabled by default. If you have a self-managed instance, an +administrator can open a Rails console and disable them with the following command: + +```ruby +Feature.disable(:value_stream_analytics_create_multiple_value_streams) +``` + +## Days to completion chart + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21631) in GitLab 12.6. +> - [Chart median line removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235455) in GitLab 13.4. + +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 +from within the chart itself. + +The chart data is limited to the last 500 items. + +### Disabling chart + +This chart is enabled by default. If you have a self-managed instance, an +administrator can open a Rails console and disable it with the following command: + +```ruby +Feature.disable(:cycle_analytics_scatterplot_enabled) +``` + +## Type of work - Tasks by type chart + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32421) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. + +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 +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 +select up to a total of 15 labels. + +## Permissions + +To access Group-level Value Stream Analytics, users must have Reporter access or above. + +You can [read more about permissions](../../permissions.md) in general. + +## More resources + +Learn more about Value Stream Analytics in the following resources: + +- [Value Stream Analytics feature page](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). +- [Value Stream Analytics feature preview](https://about.gitlab.com/blog/2016/09/16/feature-preview-introducing-cycle-analytics/). +- [Value Stream Analytics feature highlight](https://about.gitlab.com/blog/2016/09/21/cycle-analytics-feature-highlight/). diff --git a/doc/user/incident_management/index.md b/doc/user/incident_management/index.md index 3d883a6b119..ed3516df168 100644 --- a/doc/user/incident_management/index.md +++ b/doc/user/incident_management/index.md @@ -3,3 +3,6 @@ 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 8701b5e038b..3b2acfab34c 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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, index description: 'Read through the GitLab User documentation to learn how to use, configure, and customize GitLab and GitLab.com to your own needs.' --- @@ -10,7 +10,7 @@ description: 'Read through the GitLab User documentation to learn how to use, co Welcome to GitLab! We're glad to have you here! -As a GitLab user you'll have access to all the features +As a GitLab user you have access to all the features your [subscription](https://about.gitlab.com/pricing/) includes, except [GitLab administrator](../administration/index.md) settings, unless you have admin privileges to install, configure, @@ -60,7 +60,7 @@ With GitLab Enterprise Edition, you can also: - [Multiple Assignees for Issues](project/issues/multiple_assignees_for_issues.md). **(STARTER)** - [Multiple Issue Boards](project/issue_board.md#multiple-issue-boards). - Create formal relationships between issues with [Related Issues](project/issues/related_issues.md). -- Use [Burndown Charts](project/milestones/burndown_charts.md) to track progress during a sprint or while working on a new version of their software. +- Use [Burndown Charts](project/milestones/burndown_and_burnup_charts.md) to track progress during a sprint or while working on a new version of their software. - Leverage [Elasticsearch](../integration/elasticsearch.md) with [Advanced Search](search/advanced_global_search.md) and [Advanced Search Syntax](search/advanced_search_syntax.md) for faster, more advanced code search across your entire GitLab instance. - [Authenticate users with Kerberos](../integration/kerberos.md). - [Mirror a repository](project/repository/repository_mirroring.md) from elsewhere on your local server. @@ -175,7 +175,7 @@ such as Trello, Jira, etc. ## Webhooks Configure [webhooks](project/integrations/webhooks.md) to listen for -specific events like pushes, issues or merge requests. GitLab will send a +specific events like pushes, issues or merge requests. GitLab sends a POST request with data to the webhook URL. ## API diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index 4af18873798..4c012fbf1d9 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Motivation The Terraform integration features within GitLab enable your GitOps / Infrastructure-as-Code (IaC) -workflows to tie into GitLab's authentication and authorization. These features focus on +workflows to tie into GitLab authentication and authorization. These features focus on lowering the barrier to entry for teams to adopt Terraform, collaborate effectively within GitLab, and support Terraform best practices. @@ -31,6 +31,12 @@ Amazon S3 or Google Cloud Storage. Its features include: Read more on setting up and [using GitLab Managed Terraform states](terraform_state.md) +WARNING: +Like any other job artifact, Terraform plan data is [viewable by anyone with Guest access](../permissions.md) to the repository. +Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform plan +includes sensitive data such as passwords, access tokens, or certificates, GitLab strongly +recommends encrypting plan output or modifying the project visibility settings. + ## Terraform integration in Merge Requests 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/mr_integration.md b/doc/user/infrastructure/mr_integration.md index 7d9a036cac8..c86e5ddf1db 100644 --- a/doc/user/infrastructure/mr_integration.md +++ b/doc/user/infrastructure/mr_integration.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 @@ -17,7 +17,7 @@ modifies, or destroys. ## Setup -NOTE: **Note:** +NOTE: GitLab ships with a [pre-built CI template](index.md#quick-start) that uses GitLab Managed Terraform state and integrates Terraform changes into merge requests. We recommend customizing the pre-built image and relying on the `gitlab-terraform` helper provided within for a quick setup. To manually configure a GitLab Terraform Report artifact requires the following steps: @@ -42,7 +42,7 @@ To manually configure a GitLab Terraform Report artifact requires the following - alias convert_report="jq -r '([.resource_changes[]?.change.actions?]|flatten)|{\"create\":(map(select(.==\"create\"))|length),\"update\":(map(select(.==\"update\"))|length),\"delete\":(map(select(.==\"delete\"))|length)}'" ``` - NOTE: **Note:** + NOTE: In distributions that use Bash (for example, Ubuntu), `alias` statements are not expanded in non-interactive mode. If your pipelines fail with the error `convert_report: command not found`, alias expansion can be activated explicitly diff --git a/doc/user/infrastructure/terraform_state.md b/doc/user/infrastructure/terraform_state.md index ef36f0217be..cbd2a63524d 100644 --- a/doc/user/infrastructure/terraform_state.md +++ b/doc/user/infrastructure/terraform_state.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 @@ -186,7 +186,7 @@ and the CI YAML file: The output from the above `terraform` commands should be viewable in the job logs. -CAUTION: **Caution:** +WARNING: Like any other job artifact, Terraform plan data is [viewable by anyone with Guest access](../permissions.md) to the repository. Neither Terraform nor GitLab encrypts the plan file by default. If your Terraform plan includes sensitive data such as passwords, access tokens, or certificates, GitLab strongly @@ -344,7 +344,7 @@ location. You can then go back to running it from within GitLab CI. ## Managing state files -NOTE: **Note:** +NOTE: We are currently working on [providing a graphical interface for managing state files](https://gitlab.com/groups/gitlab-org/-/epics/4563).  @@ -356,5 +356,5 @@ The state files attached to a project can be found under Operations / Terraform. You can only remove a state file by making a request to the API, like the following example: ```shell -curl --header "Private-Token: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/<your_project_id/terraform/state/<your_state_name>" +curl --header "Private-Token: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/<your_project_id>/terraform/state/<your_state_name>" ``` diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index 68af74b69fe..33366c658d7 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Instance-level Kubernetes clusters @@ -18,7 +18,7 @@ The instance level Kubernetes clusters can be found in the top menu by navigatin ## Cluster precedence -GitLab will try to match clusters in the following order: +GitLab tries to match clusters in the following order: - Project-level clusters. - Group-level clusters. diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 4bdf72673a1..be6e483aa54 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -1,28 +1,28 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- # GitLab Markdown -This Markdown guide is **valid only for GitLab's internal Markdown rendering system for entries and files**. +This Markdown guide is **valid only for the GitLab internal Markdown rendering system for entries and files**. It is **not** valid for the [GitLab documentation website](https://docs.gitlab.com) -or [GitLab's main website](https://about.gitlab.com), as they both use +or the [GitLab main website](https://about.gitlab.com), as they both use [Kramdown](https://kramdown.gettalong.org) as their Markdown engine. The documentation website uses an extended Kramdown gem, [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown). Consult the [GitLab Kramdown Guide](https://about.gitlab.com/handbook/markdown-guide/) for a complete Kramdown reference. -NOTE: **Note:** +NOTE: We encourage you to view this document as [rendered by GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md). ## 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. -It was inspired by [GitHub Flavored Markdown](https://docs.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax). +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: @@ -52,7 +52,7 @@ The documentation website had its [Markdown engine migrated from Redcarpet to Kr 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 GitLab's RedCarpet version +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. @@ -162,6 +162,7 @@ Color written inside backticks is followed by a color "chip": ### Diagrams and flowcharts It's possible to generate diagrams and flowcharts from text in GitLab using [Mermaid](https://mermaidjs.github.io/) or [PlantUML](https://plantuml.com). +It's also possible to use [Kroki](https://kroki.io) to create a wide variety of diagrams. #### Mermaid @@ -231,6 +232,11 @@ end To make PlantUML available in GitLab, a GitLab administrator needs to enable it first. Read more in [PlantUML & GitLab](../administration/integration/plantuml.md). +#### Kroki + +To make Kroki available in GitLab, a GitLab administrator needs to enable it first. +Read more in the [Kroki integration](../administration/integration/kroki.md) page. + ### 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). @@ -347,7 +353,7 @@ The wrapping tags can be either curly braces or square brackets: - [- deletion 4 -] ``` - + --- @@ -369,7 +375,7 @@ backslash `\`, otherwise the diff highlight don't render correctly: - {+ Text with escaped \`backticks\` inside +} ``` - + ### Math @@ -425,7 +431,7 @@ GFM recognizes the following: | merge request | `!123` | `namespace/project!123` | `project!123` | | snippet | `$123` | `namespace/project$123` | `project$123` | | epic **(ULTIMATE)** | `&123` | `group1/subgroup&123` | | -| vulnerability **(ULTIMATE)** *(1)* | `[vulnerability:123]` | `[vulnerability:namespace/project/123]` | `[vulnerability:project/123]` | +| vulnerability **(ULTIMATE)** (1)| `[vulnerability:123]` | `[vulnerability:namespace/project/123]` | `[vulnerability: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"` | @@ -435,29 +441,11 @@ GFM recognizes the following: | multi-word milestone by name | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` | | specific commit | `9ba12248` | `namespace/project@9ba12248` | `project@9ba12248` | | commit range comparison | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` | -| repository file references | `[README](doc/README)` | | | -| repository file line references | `[README](doc/README#L13)` | | | +| repository file references | `[README](doc/README.md)` | | | +| repository file line references | `[README](doc/README.md#L13)` | | | | [alert](../operations/incident_management/alerts.md) | `^alert#123` | `namespace/project^alert#123` | `project^alert#123` | -1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/281035) in GitLab 13.6. - - The Vulnerability special references 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. - It's disabled on GitLab.com. - - To disable it: - - ```ruby - Feature.disable(:vulnerability_special_references) - ``` - - To enable it: - - ```ruby - Feature.enable(:vulnerability_special_references) - ``` +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 @@ -471,7 +459,7 @@ In addition to this, links to some objects are also recognized and formatted. So ### Task lists -> If this 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 is not 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 @@ -494,7 +482,7 @@ unordered or ordered lists: 1. [x] Sub-task 2 ``` - + ### Table of contents @@ -774,6 +762,7 @@ But let's throw in a <b>tag</b>. There are multiple ways to emphasize text in Markdown. You can italicize, bold, strikethrough, as well as combine these emphasis styles together. +Strikethrough is not part of the core Markdown standard, but is part of GFM. Examples: @@ -795,9 +784,6 @@ Combined emphasis with **asterisks and _underscores_**. Strikethrough uses two tildes. ~~Scratch this.~~ -NOTE: **Note:** -Strikethrough is not part of the core Markdown standard, but is part of GFM. - #### 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). @@ -1072,7 +1058,7 @@ are separated into their own lines: ``` <!-- -Note: The example below uses HTML to force correct rendering on docs.gitlab.com, +The example below uses HTML to force correct rendering on docs.gitlab.com, Markdown is fine in GitLab. --> @@ -1124,7 +1110,7 @@ These details <em>remain</em> <strong>hidden</strong> until expanded. Markdown inside these tags is supported as well. -TIP: **Tip:** +NOTE: If your Markdown isn't rendering correctly, try adding `{::options parse_block_html="true" /}` to the top of the page, and add `markdown="span"` to the opening summary tag like this: `<summary markdown="span">`. @@ -1263,7 +1249,7 @@ Do not change to reference style links. Some text to show that the reference links can follow later. -NOTE: **Note:** +NOTE: Relative links do not allow the referencing of project files in a wiki page, or a wiki page in a project file. The reason for this is that a wiki is always in a separate Git repository in GitLab. For example, `[I'm a reference-style link](style)` diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 9e2dfd9ad96..bef768cad4e 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Operations Dashboard **(PREMIUM)** @@ -15,7 +15,7 @@ The dashboard can be accessed via the top bar, by clicking **More > Operations** ## Adding a project to the dashboard -NOTE: **Note:** +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. @@ -26,7 +26,7 @@ To add a project to the dashboard: 1. Search and add one or more projects using the **Search your projects** field. 1. Click the **Add projects** button. -Once added, the dashboard will display the project's number of active alerts, +Once added, the dashboard displays the project's number of active alerts, last commit, pipeline status, and when it was last deployed. The Operations and [Environments](../../ci/environments/environments_dashboard.md) dashboards share the same list of projects. Adding or removing a project from one adds or removes the project from the other. @@ -35,7 +35,7 @@ The Operations and [Environments](../../ci/environments/environments_dashboard.m ## Arranging projects on a dashboard -You can drag project cards to change their order. The card order is currently only saved to your browser, so will not change the dashboard for other people. +You can drag project cards to change their order. The card order is currently only saved to your browser, so it doesn't change the dashboard for other people. ## Making it the default dashboard when you sign in diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 6e5563d0d4e..751915f84a0 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -70,13 +70,16 @@ so that anyone who can access the project can use the package as a dependency. Prerequisites: -- A package in a GitLab repository. +- A package in a GitLab repository. Composer packages should be versioned based on + the [Composer specification](https://getcomposer.org/doc/04-schema.md#version). + If the version is not valid, for example, it has three dots (`1.0.0.0`), an + error (`Validation failed: Version is invalid`) occurs when you publish. - A valid `composer.json` file. - The Packages feature is enabled in a GitLab repository. - The project ID, which is on the project's home page. - A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api`. - NOTE: **Note:** + NOTE: [Deploy tokens](../../project/deploy_tokens/index.md) are [not yet supported](https://gitlab.com/gitlab-org/gitlab/-/issues/240897) for use with Composer. @@ -116,7 +119,7 @@ You can publish a Composer package to the Package Registry as part of your CI/CD 1. Run the pipeline. -You can view the published package by going to **Packages & Registries > Package Registry** and selecting the **Composer** tab. +To view the published package, go to **Packages & Registries > Package Registry** and select the **Composer** tab. ### Use a CI/CD template @@ -126,7 +129,7 @@ A more detailed Composer CI/CD file is also available as a `.gitlab-ci.yml` temp 1. Above the file list, click **Set up CI/CD**. If this button is not available, select **CI/CD Configuration** and then **Edit**. 1. From the **Apply a template** list, select **Composer**. -CAUTION: **Warning:** +WARNING: Do not save unless you want to overwrite the existing CI/CD file. ## Install a Composer package @@ -139,7 +142,7 @@ Prerequisites: - The group ID, which is on the group's home page. - A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to, at minimum, `read_api`. - NOTE: **Note:** + NOTE: [Deploy tokens](../../project/deploy_tokens/index.md) are [not yet supported](https://gitlab.com/gitlab-org/gitlab/-/issues/240897) for use with Composer. @@ -248,14 +251,14 @@ To install a package: composer config --unset gitlab-domains ``` - NOTE: **Note:** + NOTE: On GitLab.com, Composer uses the GitLab token from `auth.json` as a private token by default. Without the `gitlab-domains` definition in `composer.json`, Composer uses the GitLab token as basic-auth, with the token as a username and a blank password. This results in a 401 error. Output indicates that the package has been successfully installed. -CAUTION: **Important:** +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-with-satis.md#authentication) tool with your personal access token stored in a [GitLab CI/CD environment variable](../../../ci/variables/README.md) or in diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index f6f8d6d61b6..73798d363af 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -51,7 +51,7 @@ compilers. This example uses the CMake compiler. To install CMake: -- For Mac, use [homebrew](https://brew.sh/) and run `brew install cmake`. +- For Mac, use [Homebrew](https://brew.sh/) and run `brew install cmake`. - For other operating systems, follow the instructions at [cmake.org](https://cmake.org/install/). When installation is complete, verify you can use CMake in your terminal by @@ -86,7 +86,7 @@ To build a package: conan create . mycompany/beta ``` - NOTE: **Note:** + NOTE: If you use an [instance remote](#add-a-remote-for-your-instance), you must follow a specific [naming convention](#package-recipe-naming-convention-for-instance-remotes). @@ -205,7 +205,7 @@ For example: CONAN_LOGIN_USERNAME=<gitlab_username or deploy_token_username> CONAN_PASSWORD=<personal_access_token or deploy_token> conan upload Hello/0.1@mycompany/beta --all --remote=gitlab ``` -NOTE: **Note:** +NOTE: Because your authentication with GitLab expires on a regular basis, you may occasionally need to re-enter your personal access token. @@ -221,7 +221,7 @@ In a terminal, run this command: conan remote add_ref Hello/0.1@mycompany/beta gitlab ``` -NOTE: **Note:** +NOTE: The package recipe includes the version, so the default remote for `Hello/0.1@user/channel` doesn't work for `Hello/0.2@user/channel`. @@ -292,7 +292,7 @@ Prerequisites: - [Authentication](#authenticate-to-the-package-registry) with the Package Registry must be configured. -1. In the project where you want to install the package as a dependency, open +1. In the project where you want to install the package as a dependency, open `conanfile.txt`. Or, in the root of your project, create a file called `conanfile.txt`. @@ -316,10 +316,10 @@ Prerequisites: 1. Install the dependencies listed in `conanfile.txt`: ```shell - conan install <options> + conan install .. <options> ``` -NOTE: **Note:** +NOTE: If you try to install the package you just created in this tutorial, the package already exists on your local computer, so this command has no effect. @@ -336,7 +336,7 @@ There are two ways to remove a Conan package from the GitLab Package Registry. You must explicitly include the remote in this command, otherwise the package is removed only from your local system cache. - NOTE: **Note:** + NOTE: This command removes all recipe and binary package files from the Package Registry. diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 1cb6c951bd9..4e8d105adfa 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 Container Registry @@ -16,6 +16,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - The group-level Container Registry was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23315) in GitLab 12.10. > - Searching by image repository name was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31322) in GitLab 13.0. +NOTE: +If you pull container images from Docker Hub, you can also use the [GitLab Dependency Proxy](../dependency_proxy/index.md#use-the-dependency-proxy-for-docker-images) to avoid running into rate limits and speed up your pipelines. + With the Docker Container Registry integrated into GitLab, every GitLab project can have its own space to store its Docker images. @@ -127,7 +130,7 @@ To build and push to the Container Registry: docker push registry.example.com/group/project/image ``` -You can also view these commands by going to your project's **Packages & Registries > Container Registry**. +To view these commands, go to your project's **Packages & Registries > Container Registry**. ## Build and push by using GitLab CI/CD @@ -291,7 +294,7 @@ deploy: - master ``` -NOTE: **Note:** +NOTE: This example explicitly calls `docker pull`. If you prefer to implicitly pull the built image using `image:`, and use either the [Docker](https://docs.gitlab.com/runner/executors/docker.html) or [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html) executor, @@ -332,11 +335,11 @@ error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker You can delete images from your Container Registry in multiple ways. -CAUTION: **Warning:** +WARNING: Deleting images is a destructive action and can't be undone. To restore a deleted image, you must rebuild and re-upload it. -NOTE: **Note:** +NOTE: Administrators should review how to [garbage collect](../../../administration/packages/container_registry.md#container-registry-garbage-collection) the deleted images. @@ -368,7 +371,7 @@ information, see the following endpoints: ### Delete images using GitLab CI/CD -CAUTION: **Warning:** +WARNING: GitLab CI/CD doesn't provide a built-in way to remove your images, but this example uses a third-party tool called [reg](https://github.com/genuinetools/reg) that talks to the GitLab Registry API. You are responsible for your own actions. @@ -426,7 +429,7 @@ delete_image: - master ``` -TIP: **Tip:** +NOTE: You can download the latest `reg` release from [the releases page](https://github.com/genuinetools/reg/releases), then update the code example by changing the `REG_SHA256` and `REG_VERSION` variables @@ -489,6 +492,8 @@ Cleanup policies can be run on all projects, with these exceptions: The cleanup policy collects all tags in the Container Registry and excludes tags until only the tags to be deleted remain. +The cleanup policy searches for images based on the tag name. Support for the full path [has not yet been implemented](https://gitlab.com/gitlab-org/gitlab/-/issues/281071), but would allow you to clean up dynamically-named tags. + The cleanup policy: 1. Collects all tags for a given repository in a list. @@ -501,7 +506,7 @@ The cleanup policy: 1. Excludes from the list any tags matching the `name_regex_keep` value (tags to preserve). 1. Finally, the remaining tags in the list are deleted from the Container Registry. -CAUTION: **Warning:** +WARNING: On GitLab.com, the execution time for the cleanup policy is limited, and some of the tags may remain in the Container Registry after the policy runs. The next time the policy runs, the remaining tags are included, so it may take multiple runs for all tags to be deleted. @@ -513,29 +518,31 @@ You can create a cleanup policy in [the API](#use-the-cleanup-policy-api) or the To create a cleanup policy in the UI: 1. For your project, go to **Settings > CI/CD**. -1. Expand the **Cleanup policy for tags** section. +1. Expand the **Clean up image tags** section. 1. Complete the fields. | Field | Description | |---------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| - | **Cleanup policy** | Turn the policy on or off. | - | **Expiration interval** | How long tags are exempt from being deleted. | - | **Expiration schedule** | How often the policy should run. | - | **Number of tags to retain** | How many tags to _always_ keep for each image. | - | **Tags with names matching this regex pattern expire:** | The regex pattern that determines which tags to remove. This value cannot be blank. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | - | **Tags with names matching this regex pattern are preserved:** | The regex pattern that determines which tags to preserve. The `latest` tag is always preserved. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | + | **Toggle** | Turn the policy on or off. | + | **Run cleanup** | How often the policy should run. | + | **Keep the most recent** | How many tags to _always_ keep for each image. | + | **Keep tags matching** | The regex pattern that determines which tags to preserve. The `latest` tag is always preserved. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | + | **Remove tags older than** | Remove only tags older than X days. | + | **Remove tags matching** | The regex pattern that determines which tags to remove. This value cannot be blank. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | -1. Click **Set cleanup policy**. +1. Click **Save**. Depending on the interval you chose, the policy is scheduled to run. -NOTE: **Note:** -If you edit the policy and click **Set cleanup policy** again, the interval is reset. +NOTE: +If you edit the policy and click **Save** again, the interval is reset. ### Regex pattern examples Cleanup policies use regex patterns to determine which tags should be preserved or removed, both in the UI and the API. +Regex patterns are automatically surrounded with `\A` and `\Z` anchors. Do not include any `\A`, `\Z`, `^` or `$` token in the regex patterns as they are not necessary. + Here are examples of regex patterns you may want to use: - Match all tags: @@ -573,7 +580,7 @@ Examples: - Select all tags, keep at least 1 tag per image, clean up any tag older than 14 days, run once a month, preserve any images with the name `master` and the policy is enabled: ```shell - curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-master"}}' 'https://gitlab.example.com/api/v4/projects/2' + curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-master"}}' "https://gitlab.example.com/api/v4/projects/2" ``` See the API documentation for further details: [Edit project](../../../api/projects.md#edit-project). diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index e1fae770a5d..fbede6d13b7 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -1,13 +1,15 @@ --- stage: Package group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Dependency Proxy > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Core](https://about.gitlab.com/pricing/) in GitLab 13.6. +> - [Support for private groups](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. +> - Anonymous access to images in public groups is no longer available starting in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. The GitLab Dependency Proxy is a local proxy you can use for your frequently-accessed upstream images. @@ -15,11 +17,14 @@ upstream images. In the case of CI/CD, the Dependency Proxy receives a request and returns the upstream image from a registry, acting as a pull-through cache. -## Prerequisites +NOTE: +The Dependency Proxy is not compatible with Docker version 20.x and later. +If you are using the Dependency Proxy, Docker version 19.x.x is recommended until +[issue #290944](https://gitlab.com/gitlab-org/gitlab/-/issues/290944) is resolved. -To use the Dependency Proxy: +## Prerequisites -- Your group must be public. Authentication for private groups is [not supported yet](https://gitlab.com/gitlab-org/gitlab/-/issues/11582). +The Dependency Proxy must be [enabled by an administrator](../../../administration/packages/dependency_proxy.md). ### Supported images and packages @@ -32,6 +37,11 @@ The following images and packages are supported. For a list of planned additions, view the [direction page](https://about.gitlab.com/direction/package/dependency_proxy/#top-vision-items). +## Enable the Dependency Proxy + +The Dependency Proxy is disabled by default. +[Learn how an administrator can enable it](../../../administration/packages/dependency_proxy.md). + ## View the Dependency Proxy To view the Dependency Proxy: @@ -42,16 +52,136 @@ The Dependency Proxy is not available for projects. ## Use the Dependency Proxy for Docker images -CAUTION: **Important:** -In some specific storage configurations, an issue occurs and container images are not pulled correctly from the cache. The problem occurs when an image is located in object storage. The proxy looks for it locally and fails to find it. View [issue #208080](https://gitlab.com/gitlab-org/gitlab/-/issues/208080) for details. - You can use GitLab as a source for your Docker images. Prerequisites: - Your images must be stored on [Docker Hub](https://hub.docker.com/). -- Docker Hub must be available. Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/241639) - for progress on accessing images when Docker Hub is down. + +### Authenticate with the Dependency Proxy + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. +> - 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)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. +The requirement to authenticate is a breaking change added in 13.7. An [administrator can temporarily +disable it](../../../administration/packages/dependency_proxy.md#disabling-authentication) if it +has disrupted your existing Dependency Proxy usage. + +Because the Dependency Proxy is storing Docker images in a space associated with your group, +you must authenticate against the Dependency Proxy. + +Follow the [instructions for using images from a private registry](../../../ci/docker/using_docker_images.md#define-an-image-from-a-private-container-registry), +but instead of using `registry.example.com:5000`, use your GitLab domain with no port `gitlab.example.com`. + +For example, to manually log in: + +```shell +docker login gitlab.example.com --username my_username --password my_password +``` + +You can authenticate using: + +- Your GitLab username and password. +- A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `read_registry` and `write_registry`. + +#### Authenticate within CI/CD + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/280582) in GitLab 13.7. + +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: + +```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 +``` + +`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: + +```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 other credentials such as: + + ```shell + echo -n "my_username:personal_access_token" | base64 + echo -n "deploy_token_username:deploy_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 + ... + ``` + +### Store a Docker image in Dependency Proxy cache To store a Docker image in Dependency Proxy storage: @@ -89,3 +219,69 @@ stored. To reclaim disk space used by image blobs that are no longer needed, use the [Dependency Proxy API](../../../api/dependency_proxy.md). + +## Docker Hub rate limits and the Dependency Proxy + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241639) in [GitLab Core](https://about.gitlab.com/pricing/) 13.7. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +Watch how to [use the Dependency Proxy to help avoid Docker Hub rate limits](https://youtu.be/Nc4nUo7Pq08). + +In November 2020, Docker introduced +[rate limits on pull requests from Docker Hub](https://docs.docker.com/docker-hub/download-rate-limit/). +If your GitLab [CI/CD configuration](../../../ci/README.md) uses +an image from Docker Hub, each time a job runs, it may count as a pull request. +To help get around this limit, you can pull your image from the Dependency Proxy cache instead. + +When you pull an image (by using a command like `docker pull` or, in a `.gitlab-ci.yml` +file, `image: foo:latest`), the Docker client makes a collection of requests: + +1. The image manifest is requested. The manifest contains information about + how to build the image. +1. Using the manifest, the Docker client requests a collection of layers, also + known as blobs, one at a time. + +The Docker Hub rate limit is based on the number of GET requests for the manifest. The Dependency Proxy +caches both the manifest and blobs for a given image, so when you request it again, +Docker Hub does not have to be contacted. + +### How does GitLab know if a cached tagged image is stale? + +If you are using an image tag like `alpine:latest`, the image changes +over time. Each time it changes, the manifest contains different information about which +blobs to request. The Dependency Proxy does not pull a new image each time the +manifest changes; it checks only when the manifest becomes stale. + +Docker does not count HEAD requests for the image manifest towards the rate limit. +You can make a HEAD request for `alpine:latest`, view the digest (checksum) +value returned in the header, and determine if a manifest has changed. + +The Dependency Proxy starts all requests with a HEAD request. If the manifest +has become stale, only then is a new image pulled. + +For example, if your pipeline pulls `node:latest` every five +minutes, the Dependency Proxy caches the entire image and only updates it if +`node:latest` changes. So instead of having 360 requests for the image in six hours +(which exceeds the Docker Hub rate limit), you only have one pull request, unless +the manifest changed during that time. + +### Check your Docker Hub rate limit + +If you are curious about how many requests to Docker Hub you have made and how +many remain, you can run these commands from your runner, or even in a CI/CD +script: + +```shell +# Note, you must have jq installed to run this command +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 | grep RateLimit +... +``` + +The output is something like: + +```shell +RateLimit-Limit: 100;w=21600 +RateLimit-Remaining: 98;w=21600 +``` + +This example shows the total limit of 100 pulls in six hours, with 98 pulls remaining. diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index f489c7c800f..c9859840c9c 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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)** @@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - It's recommended for production use. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-generic-packages-in-the-package-registry). -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. Publish generic files, like release binaries, in your project’s Package Registry. Then, install the packages whenever you need to use them as a dependency. @@ -39,7 +39,7 @@ 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 expresion. +| `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 (`_`). Provide the file context in the request body. @@ -49,7 +49,7 @@ Example request: ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" \ --upload-file path/to/file.txt \ - https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt + "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt" ``` Example response: @@ -79,13 +79,13 @@ GET /projects/:id/packages/generic/:package_name/:package_version/:file_name | `package_version` | string | yes | The package version. | | `file_name` | string | yes | The file name. | -The file context is served in the response body. The response content type will be `application/octet-stream`. +The file context is served in the response body. The response content type is `application/octet-stream`. Example request that uses a personal access token: ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" \ - https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt + "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt" ``` ## Publish a generic package by using CI/CD @@ -105,7 +105,7 @@ stages: upload: stage: upload script: - - 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file path/to/file.txt ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/0.0.1/file.txt' + - 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file path/to/file.txt "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/0.0.1/file.txt"' download: stage: download diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index 81edc3afcfd..87cd4a4a9a6 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -45,7 +45,7 @@ Feature.enable(:go_proxy, Project.find(1)) Feature.disable(:go_proxy, Project.find(2)) ``` -NOTE: **Note:** +NOTE: Even if it's enabled, GitLab doesn't display Go modules in the **Package Registry**. Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/213770) for details. @@ -159,7 +159,7 @@ later, can be written with `go env -w <var>=<value>`. For example, Go modules and module versions are defined by source repositories, such as Git, SVN, and Mercurial. A module is a repository that contains `go.mod` and Go -files. Module versions are defined by VCS tags. +files. Module versions are defined by version control system (VCS) tags. To publish a module, push `go.mod` and source files to a VCS repository. To publish a module version, push a VCS tag. diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index 83d179cbc9c..9da14842845 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Packages & Registries @@ -32,8 +32,8 @@ You can also use the [API](../../api/packages.md) to administer the Package Regi ## Accepting contributions -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) will -guide you through the process. +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. | Format | Status | | ------ | ------ | diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 5d0d64b310d..e0f5a400977 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -361,7 +361,7 @@ To use the GitLab endpoint for Maven packages, choose an option: - **Instance-level**: Use when you have many Maven packages in different GitLab groups or in their own namespace. -The option you choose determines the settings you'll add to your `pom.xml` file. +The option you choose determines the settings you add to your `pom.xml` file. In all cases, to publish a package, you need: @@ -653,7 +653,7 @@ The message should show that the package is downloading from the Package Registr Downloading from gitlab-maven: http://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom ``` -TIP: **Tip:** +NOTE: In the GitLab UI, on the Package Registry page for Maven, you can view and copy these commands. ### Use Gradle @@ -707,23 +707,23 @@ 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, - or you can hard code your project's ID. + or you can hard code your server's hostname and project's ID. ```xml <repositories> <repository> <id>gitlab-maven</id> - <url>https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + <url>${env.CI_SERVER_URL}/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> </repository> </repositories> <distributionManagement> <repository> <id>gitlab-maven</id> - <url>https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + <url>${env.CI_SERVER_URL}/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> </repository> <snapshotRepository> <id>gitlab-maven</id> - <url>https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + <url>${env.CI_SERVER_URL}/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> </snapshotRepository> </distributionManagement> ``` @@ -793,7 +793,7 @@ mvn deploy \ -Dorg.slf4j.simpleLogger.log.org.apache.maven.wagon.providers.http.httpclient.wire=trace ``` -CAUTION: **Caution:** +WARNING: When you set these options, all network requests are logged and a large amount of output is generated. ### Useful Maven command-line options diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index feb797240f4..51b41b842fa 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w 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. +Only [scoped](https://docs.npmjs.com/misc/scope/) packages are supported. ## Build an NPM package @@ -25,7 +25,7 @@ the [next section](#authenticate-to-the-package-registry). ### Install NPM 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). +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 running: @@ -102,10 +102,11 @@ To authenticate to the Package Registry, you must use one of the following: - It's not recommended, but you can use [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow). Standard OAuth tokens cannot authenticate to the GitLab NPM Registry. You must use a personal access token with OAuth headers. - A [CI job token](#authenticate-with-a-ci-job-token). +- Your NPM package name must be in the format of [@scope:package-name](#package-naming-convention). It must match exactly, including the case. ### Authenticate with a personal access token or deploy token -To authenticate with the Package Registry, you will need a [personal access token](../../profile/personal_access_tokens.md) or [deploy token](../../project/deploy_tokens/index.md). +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 @@ -228,7 +229,7 @@ This regex allows almost all of the characters that NPM allows, with a few excep 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. -CAUTION: **Caution:** +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 @@ -240,6 +241,7 @@ Prerequisites: - [Authenticate](#authenticate-to-the-package-registry) to the Package Registry. - Set a [project-level NPM endpoint](#use-the-gitlab-endpoint-for-npm-packages). +- Your NPM package name must be in the format of [@scope:package-name](#package-naming-convention). It must match exactly, including the case. To upload an NPM package to your project, run this command: @@ -277,6 +279,10 @@ deploy: - npm publish ``` +See the +[Publish NPM packages to the GitLab Package Registry using semantic-release](../../../ci/examples/semantic-release.md) +step-by-step guide and demo project for a complete example. + ## Publishing packages with the same name or version You cannot publish a package if a package of the same name and version already exists. @@ -356,7 +362,7 @@ In GitLab 12.6 and later, packages published to the Package Registry expose the > - [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. -You can add [distribution tags](https://docs.npmjs.com/cli/dist-tag) to newly-published packages. +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. When you publish a package without a tag, the `latest` tag is added by default. @@ -451,3 +457,11 @@ If you get this error, ensure that: - The scoped packages URL includes a trailing slash: - Correct: `//gitlab.example.com/api/v4/packages/npm/` - Incorrect: `//gitlab.example.com/api/v4/packages/npm` + +### `npm publish` returns `npm ERR! 400 Bad Request` + +If you get this error, your package name may not meet the +[@scope:package-name package naming convention](#package-naming-convention). + +Ensure the name meets the convention exactly, including the case. +Then try to publish again. diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 2b61c4a6c28..bdf50ecef0b 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -181,7 +181,7 @@ nuget push <package_file> -Source <source_name> Prerequisite: -[A NuGet package created with .NET CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package-dotnet-cli). +- [A NuGet package created with .NET CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package-dotnet-cli). Publish a package by running this command: @@ -233,7 +233,7 @@ updated: ### Install a package with the NuGet CLI -CAUTION: **Warning:** +WARNING: By default, `nuget` checks the official source at `nuget.org` first. If you have a NuGet package in the Package Registry with the same name as a package at `nuget.org`, you must specify the source name to install the correct package. @@ -253,7 +253,7 @@ nuget install <package_id> -OutputDirectory <output_directory> \ ### Install a package with the .NET CLI -CAUTION: **Warning:** +WARNING: If you have a package in the Package Registry with the same name as a package at a different source, verify the order in which `dotnet` checks sources during install. This is defined in the `nuget.config` file. diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index 56fd4a02ba0..5876ef19ad9 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Package Registry @@ -33,20 +33,19 @@ CI/CD templates, which you can use to get started, are in [this repo](https://gi Learn more about using CI/CD to build: -- [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) - [Composer packages](../composer_repository/index.md#publish-a-composer-package-by-using-cicd) -- [NuGet packages](../nuget_repository/index.md#publish-a-nuget-package-by-using-cicd) - [Conan packages](../conan_repository/index.md#publish-a-conan-package-by-using-cicd) - [Generic packages](../generic_packages/index.md#publish-a-generic-package-by-using-cicd) +- [Maven packages](../maven_repository/index.md#create-maven-packages-with-gitlab-cicd) +- [NPM packages](../npm_registry/index.md#publish-an-npm-package-by-using-cicd) +- [NuGet packages](../nuget_repository/index.md#publish-a-nuget-package-by-using-cicd) If you use CI/CD to build a package, extended activity information is displayed when you view the package details:  -When using Maven and NPM, you can view which pipeline published the package, and -the commit and user who triggered it. +You can view which pipeline published the package, and the commit and user who triggered it. However, the history is limited to five updates of a given package. ## Download a package @@ -95,4 +94,3 @@ The **Packages & Registries > Package Registry** entry is removed from the sideb Learn how to use the GitLab Package Registry to build your own custom package workflow. - [Use a project as a package registry](../workflows/project_registry.md) to publish all of your packages to one project. -- Publish multiple different packages from one [monorepo project](../workflows/monorepo.md). diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 83b29d5f53a..e78224f89d1 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -1,7 +1,7 @@ --- stage: Package group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -237,11 +237,11 @@ When publishing packages, note that: - The maximum allowed size is 50 MB. - You can't upload the same version of a package multiple times. If you try, - you'll receive the error `Validation failed: File name has already been taken`. + you receive the error `Validation failed: File name has already been taken`. ### Ensure your version string is valid -If your version string (for example, `0.0.1`) isn't valid, it will be rejected. +If your version string (for example, `0.0.1`) isn't valid, it gets rejected. GitLab uses the following regex to validate the version string. ```ruby diff --git a/doc/user/packages/workflows/monorepo.md b/doc/user/packages/workflows/monorepo.md index 1e375dffe7e..abba9df6ec2 100644 --- a/doc/user/packages/workflows/monorepo.md +++ b/doc/user/packages/workflows/monorepo.md @@ -1,120 +1,9 @@ --- -stage: Package -group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +redirect_to: '../npm_registry/index.md' +disqus_identifier: 'https://docs.gitlab.com/ee/user/packages/workflows/monorepo.html' --- -# Monorepo package management workflows +This document was moved to [another location](../npm_registry/index.md). -Oftentimes, one project or Git repository may contain multiple different -sub-projects or submodules that all get packaged and published individually. - -## Publishing different packages to the parent project - -The number and name of packages you can publish to one project is not limited. -You can accomplish this by setting up different configuration files for each -package. See the documentation for the package manager of your choice since -each has its own specific files and instructions to follow to publish -a given package. - -Here, we take a walk through how to do this with [NPM](../npm_registry/index.md). - -Let us say we have a project structure like so: - -```plaintext -MyProject/ - |- src/ - | |- components/ - | |- Foo/ - |- package.json -``` - -`MyProject` is the parent project, which contains a sub-project `Foo` in the -`components` directory. We would like to publish packages for both `MyProject` -as well as `Foo`. - -Following the instructions in the -[GitLab NPM registry documentation](../npm_registry/index.md), -publishing `MyProject` consists of modifying the `package.json` file with a -`publishConfig` section, as well as either modifying your local NPM configuration with -CLI commands like `npm config set`, or saving a `.npmrc` file in the root of the -project specifying these configuration settings. - -If you follow the instructions you can publish `MyProject` by running -`npm publish` from the root directory. - -Publishing `Foo` is almost exactly the same, you simply have to follow the steps -while in the `Foo` directory. `Foo` needs its own `package.json` file, -which can be added manually or using `npm init`. It also needs its own -configuration settings. Since you are publishing to the same place, if you -used `npm config set` to set the registry for the parent project, then no -additional setup is necessary. If you used a `.npmrc` file, you need an -additional `.npmrc` file in the `Foo` directory (be sure to add `.npmrc` files -to the `.gitignore` file or use environment variables in place of your access -tokens to prevent them from being exposed). It can be identical to the -one you used in `MyProject`. You can now run `npm publish` from the `Foo` -directory and you can publish `Foo` separately from `MyProject` - -A similar process could be followed for Conan packages, instead of dealing with -`.npmrc` and `package.json`, you just deal with `conanfile.py` in -multiple locations within the project. - -## Publishing to other projects - -A package is associated with a project on GitLab, but the package does not -need to be associated with the code in that project. Notice when configuring -NPM or Maven, you only use the `Project ID` to set the registry URL that the -package is to be uploaded to. If you set this to any project that you have -access to and update any other configuration similarly depending on the package type, -your packages are published to that project. This means you can publish -multiple packages to one project, even if their code does not exist in the same -place. See the [project registry workflow documentation](project_registry.md) -for more details. - -## CI workflows for automating packaging - -CI pipelines open an entire world of possibilities for dealing with the patterns -described in the previous sections. A common desire would be to publish -specific packages only if changes were made to those directories. - -Using the example project above, this `gitlab-ci.yml` file publishes -`Foo` anytime changes are made to the `Foo` directory on the `master` branch, -and publish `MyPackage` anytime changes are made to anywhere _except_ the `Foo` -directory on the `master` branch. - -```yaml -image: node:latest - -stages: - - build - -build-foo-package: - stage: build - variables: - PACKAGE: "Foo" - script: - - cd src/components/Foo - - echo "Building $PACKAGE" - - npm publish - only: - refs: - - master - - merge_requests - changes: - - "src/components/Foo/**/*" - -build-my-project-package: - stage: build - variables: - PACKAGE: "MyPackage" - script: - - echo "Building $PACKAGE" - - npm publish - only: - refs: - - master - - merge_requests - except: - changes: - - "src/components/Foo/**/*" -``` +<!-- This redirect file can be deleted after <2021-02-14>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index a8972f05acd..aea1238b9da 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -1,98 +1,84 @@ --- stage: Package group: Package -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Project as a package registry +# Store all of your packages in one GitLab project -Using the features of the package registry, it is possible to use one project to store all of your packages. +You can store all of your packages in one project's Package Registry. Rather than using +a GitLab repository to store code, you can use the repository to store all your packages. +Then you can configure your remote repositories to point to the project in GitLab. -This guide mirrors the creation of [this package registry](https://gitlab.com/sabrams/my-package-registry). +You might want to do this because: -For the video version, see [Single Project Package Registry Demo](https://youtu.be/ui2nNBwN35c). - -## How does this work? - -You might be wondering "how is it possible to upload two packages from different codebases to the same project on GitLab?". - -It is easy to forget that a package on GitLab belongs to a project, but a project does not have to be a code repository. -The code used to build your packages can be stored anywhere - maybe it is another project on GitLab, or maybe a completely -different system altogether. All that matters is that when you configure your remote repositories for those packages, you -point them at the same project on GitLab. - -## Why would I do this? - -There are a few reasons you might want to publish all your packages to one project on GitLab: - -1. You want to publish your packages on GitLab, but to a project that is different from where your code is stored. -1. You would like to group packages together in ways that make sense for your usage (such as all NPM packages in one project, - all packages being used by a specific department in one project, or all private packages in one project) -1. You want to use one remote for all of your packages when installing them into other projects. -1. You would like to migrate your packages to a single place on GitLab from a third-party package registry and do not - want to worry about setting up separate projects for each package. -1. You want to have your CI pipelines build all of your packages to one project so the individual responsible for -validating packages can manage them all in one place. +- 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, + 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 + want to worry about setting up separate projects for each package. +- You want to have your CI/CD pipelines build all of your packages to one project, so the person responsible for + validating packages can manage them all in one place. ## Example walkthrough -There is no functionality specific to this feature. All we are doing is taking advantage of functionality available in each -of the package management systems to publish packages of different types to the same place. - -Let's take a look at how you might create a public place to hold all of your public packages. - -### Create a project - -First, create a new project on GitLab. It does not have to have any code or content. Make note of the project ID -displayed on the project overview page for use later in this process. - -### Create an access token +No functionality is specific to this feature. Instead, we're taking advantage of the functionality +of each package management system to publish different package types to the same place. -All of the package repositories available on the GitLab package registry are accessible using [GitLab personal access -tokens](../../profile/personal_access_tokens.md). +- <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). +- [View an example project](https://gitlab.com/sabrams/my-package-registry/-/packages). -While using CI, you can alternatively use CI job tokens (`CI_JOB_TOKEN`) to authenticate. +## Store different package types in one GitLab project -### Configure your local project for the GitLab registry and upload +Let's take a look at how you might create a public place to hold all of your public packages. -There are many ways to use this feature. You can upload all types of packages to the same project, -split things up based on package type, or package visibility level. +1. Create a new project in GitLab. The project doesn't require any code or content. Note the project ID + that's displayed on the project overview page. +1. Create an access token. All package types in the Package Registry are accessible by using + [GitLab personal access tokens](../../profile/personal_access_tokens.md). + If you're using CI/CD, you can use CI job tokens (`CI_JOB_TOKEN`) to authenticate. +1. Configure your local project and publish the package. -The purpose of this tutorial is to demonstrate the root idea that one project can hold many unrelated -packages, and to allow you to discover the best way to use this functionality yourself. +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 are using NPM, this involves creating an `.npmrc` file and adding the appropriate URL for uploading packages -to your project using your project ID, then adding a section to your `package.json` file with a similar URL. +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 push your NPM package to your project using `npm publish`, as described in the -[publishing packages](../npm_registry/index.md#publish-an-npm-package) section of the docs. +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 +[publishing packages](../npm_registry/index.md#publish-an-npm-package) section. -#### Maven +### Maven -If you are using Maven, this involves updating your `pom.xml` file with distribution sections, including the +If you are using Maven, you update your `pom.xml` file with distribution sections. These updates include the appropriate URL for your project, as described in the [GitLab Maven Repository documentation](../maven_repository/index.md#project-level-maven-endpoint). Then, you need to add a `settings.xml` file and [include your access token](../maven_repository/index.md#authenticate-with-a-personal-access-token-in-maven). -Now you can [deploy Maven packages](../maven_repository/index.md#publish-a-package) to your project. +Now you can [publish Maven packages](../maven_repository/index.md#publish-a-package) to your project. + +### Conan -#### Conan +For Conan, you need to add GitLab as a Conan registry remote. Follow the instructions in the +[GitLab Conan Repository docs](../conan_repository/index.md#add-the-package-registry-as-a-conan-remote). +Then, create your package using the plus-separated (`+`) project path as your Conan user. For example, +if your project is located at `https://gitlab.com/foo/bar/my-proj`, +[create your Conan package](../conan_repository/index.md) using `conan create . foo+bar+my-proj/channel`. +`channel` is your package channel (such as `stable` or `beta`). -For Conan, first you need to add GitLab as a Conan registry remote. Follow the instructions in the [GitLab Conan Repository docs](../conan_repository/index.md#add-the-package-registry-as-a-conan-remote) -to do so. Then, create your package using the plus-separated (`+`) project path as your Conan user. For example, -if your project is located at `https://gitlab.com/foo/bar/my-proj`, then you can [create your Conan package](../conan_repository/index.md) -using `conan create . foo+bar+my-proj/channel`, where `channel` is your package channel (such as `stable` or `beta`). After your package -is created, you are ready to [upload your package](../conan_repository/index.md#publish-a-conan-package) depending on your final package recipe. For example: +After you create your package, you're ready to [publish your package](../conan_repository/index.md#publish-a-conan-package), +depending on your final package recipe. For example: ```shell CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan upload MyPackage/1.0.0@foo+bar+my-proj/channel --all --remote=gitlab ``` -#### Composer - -It is currently not possible to publish a Composer package to a project that is different from where its code resides. +### All other package types -If you attempt to publish a Composer package to a different project, you get a `404 Branch Not Found` -or `404 Tag Not Found` error. +[All package types supported by GitLab](../index.md) can be published in +the same GitLab project. In previous releases, not all package types could +be published in the same project. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index f1365ee1cab..0dd7d6f7696 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -1,7 +1,7 @@ --- stage: Manage group: Access -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Permissions @@ -36,7 +36,7 @@ usernames. A GitLab administrator can configure the GitLab instance to ## Project members permissions -NOTE: **Note:** +NOTE: In GitLab 11.0, the Master role was renamed to Maintainer. While Maintainer is the highest project-level role, some actions can only be performed by a personal namespace or group owner, @@ -61,10 +61,11 @@ The following table depicts the various user permission levels in a project. | View wiki pages | ✓ | ✓ | ✓ | ✓ | ✓ | | See a list of jobs | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | | See a job log | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| See a job with [debug logging](../ci/variables/README.md#debug-logging) | | | ✓ | ✓ | ✓ | | Download and browse job artifacts | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| Create confidential issue | ✓ | ✓ | ✓ | ✓ | ✓ | | Create new issue | ✓ | ✓ | ✓ | ✓ | ✓ | | See related issues | ✓ | ✓ | ✓ | ✓ | ✓ | -| Create confidential issue | ✓ | ✓ | ✓ | ✓ | ✓ | | View [Releases](project/releases/index.md) | ✓ (*6*) | ✓ | ✓ | ✓ | ✓ | | View requirements **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -91,7 +92,13 @@ The following table depicts the various user permission levels in a project. | View Error Tracking list | | ✓ | ✓ | ✓ | ✓ | | Create new merge request | | ✓ | ✓ | ✓ | ✓ | | View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | +| Archive/reopen requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | | Create/edit requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| Import requirements **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| Create new [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | +| Archive [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | +| Move [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | +| Reopen [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | | Pull [packages](packages/index.md) | | ✓ | ✓ | ✓ | ✓ | | Publish [packages](packages/index.md) | | | ✓ | ✓ | ✓ | | Create/edit/delete a Cleanup policy | | | ✓ | ✓ | ✓ | @@ -159,9 +166,10 @@ The following table depicts the various user permission levels in a project. | Manage Terraform state | | | | ✓ | ✓ | | Manage license policy **(ULTIMATE)** | | | | ✓ | ✓ | | Edit comments (posted by any user) | | | | ✓ | ✓ | +| Reposition comments on images (posted by any user)|✓ (*11*) | ✓ (*11*) | ✓ (*11*) | ✓ | ✓ | | Manage Error Tracking | | | | ✓ | ✓ | | Delete wiki pages | | | | ✓ | ✓ | -| View project Audit Events | | | | ✓ | ✓ | +| 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)** | | | | ✓ | ✓ | | Switch visibility level | | | | | ✓ | @@ -188,6 +196,8 @@ The following table depicts the various user permission levels in a project. 1. For information on eligible approvers for merge requests, see [Eligible approvers](project/merge_requests/merge_request_approvals.md#eligible-approvers). 1. Owner permission is only available at the group or personal namespace level (and for instance admins) and is inherited by its projects. +1. Applies only to comments on [Design Management](project/issues/design_management.md) designs. +1. Users can only view events based on their individual actions. ## Project features permissions @@ -233,7 +243,7 @@ read through the documentation on [permissions and access to confidential issues ## Group members permissions -NOTE: **Note:** +NOTE: In GitLab 11.0, the Master role was renamed to Maintainer. Any user can remove themselves from a group, unless they are the last Owner of @@ -245,8 +255,8 @@ group. | Browse group | ✓ | ✓ | ✓ | ✓ | ✓ | | View group wiki pages **(PREMIUM)** | ✓ (6) | ✓ | ✓ | ✓ | ✓ | | View Insights charts **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View group epic **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| Create/edit group epic **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| View group epic **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| Create/edit group epic **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | | Manage group labels | | ✓ | ✓ | ✓ | ✓ | | See a container registry | | ✓ | ✓ | ✓ | ✓ | | Pull [packages](packages/index.md) | | ✓ | ✓ | ✓ | ✓ | @@ -270,9 +280,9 @@ group. | Create/Delete group deploy tokens | | | | | ✓ | | Manage group members | | | | | ✓ | | Delete group | | | | | ✓ | -| Delete group epic **(ULTIMATE)** | | | | | ✓ | +| Delete group epic **(PREMIUM)** | | | | | ✓ | | Edit SAML SSO Billing **(SILVER ONLY)** | ✓ | ✓ | ✓ | ✓ | ✓ (4) | -| View group Audit Events | | | | | ✓ | +| View group Audit Events | | | ✓ (7) | ✓ (7) | ✓ | | Disable notification emails | | | | | ✓ | | View Contribution analytics | ✓ | ✓ | ✓ | ✓ | ✓ | | View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -281,6 +291,7 @@ group. | View Value Stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | | View Billing **(FREE ONLY)** | | | | | ✓ (4) | | View Usage Quotas **(FREE ONLY)** | | | | | ✓ (4) | +| Filter members by 2FA status | | | | | ✓ | 1. Groups can be set to [allow either Owners or Owners and Maintainers to create subgroups](group/subgroups/index.md#creating-a-subgroup) @@ -291,6 +302,7 @@ group. 1. Does not apply to subgroups. 1. Developers can push commits to the default branch of a new project only if the [default branch protection](group/index.md#changing-the-default-branch-protection-of-a-group) is set to "Partially protected" or "Not protected". 1. In addition, if your group is public or internal, all users who can see the group can also see group wiki pages. +1. Users can only view events based on their individual actions. ### Subgroup permissions @@ -329,7 +341,7 @@ always take into account the [project's visibility and permissions settings](project/settings/index.md#sharing-and-permissions) as well as the permission level of the user. -NOTE: **Note:** +NOTE: External users still count towards a license seat. An administrator can flag a user as external by either of the following methods: @@ -358,7 +370,7 @@ and the ignore case flag is set (`/regex pattern/i`). Here are some examples: - Use `^(?:(?!\.ext@domain\.com).)*$\r?` to mark users with email addresses NOT including `.ext@domain.com` as internal. -CAUTION: **Warning:** +WARNING: Be aware that this regex could lead to a [regular expression denial of service (ReDoS) attack](https://en.wikipedia.org/wiki/ReDoS). @@ -376,7 +388,7 @@ project is internal or private, Guest users have all the abilities that are mentioned in the [permissions table above](#project-members-permissions) (they are unable to browse the project's repository, for example). -TIP: **Tip:** +NOTE: To prevent a guest user from creating projects, as an admin, you can edit the user's profile to mark the user as [external](#external-users). Beware though that even if a user is external, if they already have Reporter or @@ -405,6 +417,11 @@ automatically have access to projects and subgroups underneath. To support such Users with minimal access can list the group in the UI and through the API. However, they cannot see details such as projects or subgroups. They do not have access to the group's page or list any of its subgroups or projects. +### 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. + ## Project features Project features like wiki and issues can be hidden from users depending on @@ -417,7 +434,7 @@ which visibility level you select on project settings. ## GitLab CI/CD permissions -NOTE: **Note:** +NOTE: In GitLab 11.0, the Master role was renamed to Maintainer. GitLab CI/CD permissions rely on the role the user has in GitLab. There are four @@ -451,10 +468,10 @@ instance and project. In addition, all admins can use the admin interface under ### Job permissions -NOTE: **Note:** +NOTE: In GitLab 11.0, the Master role was renamed to Maintainer. -NOTE: **Note:** +NOTE: GitLab 8.12 has a completely redesigned job permissions system. Read all about the [new model and its implications](project/new_ci_build_permissions_model.md). diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index cf5e4591a50..cdf80f722f7 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -2,7 +2,7 @@ type: reference stage: Manage group: Access -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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)** diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 637d740ab0f..e347221bd66 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Access -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Deleting a User account @@ -12,7 +12,7 @@ Users can be deleted from a GitLab instance, either by: - The user themselves. - An administrator. -NOTE: **Note:** +NOTE: Deleting a user will delete all projects in that user namespace. ## As a user @@ -35,7 +35,7 @@ As an administrator, you can delete a user account by: - **Delete user and contributions** to delete the user and their associated records. -DANGER: **Warning:** +WARNING: Using the **Delete user and contributions** option may result in removing more data than intended. Please see [associated records](#associated-records) below for additional details. diff --git a/doc/user/profile/account/index.md b/doc/user/profile/account/index.md index 56b6498e16c..b10cc778f45 100644 --- a/doc/user/profile/account/index.md +++ b/doc/user/profile/account/index.md @@ -3,3 +3,6 @@ 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 dacb6c3a5a7..c25535cbf65 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -2,14 +2,14 @@ type: howto stage: Manage group: Access -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Two-factor authentication Two-factor authentication (2FA) provides an additional level of security to your GitLab account. After being enabled, in addition to supplying your username and -password to sign in, you'll be prompted for a code generated by your one-time +password to sign in, you are prompted for a code generated by your one-time password authenticator (for example, a password manager on one of your devices). By enabling 2FA, the only way someone other than you can sign in to your account @@ -18,24 +18,25 @@ password secret. ## Overview -TIP: **Tip:** +NOTE: When you enable 2FA, don't forget to back up your [recovery codes](#recovery-codes)! In addition to time-based one time passwords (TOTP), GitLab supports U2F -(universal 2nd factor) and WebAuthn (experimental) devices as the second factor of authentication. Once -enabled, in addition to supplying your username and password to log in, you'll -be prompted to activate your U2F / WebAuthn device (usually by pressing a button on it), -and it will perform secure authentication on your behalf. +(universal 2nd factor) and WebAuthn (experimental) devices as the second factor +of authentication. After being enabled, in addition to supplying your username +and password to sign in, you're prompted to activate your U2F / WebAuthn device +(usually by pressing a button on it) which performs secure authentication on +your behalf. -It is highly recommended that you set up 2FA with both a -[one-time password authenticator](#one-time-password) or use [FortiAuthenticator](#one-time-password-via-fortiauthenticator) -and a [U2F device](#u2f-device) or a [WebAuthn device](#webauthn-device), so you can still access your account -if you lose your U2F / WebAuthn device. +It's highly recommended that you set up 2FA with both a [one-time password authenticator](#one-time-password) +or use [FortiAuthenticator](#one-time-password-via-fortiauthenticator) and a +[U2F device](#u2f-device) or a [WebAuthn device](#webauthn-device), so you can +still access your account if you lose your U2F / WebAuthn device. ## Enabling 2FA -There are multiple ways to enable two-factor authentication: via a one time password authenticator -or a U2F / WebAuthn device. +There are multiple ways to enable two-factor authentication: by using a one-time +password authenticator or a U2F / WebAuthn device. ### One-time password @@ -62,8 +63,8 @@ To enable 2FA: code** field. 1. Select **Submit**. -If the pin you entered was correct, you'll see a message indicating that -two-factor authentication has been enabled, and you'll be presented with a list +If the pin you entered was correct, a message displays indicating that +two-factor authentication has been enabled, and you're shown a list of [recovery codes](#recovery-codes). Be sure to download them and keep them in a safe place. @@ -77,7 +78,7 @@ You can use FortiAuthenticator as an OTP provider in GitLab. Users must exist in both FortiAuthenticator and GitLab with the exact same username, and users must have FortiToken configured in FortiAuthenticator. -You'll also need a username and access token for FortiAuthenticator. The +You need a username and access token for FortiAuthenticator. The `access_token` in the code samples shown below is the FortAuthenticator access key. To get the token, see the `REST API Solution Guide` at [`Fortinet Document Library`](https://docs.fortinet.com/document/fortiauthenticator/6.2.0/rest-api-solution-guide/158294/the-fortiauthenticator-api). @@ -141,6 +142,86 @@ to run the following command: Feature.enable(:forti_authenticator, User.find(<user ID>)) ``` +### One-time password via FortiToken Cloud + +> - Introduced in [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/212313). +> - 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](#enable-or-disable-fortitoken-cloud-integration). + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +You can use FortiToken Cloud as an OTP provider in GitLab. Users must exist in +both FortiToken Cloud and GitLab with the exact same username, and users must +have FortiToken configured in FortiToken Cloud. + +You'll also need a `client_id` and `client_secret` to configure FortiToken Cloud. +To get these, see the `REST API Guide` at +[`Fortinet Document Library`](https://docs.fortinet.com/document/fortitoken-cloud/20.4.d/rest-api). + +First configure FortiToken Cloud in GitLab. On your GitLab server: + +1. Open the configuration file. + + For Omnibus GitLab: + + ```shell + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```shell + cd /home/git/gitlab + sudo -u git -H editor config/gitlab.yml + ``` + +1. Add the provider configuration: + + For Omnibus package: + + ```ruby + gitlab_rails['forti_token_cloud_enabled'] = true + gitlab_rails['forti_token_cloud_client_id'] = '<your_fortinet_cloud_client_id>' + gitlab_rails['forti_token_cloud_client_secret'] = '<your_fortinet_cloud_client_secret>' + ``` + + For installations from source: + + ```yaml + forti_token_cloud: + enabled: true + client_id: YOUR_FORTI_TOKEN_CLOUD_CLIENT_ID + client_secret: YOUR_FORTI_TOKEN_CLOUD_CLIENT_SECRET + ``` + +1. Save the configuration file. +1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) + or [restart GitLab](../../../administration/restart_gitlab.md#installations-from-source) + for the changes to take effect if you installed GitLab via Omnibus or from + source respectively. + +#### Enable or disable FortiToken Cloud integration + +FortiToken Cloud integration 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(:forti_token_cloud, User.find(<user ID>)) +``` + +To disable it: + +```ruby +Feature.disable(:forti_token_cloud, User.find(<user ID>)) +``` + ### U2F device > Introduced in [GitLab 8.9](https://about.gitlab.com/blog/2016/06/22/gitlab-adds-support-for-u2f/). @@ -157,7 +238,7 @@ following desktop browsers: - Firefox 67+ - Opera -NOTE: **Note:** +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). Search for `security.webauth.u2f` and double click on it to toggle to `true`. @@ -170,9 +251,9 @@ To set up 2FA with a U2F device: 1. Click **Enable Two-Factor Authentication**. 1. Connect your U2F device. 1. Click on **Set up New U2F Device**. -1. A light will start blinking on your device. Activate it by pressing its button. +1. A light begins blinking on your device. Activate it by pressing its button. -You will see a message indicating that your device was successfully set up. +A message displays, indicating that your device was successfully set up. Click on **Register U2F Device** to complete the process. ### WebAuthn device @@ -208,23 +289,26 @@ To set up 2FA with a WebAuthn compatible device: 1. Select **Set up New WebAuthn Device**. 1. Depending on your device, you might need to press a button or touch a sensor. -You will see a message indicating that your device was successfully set up. +A message displays, indicating that your device was successfully set up. Recovery codes are not generated for WebAuthn devices. ## Recovery codes -NOTE: **Note:** +NOTE: Recovery codes are not generated for U2F / WebAuthn devices. -CAUTION: **Caution:** +WARNING: Each code can be used only once to log in to your account. -Immediately after successfully enabling two-factor authentication, you'll be +Immediately after successfully enabling two-factor authentication, you're prompted to download a set of generated recovery codes. Should you ever lose access to your one-time password authenticator, you can use one of these recovery codes to log in to your account. We suggest copying and printing them, or downloading them using the **Download codes** button for storage in a safe place. If you choose to -download them, the file will be called `gitlab-recovery-codes.txt`. +download them, the file is called `gitlab-recovery-codes.txt`. + +The UI now includes **Copy codes** and **Print codes** buttons, for your convenience. +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267730) in GitLab 13.7. If you lose the recovery codes or just want to generate new ones, you can do so from the [two-factor authentication account settings page](#regenerate-2fa-recovery-codes) or @@ -233,8 +317,8 @@ from the [two-factor authentication account settings page](#regenerate-2fa-recov ## Logging in with 2FA Enabled Logging in with 2FA enabled is only slightly different than a normal login. -Enter your username and password credentials as you normally would, and you'll -be presented with a second prompt, depending on which type of 2FA you've enabled. +Enter your username and password credentials as you normally would, and you're +presented with a second prompt, depending on which type of 2FA you've enabled. ### Log in via a one-time password @@ -246,19 +330,19 @@ recovery code to log in. To log in via a U2F device: 1. Click **Login via U2F Device**. -1. A light will start blinking on your device. Activate it by touching/pressing +1. A light begins blinking on your device. Activate it by touching/pressing its button. -You will see a message indicating that your device responded to the authentication -request and you will be automatically logged in. +A message displays, indicating that your device responded to the authentication +request, and you're automatically logged in. ### Log in via WebAuthn device In supported browsers you should be automatically prompted to activate your WebAuthn device (e.g. by touching/pressing its button) after entering your credentials. -You will see a message indicating that your device responded to the authentication -request and you will be automatically logged in. +A message displays, indicating that your device responded to the authentication +request and you're automatically logged in. ## Disabling 2FA @@ -269,14 +353,14 @@ If you ever need to disable 2FA: 1. Go to **Account**. 1. Click **Disable**, under **Two-Factor Authentication**. -This will clear all your two-factor authentication registrations, including mobile +This clears all your two-factor authentication registrations, including mobile applications and U2F / WebAuthn devices. ## Personal access tokens When 2FA is enabled, you can no longer use your normal account password to authenticate with Git over HTTPS on the command line or when using -[GitLab's API](../../../api/README.md). You must use a +the [GitLab API](../../../api/README.md). You must use a [personal access token](../personal_access_tokens.md) instead. ## Recovery options @@ -312,7 +396,7 @@ a new set of recovery codes with SSH: ssh git@gitlab.example.com 2fa_recovery_codes ``` -1. You will then be prompted to confirm that you want to generate new codes. +1. You are prompted to confirm that you want to generate new codes. Continuing this process invalidates previously saved codes: ```shell @@ -357,14 +441,14 @@ To regenerate 2FA recovery codes, you need access to a desktop browser: 1. If you've already configured 2FA, click **Manage two-factor authentication**. 1. In the **Register Two-Factor Authenticator** pane, click **Regenerate recovery codes**. -NOTE: **Note:** -If you regenerate 2FA recovery codes, save them. You won't be able to use any previously created 2FA codes. +NOTE: +If you regenerate 2FA recovery codes, save them. You can't use any previously created 2FA codes. ### Ask a GitLab administrator to disable two-factor authentication on your account If you cannot use a saved recovery code or generate new recovery codes, ask a GitLab global administrator to disable two-factor authentication for your -account. This will temporarily leave your account in a less secure state. +account. This temporarily leaves your account in a less secure state. Sign in and re-enable two-factor authentication as soon as possible. ## Note to GitLab administrators diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index 4630215eca6..381015f17c3 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -32,9 +32,9 @@ exceeds 100, the oldest ones are deleted. 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. -NOTE: **Note:** +NOTE: When any session is revoked all **Remember me** tokens for all -devices will be revoked. See ['Why do I keep getting signed out?'](index.md#why-do-i-keep-getting-signed-out) +devices are revoked. See ['Why do I keep getting signed out?'](index.md#why-do-i-keep-getting-signed-out) for more information about the **Remember me** feature. <!-- ## Troubleshooting diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 37623c94eda..d60fb528499 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -2,7 +2,7 @@ type: index, howto stage: Manage group: Access -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # User account @@ -74,7 +74,7 @@ From there, you can: - Manage your [preferences](preferences.md#syntax-highlighting-theme) to customize your own GitLab experience - [View your active sessions](active_sessions.md) and revoke any of them if necessary -- Access your audit log, a security log of important events involving your account +- Access your audit events, a security log of important events involving your account ## Changing your password @@ -101,12 +101,12 @@ To change your `username`: 1. Enter a new username under **Change username**. 1. Click **Update username**. -CAUTION: **Caution:** +WARNING: It is currently 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. -TIP: **Tip:** +NOTE: If you want to retain ownership over the original namespace and protect the URL redirects, then instead of changing a group's path or renaming a username, you can create a new group and transfer projects to it. @@ -135,7 +135,7 @@ To enable private profile: 1. Check the **Private profile** option in the **Main settings** section. 1. Click **Update profile settings**. -NOTE: **Note:** +NOTE: All your profile information can be seen by yourself, and GitLab admins, even if the **Private profile** option is enabled. @@ -302,10 +302,10 @@ to get you a new `_gitlab_session` and keep you signed in through browser restar After your `remember_user_token` expires and your `_gitlab_session` is cleared/expired, you are asked to sign in again to verify your identity for security reasons. -NOTE: **Note:** +NOTE: When any session is signed out, or when a session is revoked via [Active Sessions](active_sessions.md), all **Remember me** tokens are revoked. -While other sessions will remain active, the **Remember me** feature will not restore +While other sessions remain active, the **Remember me** feature doesn't restore a session if the browser is closed or the existing session expires. ### Increased sign-in time diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index f3d27147557..8974505cf02 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -2,7 +2,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/notifications.html' 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/#designated-technical-writers +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 Notification Emails @@ -13,15 +13,15 @@ Notifications are sent via email. ## Receiving notifications -You will receive notifications for one of the following reasons: +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_. -While notifications are enabled, you will receive notification of actions occurring in that issue, merge request, or epic. +While notifications are enabled, you receive notification of actions occurring in that issue, merge request, or epic. -NOTE: **Note:** -Notifications can be blocked by an admin, preventing them from being sent. +NOTE: +Notifications can be blocked by an administrator, preventing them from being sent. ## Tuning your notifications @@ -50,7 +50,7 @@ These notification settings apply only to you. They do not affect the notificati Your **Global notification settings** are the default settings unless you select different values for a project or a group. - Notification email - - This is the email address your notifications will be sent to. + - 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 notifications about your own activity. @@ -138,7 +138,7 @@ For each project and group you can select one of the following levels: ## Notification events -Users will be notified of the following events: +Users are notified of the following events: | Event | Sent to | Settings level | |------------------------------|---------------------|------------------------------| @@ -158,7 +158,7 @@ Users will be notified of the following events: ## Issue / Epics / Merge request events -In most of the below cases, the notification will be sent to: +In most of the below cases, the notification is sent to: - Participants: - the author and assignee of the issue/merge request @@ -169,7 +169,7 @@ In most of the below cases, the notification will be sent to: - 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 -NOTE: **Note:** +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. | Event | Sent to | @@ -193,23 +193,23 @@ To minimize the number of notifications that do not require any action, from [Gi | 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. | -| 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 will be sent for the first successful pipeline after the failure, then a `Successful pipeline` message for any further successful pipelines. | +| 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 -changed, notifications will be sent to any **new** mentions by `@username` as +changed, notifications are sent to any **new** mentions by `@username` as if they had been mentioned in the original text. -You won't receive notifications for Issues, Merge Requests or Milestones created -by yourself (except when an issue is due). You will only receive automatic +You don't receive notifications for Issues, Merge Requests or Milestones created +by yourself (except when an issue is due). You only receive automatic notifications when somebody else comments or adds changes to the ones that you've created or mentions you. -If an open merge request becomes unmergeable due to conflict, its author will be notified about the cause. +If an open merge request becomes unmergeable due to conflict, its author is notified about the cause. If a user has also set the merge request to automatically merge once pipeline succeeds, -then that user will also be notified. +then that user is also notified. ## Design email notifications @@ -252,9 +252,9 @@ The `X-GitLab-NotificationReason` header contains the reason for the notificatio - `mentioned` The reason for the notification is also included in the footer of the notification email. For example an email with the -reason `assigned` will have this sentence in the footer: +reason `assigned` has this sentence in the footer: - `You are receiving this email because you have been assigned an item on <configured GitLab hostname>.` -NOTE: **Note:** +NOTE: Notification of other events is being considered for inclusion in the `X-GitLab-NotificationReason` header. For details, see this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/20689). diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 911be117716..cfc70c5a6f0 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -2,7 +2,7 @@ type: concepts, howto stage: Manage group: Access -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Personal access tokens @@ -14,7 +14,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w If you're unable to use [OAuth2](../../api/oauth2.md), you can use a personal access token to authenticate with the [GitLab API](../../api/README.md#personalproject-access-tokens). -You can also use personal access tokens with Git to authenticate over HTTP or SSH. Personal access tokens are required when [Two-Factor Authentication (2FA)](account/two_factor_authentication.md) is enabled. In both cases, you can authenticate with a token in place of your password. +You can also use personal access tokens with Git to authenticate over HTTP. Personal access tokens are required when [Two-Factor Authentication (2FA)](account/two_factor_authentication.md) is enabled. In both cases, you can authenticate with a token in place of your password. Personal access tokens expire on the date you define, at midnight UTC. @@ -91,7 +91,7 @@ This can be shortened into a single-line shell command using the sudo gitlab-rails runner "token = User.find_by_username('automation-bot').personal_access_tokens.create(scopes: [:read_user, :read_repository], name: 'Automation token'); token.set_token('token-string-here123'); token.save!" ``` -NOTE: **Note:** +NOTE: The token string must be 20 characters in length to be recognized as a valid personal access token. diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 168bcb5a42e..af7bfb80cac 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts, howto --- @@ -45,7 +45,7 @@ The default theme is Indigo. You can choose between 10 themes: GitLab has started work on dark mode! The dark mode Alpha release is available in the spirit of iteration and the lower expectations of -[Alpha versions](https://about.gitlab.com/handbook/product/#alpha). +[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: @@ -59,12 +59,12 @@ Dark mode is available as a navigation theme, for MVC and compatibility reasons. the future, we plan to make it configurable in its own section along with support for [different navigation themes](https://gitlab.com/gitlab-org/gitlab/-/issues/219512). -NOTE: **Note:** +NOTE: Dark theme currently only works with the 'Dark' syntax highlighting. ## Syntax highlighting theme -NOTE: **Note:** +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 @@ -92,7 +92,7 @@ which apply to the entire Web IDE screen. ## Behavior -The following settings allow you to customize the behavior of GitLab's layout +The following settings allow you to customize the behavior of the GitLab layout and default views of your dashboard and the projects' landing pages. ### Layout width @@ -100,15 +100,15 @@ and default views of your dashboard and the projects' landing pages. GitLab can be set up to use different widths depending on your liking. Choose between the fixed (max. `1280px`) and the fluid (`100%`) application layout. -NOTE: **Note:** +NOTE: While `1280px` is the standard max width when using fixed layout, some pages still use 100% width, depending on the content. ### Default dashboard For users who have access to a large number of projects but only keep up with a select few, the amount of activity on the default Dashboard page can be -overwhelming. Changing this setting allows you to redefine what your default -dashboard will be. +overwhelming. Changing this setting allows you to redefine your default +dashboard. You have 8 options here that you can use for your default dashboard view: @@ -142,7 +142,7 @@ see on a project’s home page. You can set the displayed width of tab characters across various parts of GitLab, for example, blobs, diffs, and snippets. -NOTE: **Note:** +NOTE: Some parts of GitLab do not respect this setting, including the WebIDE, file editor and Markdown editor. @@ -164,7 +164,7 @@ You can choose one of the following options as the first day of the week: - Sunday - Monday -If you select **System Default**, the system-wide default setting will be used. +If you select **System Default**, the system-wide default setting is used. ## Integrations @@ -172,7 +172,7 @@ Configure your preferences with third-party services which provide enhancements ### Sourcegraph -NOTE: **Note:** +NOTE: This setting is only visible if Sourcegraph has been enabled by a GitLab administrator. Manage the availability of integrated code intelligence features powered by diff --git a/doc/user/profile/unknown_sign_in_notification.md b/doc/user/profile/unknown_sign_in_notification.md index a97af3d6965..1eec351e4da 100644 --- a/doc/user/profile/unknown_sign_in_notification.md +++ b/doc/user/profile/unknown_sign_in_notification.md @@ -2,14 +2,14 @@ type: concepts, howto stage: Manage group: Access -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 notification for unknown sign-ins > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27211) in GitLab 13.0. -NOTE: **Note:** +NOTE: This feature is enabled by default for self-managed instances. Administrators may disable this feature through the [Sign-in restrictions](../admin_area/settings/sign_in_restrictions.md#email-notification-for-unknown-sign-ins) section of the UI. The feature is always enabled on GitLab.com. diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md index ff9cb1c712e..1aa040c9cb8 100644 --- a/doc/user/project/autocomplete_characters.md +++ b/doc/user/project/autocomplete_characters.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +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." --- diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index fd0287fb5fb..f7bb88c33aa 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -84,7 +84,7 @@ are available: - `%{commit_sha}`: ID of the most recent commit to the default branch of a project's repository -NOTE: **Note:** +NOTE: Placeholders allow badges to expose otherwise-private information, such as the default branch or commit SHA when the project is configured to have a private repository. This is by design, as badges are intended to be used publicly. Avoid diff --git a/doc/user/project/builds/artifacts.md b/doc/user/project/builds/artifacts.md index 1b0f3f61394..e7572b4ff1f 100644 --- a/doc/user/project/builds/artifacts.md +++ b/doc/user/project/builds/artifacts.md @@ -3,3 +3,6 @@ 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 98584a939ea..a29c0754d31 100644 --- a/doc/user/project/bulk_editing.md +++ b/doc/user/project/bulk_editing.md @@ -1,12 +1,12 @@ --- 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/#designated-technical-writers +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 --- # Bulk editing issues and merge requests at the project level -NOTE: **Note:** +NOTE: Bulk editing issues, epics, and merge requests is also available at the **group level**. For more details, see [Bulk editing issues, epics, and merge requests at the group level](../group/bulk_editing/index.md). @@ -14,14 +14,14 @@ 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: **Note:** +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: **Note:** +NOTE: You need a permission level of [Reporter or higher](../permissions.md) to manage issues. When bulk editing issues in a project, you can edit the following attributes: @@ -46,7 +46,7 @@ To update multiple project issues at the same time: ## Bulk edit merge requests at the project level -NOTE: **Note:** +NOTE: You need a permission level of [Developer or higher](../permissions.md) to 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 e9bb6d0e3ff..52c825932fa 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 **(PREMIUM)** @@ -32,13 +32,13 @@ deployments right inside the [Deploy Board](deploy_boards.md), without the need Canary deployments can be used when you want to ship features to only a portion of your pods fleet and watch their behavior as a percentage of your user base visits the temporarily deployed feature. If all works well, you can deploy the -feature to production knowing that it won't cause any problems. +feature to production knowing that it shouldn't cause any problems. Canary deployments are also especially useful for backend refactors, performance improvements, or other changes where the user interface doesn't change, but you want to make sure the performance stays the same, or improves. Developers need to be careful when using canaries with user-facing changes, because by default, -requests from the same user will be randomly distributed between canary and +requests from the same user are randomly distributed between canary and non-canary pods, which could result in confusion or even errors. If needed, you may want to consider [setting `service.spec.sessionAffinity` to `ClientIP` in your Kubernetes service definitions](https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies), but that is beyond the scope of @@ -60,7 +60,7 @@ This allows GitLab to discover whether a deployment is stable or canary (tempora Once all of the above are set up and the pipeline has run at least once, navigate to the environments page under **Pipelines > Environments**. -As the pipeline executes Deploy Boards will clearly mark canary pods, enabling +As the pipeline executes, Deploy Boards clearly mark canary pods, enabling quick and easy insight into the status of each environment and deployment. Canary deployments are marked with a yellow dot in the Deploy Board so that you @@ -68,9 +68,10 @@ can easily notice them.  -### Advanced traffic control with Canary Ingress **(PREMIUM)** +### 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. +> - [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.7. 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 @@ -102,21 +103,22 @@ Here's an example setup flow from scratch: #### How to check the current traffic weight on a Canary Ingress -1. Visit [Deploy Board](../../user/project/deploy_boards.md). -1. Open your browser's inspection tool and examine a response from the `environments.json` endpoint. - You can find the current weight under `rollout_status`. +1. Visit the [Deploy Board](../../user/project/deploy_boards.md). +1. View the current weights on the right. -  - - Note that we have [a plan](https://gitlab.com/gitlab-org/gitlab/-/issues/218139) - to visualize this information in a [Deploy Board](../../user/project/deploy_boards.md) - without needing a browser's inspection tool. +  #### How to change the traffic weight on a Canary Ingress -You can change the traffic weight by using [GraphiQL](../../api/graphql/getting_started.md#graphiql) +You can change the traffic weight within your environment's Deploy Board by using [GraphiQL](../../api/graphql/getting_started.md#graphiql), or by sending requests to the [GraphQL API](../../api/graphql/getting_started.md#command-line). +To use your [Deploy Board](../../user/project/deploy_boards.md): + +1. Navigate to **Operations > Environments** for your project. +1. Set the new weight with the dropdown on the right side. +1. Confirm your selection. + Here's an example using [GraphiQL](../../api/graphql/getting_started.md#graphiql): 1. Visit [GraphiQL Explorer](https://gitlab.com/-/graphql-explorer). @@ -135,6 +137,3 @@ Here's an example using [GraphiQL](../../api/graphql/getting_started.md#graphiql 1. If the request succeeds, the `errors` response contains an empty array. GitLab sends a `PATCH` request to your Kubernetes cluster for updating the weight parameter on a Canary Ingress. - -Note that there's [a plan](https://gitlab.com/gitlab-org/gitlab/-/issues/218139) -to control the weight from a [Deploy Board](../../user/project/deploy_boards.md). diff --git a/doc/user/project/ci_cd_for_external_repo.md b/doc/user/project/ci_cd_for_external_repo.md index a92d3a2c308..57747be3859 100644 --- a/doc/user/project/ci_cd_for_external_repo.md +++ b/doc/user/project/ci_cd_for_external_repo.md @@ -3,3 +3,6 @@ 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 c3f2b96ce9f..07aa02db2b5 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 @@ -10,7 +10,7 @@ GitLab supports adding new and existing EKS clusters. ## EKS requirements -Before creating your first cluster on Amazon EKS with GitLab's integration, make sure the following +Before creating your first cluster on Amazon EKS with the GitLab integration, make sure the following requirements are met: - An [Amazon Web Services](https://aws.amazon.com/) account is set up and you are able to log in. @@ -23,9 +23,9 @@ requirements are met: ### Additional requirements for self-managed instances **(CORE ONLY)** If you are using a self-managed GitLab instance, GitLab must first be configured with a set of -Amazon credentials. These credentials will be used to assume an Amazon IAM role provided by the user +Amazon credentials. These credentials are used to assume an Amazon IAM role provided by the user creating the cluster. Create an IAM user and ensure it has permissions to assume the role(s) that -your users will use to create EKS clusters. +your users need to create EKS clusters. For example, the following policy document allows assuming a role whose name starts with `gitlab-eks-` in account `123456789012`: @@ -60,7 +60,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - Group's **Kubernetes** page, for a group-level cluster. - **Admin Area > Kubernetes**, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. -1. Under the **Create new cluster** tab, click **Amazon EKS**. You will be provided with an +1. Under the **Create new cluster** tab, click **Amazon EKS** to display an `Account ID` and `External ID` needed for later steps. 1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM policy: 1. From the left panel, select **Policies**. @@ -137,9 +137,9 @@ To create and add a new Kubernetes cluster to your project, group, or instance: 1. Click **Next: Tags**, and optionally enter any tags you wish to associate with this role. 1. Click **Next: Review**. 1. Enter a role name and optional description into the fields provided. - 1. Click **Create role**, the new role name will appear at the top. Click on its name and copy the `Role ARN` from the newly created role. + 1. Click **Create role**, the new role name displays at the top. Click on its name and copy the `Role ARN` from the newly created role. 1. In GitLab, enter the copied role ARN into the `Role ARN` field. -1. In the **Cluster Region** field, enter the [region](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) you plan to use for your new cluster. GitLab will authenticate you have access to this region when authenticating your role. +1. In the **Cluster Region** field, enter the [region](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) you plan to use for your new cluster. GitLab confirms you have access to this region when authenticating your role. 1. Click **Authenticate with AWS**. 1. Choose your cluster's settings: - **Kubernetes cluster name** - The name you wish to give the cluster. @@ -148,7 +148,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - **Service role** - Select the **EKS IAM role** you created earlier to allow Amazon EKS and the Kubernetes control plane to manage AWS resources on your behalf. - NOTE: **Note:** + NOTE: This IAM role is _not_ the IAM role you created in the previous step. It should be the one you created much earlier by following the [Amazon EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) @@ -158,7 +158,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - **VPC** - Select a [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) to use for your EKS Cluster resources. - **Subnets** - Choose the [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) - in your VPC where your worker nodes will run. You must select at least two. + in your VPC where your worker nodes run. You must select at least two. - **Security group** - Choose the [security group](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) to apply to the EKS-managed Elastic Network Interfaces that are created in your worker node subnets. - **Instance type** - The [instance type](https://aws.amazon.com/ec2/instance-types/) of your worker nodes. @@ -167,11 +167,11 @@ To create and add a new Kubernetes cluster to your project, group, or instance: See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. 1. Finally, click the **Create Kubernetes cluster** button. -After about 10 minutes, your cluster will be ready to go. You can now proceed +After about 10 minutes, your cluster is ready to go. You can now proceed to install some [pre-defined applications](index.md#installing-applications). -NOTE: **Note:** -You will need to add your AWS external ID to the +NOTE: +You must add your AWS external ID to the [IAM Role in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-xaccount) to manage your cluster using `kubectl`. @@ -205,7 +205,7 @@ If the `Cluster` resource failed with the error `The provided role doesn't have the Amazon EKS Managed Policies associated with it.`, the role specified in **Role name** is not configured correctly. -NOTE: **Note:** +NOTE: This role should be the role you created by following the [EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) guide. In addition to the policies that guide suggests, you must also include the @@ -219,9 +219,9 @@ For information on adding an existing EKS cluster, see ### Create a default Storage Class Amazon EKS doesn't have a default Storage Class out of the box, which means -requests for persistent volumes will not be automatically fulfilled. As part +requests for persistent volumes are not automatically fulfilled. As part of Auto DevOps, the deployed PostgreSQL instance requests persistent storage, -and without a default storage class it will fail to start. +and without a default storage class it cannot start. If a default Storage Class doesn't already exist and is desired, follow Amazon's [guide on storage classes](https://docs.aws.amazon.com/eks/latest/userguide/storage-classes.html) @@ -239,18 +239,17 @@ to build, test, and deploy the app. [Enable Auto DevOps](../../../topics/autodevops/index.md#at-the-project-level) if not already enabled. If a wildcard DNS entry was created resolving to the Load Balancer, enter it in the `domain` field under the Auto DevOps settings. -Otherwise, the deployed app will not be externally available outside of the cluster. +Otherwise, the deployed app isn't externally available outside of the cluster.  -A new pipeline will automatically be created, which will begin to build, test, -and deploy the app. +GitLab creates a new pipeline, which begins to build, test, and deploy the app. -After the pipeline has finished, your app will be running in EKS and available +After the pipeline has finished, your app runs in EKS, and is available to users. Click on **CI/CD > Environments**.  -You will see a list of the environments and their deploy status, as well as +GitLab displays a list of the environments and their deploy status, as well as options to browse to the app, view monitoring metrics, and even access a shell on the running pod. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 720f9bdf253..e3e6efc887f 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 @@ -10,7 +10,7 @@ GitLab supports adding new and existing GKE clusters. ## GKE requirements -Before creating your first cluster on Google GKE with GitLab's integration, make sure the following +Before creating your first cluster on Google GKE with GitLab integration, make sure the following requirements are met: - A [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) @@ -33,7 +33,7 @@ Note the following: created by GitLab are RBAC-enabled. Take a look at the [RBAC section](add_remove_clusters.md#rbac-cluster-resources) for more information. - Starting from [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18341), the - cluster's pod address IP range will be set to /16 instead of the regular /14. /16 is a CIDR + cluster's pod address IP range is set to `/16` instead of the regular `/14`. `/16` is a CIDR notation. - GitLab requires basic authentication enabled and a client certificate issued for the cluster to set up an [initial service account](add_remove_clusters.md#access-controls). In [GitLab versions @@ -57,20 +57,20 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - **Kubernetes cluster name** - The name you wish to give the cluster. - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope) to this cluster. - **Google Cloud Platform project** - Choose the project you created in your GCP - console that will host the Kubernetes cluster. Learn more about + console to host the Kubernetes cluster. Learn more about [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). - **Zone** - Choose the [region zone](https://cloud.google.com/compute/docs/regions-zones/) - under which the cluster will be created. + under which to create the cluster. - **Number of nodes** - Enter the number of nodes you wish the cluster to have. - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types) - of the Virtual Machine instance that the cluster will be based on. + of the Virtual Machine instance to base the cluster on. - **Enable Cloud Run for Anthos** - Check this if you want to use Cloud Run for Anthos for this cluster. See the [Cloud Run for Anthos section](#cloud-run-for-anthos) for more information. - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. 1. Finally, click the **Create Kubernetes cluster** button. -After a couple of minutes, your cluster will be ready to go. You can now proceed +After a couple of minutes, your cluster is ready. You can now proceed to install some [pre-defined applications](index.md#installing-applications). ### Cloud Run for Anthos @@ -79,7 +79,7 @@ to install some [pre-defined applications](index.md#installing-applications). You can choose to use Cloud Run for Anthos in place of installing Knative and Istio separately after the cluster has been created. This means that Cloud Run -(Knative), Istio, and HTTP Load Balancing will be enabled on the cluster at +(Knative), Istio, and HTTP Load Balancing are enabled on the cluster at create time and cannot be [installed or uninstalled](../../clusters/applications.md) separately. ## Existing GKE cluster diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index c96e38b1dfc..8ee9b1f37dd 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 @@ -13,16 +13,16 @@ GitLab offers integrated cluster creation for the following Kubernetes providers GitLab can also integrate with any standard Kubernetes provider, either on-premise or hosted. -NOTE: **Note:** +NOTE: Watch the webcast [Scalable app deployment with GitLab and Google Cloud Platform](https://about.gitlab.com/webcast/scalable-app-deploy/) and learn how to spin up a Kubernetes cluster managed by Google Cloud Platform (GCP) in a few clicks. -TIP: **Tip:** +NOTE: Every new Google Cloud Platform (GCP) account receives [$300 in credit upon sign up](https://console.cloud.google.com/freetrial). In partnership with Google, GitLab is able to offer an additional $200 for new GCP -accounts to get started with GitLab's Google Kubernetes Engine Integration. +accounts to get started with the GitLab integration with Google Kubernetes Engine. [Follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form) to apply for credit. @@ -260,7 +260,7 @@ To add a Kubernetes cluster to your project, group, or instance: kubectl apply -f gitlab-admin-service-account.yaml --username=admin --password=<password> ``` - NOTE: **Note:** + NOTE: Basic Authentication can be turned on and the password credentials can be obtained using the Google Cloud Console. @@ -295,7 +295,7 @@ To add a Kubernetes cluster to your project, group, or instance: token: <authentication_token> ``` - NOTE: **Note:** + NOTE: For GKE clusters, you need the `container.clusterRoleBindings.create` permission to create a cluster role binding. You can follow the [Google Cloud @@ -330,7 +330,7 @@ integration to work properly.  -CAUTION: **Caution:** +WARNING: Disabling RBAC means that any application running in the cluster, or user who can authenticate to the cluster, has full API access. This is a [security concern](index.md#security-implications), and may not be desirable. diff --git a/doc/user/project/clusters/eks_and_gitlab/index.md b/doc/user/project/clusters/eks_and_gitlab/index.md index 895b51ea9bb..e38fbb871c1 100644 --- a/doc/user/project/clusters/eks_and_gitlab/index.md +++ b/doc/user/project/clusters/eks_and_gitlab/index.md @@ -3,3 +3,6 @@ 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 9273fb7b361..80db1c960db 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -1,7 +1,7 @@ --- stage: Monitor 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/#designated-technical-writers +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 @@ -20,7 +20,7 @@ Using the GitLab project Kubernetes integration, you can: - Detect and [monitor Kubernetes](#monitoring-your-kubernetes-cluster). - Use it with [Auto DevOps](#auto-devops). - Use [Web terminals](#web-terminals). -- Use [Deploy Boards](#deploy-boards). **(PREMIUM)** +- Use [Deploy Boards](#deploy-boards). - Use [Canary Deployments](#canary-deployments). **(PREMIUM)** - Use [deployment variables](#deployment-variables). - Use [role-based or attribute-based access controls](add_remove_clusters.md#access-controls). @@ -45,18 +45,18 @@ versions at any given time. We regularly review the versions we support, and provide a three-month deprecation period before we remove support of a specific version. The range of supported versions is based on the evaluation of: -- Our own needs. - The versions supported by major managed Kubernetes providers. - The versions [supported by the Kubernetes community](https://kubernetes.io/docs/setup/release/version-skew-policy/#supported-versions). GitLab supports the following Kubernetes versions, and you can upgrade your Kubernetes version to any supported version at any time: -- 1.17 -- 1.16 -- 1.15 +- 1.19 (support ends on February 22, 2022) +- 1.18 (support ends on November 22, 2021) +- 1.17 (support ends on September 22, 2021) +- 1.16 (support ends on July 22, 2021) +- 1.15 (support ends on May 22, 2021) - 1.14 (deprecated, support ends on December 22, 2020) -- 1.13 (deprecated, support ends on November 22, 2020) Some GitLab features may support versions outside the range provided here. @@ -66,7 +66,7 @@ See [Adding and removing Kubernetes clusters](add_remove_clusters.md) for detail to: - Create a cluster in Google Cloud Platform (GCP) or Amazon Elastic Kubernetes Service - (EKS) using GitLab's UI. + (EKS) using the GitLab UI. - Add an integration to an existing cluster from any Kubernetes platform. ### Multiple Kubernetes clusters @@ -79,8 +79,8 @@ 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 -[set an environment scope](#setting-the-environment-scope) that will -differentiate the new cluster with the rest. +[set an environment scope](#setting-the-environment-scope) that +differentiates the new cluster from the rest. #### Setting the environment scope @@ -89,9 +89,9 @@ them with an environment scope. The environment scope associates clusters with [ [environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables) work. The default environment scope is `*`, which means all jobs, regardless of their -environment, will use that cluster. Each scope can only be used by a single -cluster in a project, and a validation error will occur if otherwise. -Also, jobs that don't have an environment keyword set will not be able to access any cluster. +environment, use that cluster. Each scope can be used only by a single cluster +in a project, and a validation error occurs if otherwise. Also, jobs that don't +have an environment keyword set can't access any cluster. For example, let's say the following Kubernetes clusters exist in a project: @@ -127,13 +127,13 @@ deploy to production: url: https://example.com/ ``` -The result will then be: +The results: -- The Development cluster details will be available in the `deploy to staging` +- The Development cluster details are available in the `deploy to staging` job. -- The production cluster details will be available in the `deploy to production` +- The production cluster details are available in the `deploy to production` job. -- No cluster details will be available in the `test` job because it doesn't +- No cluster details are available in the `test` job because it doesn't define any environment. ## Configuring your Kubernetes cluster @@ -143,7 +143,7 @@ important considerations for configuring Kubernetes clusters with GitLab. ### Security implications -CAUTION: **Important:** +WARNING: The whole cluster security is based on a model where [developers](../../permissions.md) are trusted, so **only trusted users should be allowed to control your clusters**. @@ -157,15 +157,15 @@ applications running on the cluster. > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 11.5. > - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26565) in GitLab 11.11. -You can choose to allow GitLab to manage your cluster for you. If your cluster is -managed by GitLab, resources for your projects will be automatically created. See the -[Access controls](add_remove_clusters.md#access-controls) section for details on which resources will -be created. +You can choose to allow GitLab to manage your cluster for you. If your cluster +is managed by GitLab, resources for your projects are automatically created. See +the [Access controls](add_remove_clusters.md#access-controls) section for +details about the created resources. -If you choose to manage your own cluster, project-specific resources will not be created -automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you will -need to explicitly provide the `KUBE_NAMESPACE` [deployment variable](#deployment-variables) -that will be used by your deployment jobs, otherwise a namespace will be created for you. +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. #### Important notes @@ -198,10 +198,10 @@ To clear the cache: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24580) in GitLab 11.8. You do not need to specify a base domain on cluster settings when using GitLab Serverless. The domain in that case -will be specified as part of the Knative installation. See [Installing Applications](#installing-applications). +is specified as part of the Knative installation. See [Installing Applications](#installing-applications). -Specifying a base domain will automatically set `KUBE_INGRESS_BASE_DOMAIN` as an environment variable. -If you are using [Auto DevOps](../../../topics/autodevops/index.md), this domain will be used for the different +Specifying a base domain automatically sets `KUBE_INGRESS_BASE_DOMAIN` as an environment variable. +If you are using [Auto DevOps](../../../topics/autodevops/index.md), this domain is used for the different stages. For example, Auto Review Apps and Auto Deploy. The domain should have a wildcard DNS configured to the Ingress IP address. After Ingress has been installed (see [Installing Applications](#installing-applications)), @@ -224,7 +224,7 @@ 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) you will need the Kubernetes project integration enabled, but +Auto Monitoring) the Kubernetes project integration must be enabled, but Kubernetes clusters can be used without Auto DevOps. [Read more about Auto DevOps](../../../topics/autodevops/index.md) @@ -237,8 +237,8 @@ A Kubernetes cluster can be the destination for a deployment job. If [deployment variables](#deployment-variables) are made available to your job and configuration is not required. You can immediately begin interacting with the cluster from your jobs using tools such as `kubectl` or `helm`. -- You don't use GitLab's cluster integration you can still deploy to your - cluster. However, you will need configure Kubernetes tools yourself +- 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) before you can interact with the cluster from your jobs. @@ -257,14 +257,14 @@ The Kubernetes cluster integration exposes the following GitLab CI/CD build environment to deployment jobs, which are jobs that have [defined a target environment](../../../ci/environments/index.md#defining-environments). -| Variable | Description | -| -------- | ----------- | -| `KUBE_URL` | Equal to the API URL. | -| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main service account of the cluster integration. | -| `KUBE_NAMESPACE` | The namespace associated with the project's deployment service account. In the format `<project_name>-<project_id>-<environment>`. For GitLab-managed clusters, a matching namespace is automatically created by GitLab in the cluster. If your cluster was created before GitLab 12.2, the default `KUBE_NAMESPACE` is set to `<project_name>-<project_id>`. | -| `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. | -| `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. | -| `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This configuration also embeds the same token defined in `KUBE_TOKEN` so you likely will only need this variable. This variable name is also automatically picked up by `kubectl` so you won't actually need to reference it explicitly if using `kubectl`. | +| Variable | Description | +|----------------------------|-------------| +| `KUBE_URL` | Equal to the API URL. | +| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main service account of the cluster integration. | +| `KUBE_NAMESPACE` | The namespace associated with the project's deployment service account. In the format `<project_name>-<project_id>-<environment>`. For GitLab-managed clusters, a matching namespace is automatically created by GitLab in the cluster. If your cluster was created before GitLab 12.2, the default `KUBE_NAMESPACE` is set to `<project_name>-<project_id>`. | +| `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. | +| `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. | +| `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This configuration also embeds the same token defined in `KUBE_TOKEN` so you likely need only this variable. This variable name is also automatically picked up by `kubectl` so you don't need to reference it explicitly if using `kubectl`. | | `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, this variable can be used to set a domain per cluster. See [cluster domains](#base-domain) for more information. | ### Custom namespace @@ -294,7 +294,7 @@ You can customize the deployment namespace in a few ways: When you customize the namespace, existing environments remain linked to their current namespaces until you [clear the cluster cache](#clearing-the-cluster-cache). -CAUTION: **Warning:** +WARNING: By default, anyone who can create a deployment job can access any CI variable within an environment's deployment job. This includes `KUBECONFIG`, which gives access to any secret available to the associated service account in your cluster. @@ -316,9 +316,9 @@ the need to leave GitLab. [Read more about Canary Deployments](../canary_deployments.md) -#### Deploy Boards **(PREMIUM)** +#### Deploy Boards -GitLab's Deploy Boards offer a consolidated view of the current health and +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 teammates can view the progress and status of a rollout, pod by pod, in the @@ -362,7 +362,7 @@ the deployment job: - A namespace. - A service account. -However, sometimes GitLab can not create them. In such instances, your job will fail with the message: +However, sometimes GitLab can not create them. In such instances, your job can fail with the message: ```plaintext This job failed because the necessary resources were not successfully created. @@ -376,9 +376,9 @@ Reasons for failure include: privileges required by GitLab. - Missing `KUBECONFIG` or `KUBE_TOKEN` variables. To be passed to your job, they must have a matching [`environment:name`](../../../ci/environments/index.md#defining-environments). If your job has no - `environment:name` set, it will not be passed the Kubernetes credentials. + `environment:name` set, the Kubernetes credentials are not passed to it. -NOTE: **Note:** +NOTE: Project-level clusters upgraded from GitLab 12.0 or older may be configured in a way that causes this error. Ensure you deselect the [GitLab-managed cluster](#gitlab-managed-clusters) option if you want to manage @@ -396,6 +396,6 @@ Automatically detect and monitor Kubernetes metrics. Automatic monitoring of > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4701) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/208224) to GitLab Core in 13.2. -When [Prometheus is deployed](#installing-applications), GitLab will automatically monitor the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start. +When [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 2e224208eb8..2523dc3e0a2 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -1,7 +1,7 @@ --- stage: Monitor 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/#designated-technical-writers +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 diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index c1e4e821efd..332c1f35d89 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 @@ -25,7 +25,7 @@ pre-written code blocks or database queries against a given environment. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45912) in GitLab 11.4. -The JupyterHub app offered via GitLab’s Kubernetes integration now ships +The JupyterHub app offered via the GitLab Kubernetes integration now ships with Nurtch’s Rubix library, providing a simple way to create DevOps runbooks. A sample runbook is provided, showcasing common operations. While Rubix makes it simple to create common Kubernetes and AWS workflows, you can @@ -37,11 +37,11 @@ for an overview of how this is accomplished in GitLab! ## Requirements -To create an executable runbook, you will need: +To create an executable runbook, you need: - **Kubernetes** - A Kubernetes cluster is required to deploy the rest of the applications. The simplest way to get started is to add a cluster using one - of [GitLab's integrations](../add_remove_clusters.md#create-new-cluster). + of the [GitLab integrations](../add_remove_clusters.md#create-new-cluster). - **Ingress** - Ingress can provide load balancing, SSL termination, and name-based virtual hosting. It acts as a web proxy for your applications. - **JupyterHub** - [JupyterHub](https://jupyterhub.readthedocs.io/) is a multi-user @@ -71,7 +71,7 @@ the components outlined above and the pre-loaded demo runbook.  1. After Ingress has been installed successfully, click the **Install** button next - to the **JupyterHub** application. You will need the **Jupyter Hostname** provided + to the **JupyterHub** application. You need the **Jupyter Hostname** provided here in the next step.  @@ -84,8 +84,8 @@ the components outlined above and the pre-loaded demo runbook.  -1. Click **Authorize**, and you will be redirected to the JupyterHub application. -1. Click **Start My Server**, and the server will start in a few seconds. +1. Click **Authorize**, and GitLab redirects you to the JupyterHub application. +1. Click **Start My Server** to start the server in a few seconds. 1. To configure the runbook's access to your GitLab project, you must enter your [GitLab Access Token](../../../profile/personal_access_tokens.md) and your Project ID in the **Setup** section of the demo runbook: diff --git a/doc/user/project/clusters/securing.md b/doc/user/project/clusters/securing.md index 2d74f67ba35..fa80bd6423b 100644 --- a/doc/user/project/clusters/securing.md +++ b/doc/user/project/clusters/securing.md @@ -1,7 +1,7 @@ --- stage: Protect group: Container Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Securing your deployed applications @@ -40,7 +40,7 @@ Minimum requirements (depending on the GitLab Manage Application you want to ins ### Understanding how GitLab Managed Apps are installed -NOTE: **Note:** +NOTE: These diagrams use the term _Kubernetes_ for simplicity. In practice, Sidekiq connects to a Helm command runner pod in the cluster. diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 0de0fd38336..a52d3400aa2 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 @@ -29,7 +29,7 @@ Alternatively, you can quickly [create a new project with a template](../../../. ### Example -In the following example, you will: +This example shows you how to: 1. Create a basic AWS Lambda Node.js function. 1. Link the function to an API Gateway `GET` endpoint. @@ -49,7 +49,7 @@ Lets take it step by step. #### Creating a Lambda handler function -Your Lambda function will be the primary handler of requests. In this case we will create a very simple Node.js `hello` function: +Your Lambda function is the primary handler of requests. In this case, create a very simple Node.js `hello` function: ```javascript 'use strict'; @@ -72,13 +72,13 @@ Place this code in the file `src/handler.js`. `src` is the standard location for serverless functions, but is customizable should you desire that. -In our case, `module.exports.hello` defines the `hello` handler that will be referenced later in the `serverless.yml` +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> #### Creating a `serverless.yml` file -In the root of your project, create a `serverless.yml` file that will contain configuration specifics for the Serverless Framework. +In the root of your project, create a `serverless.yml` file containing configuration specifics for the Serverless Framework. Put the following code in the file: @@ -97,9 +97,9 @@ functions: Our function contains a handler and a event. -The handler definition will provision the Lambda function using the source code located `src/handler.hello`. +The handler definition provisions the Lambda function using the source code located `src/handler.hello`. -The `events` declaration will create a AWS API Gateway `GET` endpoint to receive external requests and hand them over to the Lambda function via a service integration. +The `events` declaration creates an AWS API Gateway `GET` endpoint to receive external requests and hand them over to the Lambda function via a service integration. You can read more about the [available properties and additional configuration possibilities](https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml/) of the Serverless Framework. @@ -141,10 +141,10 @@ For more information please see [Create a custom variable in the UI](../../../.. #### Deploying your function -`git push` the changes to your GitLab repository and the GitLab build pipeline will automatically deploy your function. +`git push` the changes to your GitLab repository and the GitLab build pipeline deploys your function. -In your GitLab deploy stage log, there will be output containing your AWS Lambda endpoint URL. -The log line will look similar to this: +Your GitLab deploy stage log contains output containing your AWS Lambda endpoint URL, +with log lines similar to this: ```plaintext endpoints: @@ -157,7 +157,7 @@ Running the following `curl` command should trigger your function. Your URL should be the one retrieved from the GitLab deploy stage log: ```shell -curl https://u768nzby1j.execute-api.us-east-1.amazonaws.com/production/hello +curl "https://u768nzby1j.execute-api.us-east-1.amazonaws.com/production/hello" ``` That should output: @@ -200,7 +200,7 @@ The `serverless-offline` plugin allows to run your code locally. To run your cod Running the following `curl` command should trigger your function. ```shell -curl http://localhost:3000/hello +curl "http://localhost:3000/hello" ``` It should output: @@ -227,9 +227,9 @@ provider: ``` From there, you can reference them in your functions as well. -Remember to add `A_VARIABLE` to your GitLab CI/CD variables under **Settings > CI/CD > Variables**, and it will get picked up and deployed with your function. +Remember to add `A_VARIABLE` to your GitLab CI/CD variables under **Settings > CI/CD > Variables** to be picked up and deployed with your function. -NOTE: **Note:** +NOTE: Anyone with access to the AWS environment may be able to see the values of those variables persisted in the lambda definition. @@ -309,7 +309,7 @@ GitLab allows developers to build and deploy serverless applications using the c ### Example -In the following example, you will: +This example shows you how to: - Install SAM CLI. - Create a sample SAM application including a Lambda function and API Gateway. @@ -414,8 +414,8 @@ Let’s examine the configuration file more closely: ### Deploying your application -Push changes to your GitLab repository and the GitLab build pipeline will automatically -deploy your application. If your: +Push changes to your GitLab repository and the GitLab build pipeline +deploys your application. If your: - Build and deploy are successful, [test your deployed application](#testing-the-deployed-application). - Build fails, look at the build log to see why the build failed. Some common reasons @@ -444,7 +444,7 @@ To test the application you deployed, please go to the build log and follow the 1. Use curl to test the API. For example: ```shell - curl https://py4rg7qtlg.execute-api.us-east-1.amazonaws.com/Prod/hello/ + curl "https://py4rg7qtlg.execute-api.us-east-1.amazonaws.com/Prod/hello/" ``` Output should be: @@ -496,7 +496,7 @@ listening on `localhost:3000`. Call the `hello` API by running: ```shell -curl http://127.0.0.1:3000/hello +curl "http://127.0.0.1:3000/hello" ``` Output again should be: diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 603c4bd73b1..fcbf85121b2 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -1,15 +1,15 @@ --- 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/#designated-technical-writers +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 > Introduced in GitLab 11.5. -CAUTION: **Caution:** -Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/#alpha). +WARNING: +Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). ## Overview @@ -39,9 +39,9 @@ With GitLab Serverless, you can deploy both functions-as-a-service (FaaS) and se ## Prerequisites -To run Knative on GitLab, you will need: +To run Knative on GitLab, you need: -1. **Existing GitLab project:** You will need a GitLab project to associate all resources. The simplest way to get started: +1. **Existing GitLab project:** You need a GitLab project to associate all resources. The simplest way to get started: - If you are planning on [deploying functions](#deploying-functions), clone the [functions example project](https://gitlab.com/knative-examples/functions) to get started. @@ -49,21 +49,21 @@ To run Knative on GitLab, you will need: clone the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. 1. **Kubernetes Cluster:** An RBAC-enabled Kubernetes cluster is required to deploy Knative. - The simplest way to get started is to add a cluster using GitLab's [GKE integration](../add_remove_clusters.md). + The simplest way to get started is to add a cluster using the GitLab [GKE integration](../add_remove_clusters.md). The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory. -1. **GitLab Runner:** A runner is required to run the CI jobs that will deploy serverless +1. **GitLab Runner:** A runner is required to run the CI jobs that deploy serverless applications or functions onto your cluster. You can install GitLab Runner onto the existing Kubernetes cluster. See [Installing Applications](../index.md#installing-applications) for more information. -1. **Domain Name:** Knative will provide its own load balancer using Istio. It will provide an - external IP address or hostname for all the applications served by Knative. You will be prompted to enter a - wildcard domain where your applications will be served. Configure your DNS server to use the +1. **Domain Name:** Knative provides its own load balancer using Istio, and an + external IP address or hostname for all the applications served by Knative. Enter a + wildcard domain to serve your applications. Configure your DNS server to use the external IP address or hostname for that domain. 1. **`.gitlab-ci.yml`:** GitLab uses [Kaniko](https://github.com/GoogleContainerTools/kaniko) to build the application. We also use [GitLab Knative tool](https://gitlab.com/gitlab-org/gitlabktl) CLI to simplify the deployment of services and functions to Knative. 1. **`serverless.yml`** (for [functions only](#deploying-functions)): When using serverless to deploy functions, the `serverless.yml` file - will contain the information for all the functions being hosted in the repository as well as a reference to the - runtime being used. + contains the information for all the functions being hosted in the repository as well as a reference + to the runtime being used. 1. **`Dockerfile`** (for [applications only](#deploying-serverless-applications)): Knative requires a `Dockerfile` in order to build your applications. It should be included at the root of your project's repository and expose port `8080`. `Dockerfile` is not require if you plan to build serverless functions @@ -73,7 +73,7 @@ To run Knative on GitLab, you will need: 1. **Logging** (optional): Configuring logging allows you to view and search request logs for your serverless function/application. See [Configuring logging](#configuring-logging) for more information. -## Installing Knative via GitLab's Kubernetes integration +## Installing Knative via the GitLab Kubernetes integration The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB memory. **RBAC must be enabled.** @@ -87,12 +87,12 @@ memory. **RBAC must be enabled.** 1. After the Knative installation has finished, you can wait for the IP address or hostname to be displayed in the **Knative Endpoint** field or [retrieve the Istio Ingress Endpoint manually](../../../clusters/applications.md#determining-the-external-endpoint-manually). - NOTE: **Note:** + NOTE: Running `kubectl` commands on your cluster requires setting up access to the cluster first. For clusters created on GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl), for other platforms [Install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). -1. The Ingress is now available at this address and will route incoming requests to the proper service based on the DNS +1. The Ingress is now available at this address and routes incoming requests to the proper service based on the DNS name in the request. To support this, a wildcard DNS record should be created for the desired domain name. For example, if your Knative base domain is `knative.info` then you need to create an A record or CNAME record with domain `*.knative.info` pointing the IP address or hostname of the Ingress. @@ -107,7 +107,7 @@ on a given project, but not both. The current implementation makes use of a > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58941) in GitLab 12.0. -The _invocations_ monitoring feature of GitLab serverless won't work when +The _invocations_ monitoring feature of GitLab serverless is unavailable when adding an existing installation of Knative. It's also possible to use GitLab Serverless with an existing Kubernetes cluster @@ -121,9 +121,9 @@ which already has Knative installed. You must do the following: - For a non-GitLab managed cluster, ensure that the service account for the token provided can manage resources in the `serving.knative.dev` API group. - For a GitLab managed cluster, if you added the cluster in [GitLab 12.1 or later](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30235), - then GitLab will already have the required access and you can proceed to the next step. + then GitLab already has the required access and you can proceed to the next step. - Otherwise, you need to manually grant GitLab's service account the ability to manage + Otherwise, you need to manually grant the GitLab service account the ability to manage resources in the `serving.knative.dev` API group. Since every GitLab service account has the `edit` cluster role, the simplest way to do this is with an [aggregated ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles) @@ -234,12 +234,12 @@ Follow these steps to deploy a function using the Node.js runtime to your Knative instance (you can skip these steps if you've cloned the example project): -1. Create a directory that will house the function. In this example we will +1. Create a directory to house the function. In this example we will create a directory called `echo` at the root of the project. -1. Create the file that will contain the function code. In this example, our file is called `echo.js` and is located inside the `echo` directory. If your project is: +1. Create the file to contain the function code. In this example, our file is called `echo.js` and is located inside the `echo` directory. If your project is: - Public, continue to the next step. - - Private, you will need to [create a GitLab deploy token](../../deploy_tokens/index.md#creating-a-deploy-token) with `gitlab-deploy-token` as the name and the `read_registry` scope. + - Private, you must [create a GitLab deploy token](../../deploy_tokens/index.md#creating-a-deploy-token) with `gitlab-deploy-token` as the name and the `read_registry` scope. 1. `.gitlab-ci.yml`: this defines a pipeline used to deploy your functions. It must be included at the root of your repository: @@ -304,7 +304,7 @@ Explanation of the fields used above: | Parameter | Description | |-----------|-------------| -| `service` | Name for the Knative service which will serve the function. | +| `service` | Name for the Knative service which serves the function. | | `description` | A short description of the `service`. | ### `provider` @@ -349,9 +349,9 @@ The optional `runtime` parameter can refer to one of the following runtime alias | `openfaas/classic/ruby` | OpenFaaS | After the `gitlab-ci.yml` template has been added and the `serverless.yml` file -has been created, pushing a commit to your project will result in a CI pipeline -being executed which will deploy each function as a Knative service. Once the -deploy stage has finished, additional details for the function will appear +has been created, pushing a commit to your project results in a CI pipeline +being executed which deploys each function as a Knative service. After the +deploy stage has finished, additional details for the function display under **Operations > Serverless**.  @@ -376,7 +376,7 @@ The sample function can now be triggered from any HTTP client using a simple `PO --header "Content-Type: application/json" \ --request POST \ --data '{"GitLab":"FaaS"}' \ - http://functions-echo.functions-1.functions.example.com/ + "http://functions-echo.functions-1.functions.example.com/" ``` 1. Using a web-based tool (such as Postman or Restlet) @@ -443,14 +443,13 @@ To run a function locally: 1. Invoke your function: ```shell - curl http://localhost:8080 + curl "http://localhost:8080" ``` ## Deploying Serverless applications > Introduced in GitLab 11.5. -12345678901234567890123456789012345678901234567890123456789012345678901234567890 Serverless applications are an alternative to [serverless functions](#deploying-functions). They're useful in scenarios where an existing runtime does not meet the needs of an application, such as one written in a language that has no runtime available. @@ -482,7 +481,7 @@ A `serverless.yml` file is not required when deploying serverless applications. ### Deploy the application with Knative -With all the pieces in place, the next time a CI pipeline runs, the Knative application will be deployed. Navigate to +With all the pieces in place, the next time a CI pipeline runs the Knative application deploys. Navigate to **CI/CD > Pipelines** and click the most recent pipeline. ### Function details @@ -498,13 +497,13 @@ rows to bring up the function details page.  -The pod count will give you the number of pods running the serverless function instances on a given cluster. +The pod count gives you the number of pods running the serverless function instances on a given cluster. For the Knative function invocations to appear, [Prometheus must be installed](../index.md#installing-applications). Once Prometheus is installed, a message may appear indicating that the metrics data _is -loading or is not available at this time._ It will appear upon the first access of the +loading or is not available at this time._ It appears upon the first access of the page, but should go away after a few seconds. If the message does not disappear, then it is possible that GitLab is unable to connect to the Prometheus instance running on the cluster. @@ -558,7 +557,7 @@ Or: ## Enabling TLS for Knative services -By default, a GitLab serverless deployment will be served over `http`. To serve +By default, a GitLab serverless deployment is served over `http`. To serve over `https`, you must manually obtain and install TLS certificates. 12345678901234567890123456789012345678901234567890123456789012345678901234567890 @@ -647,7 +646,7 @@ or with other versions of Python. ``` 1. Create certificate and private key files. Using the contents of the files - returned by Certbot, we'll create two files in order to create the + returned by Certbot, create two files in order to create the Kubernetes secret: Run the following command to see the contents of `fullchain.pem`: @@ -767,7 +766,7 @@ or with other versions of Python. 1. Create a Kubernetes secret to hold your TLS certificate, `cert.pem`, and the private key `cert.pk`: - NOTE: **Note:** + NOTE: Running `kubectl` commands on your cluster requires setting up access to the cluster first. For clusters created on GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl). @@ -828,8 +827,8 @@ or with other versions of Python. ``` After your changes are running on your Knative cluster, you can begin using the HTTPS protocol for secure access your deployed Knative services. - In the event a mistake is made during this process and you need to update the cert, you will need to edit the gateway `knative-ingress-gateway` - to switch back to `PASSTHROUGH` mode. Once corrections are made, edit the file again so the gateway will use the new certificates. + In the event a mistake is made during this process and you need to update the cert, you must edit the gateway `knative-ingress-gateway` + to switch back to `PASSTHROUGH` mode. Once corrections are made, edit the file again so the gateway uses the new certificates. ## Using an older version of `gitlabktl` diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index 5f96f65ea06..19dc3588162 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +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 --- diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 37ebef3a26e..d0e89400d88 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +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 --- @@ -112,7 +112,7 @@ in the `.gitignore` file followed by one or more of: - A user's `@username`. - A user's email address. - The `@name` of one or more groups that should be owners of the file. -- Lines starting with `#` are escaped. +- 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. diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md index 91c9d3171dc..17e86b6d7e8 100644 --- a/doc/user/project/container_registry.md +++ b/doc/user/project/container_registry.md @@ -3,3 +3,6 @@ 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 index 9d1cc508f63..5c235f6708b 100644 --- a/doc/user/project/cycle_analytics.md +++ b/doc/user/project/cycle_analytics.md @@ -3,3 +3,6 @@ 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 2bf35b48547..7546556a7c0 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -1,15 +1,16 @@ --- stage: Release -group: Progressive Delivery -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 +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 type: howto, reference --- -# Deploy Boards **(PREMIUM)** +# Deploy Boards **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. +> - [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.7. -GitLab's Deploy Boards offer a consolidated view of the current health and +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 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 @@ -74,7 +75,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ 1. Have a Kubernetes cluster up and running. - NOTE: **Running on OpenShift:** + NOTE: If you are using OpenShift, ensure that you're using the `Deployment` resource instead of `DeploymentConfiguration`. Otherwise, the Deploy Boards won't render correctly. For more information, read the @@ -98,7 +99,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ Kubernetes as well. The image below demonstrates how this is shown inside Kubernetes. - NOTE: **Note:** + NOTE: Matching based on the Kubernetes `app` label was removed in [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/14020). To migrate, please apply the required annotations (see above) and @@ -143,7 +144,7 @@ spec: The annotations will be applied to the deployments, replica sets, and pods. By changing the number of replicas, like `kubectl scale --replicas=3 deploy APPLICATION_NAME -n ${KUBE_NAMESPACE}`, you can follow the instances' pods from the board. -NOTE: **Note:** +NOTE: The YAML file is static. If you apply it using `kubectl apply`, you must manually provide the project and environment slugs, or create a script to replace the variables in the YAML before applying. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 4f344554016..39b790544c1 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -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 +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 type: howto, reference --- @@ -27,7 +27,7 @@ repository in automation, it's a simple solution. A drawback is that your repository could become vulnerable if a remote machine is compromised by a hacker. You should limit access to the remote machine before a deploy key is -enabled on your repository. A good rule to follow is to access only to trusted users, +enabled on your repository. A good rule to follow is to provide access only to trusted users, and make sure that the allowed users have [maintainer permissions or higher](../../permissions.md) in the GitLab project. @@ -108,7 +108,7 @@ keys that were [made available to your entire GitLab instance](#public-deploy-ke After a key is added, you can edit it to update its title, or switch between `read-only` and `read-write` access. -NOTE: **Note:** +NOTE: If you have enabled a privately or publicly accessible or deploy key for your project, and if you then update the access level for this key from `read-only` to `read-write`, the change will be only for the **current project**. @@ -134,7 +134,7 @@ Instance administrators can add public deploy keys: After adding a key, it will be 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. -NOTE: **Note:** +NOTE: The **Publicly accessible deploy keys** tab within Project's CI/CD settings only appears if there is at least one Public deploy key configured. @@ -146,7 +146,7 @@ When creating a Public deploy key, determine whether or not it can be defined fo very narrow usage, such as just a specific service, or if it needs to be defined for broader usage, such as full `read-write` access for all services. -CAUTION: **Warning:** +WARNING: Adding a public deploy key does not immediately expose any repository to it. Public deploy keys enable access from other systems, but access is not given to any project until a project maintainer chooses to make use of it. diff --git a/doc/user/project/deploy_tokens/img/deploy_tokens.png b/doc/user/project/deploy_tokens/img/deploy_tokens.png Binary files differdeleted file mode 100644 index 1981b0747bf..00000000000 --- a/doc/user/project/deploy_tokens/img/deploy_tokens.png +++ /dev/null diff --git a/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png b/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png Binary files differnew file mode 100644 index 00000000000..83f59b8f6f0 --- /dev/null +++ b/doc/user/project/deploy_tokens/img/deploy_tokens_ui.png diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 1ac528ca4ae..ac19c44c58a 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -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 +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 type: howto --- @@ -18,6 +18,8 @@ container registry images of a project without having a user and a password. Deploy tokens can be managed by [maintainers only](../../permissions.md). +Deploy tokens cannot be used with the GitLab API. + If you have a key pair, you might want to use [deploy keys](../../../ssh/README.md#deploy-keys) instead. @@ -36,7 +38,7 @@ project. Alternatively, you can also create [group-scoped deploy tokens](#group- 1. Save the deploy token somewhere safe. After you leave or refresh the page, **you won't be able to access it again**. - + ## Deploy token expiration @@ -91,7 +93,7 @@ To read the container registry images, you'll need to: 1. Create a Deploy Token with `read_registry` as a scope. 1. Take note of your `username` and `token`. -1. Sign in to GitLab’s Container Registry using the deploy token: +1. Sign in to the GitLab Container Registry using the deploy token: ```shell docker login -u <username> -p <deploy_token> registry.example.com @@ -108,7 +110,7 @@ To push the container registry images, you'll need to: 1. Create a Deploy Token with `write_registry` as a scope. 1. Take note of your `username` and `token`. -1. Sign in to GitLab’s Container Registry using the deploy token: +1. Sign in to the GitLab Container Registry using the deploy token: ```shell docker login -u <username> -p <deploy_token> registry.example.com @@ -149,6 +151,9 @@ belong either to the specific group or to one of its subgroups. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Group Deploy Tokens](https://youtu.be/8kxTJvaD9ks). +The Group Deploy Tokens UI is now accessible under **Settings > Repository**, +not **Settings > CI/CD** as indicated in the video. + To use a group deploy token: 1. [Create](#creating-a-deploy-token) a deploy token for a group. @@ -174,7 +179,7 @@ those variables: docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY ``` -NOTE: **Note:** +NOTE: The special handling for the `gitlab-deploy-token` deploy token is not currently implemented for group deploy tokens. For the deploy token to be available for CI/CD jobs, it must be created at the project level. For details, see diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 4c14251cfa5..db2631f9596 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Description templates @@ -26,7 +26,7 @@ are added to the root directory of a GitLab project's repository. 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 will be taken into account. +templates of the default branch are taken into account. ## Use-cases @@ -53,7 +53,7 @@ To create a Markdown file: 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'll need to create it. +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: @@ -74,12 +74,12 @@ push to your default branch. ## Using the templates Let's take for example that you've created the file `.gitlab/issue_templates/Bug.md`. -This will enable the `Bug` dropdown option when creating or editing issues. When -`Bug` is selected, the content from the `Bug.md` template file will be copied -to the issue description field. The 'Reset template' button will discard any -changes you made after picking the template and return it to its initial status. +This enables the `Bug` dropdown option when creating or editing issues. When +`Bug` is selected, the content from the `Bug.md` template file is copied +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. -TIP: **Tip:** +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`.  @@ -92,7 +92,7 @@ You can create short-cut links to create an issue using a designated template. F The visibility of issues and/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 won't show. This is the default behavior so in most cases +template text areas don't show. This is the default behavior, so in most cases you should be fine. 1. Go to your project's **Settings**. @@ -108,7 +108,7 @@ you should be fine.  After you add the description, hit **Save changes** for the settings to take -effect. Now, every time a new merge request or issue is created, it will be +effect. Now, every time a new merge request or issue is created, it is pre-filled with the text you entered in the template(s). ## Description template example @@ -117,9 +117,9 @@ We make use of Description Templates for Issues and Merge Requests within the Gi Edition project. Please refer to the [`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/tree/master/.gitlab) for some examples. -TIP: **Tip:** +NOTE: It's possible to use [quick actions](quick_actions.md) within description templates to quickly add -labels, assignees, and milestones. The quick actions will only be executed if the user submitting +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: diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 46c2e211d57..49918b8f023 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -152,7 +152,7 @@ git lfs unlock --id=123 --force You can normally push files to GitLab whether they're locked or unlocked. -NOTE: **Note:** +NOTE: Although multi-branch file locks can be created and managed through the Git LFS command line interface, file locks can be created for any file. @@ -175,7 +175,7 @@ tracked by Git LFS plus a padlock icon on exclusively-locked files: You can also [view and remove existing locks](#view-and-remove-existing-locks) from the GitLab UI. -NOTE: **Note:** +NOTE: When you rename an exclusively-locked file, the lock is lost. You'll have to lock it again to keep it locked. diff --git a/doc/user/project/git_attributes.md b/doc/user/project/git_attributes.md index 577f0f1f754..459abea455b 100644 --- a/doc/user/project/git_attributes.md +++ b/doc/user/project/git_attributes.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +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 --- diff --git a/doc/user/project/gpg_signed_commits/index.md b/doc/user/project/gpg_signed_commits/index.md index bd9a5313489..206013210a0 100644 --- a/doc/user/project/gpg_signed_commits/index.md +++ b/doc/user/project/gpg_signed_commits/index.md @@ -3,3 +3,6 @@ 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 5f7c754ec75..1d92e32e071 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -9,7 +9,7 @@ type: reference 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. -NOTE: **Note:** +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. @@ -28,7 +28,7 @@ The paths here are simply Git's built-in [`.gitattributes` interface](https://gi /Nicefile gitlab-language=ruby ``` -To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shenanigans are available through CGI options, such as: +To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shenanigans are available through common gateway interface (CGI) options, such as: ``` conf # json with erb in it @@ -40,5 +40,5 @@ To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shen Please note that these configurations will only take effect when the `.gitattributes` file is in your default branch (usually `master`). -NOTE: **Note:** +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/canary_weight.png b/doc/user/project/img/canary_weight.png Binary files differnew file mode 100644 index 00000000000..e6544358c15 --- /dev/null +++ b/doc/user/project/img/canary_weight.png diff --git a/doc/user/project/img/issue_board_default_lists_v13_4.png b/doc/user/project/img/issue_board_default_lists_v13_4.png Binary files differdeleted file mode 100644 index 23cdc9b4e22..00000000000 --- a/doc/user/project/img/issue_board_default_lists_v13_4.png +++ /dev/null diff --git a/doc/user/project/img/issue_boards_add_issues_modal_v13_6.png b/doc/user/project/img/issue_boards_add_issues_modal_v13_6.png Binary files differdeleted file mode 100644 index a138efc9c1c..00000000000 --- a/doc/user/project/img/issue_boards_add_issues_modal_v13_6.png +++ /dev/null diff --git a/doc/user/project/img/protected_branches_deploy_keys_v13_5.png b/doc/user/project/img/protected_branches_deploy_keys_v13_5.png Binary files differnew file mode 100644 index 00000000000..6eda7a671b2 --- /dev/null +++ b/doc/user/project/img/protected_branches_deploy_keys_v13_5.png diff --git a/doc/user/project/img/rollout_status_canary_ingress.png b/doc/user/project/img/rollout_status_canary_ingress.png Binary files differdeleted file mode 100644 index fb59ba31615..00000000000 --- a/doc/user/project/img/rollout_status_canary_ingress.png +++ /dev/null diff --git a/doc/user/project/img/service_desk_issue_tracker.png b/doc/user/project/img/service_desk_issue_tracker.png Binary files differindex 02d18c9debb..0fde4c182cf 100644 --- a/doc/user/project/img/service_desk_issue_tracker.png +++ b/doc/user/project/img/service_desk_issue_tracker.png diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 56266718d12..6f274dd12a2 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -2,12 +2,12 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Import your project from Bitbucket Cloud to GitLab -NOTE: **Note:** +NOTE: The Bitbucket Cloud importer works only with Bitbucket.org, not with Bitbucket Server (aka Stash). If you are trying to import projects from Bitbucket Server, use [the Bitbucket Server importer](bitbucket_server.md). @@ -38,10 +38,10 @@ to enable this if not already. ## How it works When issues/pull requests are being imported, the Bitbucket importer tries to find -the Bitbucket author/assignee in GitLab's database using the Bitbucket `nickname`. +the Bitbucket author/assignee in the GitLab database using the Bitbucket `nickname`. For this to work, the Bitbucket author/assignee should have signed in beforehand in GitLab and **associated their Bitbucket account**. Their `nickname` must also match their Bitbucket -`username.`. If the user is not found in GitLab's database, the project creator +`username.`. If the user is not found in the GitLab database, the project creator (most of the times the current user that started the import process) is set as the author, but a reference on the issue about the original Bitbucket author is kept. diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index ac5be2b46a4..bb2256c9464 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -2,14 +2,14 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Import your project from Bitbucket Server to GitLab > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20164) in GitLab 11.2. -NOTE: **Note:** +NOTE: The Bitbucket Server importer does not work with [Bitbucket Cloud](https://bitbucket.org). Use the [Bitbucket Cloud importer](bitbucket.md) for that. @@ -70,7 +70,7 @@ namespace that started the import process. > - It's not recommended for production use. > - To use it in GitLab self-managed instances, ask a GitLab administrator to enable it. -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. If you've enabled this feature, the importer tries to find a user in the GitLab user database with diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index a825084dd1a..7e07ca6f865 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -2,12 +2,12 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Migrating from ClearCase -[ClearCase](https://www.ibm.com/us-en/marketplace/rational-clearcase) is a set of +[ClearCase](https://www.ibm.com/products/rational-clearcase) is a set of tools developed by IBM which also include a centralized version control system similar to Git. diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index 2957b33c20e..82ff889c043 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Migrating from CVS @@ -69,7 +69,8 @@ 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](http://www.catb.org/~esr/reposurgeon/dvcs-migration-guide.html) ([_source code_](https://gitlab.com/esr/cvs-fast-export)) +- [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) - [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/fogbugz.md b/doc/user/project/import/fogbugz.md index 149b5d1913c..1371ca57bc9 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Import your project from FogBugz to GitLab diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md index 2d0caa7d46e..38679914a9d 100644 --- a/doc/user/project/import/gemnasium.md +++ b/doc/user/project/import/gemnasium.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Gemnasium **(ULTIMATE)** @@ -66,19 +66,19 @@ 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 the "CI/CD for external repo" tab: +1. Create a new project, and select "CI/CD for external repo": -  +  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". -  +  - Once the configuration is done, you may click on your new + After the configuration is done, you may click on your new project on GitLab.  @@ -107,7 +107,7 @@ back to both GitLab and GitHub when completed.  -NOTE: **Note:** +NOTE: If you don't commit very often to your project, you may want to use [scheduled pipelines](../../../ci/pipelines/schedules.md) to run the job on a regular basis. diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 81ab16590dc..26e5a86b808 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Import your project from Gitea to GitLab @@ -11,7 +11,7 @@ Import your projects from Gitea to GitLab with minimal effort. ## Overview -NOTE: **Note:** +NOTE: This requires Gitea `v1.0.0` or newer. - At its current state, Gitea importer can import: @@ -27,7 +27,7 @@ This requires Gitea `v1.0.0` or newer. ## How it works Since Gitea is currently not an OAuth provider, author/assignee cannot be mapped -to users in your GitLab's instance. This means that the project creator (most of +to users in your GitLab instance. This means that the project creator (most of the times the current user that started the import process) is set as the author, but a reference on the issue about the original Gitea author is kept. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 6c0105aaded..8b6d86b14c9 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Import your project from GitHub to GitLab @@ -23,6 +23,8 @@ The following aspects of a project are imported: - Labels (GitLab.com & 8.7+) - Release note descriptions (GitLab.com & 8.12+) - Pull request review comments (GitLab.com & 10.2+) +- Pull request reviews (GitLab.com & 13.7+) +- Pull request "merged by" information (GitLab.com & 13.7+) - Regular issue and pull request comments - [Git Large File Storage (LFS) Objects](../../../topics/git/lfs/index.md) @@ -59,11 +61,11 @@ For this association to succeed, each GitHub author and assignee in the reposito must meet one of the following conditions prior to the import: - Have previously logged in to a GitLab account using the GitHub icon. -- Have a GitHub account with a - [primary email address](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address) - that matches their GitLab account's email address. +- Have a GitHub account with a publicly visible + [primary email address](https://docs.github.com/en/free-pro-team@latest/rest/reference/users#get-a-user) + on their profile that matches their GitLab account's email address. -If a user referenced in the project is not found in GitLab's database, the project creator (typically the user +If a user referenced in the project is not found in the GitLab database, the project creator (typically the user that initiated the import process) is set as the author/assignee, but a note on the issue mentioning the original GitHub author is added. @@ -89,24 +91,24 @@ Before you begin, ensure that any GitHub users who you want to map to GitLab use - A GitLab account that has logged in using the GitHub icon \- or - -- A GitLab account with an email address that matches the [public email address](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address) of the GitHub user +- A GitLab account with an email address that matches the [publicly visible email address](https://docs.github.com/en/free-pro-team@latest/rest/reference/users#get-a-user) in the profile of the GitHub user User-matching attempts occur in that order, and if a user is not identified either way, the activity is associated with the user account that is performing the import. -NOTE: **Note:** +NOTE: If you are using a self-managed GitLab instance or if you are importing from GitHub Enterprise, this process requires that you have configured [GitHub integration](../../../integration/github.md). 1. From the top navigation bar, click **+** and select **New project**. 1. Select the **Import project** tab and then select **GitHub**. 1. Select the first button to **List your GitHub repositories**. You are redirected to a page on [GitHub](https://github.com) to authorize the GitLab application. -1. Click **Authorize GitlabHQ**. You are redirected back to GitLab's Import page and all of your GitHub repositories are listed. +1. Click **Authorize GitlabHQ**. You are redirected back to the GitLab Import page and all of your GitHub repositories are listed. 1. Continue on to [selecting which repositories to import](#selecting-which-repositories-to-import). ### Using a GitHub token -NOTE: **Note:** +NOTE: Using a personal access token to import projects is not recommended. If you are a GitLab.com user, you can use a personal access token to import your project from GitHub, but this method cannot associate all user activity (such as issues and pull requests) with matching GitLab users. @@ -154,8 +156,8 @@ of the above are automatically configured. **(PREMIUM)** ## Improving the speed of imports on self-managed instances -NOTE: **Note:** -Admin access to the GitLab server is required. +NOTE: +Administrator access to the GitLab server is required. For large projects it may take a while to import all data. To reduce the time necessary, you can increase the number of Sidekiq workers that process the following queues: diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index 6c622ece4ac..add457c217e 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Project importing from GitLab.com to your private GitLab instance @@ -13,7 +13,7 @@ mind that it is possible only if GitLab.com integration is enabled on your GitLa To get to the importer page you need to go to "New project" page. -NOTE: **Note:** +NOTE: If you are interested in importing Wiki and Merge Request data to your new instance, you'll need to follow the instructions for [exporting a project](../settings/import_export.md#exporting-a-project-and-its-data) diff --git a/doc/user/project/import/img/gemnasium/connect_github.png b/doc/user/project/import/img/gemnasium/connect_github.png Binary files differdeleted file mode 100644 index fae62e8d840..00000000000 --- a/doc/user/project/import/img/gemnasium/connect_github.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/connect_github_v13_5.png b/doc/user/project/import/img/gemnasium/connect_github_v13_5.png Binary files differnew file mode 100644 index 00000000000..575d257a213 --- /dev/null +++ b/doc/user/project/import/img/gemnasium/connect_github_v13_5.png diff --git a/doc/user/project/import/img/gemnasium/create_project.png b/doc/user/project/import/img/gemnasium/create_project.png Binary files differdeleted file mode 100644 index 8edbf711629..00000000000 --- a/doc/user/project/import/img/gemnasium/create_project.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/create_project_v13_5.png b/doc/user/project/import/img/gemnasium/create_project_v13_5.png Binary files differnew file mode 100644 index 00000000000..37467bc3fed --- /dev/null +++ b/doc/user/project/import/img/gemnasium/create_project_v13_5.png diff --git a/doc/user/project/import/img/gemnasium/select_project.png b/doc/user/project/import/img/gemnasium/select_project.png Binary files differdeleted file mode 100644 index 588c5ca7ce1..00000000000 --- a/doc/user/project/import/img/gemnasium/select_project.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/select_project_v13_5.png b/doc/user/project/import/img/gemnasium/select_project_v13_5.png Binary files differnew file mode 100644 index 00000000000..30575954811 --- /dev/null +++ b/doc/user/project/import/img/gemnasium/select_project_v13_5.png diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index a113758495a..754c3e31799 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Migrating projects to a GitLab instance @@ -47,7 +47,7 @@ All GitLab user associations (such as comment author) will be changed to the use If you need to migrate all data over, you can leverage our [API](../../../api/README.md) to migrate from self-managed to GitLab.com. The order of assets to migrate from a self-managed instance to GitLab.com is the following: -NOTE: **Note:** +NOTE: When migrating to GitLab.com, users would need to be manually created unless [SCIM](../../../user/group/saml_sso/scim_setup.md) is going to be used. Creating users with the API is limited to self-managed instances as it requires administrator access. 1. [Groups](../../../api/groups.md) @@ -61,7 +61,7 @@ Docker pulls and pushes and re-run any CI pipelines to retrieve any build artifa ## Migrating from GitLab.com to self-managed GitLab -The process is essentially the same as for [migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). The main difference is that users can be created on the self-managed GitLab instance by an admin through the UI or the [users API](../../../api/users.md#user-creation). +The process is essentially the same as for [migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). The main difference is that users can be created on the self-managed GitLab instance by an administrator through the UI or the [users API](../../../api/users.md#user-creation). ## Migrating between two self-managed GitLab instances @@ -73,4 +73,4 @@ then restore it on the new server. In the event of merging two GitLab instances together (for example, both instances have existing data on them and one can't be wiped), refer to the instructions in [Migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). -Additionally, you can migrate users using the [Users API](../../../api/users.md) with an admin user. +Additionally, you can migrate users using the [Users API](../../../api/users.md) with an administrator user. diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index 7f179865f4f..5fb737cf74a 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Import your Jira project issues to GitLab @@ -33,7 +33,7 @@ Our parser for converting text in Jira issues to GitLab Flavored Markdown is onl Jira V3 REST API. There is an [epic](https://gitlab.com/groups/gitlab-org/-/epics/2738) tracking the addition of -items, such as issue assignees, comments, and much more. These will be included in the future +items, such as issue assignees, comments, and much more. These are included in the future iterations of the GitLab Jira importer. ## Prerequisites @@ -56,7 +56,7 @@ Make sure you have the integration set up before trying to import Jira issues. To import Jira issues to a GitLab project, follow the steps below. -NOTE: **Note:** +NOTE: Importing Jira issues is done as an asynchronous background job, which may result in delays based on import queues load, system load, or other factors. Importing large projects may take several minutes depending on the size of the import. @@ -76,7 +76,7 @@ Importing large projects may take several minutes depending on the size of the i 1. Click the **Import from** dropdown and select the Jira project that you wish to import issues from. In the **Jira-GitLab user mapping template** section, the table shows to which GitLab users your Jira - users will be mapped. + users are mapped. When the form appears, the dropdown defaults to the user conducting the import. 1. To change any of the mappings, click the dropdown in the **GitLab username** column and @@ -88,6 +88,6 @@ Importing large projects may take several minutes depending on the size of the i 1. Click **Continue**. You're presented with a confirmation that import has started. While the import is running in the background, you can navigate away from the import status page - to the issues page, and you'll see the new issues appearing in the issues list. + to the issues page, and you can see the new issues appearing in the issues list. 1. To check the status of your import, go to the Jira import page again. diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index ba1e2011d08..6ef91a54987 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Import multiple repositories by uploading a manifest file diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index 4ccc34efe30..85c8a3020b9 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Migrating from Perforce Helix @@ -35,7 +35,7 @@ Git: ## Why migrate -Perforce Helix can be difficult to manage both from a user and an admin +Perforce Helix can be difficult to manage both from a user and an administrator perspective. Migrating to Git/GitLab there is: - **No licensing costs**, Git is GPL while Perforce Helix is proprietary. diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index a19068199db..189afac1226 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -2,13 +2,20 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Import Phabricator tasks into a GitLab project > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/60562) in GitLab 12.0. +WARNING: +The Phabricator task importer is in +[beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) and is +[**not** complete](https://gitlab.com/gitlab-org/gitlab/-/issues/284406). It imports +only an issue's title and description. The GitLab project created during the import +process contains only issues, and the associated repository is disabled. + GitLab allows you to import all tasks from a Phabricator instance into GitLab issues. The import creates a single project with the repository disabled. diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 5c53b6eaf06..0e8cc159aec 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Import project from repository by URL diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index d5f4a014705..3642d07106c 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -2,7 +2,7 @@ type: howto stage: Manage group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Migrating from SVN to GitLab diff --git a/doc/user/project/import/tfs.md b/doc/user/project/import/tfs.md index 7b3b11b9519..31f9b200558 100644 --- a/doc/user/project/import/tfs.md +++ b/doc/user/project/import/tfs.md @@ -3,3 +3,6 @@ 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/import/tfvc.md b/doc/user/project/import/tfvc.md index cbc25552873..0d347a16697 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts --- @@ -38,7 +38,7 @@ Advantages of migrating to Git/GitLab: - **No licensing costs:** Git is open source, while TFVC is proprietary. - **Shorter learning curve:** Git has a big community and a vast number of tutorials to get you started (see our [Git topic](../../../topics/git/index.md)). -- **Integration with modern tools:** After migrating to Git and GitLab, you will have +- **Integration with modern tools:** After migrating to Git and GitLab, you have an open source, end-to-end software development platform with built-in version control, issue tracking, code review, CI/CD, and more. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 333c72a65b1..e3079c3731d 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +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 --- @@ -50,7 +50,7 @@ When you create a project in GitLab, you'll have access to a large number of - [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 GitLab's UI + 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 @@ -69,7 +69,7 @@ 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): GitLab's 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): 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 - [Container Registry](../packages/container_registry/index.md): Build and push Docker images out-of-the-box - [Auto Deploy](../../topics/autodevops/stages.md#auto-deploy): Configure GitLab CI/CD @@ -100,7 +100,7 @@ When you create a project in GitLab, you'll have access to a large number of - [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 GitLab's default choice of language. + 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 @@ -327,7 +327,7 @@ login <gitlab_user_name> password <personal_access_token> ``` -NOTE: **Note:** +NOTE: On Windows, Go reads `~/_netrc` instead of `~/.netrc`. ### Authenticate Git fetches @@ -374,6 +374,16 @@ 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: @@ -394,3 +404,4 @@ 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) diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index eaef0b8d69f..1efb3583fbf 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Insights **(ULTIMATE)** @@ -14,7 +14,7 @@ requests to be merged and much more.  -NOTE: **Note:** +NOTE: This feature is [also available at the group level](../../group/insights/index.md). ## View your project's Insights @@ -27,26 +27,26 @@ link in the left sidebar: ## Configure your Insights Insights are configured using a YAML file called `.gitlab/insights.yml` within -a project. That file will then be used in the project's Insights page. +a project. That file is used in the project's Insights page. See [Writing your `.gitlab/insights.yml`](#writing-your-gitlabinsightsyml) below for details about the content of this file. -NOTE: **Note:** -Once the configuration file is created, you can also +NOTE: +After the configuration file is created, you can also [use it for your project's group](../../group/insights/index.md#configure-your-insights). -NOTE: **Note:** -If the project doesn't have any configuration file, it'll try to use +NOTE: +If the project doesn't have any configuration file, it attempts to use the group configuration if possible. If the group doesn't have any -configuration, the default configuration will be used. +configuration, the default configuration is used. ## Permissions If you have access to view a project, then you have access to view their Insights. -NOTE: **Note:** +NOTE: Issues or merge requests that you don't have access to (because you don't have access to the project they belong to, or because they are confidential) are filtered out of the Insights charts. @@ -56,11 +56,11 @@ You may also consult the [group permissions table](../../permissions.md#group-me ## Writing your `.gitlab/insights.yml` The `.gitlab/insights.yml` file defines the structure and order of the Insights -charts that will be displayed in each Insights page of your project or group. +charts displayed in each Insights page of your project or group. Each page has a unique key and a collection of charts to fetch and display. -For example, here's a single definition for Insights that will display one page with one chart: +For example, here's a single definition for Insights that displays one page with one chart: ```yaml bugsCharts: @@ -103,8 +103,8 @@ The following table lists available parameters for charts: | Keyword | Description | |:---------------------------------------------------|:------------| -| [`title`](#title) | The title of the chart. This will displayed on the Insights page. | -| [`description`](#description) | A description for the individual chart. This will be displayed above the relevant chart. | +| [`title`](#title) | The title of the chart. This displays on the Insights page. | +| [`description`](#description) | A description for the individual chart. This displays above the relevant chart. | | [`type`](#type) | The type of chart: `bar`, `line` or `stacked-bar`. | | [`query`](#query) | A hash that defines the conditions for issues / merge requests to be part of the chart. | @@ -115,7 +115,7 @@ Insights charts. ### `title` -`title` is the title of the chart as it will be displayed on the Insights page. +`title` is the title of the chart as it displays on the Insights page. For example: ```yaml @@ -187,14 +187,14 @@ Defines the type of "issuable" you want to create a chart for. Supported values are: -- `issue`: The chart will display issues' data. -- `merge_request`: The chart will display merge requests' data. +- `issue`: The chart displays issues' data. +- `merge_request`: The chart displays merge requests' data. #### `query.issuable_state` Filter by the state of the queried "issuable". -By default, the `opened` state filter will be applied. +By default, the `opened` state filter is applied. Supported values are: @@ -208,7 +208,7 @@ Supported values are: Filter by labels applied to the queried "issuable". -By default, no labels filter will be applied. All the defined labels must be +By default, no labels filter is applied. All the defined labels must be applied to the "issuable" in order for it to be selected. Example: @@ -229,7 +229,7 @@ monthlyBugsCreated: Group "issuable" by the configured labels. -By default, no grouping will be done. When using this keyword, you need to +By default, no grouping is done. When using this keyword, you need to set `type` to either `line` or `stacked-bar`. Example: @@ -268,7 +268,7 @@ The unit is related to the `query.group_by` you defined. For instance if you defined `query.group_by: 'day'` then `query.period_limit: 365` would mean "Gather and display data for the last 365 days". -By default, default values will be applied depending on the `query.group_by` +By default, default values are applied depending on the `query.group_by` you defined. | `query.group_by` | Default value | @@ -293,10 +293,9 @@ The `period_field` is automatically set to: - `merged_at` if `query.issuable_state` is `merged` - `created_at` otherwise -NOTE: **Note:** -Until [this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/26911), is resolved, you may see `created_at` -in place of `merged_at`. -`created_at` will be used instead. +NOTE: +Until [this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/26911), is resolved, +you may see `created_at` in place of `merged_at`. `created_at` is used instead. ### `projects` @@ -304,22 +303,22 @@ in place of `merged_at`. You can limit where the "issuables" can be queried from: -- If `.gitlab/insights.yml` is used for a [group's insights](../../group/insights/index.md#configure-your-insights), with `projects`, you can limit the projects to be queried. By default, all projects under the group will be used. -- If `.gitlab/insights.yml` is used for a project's insights, specifying any other projects will yield no results. By default, the project itself will be used. +- If `.gitlab/insights.yml` is used for a [group's insights](../../group/insights/index.md#configure-your-insights), with `projects`, you can limit the projects to be queried. By default, all projects under the group are used. +- If `.gitlab/insights.yml` is used for a project's insights, specifying any other projects yields no results. By default, the project itself is used. #### `projects.only` The `projects.only` option specifies the projects which the "issuables" should be queried from. -Projects listed here will be ignored when: +Projects listed here are ignored when: - They don't exist. - The current user doesn't have sufficient permissions to read them. - They are outside of the group. In the following `insights.yml` example, we specify the projects -the queries will be used on. This example is useful when setting +the queries are used on. This example is useful when setting a group's insights: ```yaml diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 9cade323ed2..30a21dd7f66 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -1,14 +1,14 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Atlassian Bamboo CI Service GitLab provides integration with Atlassian Bamboo for continuous integration. -When configured, pushes to a project will trigger a build in Bamboo automatically. -Merge requests will also display CI status showing whether the build is pending, +When configured, pushes to a project trigger a build in Bamboo automatically. +Merge requests also display CI status showing whether the build is pending, failed, or completed successfully. It also provides a link to the Bamboo build page for more information. @@ -56,12 +56,12 @@ service in GitLab. access to trigger the build plan. Leave these fields blank if you do not require authentication. 1. Save or optionally click 'Test Settings'. Please note that 'Test Settings' - will actually trigger a build in Bamboo. + actually triggers a build in Bamboo. ## Troubleshooting 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: **Note:** +NOTE: Starting with GitLab 8.14.0, builds are triggered on push events. diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 2ed14a4c69c..4e2ee9b3662 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Bugzilla Service @@ -16,7 +16,7 @@ in the table below. | `issues_url` | The URL to the issue in Bugzilla project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | | `new_issue_url` | This is the URL to create a new issue in Bugzilla for the project linked to this GitLab project. Note that the `new_issue_url` requires PRODUCT_NAME to be updated with the product/project name in Bugzilla. | -Once you have configured and enabled Bugzilla you'll see the Bugzilla link on the GitLab project pages that takes you to the appropriate Bugzilla project. +Once you have configured and enabled Bugzilla, you see the Bugzilla link on the GitLab project pages that takes you to the appropriate Bugzilla project. ## Referencing issues in Bugzilla @@ -27,7 +27,7 @@ Issues in Bugzilla can be referenced in two alternative ways: then followed by capital letters, numbers or underscores, and `<ID>` is a number (example `API_32-143`). -We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker the internal issue will be linked. +We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker, the internal issue is linked. Please note that `<PROJECT>` part is ignored and links always point to the address specified in `issues_url`. diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 1329f584fdc..143f0e2a25d 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Custom Issue Tracker service @@ -11,7 +11,7 @@ To enable the Custom Issue Tracker integration in a project: 1. Go to **Settings > Integrations**. 1. Click **Custom Issue Tracker** 1. Fill in the tracker's details, such as title, description, and URLs. - You will be able to edit these fields later as well. + You can edit these fields later as well. These are some of the required fields: @@ -19,11 +19,11 @@ To enable the Custom Issue Tracker integration in a project: | --------------- | ----------- | | **Project URL** | The URL to the project in the custom issue tracker. | | **Issues URL** | The URL to the issue in the issue tracker project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. For example, `https://customissuetracker.com/project-name/:id`. | - | **New issue URL** | Currently unused. Will be changed in a future release. | + | **New issue URL** | Currently unused. Planned to be changed in a future release. | 1. Click **Test settings and save changes**. -After you configure and enable the Custom Issue Tracker service, you'll see a link on the GitLab +After you configure and enable the Custom Issue Tracker service, you see a link on the GitLab project pages that takes you to that custom issue tracker. ## Referencing issues diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index f261362eeae..8e0a167a968 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Discord Notifications service @@ -17,7 +17,7 @@ To send GitLab event notifications to a Discord channel, create a webhook in Dis 1. Open the Discord channel you want to receive GitLab event notifications. 1. From the channel menu, select **Edit channel**. 1. Click on **Webhooks** menu item. -1. Click the **Create Webhook** button and fill in the name of the bot that will post the messages. Optionally, edit the avatar. +1. Click the **Create Webhook** button and fill in the name of the bot to post the messages. Optionally, edit the avatar. 1. Note the URL from the **WEBHOOK URL** field. 1. Click the **Save** button. @@ -32,4 +32,4 @@ With the webhook URL created in the Discord channel, you can set up the Discord 1. Paste the webhook URL that you copied from the create Discord webhook step. 1. Configure the remaining options and click the **Save changes** button. -The Discord channel you created the webhook for will now receive notification of the GitLab events that were configured. +The Discord channel you created the webhook for now receives notification of the GitLab events that were configured. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index d8b864e0396..2274913d349 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -1,12 +1,12 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Enabling emails on push -By enabling this service, you will receive email notifications for every change +By enabling this service, you receive email notifications for every change that is pushed to your project. From the [Integrations page](overview.md#accessing-integrations) @@ -16,8 +16,8 @@ In the _Recipients_ area, provide a list of emails separated by spaces or newlin The following options are available: -- **Push events** - Email will be triggered when a push event is received. -- **Tag push events** - Email will be triggered when a tag is created and pushed. +- **Push events** - Email is triggered when a push event is received. +- **Tag push events** - Email is triggered when a tag is created and pushed. - **Send from committer** - Send notifications from the committer's email address if the domain is part of the domain GitLab is running on (e.g. `user@gitlab.com`). - **Disable code diffs** - Don't include possibly sensitive code diffs in notification body. diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index 822483a1d5b..434ae760aff 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -1,14 +1,14 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # IBM Engineering Workflow Management (EWM) Integration **(CORE)** 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. -NOTE: **Note:** +NOTE: This IBM product was [formerly named Rational Team Concert](https://jazz.net/blog/index.php/2019/04/23/renaming-the-ibm-continuous-engineering-portfolio/)(RTC). This integration is also compatible with all versions of RTC and EWM. 1. From a GitLab project, navigate to **Settings > Integrations**, and then click **EWM**. diff --git a/doc/user/project/integrations/generic_alerts.md b/doc/user/project/integrations/generic_alerts.md index 0e8e082859b..1fbbee36173 100644 --- a/doc/user/project/integrations/generic_alerts.md +++ b/doc/user/project/integrations/generic_alerts.md @@ -3,3 +3,6 @@ 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/github.md b/doc/user/project/integrations/github.md index 29818e862e0..5ef36ff4074 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # GitHub project integration **(PREMIUM)** @@ -20,7 +20,7 @@ and is automatically configured on [GitHub import](../../../integration/github.m ### Complete these steps on GitHub -This integration requires a [GitHub API token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) +This integration requires a [GitHub API token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) with `repo:status` access granted: 1. Go to your "Personal access tokens" page at <https://github.com/settings/tokens> @@ -49,8 +49,7 @@ to configure pipelines to run for open pull requests. This makes it possible to mark these status checks as _Required_ on GitHub. With **Static status check names** enabled on the integration page, your -GitLab instance host name is going to be appended to a status check name, -whereas in case of dynamic status check names, a branch name is going to be -appended. +GitLab instance host name is appended to a status check name, +whereas in case of dynamic status check names, a branch name is appended.  diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 62fccb22d36..8344baebd82 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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)** @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Introduced in GitLab 9.4. > - Distributed to Slack App Directory in GitLab 10.2. -NOTE: **Note:** +NOTE: The GitLab Slack application is only configurable for GitLab.com. It will **not** work for on-premises installations where you can configure the [Slack slash commands](slack_slash_commands.md) service instead. We're planning @@ -25,8 +25,7 @@ The simplest way to enable the GitLab Slack application for your workspace is to install the [GitLab application](https://slack-platform.slack.com/apps/A676ADMV5-gitlab) from the [Slack App Directory](https://slack.com/apps). -Clicking install will take you to the -[GitLab Slack application landing page](https://gitlab.com/profile/slack/edit) +Clicking install takes you to the [GitLab Slack application landing page](https://gitlab.com/profile/slack/edit) where you can select a project to enable the GitLab Slack application for.  @@ -40,7 +39,7 @@ Keep in mind that you need to have the appropriate permissions for your Slack team in order to be able to install a new application, read more in Slack's docs on [Adding an app to your workspace](https://slack.com/help/articles/202035138-Add-an-app-to-your-workspace). -To enable GitLab's service for your Slack team: +To enable the GitLab service for your Slack team: 1. Go to your project's **Settings > Integration > Slack application** (only visible on GitLab.com). @@ -71,7 +70,7 @@ GitLab error: project or alias not found After confirming the installation, you, and everyone else in your Slack team, can use all the [slash commands](../../../integration/slash_commands.md). -When you perform your first slash command you will be asked to authorize your +When you perform your first slash command, you are asked to authorize your Slack user on GitLab.com. The only difference with the [manually configurable Slack slash commands](slack_slash_commands.md) diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index 54f9bd8d622..06dcca6eb44 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Hangouts Chat service @@ -14,7 +14,7 @@ The Hangouts Chat service sends notifications from GitLab to the room for which 1. Open the chat room in which you want to see the notifications. 1. From the chat room menu, select **Configure Webhooks**. -1. Click on **ADD WEBHOOK** and fill in the name of the bot that will post the messages. Optionally define avatar. +1. Click on **ADD WEBHOOK** and fill in the name of the bot to post the messages. Optionally define an avatar. 1. Click **SAVE** and copy the **Webhook URL** of your webhook. See also [the Hangouts Chat documentation for configuring incoming webhooks](https://developers.google.com/hangouts/chat/how-tos/webhooks) @@ -30,6 +30,6 @@ When you have the **Webhook URL** for your Hangouts Chat room webhook, you can s 1. Paste the **Webhook URL** that you copied from the Hangouts Chat configuration step. 1. Configure the remaining options and click `Save changes`. -Your Hangouts Chat room will now start receiving GitLab event notifications as configured. +Your Hangouts Chat room now starts receiving GitLab event notifications as configured.  diff --git a/doc/user/project/integrations/hipchat.md b/doc/user/project/integrations/hipchat.md index 718f00273bd..7b90d8d7cfd 100644 --- a/doc/user/project/integrations/hipchat.md +++ b/doc/user/project/integrations/hipchat.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Atlassian HipChat @@ -19,7 +19,7 @@ HipChat v1 API (legacy) supports "API Auth Tokens" in the Group API menu. A v1 token is allowed to send messages to *any* room. HipChat v2 API has tokens that are can be created using the Integrations tab -in the Group or Room admin page. By design, these are lightweight tokens that +in the Group or Room administration page. By design, these are lightweight tokens that allow GitLab to send messages only to *one* room. ### Complete these steps in HipChat diff --git a/doc/user/project/integrations/img/microsoft_teams_select_incoming_webhook.png b/doc/user/project/integrations/img/microsoft_teams_select_incoming_webhook.png Binary files differnew file mode 100644 index 00000000000..216e65a8b30 --- /dev/null +++ b/doc/user/project/integrations/img/microsoft_teams_select_incoming_webhook.png diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 0a1db5da61d..0e5163e992a 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -1,13 +1,13 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Project integrations You can find the available integrations under your project's -**Settings ➔ Integrations** page. You need to have at least +**Settings > Integrations** page. You need to have at least [maintainer permission](../../permissions.md) on the project. ## Integrations @@ -16,13 +16,13 @@ Integrations allow you to integrate GitLab with other applications. They are a bit like plugins in that they allow a lot of freedom in adding functionality to GitLab. -[Learn more about integrations.](overview.md) +Learn more [about integrations](overview.md). ## Project webhooks Project webhooks allow you to trigger a URL if for example new code is pushed or a new issue is created. You can configure webhooks to listen for specific events -like pushes, issues or merge requests. GitLab will send a POST request with data +like pushes, issues or merge requests. GitLab sends a POST request with data to the webhook URL. -[Learn more about webhooks.](webhooks.md) +Learn more [about webhooks](webhooks.md). diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index bb4a5b2b97f..8dd7e4309b4 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -1,20 +1,20 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Irker IRC Gateway GitLab provides a way to push update messages to an Irker server. When -configured, pushes to a project will trigger the service to send data directly +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> ## Needed setup -You will first need an Irker daemon. You can download the Irker code +You first need an Irker daemon. You can download the Irker code [from its repository](https://gitlab.com/esr/irker): ```shell @@ -26,8 +26,8 @@ This script is the gateway script, it acts both as an IRC client, for sending messages to an IRC server obviously, and as a TCP server, for receiving messages from the GitLab service. -If the Irker server runs on the same machine, you are done. If not, you will -need to follow the firsts steps of the next section. +If the Irker server runs on the same machine, you are done. If not, you +need to follow the first steps of the next section. ## Complete these steps in GitLab @@ -40,7 +40,7 @@ need to follow the firsts steps of the next section. 1. Enter the server port of `irkerd` (e.g. defaults to 6659) in the `Server port` field on the Web page. 1. Optional: if `Default IRC URI` is set, it has to be in the format - `irc[s]://domain.name` and will be prepend to each and every channel provided + `irc[s]://domain.name` and is prepended to each and every channel provided by the user which is not a full URI. 1. Specify the recipients (e.g. #channel1, user1, etc.) 1. Save or optionally click "Test Settings". @@ -48,13 +48,13 @@ need to follow the firsts steps of the next section. ## Note on Irker recipients Irker accepts channel names of the form `chan` and `#chan`, both for the -`#chan` channel. If you want to send messages in query, you will need to add +`#chan` channel. If you want to send messages in query, you need to add `,isnick` after the channel name, in this form: `Aorimn,isnick`. In this latter case, `Aorimn` is treated as a nick and no more as a channel name. Irker can also join password-protected channels. Users need to append `?key=thesecretpassword` to the channel name. When using this feature remember to -**not** put the `#` sign in front of the channel name; failing to do so will -result on Irker joining a channel literally named `#chan?key=password` henceforth +**not** put the `#` sign in front of the channel name; failing to do so +results in Irker joining a channel literally named `#chan?key=password` henceforth leaking the channel key through the `/whois` IRC command (depending on IRC server configuration). This is due to a long standing Irker bug. diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index b4e02bbd5f3..306a16bd873 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -1,12 +1,12 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 Jira integration -If you need to use Jira to track work that's implemented in GitLab, GitLab's Jira integrations make the process of working across systems more efficient. +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. 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). @@ -18,7 +18,7 @@ Features include: - 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: - - GitLab's MR displays a note that it closed the Jira issue. Prior to the merge, MRs indicate which issue they will close. + - 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)** @@ -38,7 +38,7 @@ For an overview, see [Agile Management - GitLab-Jira Basic Integration](https:// 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 will not have to explicitly associate +configured. Therefore, 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 page with a default @@ -61,7 +61,7 @@ In order to enable the Jira service in GitLab, you need to first configure the p > **Notes:** > > - The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`. -> - In order to support Oracle's Access Manager, GitLab will send additional cookies +> - In order to support Oracle's Access Manager, GitLab sends additional cookies > to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with > a value of `fromDialog`. @@ -80,17 +80,18 @@ Enter the further details on the page as described in the following table. | 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 will be used if not set. E.g., `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira Cloud**. | +| `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**. | -| `Transition ID` | Required for closing Jira issues via commits or merge requests. This is the ID of a transition in Jira that moves issues to a desired 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. | +| `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 enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and enter a Jira project key. **(PREMIUM)** You can only display issues from a single Jira project within a given GitLab project. -CAUTION: **Caution:** -If you enable Jira issues with the setting above, all users that have access to this GitLab project will be able to view all issues from the specified Jira project. +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. When you have configured all settings, click **Test settings and save changes**. @@ -127,9 +128,9 @@ Jira issue IDs must be formatted in uppercase for the integration to work. ### Reference Jira issues When GitLab project has Jira issue tracker configured and enabled, mentioning -Jira issue in GitLab will automatically add a comment in Jira issue with the +Jira issues in GitLab automatically adds a comment in Jira issue with the link back to GitLab. This means that in comments in merge requests and commits -referencing an issue, e.g., `PROJECT-7`, will add a comment in Jira issue in the +referencing an issue, `PROJECT-7` for example, adds a comment in Jira issue in the format: ```plaintext @@ -145,7 +146,7 @@ ENTITY_TITLE  -For example, the following commit will reference the Jira issue with `PROJECT-1` as its ID: +For example, the following commit references the Jira issue with `PROJECT-1` as its ID: ```shell git commit -m "PROJECT-1 Fix spelling and grammar" @@ -155,8 +156,8 @@ git commit -m "PROJECT-1 Fix spelling and grammar" Jira issues can be closed directly from GitLab by using trigger words in commits and merge requests. When a commit which contains the trigger word -followed by the Jira issue ID in the commit message is pushed, GitLab will -add a comment in the mentioned Jira issue and immediately close it (provided +followed by the Jira issue ID in the commit message is pushed, GitLab +adds a comment in the mentioned Jira issue and immediately closes it (provided the transition ID was set up correctly). There are currently three trigger words, and you can use either one to achieve @@ -168,12 +169,12 @@ the same goal: where `PROJECT-1` is the ID of the Jira issue. -> **Notes:** -> -> - Only commits and merges into the project's default branch (usually **master**) will -> close an issue in Jira. You can change your projects default branch under -> [project settings](img/jira_project_settings.png). -> - The Jira issue will not be transitioned if it has a resolution. +Note the following: + +- Only commits and merges into the project's default branch (usually `master`) + close an issue in Jira. You can change your project's default branch under + [project settings](img/jira_project_settings.png). +- The Jira issue is not transitioned if it has a resolution. Let's consider the following example: @@ -183,7 +184,7 @@ Let's consider the following example: in GitLab contains the improvement 1. In the merge request description we use the issue closing trigger `Closes PROJECT-7`. -1. Once the merge request is merged, the Jira issue will be automatically closed +1. Once the merge request is merged, the Jira issue is automatically closed with a comment and an associated link to the commit that resolved the issue. In the following screenshot you can see what the link references to the Jira @@ -191,7 +192,7 @@ issue look like.  -Once this merge request is merged, the Jira issue will be automatically closed +Once this merge request is merged, the Jira issue is automatically closed with a link to the commit that resolved the issue.  @@ -244,7 +245,7 @@ If these features do not work as expected, it is likely due to a problem with th Make sure that the Jira user you set up for the integration has the correct access permission to post comments on a Jira issue and also to transition the issue, if you'd like GitLab to also be able to do so. -Jira issue references and update comments will not work if the GitLab issue tracker is disabled. +Jira issue references and update comments do not work if the GitLab issue tracker is disabled. ### GitLab is unable to close a Jira issue @@ -259,6 +260,6 @@ Jira lists.) CAPTCHA may be triggered after several consecutive failed login attempts which may lead to a `401 unauthorized` error when testing your Jira integration. -If CAPTCHA has been triggered, you will not be able to use Jira's REST API to -authenticate with the Jira site. You will need to log in to your Jira instance +If CAPTCHA has been triggered, you can't use Jira's REST API to +authenticate with the Jira site. You need to log in to your Jira instance and complete the CAPTCHA. diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index 14999734c00..b8eebef8e42 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 @@ -11,7 +11,7 @@ below to create one: 1. Log in to [`id.atlassian.com`](https://id.atlassian.com/manage-profile/security/api-tokens) with your email address. - NOTE: **Note:** + NOTE: It is important that the user associated with this email address has *write* access to projects in Jira. diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md index dd22c26be36..f15a5ee4429 100644 --- a/doc/user/project/integrations/jira_integrations.md +++ b/doc/user/project/integrations/jira_integrations.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Jira integrations @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w 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. -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 GitLab's Jira integrations. +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. ## Integrations @@ -19,7 +19,7 @@ The following Jira integrations allow different types of cross-referencing betwe - [**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-for-jira) app in the Atlassian Marketplace and see its [documentation](../../../integration/jira_development_panel.md#gitlab-for-jira-app). + - 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). ### Feature comparison diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index 38098d7d15b..d2a42c0535e 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -1,18 +1,17 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 -We need to create a user in Jira which will have access to all projects that -need to integrate with GitLab. +We need to create a user in Jira to have access to all projects that need to integrate with GitLab. -As an example, we'll create a user named `gitlab` and add it to a new group +As an example, we create a user named `gitlab` and add it to a new group named `gitlab-developers`. -NOTE: **Note:** +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. @@ -24,15 +23,16 @@ access to your Jira projects. This is covered in the process below. 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. - _**Note:** 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 will 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 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.  -1. Create a `gitlab-developers` group. (We will 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. 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**.  @@ -53,7 +53,7 @@ access to your Jira projects. This is covered in the process below. 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. Once your permission scheme is created, you'll be taken back to the permissions scheme list. +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. @@ -61,4 +61,4 @@ access to your Jira projects. This is covered in the process below.  The Jira configuration is complete. Write down the new Jira username and its -password as they will be needed when [configuring GitLab in the next section](jira.md#configuring-gitlab). +password as they are needed when [configuring GitLab in the next section](jira.md#configuring-gitlab). diff --git a/doc/user/project/integrations/kubernetes.md b/doc/user/project/integrations/kubernetes.md index ab43eb2da7e..646c9ed66d5 100644 --- a/doc/user/project/integrations/kubernetes.md +++ b/doc/user/project/integrations/kubernetes.md @@ -3,3 +3,6 @@ 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 c12a969ca3c..e80f672d05d 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Mattermost Notifications Service @@ -15,11 +15,11 @@ You can also use Mattermost slash commands to control GitLab inside Mattermost. To enable Mattermost integration you must create an incoming webhook integration: 1. Sign in to your Mattermost instance. -1. Visit incoming webhooks, that will be something like: `https://mattermost.example.com/your_team_name/integrations/incoming_webhooks/add`. +1. Visit incoming webhooks, that is something like: `https://mattermost.example.com/your_team_name/integrations/incoming_webhooks/add`. 1. Choose a display name, description and channel, those can be overridden on GitLab. -1. Save it, copy the **Webhook URL**, we'll need this later for GitLab. +1. Save it and copy the **Webhook URL** because we need this later for GitLab. -Incoming Webhooks might be blocked on your Mattermost instance. Ask your Mattermost admin +Incoming Webhooks might be blocked on your Mattermost instance. Ask your Mattermost administrator to enable it on: - **Mattermost System Console > Integrations > Integration Management** in Mattermost @@ -27,7 +27,7 @@ to enable it on: - **Mattermost System Console > Integrations > Custom Integrations** in Mattermost versions 5.11 and earlier. -Display name override is not enabled by default, you need to ask your admin to enable it on that same section. +Display name override is not enabled by default, you need to ask your administrator to enable it on that same section. ## On GitLab @@ -35,7 +35,7 @@ After you set up Mattermost, it's time to set up GitLab. Navigate to the [Integrations page](overview.md#accessing-integrations) and select the **Mattermost notifications** service to configure it. -There, you will see a checkbox with the following events that can be triggered: +There, you see a checkbox with the following events that can be triggered: - Push - Issue @@ -55,7 +55,7 @@ At the end, fill in your Mattermost details: | Field | Description | | ----- | ----------- | -| **Webhook** | The incoming webhook URL which you have to set up on Mattermost, it will be something like: `http://mattermost.example/hooks/5xo…` | +| **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. | diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 5e08767d3f0..6c8a0ded2ae 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Mattermost slash commands @@ -37,13 +37,13 @@ commands in Mattermost and then enable the service in GitLab. ### Step 1. Enable custom slash commands in Mattermost -This step is only required when using a source install, Omnibus installs will be +This step is only required when using a source install. Omnibus installs are preconfigured with the right settings. The first thing to do in Mattermost is to enable custom slash commands from the administrator console. -1. Log in with an account that has admin privileges and navigate to the system +1. Log in with an account that has administrator privileges and navigate to the system console.  @@ -61,13 +61,12 @@ the administrator console. 1. Open a new tab for GitLab, go to your project's [Integrations page](overview.md#accessing-integrations) and select the **Mattermost command** service to configure it. - A screen will appear with all the values you need to copy in Mattermost as + A screen appears with all the values you need to copy in Mattermost as described in the next step. Leave the window open. - NOTE: **Note:** - GitLab will propose some values for the Mattermost settings. The only one - required to copy-paste as-is is the **Request URL**, all the others are just - suggestions. + NOTE: + GitLab offers some values for the Mattermost settings. Only **Request URL** is required + as offered, all the others are just suggestions.  @@ -93,15 +92,15 @@ in a new slash command. 1. Fill in the options for the custom command as described in [step 2](#step-2-open-the-mattermost-slash-commands-service-in-gitlab). - NOTE: **Note:** + NOTE: If you plan on connecting multiple projects, pick a slash command trigger word that relates to your projects such as `/gitlab-project-name` or even - just `/project-name`. Only use `/gitlab` if you will only connect a single + just `/project-name`. Only use `/gitlab` if you plan to only connect a single project to your Mattermost team.  -1. After you set up all the values, copy the token (we will use it below) and +1. After you set up all the values, copy the token (we use it below) and click **Done**.  @@ -120,12 +119,12 @@ GitLab project you configured. ## Authorizing Mattermost to interact with GitLab -The first time a user will interact with the newly created slash commands, -Mattermost will trigger an authorization process. +The first time a user interacts with the newly created slash commands, +Mattermost triggers an authorization process.  -This will connect your Mattermost user with your GitLab user. You can +This connects your Mattermost user with your GitLab user. You can see all authorized chat accounts in your profile's page under **Chat**. When the authorization process is complete, you can start interacting with @@ -158,7 +157,7 @@ Mattermost webhooks do not have access to private channels. If a private channel is required, you can edit the webhook's channel in Mattermost and select a private channel. It is not possible to use different channels for -different types of notifications - all events will be sent to the specified channel. +different types of notifications. All events are sent to the specified channel. ## Further reading diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index b2a2f1c3e7b..136da05d0e8 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Microsoft Teams service @@ -9,7 +9,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## On Microsoft Teams To enable Microsoft Teams integration you must create an incoming webhook integration on Microsoft -Teams by following the steps described in [Sending messages to Connectors and Webhooks](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using). +Teams by following the steps below: + +1. Search for "incoming webhook" on the search bar in Microsoft Teams and select the + **Incoming Webhook** item. + +  + +1. Click the **Add to a team** button. +1. Select the team and channel you want to add the integration to. +1. Add a name for the webhook. The name is displayed next to every message that + comes in through the webhook. +1. Copy the webhook URL for the next steps. + +Learn more about +[setting up an incoming webhook on Microsoft Teams](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using#setting-up-a-custom-incoming-webhook). ## On GitLab @@ -17,7 +31,7 @@ After you set up Microsoft Teams, it's time to set up GitLab. Navigate to the [Integrations page](overview.md#accessing-integrations) and select the **Microsoft Teams Notification** service to configure it. -There, you will see a checkbox with the following events that can be triggered: +There, you see a checkbox with the following events that can be triggered: - Push - Issue diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index 4567d345336..18f0ad6b275 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Mock CI Service diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index a502dfbf320..c391877be20 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Integrations @@ -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/generic_alerts.md) **(ULTIMATE)** | Receive alerts on GitLab from any source | No | +| [Generic alerts](../../../operations/incident_management/alert_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 | @@ -69,7 +69,7 @@ Click on the service links to see further configuration instructions and details > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17874) in GitLab 12.4. If a single push includes changes to more than three branches or tags, services -supported by `push_hooks` and `tag_push_hooks` events won't be executed. +supported by `push_hooks` and `tag_push_hooks` events aren't executed. The number of branches or tags supported can be changed via [`push_event_hooks_limit` application setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls). diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index 90f91fbaa0d..69e2ea2856c 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -3,3 +3,6 @@ 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 97be16f8dd3..9d7960790ff 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -1,7 +1,7 @@ --- stage: Monitor 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/#designated-technical-writers +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 @@ -19,7 +19,7 @@ There are two ways to set up Prometheus integration, depending on where your app - 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). -Once enabled, GitLab will automatically detect 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 @@ -48,7 +48,7 @@ Once you have a connected Kubernetes cluster, deploying a managed Prometheus is 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/). -The Prometheus server will [automatically detect and monitor](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, simply 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. @@ -165,8 +165,8 @@ Installing and configuring Prometheus to monitor applications is fairly straight #### Configuration in GitLab -The actual configuration of Prometheus integration within GitLab is very simple. -All you will need is the domain name or IP address of the Prometheus server you'd like +The actual configuration of Prometheus integration within 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 @@ -189,7 +189,7 @@ 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. You will need the domain name or IP address of the Thanos server you'd like +with GitLab, using 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). @@ -199,9 +199,10 @@ to integrate with. ### Precedence with multiple Prometheus configurations +12345678901234567890123456789012345678901234567890123456789012345678901234567890 Although you can enable both a [manual configuration](#manual-configuration-of-prometheus) -and [auto configuration](#managed-prometheus-on-kubernetes) of Prometheus, only -one of them will be used: +and [auto configuration](#managed-prometheus-on-kubernetes) of Prometheus, you +can use only one: - If you have enabled a [Prometheus manual configuration](#manual-configuration-of-prometheus) @@ -225,16 +226,16 @@ Developers can view the performance impact of their changes within 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 -numeric comparison of the average memory consumption will appear. On the +numeric comparison of the average memory consumption displays. On the sparkline, a dot indicates when the current changes were deployed, with up to 30 minutes of performance data displayed before and after. The comparison shows the difference between the 30 minute average before and after the deployment. This information is updated after each commit has been deployed. -Once merged and the target branch has been redeployed, the metrics will switch +Once merged and the target branch has been redeployed, the metrics switches to show the new environments this revision has been deployed to. -Performance data will be available for the duration it is persisted on the +Performance data is available for the duration it is persisted on the Prometheus server.  diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index 70f8a55bb07..b563dd34896 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -1,7 +1,7 @@ --- stage: Monitor 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/#designated-technical-writers +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 @@ -33,4 +33,4 @@ A sample Cloudwatch Exporter configuration file, configured for basic AWS ELB mo ## Specifying the Environment label In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](index.md#identifying-environments). +however, GitLab needs a method to detect which labels are associated. To do this, GitLab [looks for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index 0fbc49ddad7..c14c14658b7 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -1,7 +1,7 @@ --- stage: Monitor 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/#designated-technical-writers +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 @@ -28,4 +28,4 @@ To get started with NGINX monitoring, you should install and configure the [HAPr ## Specifying the Environment label In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](index.md#identifying-environments). +however, GitLab needs a method to detect which labels are associated. To do this, GitLab [looks for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index 35b111ab2b2..501e8ba7c1d 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -1,7 +1,7 @@ --- stage: Monitor 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/#designated-technical-writers +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 @@ -21,8 +21,8 @@ Currently supported exporters are: - [HAProxy](haproxy.md) - [Amazon Cloud Watch](cloudwatch.md) -We have tried to surface the most important metrics for each exporter, and will -be continuing to add support for additional exporters in future releases. If you +We have tried to surface the most important metrics for each exporter, and +continue to add support for additional exporters in future releases. If you would like to add support for other official exporters, contributions are welcome. ## Identifying Environments diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 43c2d305437..ae330158a58 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -1,7 +1,7 @@ --- stage: Monitor 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/#designated-technical-writers +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 diff --git a/doc/user/project/integrations/prometheus_library/metrics.md b/doc/user/project/integrations/prometheus_library/metrics.md index 7ace0ec5a93..a275efce5bb 100644 --- a/doc/user/project/integrations/prometheus_library/metrics.md +++ b/doc/user/project/integrations/prometheus_library/metrics.md @@ -3,3 +3,6 @@ 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 1757378fb70..4cb827b3b4a 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -1,7 +1,7 @@ --- stage: Monitor 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/#designated-technical-writers +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 @@ -29,11 +29,11 @@ NGINX server metrics are detected, which tracks the pages and content directly s ## Configuring Prometheus to monitor for NGINX metrics -To get started with NGINX monitoring, you should first enable the [VTS statistics](https://github.com/vozlt/nginx-module-vts) module for your NGINX server. This will capture and display statistics in an HTML readable form. Next, you should install and configure the [NGINX VTS exporter](https://github.com/hnlq715/nginx-vts-exporter) which parses these statistics and translates them into a Prometheus monitoring endpoint. +To get started with NGINX monitoring, you should first enable the [VTS statistics](https://github.com/vozlt/nginx-module-vts) module for your NGINX server. This captures and displays statistics in an HTML readable form. Next, you should install and configure the [NGINX VTS exporter](https://github.com/hnlq715/nginx-vts-exporter) which parses these statistics and translates them into a Prometheus monitoring endpoint. -If you are using NGINX as your Kubernetes Ingress, GitLab will [automatically detect](nginx_ingress.md) the metrics once enabled in 0.9.0 and later releases. +If you are using NGINX as your Kubernetes Ingress, GitLab [automatically detects](nginx_ingress.md) the metrics once enabled in 0.9.0 and later releases. ## Specifying the Environment label In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](index.md#identifying-environments). +however, GitLab needs a method to detect which labels are associated. To do this, GitLab [looks for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index fdea800c410..f7542ec78f7 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -1,7 +1,7 @@ --- stage: Monitor 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/#designated-technical-writers +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 @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab has support for automatically detecting and monitoring the Kubernetes NGINX Ingress controller. This is provided by leveraging the built-in Prometheus metrics included with Kubernetes NGINX Ingress controller [version 0.16.0](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0160) onward. -NOTE: **Note:** +NOTE: NGINX Ingress versions prior to 0.16.0 offer an included [VTS Prometheus metrics exporter](nginx_ingress_vts.md), which exports metrics different than the built-in metrics. ## Requirements @@ -27,7 +27,7 @@ NGINX Ingress versions prior to 0.16.0 offer an included [VTS Prometheus metrics ## Configuring NGINX Ingress monitoring -If you have deployed NGINX Ingress using GitLab's [Kubernetes cluster integration](../../clusters/index.md#installing-applications), it will [automatically be monitored](#about-managed-nginx-ingress-deployments) by Prometheus. +If you have deployed NGINX Ingress using the GitLab [Kubernetes cluster integration](../../clusters/index.md#installing-applications), Prometheus [automatically monitors it](#about-managed-nginx-ingress-deployments). For other deployments, there is [some configuration](#manually-setting-up-nginx-ingress-for-prometheus-monitoring) required depending on your installation: @@ -37,7 +37,7 @@ For other deployments, there is [some configuration](#manually-setting-up-nginx- ### About managed NGINX Ingress deployments -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). +NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress is [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). NGINX is configured for Prometheus monitoring, by setting: @@ -45,11 +45,11 @@ NGINX is configured for Prometheus monitoring, by setting: - `prometheus.io/scrape: "true"`, to enable automatic discovery. - `prometheus.io/port: "10254"`, to specify the metrics port. -When used in conjunction with the GitLab deployed Prometheus service, response metrics will be automatically collected. +When used in conjunction with the GitLab deployed Prometheus service, response metrics are automatically collected. ### Manually setting up NGINX Ingress for Prometheus monitoring -Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) have built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint will start running on port 10254. +Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) have built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint starts running on port 10254. Next, the Ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: @@ -60,6 +60,6 @@ Managing these settings depends on how NGINX Ingress has been deployed. If you h ## Specifying the Environment label -In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab will search for metrics with appropriate labels. In this case, the `ingress` label must `<CI_ENVIRONMENT_SLUG>`. +In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. In this case, the `ingress` label must `<CI_ENVIRONMENT_SLUG>`. -If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format will be used automatically and metrics will be detected with no action on your part. +If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format is used automatically and metrics are detected with no action on your part. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index ec7b1ee6d10..c855e564753 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -1,14 +1,14 @@ --- stage: Monitor 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/#designated-technical-writers +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 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13438) in GitLab 9.5. -NOTE: **Note:** +NOTE: [NGINX Ingress version 0.16](nginx_ingress.md) and above have built-in Prometheus metrics, which are different than the VTS based metrics. GitLab has support for automatically detecting and monitoring the Kubernetes NGINX Ingress controller. This is provided by leveraging the included VTS Prometheus metrics exporter in [version 0.9.0](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#09-beta1) through [0.15.x](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0150). @@ -27,7 +27,7 @@ GitLab has support for automatically detecting and monitoring the Kubernetes NGI ## Configuring NGINX Ingress monitoring -If you have deployed NGINX Ingress using GitLab's [Kubernetes cluster integration](../../clusters/index.md#installing-applications), it will [automatically be monitored](#about-managed-nginx-ingress-deployments) by Prometheus. +If you have deployed NGINX Ingress using the GitLab [Kubernetes cluster integration](../../clusters/index.md#installing-applications), Prometheus [automatically monitors](#about-managed-nginx-ingress-deployments) it. For other deployments, there is [some configuration](#manually-setting-up-nginx-ingress-for-prometheus-monitoring) required depending on your installation: @@ -37,7 +37,7 @@ For other deployments, there is [some configuration](#manually-setting-up-nginx- ### About managed NGINX Ingress deployments -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). +NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress is [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). NGINX is configured for Prometheus monitoring, by setting: @@ -45,11 +45,11 @@ NGINX is configured for Prometheus monitoring, by setting: - `prometheus.io/scrape: "true"`, to enable automatic discovery. - `prometheus.io/port: "10254"`, to specify the metrics port. -When used in conjunction with the GitLab deployed Prometheus service, response metrics will be automatically collected. +When used in conjunction with the GitLab deployed Prometheus service, response metrics are automatically collected. ### Manually setting up NGINX Ingress for Prometheus monitoring -Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) has built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint will start running on port 10254. +Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) has built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint begins running on port 10254. Next, the Ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: @@ -60,6 +60,6 @@ Managing these settings depends on how NGINX Ingress has been deployed. If you h ## Specifying the Environment label -In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab will search for metrics with appropriate labels. In this case, the `upstream` label must be of the form `<KUBE_NAMESPACE>-<CI_ENVIRONMENT_SLUG>-*`. +In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. In this case, the `upstream` label must be of the form `<KUBE_NAMESPACE>-<CI_ENVIRONMENT_SLUG>-*`. -If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format will be used automatically and metrics will be detected with no action on your part. +If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format is used automatically and metrics are detected with no action on your part. diff --git a/doc/user/project/integrations/prometheus_units.md b/doc/user/project/integrations/prometheus_units.md index ee4f3ed77d4..0c2ce3002ee 100644 --- a/doc/user/project/integrations/prometheus_units.md +++ b/doc/user/project/integrations/prometheus_units.md @@ -3,3 +3,6 @@ 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/redmine.md b/doc/user/project/integrations/redmine.md index 2a85dd9b79b..38d6194b390 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Redmine Service @@ -15,9 +15,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w | ----- | ----------- | | `project_url` | The URL to the project in Redmine which is being linked to this GitLab project | | `issues_url` | The URL to the issue in Redmine project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | - | `new_issue_url` | This is the URL to create a new issue in Redmine for the project linked to this GitLab project. **This is currently not being used and will be removed in a future release.** | + | `new_issue_url` | This is the URL to create a new issue in Redmine for the project linked to this GitLab project. **This is currently not being used and is planned be removed in a future release.** | - Once you have configured and enabled Redmine you'll see the Redmine link on the GitLab project pages that takes you to the appropriate Redmine project. + Once you have configured and enabled Redmine, you see the Redmine link on the GitLab project pages that takes you to the appropriate Redmine project. As an example, below is a configuration for a project named `gitlab-ci`. @@ -34,7 +34,7 @@ Issues in Redmine can be referenced in two alternative ways: then followed by capital letters, numbers or underscores, and `<ID>` is a number (example `API_32-143`). -We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker the internal issue will be linked. +We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker, the internal issue is linked. Please note that `<PROJECT>` part is ignored and links always point to the address specified in `issues_url`. diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md index d549921b9d9..1de69f60a34 100644 --- a/doc/user/project/integrations/servicenow.md +++ b/doc/user/project/integrations/servicenow.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # ServiceNow integration diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md index abb072c9a0a..a60af93a899 100644 --- a/doc/user/project/integrations/services_templates.md +++ b/doc/user/project/integrations/services_templates.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 templates @@ -24,8 +24,7 @@ If you disable the template: - GitLab default values again become the default values for integrations on new projects. -- Projects previously configured using the template will continue to use - those settings. +- Projects previously configured using the template continue to use those settings. If you change the template, the revised values are applied to new projects. This feature does not provide central administration of integration settings. @@ -49,7 +48,7 @@ Recommendation: - Copy the working settings from a project to the template. There is no "Test settings" option when enabling templates. If the settings do not work, -these incorrect settings will be applied to all existing projects that do not already have +these incorrect settings are applied to all existing projects that do not already have the integration configured. Fixing the integration then needs to be done project-by-project. ## Service for external issue trackers @@ -58,6 +57,6 @@ The following image shows an example service template for Redmine.  -For each project, you will still need to configure the issue tracking +For each project, you still need to configure the issue tracking URLs by replacing `:issues_tracker_id` in the above screenshot with the ID used by your external issue tracker. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index e6f12c2532f..9e9f5b8297f 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 Notifications Service @@ -10,16 +10,16 @@ The Slack Notifications Service allows your GitLab project to send events (such as issue creation) to your existing Slack team as notifications. Setting up Slack notifications requires configuration changes for both Slack and GitLab. -NOTE: **Note:** +NOTE: You can also use Slack slash commands to control GitLab inside Slack. This is the separately configured [Slack slash commands](slack_slash_commands.md). ## Slack configuration 1. Sign in to your Slack team and [start a new Incoming WebHooks configuration](https://my.slack.com/services/new/incoming-webhook). -1. Select the Slack channel where notifications will be sent to by default. +1. Select the Slack channel where notifications should be sent to by default. Click the **Add Incoming WebHooks integration** button to add the configuration. -1. Copy the **Webhook URL**, which we will use later in the GitLab configuration. +1. Copy the **Webhook URL**, which we use later in the GitLab configuration. ## GitLab configuration @@ -36,7 +36,7 @@ separately configured [Slack slash commands](slack_slash_commands.md). - To send messages to channels, enter the Slack channel names, separated by commas. - To send direct messages, use the Member ID found in the user's Slack profile. - NOTE: **Note:** + NOTE: Usernames and private channels are not supported. 1. In **Webhook**, provide the webhook URL that you copied from the @@ -47,7 +47,7 @@ separately configured [Slack slash commands](slack_slash_commands.md). to send notifications for. 1. Click **Test settings and save changes**. -Your Slack team will now start receiving GitLab event notifications as configured. +Your Slack team now starts receiving GitLab event notifications as configured. ### Triggers available for Slack notifications @@ -110,7 +110,7 @@ result = Net::HTTP.get(URI('https://<GITLAB URL>'));0 ``` If GitLab is not trusting HTTPS connections to itself, then you may -need to [add your certificate to GitLab's trusted certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). +need to [add your certificate to the GitLab trusted certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). If GitLab is not trusting connections to Slack, then the GitLab OpenSSL trust store is incorrect. Some typical causes: overriding diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 7c2413fce81..1e4577fb88e 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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)** @@ -14,7 +14,7 @@ Slack, without having to leave it. This requires configurations in both Slack an GitLab can also send events (e.g., `issue created`) to Slack as notifications. This is the separately configured [Slack Notifications Service](slack.md). -NOTE: **Note:** +NOTE: For GitLab.com, use the [Slack app](gitlab_slack_application.md) instead. ## Configuration diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index c4959a8711b..e8dcb577aba 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Unify Circuit service @@ -12,7 +12,8 @@ The Unify Circuit service sends notifications from GitLab to the conversation fo 1. Open the conversation in which you want to see the notifications. 1. From the conversation menu, select **Configure Webhooks**. -1. Click **ADD WEBHOOK** and fill in the name of the bot that will post the messages. Optionally define avatar. +1. Click **ADD WEBHOOK** and fill in the name of the bot to post the messages. Optionally + define an avatar. 1. Click **SAVE** and copy the **Webhook URL** of your webhook. For more information, see the [Unify Circuit documentation for configuring incoming webhooks](https://www.circuit.com/unifyportalfaqdetail?articleId=164448). @@ -28,6 +29,6 @@ When you have the **Webhook URL** for your Unify Circuit conversation webhook, y 1. Paste the **Webhook URL** that you copied from the Unify Circuit configuration step. 1. Configure the remaining options and click `Save changes`. -Your Unify Circuit conversation will now start receiving GitLab event notifications as configured. +Your Unify Circuit conversation now starts receiving GitLab event notifications as configured.  diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 7654909b735..8a3383fd0e7 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Webex Teams service @@ -10,7 +10,7 @@ You can configure GitLab to send notifications to a Webex Teams space. ## Create a webhook for the space -1. Go to the [Incoming Webhooks app page](https://apphub.webex.com/teams/applications/incoming-webhooks-cisco-systems-38054). +1. Go to the [Incoming Webhooks app page](https://apphub.webex.com/messaging/applications/incoming-webhooks-cisco-systems-38054). 1. Click **Connect** and log in to Webex Teams, if required. 1. Enter a name for the webhook and select the space to receive the notifications. 1. Click **ADD**. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 6a436c5093e..d8b51e8b777 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1,18 +1,18 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Webhooks Project webhooks allow you to trigger a URL if for example new code is pushed or a new issue is created. You can configure webhooks to listen for specific events -like pushes, issues or merge requests. GitLab will send a POST request with data +like pushes, issues or merge requests. GitLab sends a POST request with data to the webhook URL. -In most cases, you'll need to set up your own [webhook receiver](#example-webhook-receiver) -to receive information from GitLab, and send it to another app, according to your needs. +You usually need to set up your own [webhook receiver](#example-webhook-receiver) +to receive information from GitLab and send it to another app, according to your requirements. We already have a [built-in receiver](slack.md) for sending [Slack](https://api.slack.com/incoming-webhooks) notifications _per project_. @@ -31,10 +31,9 @@ update a backup mirror, or even deploy to your production server. They are available **per project** for GitLab Community Edition, and **per project and per group** for **GitLab Enterprise Edition**. -Navigate to the webhooks page by going to your project's -**Settings ➔ Webhooks**. +Navigate to the webhooks page at your project's **Settings > Webhooks**. -NOTE: **Note:** +NOTE: On GitLab.com, the [maximum number of webhooks and their size](../../../user/gitlab_com/index.md#webhooks) per project, and per group, is limited. ## Version history @@ -55,7 +54,7 @@ Starting from GitLab 11.2: ``) have their target URL changed to an absolute URL. See [image URL rewriting](#image-url-rewriting) for more details. -## Use-cases +## Possible uses for webhooks - You can set up a webhook in GitLab to send a notification to [Slack](https://api.slack.com/incoming-webhooks) every time a job fails. @@ -65,27 +64,29 @@ Starting from GitLab 11.2: ## Webhook endpoint tips -If you are writing your own endpoint (web server) that will receive -GitLab webhooks keep in mind the following things: +If you are writing your own endpoint (web server) to receive +GitLab webhooks, keep in mind the following: -- Your endpoint should send its HTTP response as fast as possible. If - you wait too long, GitLab may decide the hook failed and retry it. +- Your endpoint should send its HTTP response as fast as possible. If the response takes longer than + the configured timeout, GitLab decides the hook failed and retries it. For information on + customizing this timeout, see + [Webhook fails or multiple webhook requests are triggered](#webhook-fails-or-multiple-webhook-requests-are-triggered). - Your endpoint should ALWAYS return a valid HTTP response. If you do - not do this then GitLab will think the hook failed and retry it. + not do this then GitLab thinks the hook failed and retries it. Most HTTP libraries take care of this for you automatically but if you are writing a low-level hook this is important to remember. - GitLab ignores the HTTP status code returned by your endpoint. ## Secret token -If you specify a secret token, it will be sent with the hook request in the +If you specify a secret token, it is sent with the hook request in the `X-Gitlab-Token` HTTP header. Your webhook endpoint can check that to verify that the request is legitimate. ## SSL verification By default, the SSL certificate of the webhook endpoint is verified based on -an internal list of Certificate Authorities, which means the certificate cannot +an internal list of Certificate Authorities. This means the certificate cannot be self-signed. You can turn this off in the webhook settings in your GitLab projects. @@ -108,15 +109,15 @@ Below are described the supported events. Triggered when you push to the repository except when pushing tags. -NOTE: **Note:** +NOTE: When more than 20 commits are pushed at once, the `commits` webhook -attribute will only contain the first 20 for performance reasons. Loading +attribute only contains the first 20 for performance reasons. Loading detailed commit data is expensive. Note that despite only 20 commits being -present in the `commits` attribute, the `total_commits_count` attribute will -contain the actual total. +present in the `commits` attribute, the `total_commits_count` attribute contains the actual total. Also, if a single push includes changes for more than three (by default, depending on -[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) branches, this hook won't be executed. +[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) +branches, this hook isn't executed. **Request header**: @@ -203,9 +204,10 @@ X-Gitlab-Event: Push Hook Triggered when you create (or delete) tags to the repository. -NOTE: **Note:** +NOTE: If a single push includes changes for more than three (by default, depending on -[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) tags, this hook won't be executed. +[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) +tags, this hook is not executed. **Request header**: @@ -407,14 +409,15 @@ X-Gitlab-Event: Issue Hook } ``` -> **Note**: `assignee` and `assignee_id` keys are deprecated and now show the first assignee only. +NOTE: +`assignee` and `assignee_id` keys are deprecated and now show the first assignee only. ### Comment events Triggered when a new comment is made on commits, merge requests, issues, and code snippets. -The note data will be stored in `object_attributes` (e.g. `note`, `noteable_type`). The -payload will also include information about the target of the comment. For example, -a comment on an issue will include the specific issue information under the `issue` key. +The note data is stored in `object_attributes` (for example, `note` or `noteable_type`). The +payload also includes information about the target of the comment. For example, +a comment on an issue includes the specific issue information under the `issue` key. Valid target types: - `commit` @@ -732,7 +735,8 @@ X-Gitlab-Event: Note Hook } ``` -> **Note**: `assignee_id` field is deprecated and now shows the first assignee only. +NOTE: +`assignee_id` field is deprecated and now shows the first assignee only. #### Comment on code snippet @@ -1358,6 +1362,38 @@ X-Gitlab-Event: Deployment Hook Note that `deployable_id` is the ID of the CI job. +### Member events + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260347) in GitLab 13.7. + +Triggered when a user is added as a group member. + +**Request Header**: + +```plaintext +X-Gitlab-Event: Member Hook +``` + +**Request Body**: + +```json +{ + "created_at": "2020-12-11T04:57:22Z", + "updated_at": "2020-12-11T04:57:22Z", + "group_name": "webhook-test", + "group_path": "webhook-test", + "group_id": 100, + "user_username": "test_user", + "user_name": "Test User", + "user_email": "testuser@webhooktest.com", + "user_id": 64, + "group_access": "Guest", + "group_plan": null, + "expires_at": "2020-12-14T00:00:00Z", + "event_name": "user_add_to_group" +} +``` + ### Feature Flag events Triggered when a feature flag is turned on or off. @@ -1502,21 +1538,22 @@ its description:  ``` -It will appear in the webhook body as the below (assuming that GitLab is -installed at `gitlab.example.com`, and the project is at -`example-group/example-project`): +It appears in the webhook body as follows assuming that: + +- GitLab is installed at `gitlab.example.com`. +- The project is at `example-group/example-project`. ```markdown  ``` -This will not rewrite URLs that already are pointing to HTTP, HTTPS, or -protocol-relative URLs. It will also not rewrite image URLs using advanced +This doesn't rewrite URLs that already are pointing to HTTP, HTTPS, or +protocol-relative URLs. It also doesn't rewrite image URLs using advanced Markdown features, like link labels. ## Testing webhooks -You can trigger the webhook manually. Sample data from the project will be used. +You can trigger the webhook manually. Sample data from the project is used. > For example: for triggering `Push Events` your project should have at least one commit.  @@ -1528,29 +1565,36 @@ You can find records for last 2 days in "Recent Deliveries" section on the edit  -In this section you can see HTTP status code (green for 200-299 codes, red for the others, `internal error` for failed deliveries ), triggered event, a time when the event was called, elapsed time of the request. +In this section you can see: + +- HTTP status code (green for `200-299` codes, red for the others, `internal error` for failed deliveries). +- Triggered event. +- A time when the event was called. +- Elapsed time of the request. If you need more information about execution, you can click `View details` link. On this page, you can see data that GitLab sends (request headers and body) and data that it received (response headers and body). From this page, you can repeat delivery with the same data by clicking `Resend Request` button. -NOTE: **Note:** -If URL or secret token of the webhook were updated, data will be delivered to the new address. +NOTE: +If URL or secret token of the webhook were updated, data is delivered to the new address. -### Receiving duplicate or multiple webhook requests triggered by one event +### Webhook fails or multiple webhook requests are triggered -When GitLab sends a webhook it expects a response in 10 seconds (set default value). If it does not receive one, it'll retry the webhook. -If the endpoint doesn't send its HTTP response within those 10 seconds, GitLab may decide the hook failed and retry it. +When GitLab sends a webhook, it expects a response in 10 seconds by default. If it does not receive +one, it retries the webhook. If the endpoint doesn't send its HTTP response within those 10 seconds, +GitLab may decide the hook failed and retry it. -If you are receiving multiple requests, you can try increasing the default value to wait for the HTTP response after sending the webhook -by uncommenting or adding the following setting to your `/etc/gitlab/gitlab.rb`: +If your webhooks are failing or you are receiving multiple requests, you can try changing the +default value. You can do this by uncommenting or adding the following setting to your +`/etc/gitlab/gitlab.rb` file: ```ruby gitlab_rails['webhook_timeout'] = 10 ``` -### Troubleshooting: "Unable to get local issuer certificate" +### Unable to get local issuer certificate When SSL verification is enabled, this error indicates that GitLab isn't able to verify the SSL certificate of the webhook endpoint. Typically, this is because the root certificate isn't issued by a trusted certification authority as @@ -1561,7 +1605,7 @@ Missing intermediate certificates are a common point of verification failure. ## Example webhook receiver -If you want to see GitLab's webhooks in action for testing purposes you can use +If you want to see GitLab webhooks in action for testing purposes you can use a simple echo script running in a console session. For the following script to work you need to have Ruby installed. @@ -1581,7 +1625,7 @@ end server.start ``` -Pick an unused port (e.g. 8000) and start the script: `ruby print_http_body.rb +Pick an unused port (for example, `8000`) and start the script: `ruby print_http_body.rb 8000`. Then add your server as a webhook receiver in GitLab as `http://my.host:8000/`. @@ -1594,5 +1638,6 @@ example.com - - [14/May/2014:07:45:26 EDT] "POST / HTTP/1.1" 200 0 - -> / ``` -NOTE: **Note:** -You may need to [allow requests to the local network](../../../security/webhooks.md) for this receiver to be added. +NOTE: +You may need to [allow requests to the local network](../../../security/webhooks.md) for this +receiver to be added. diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index d243ffc7a37..f9b3c083a54 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -1,7 +1,7 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # YouTrack Service @@ -17,14 +17,14 @@ To enable YouTrack integration in a project: 1. Navigate to the project's **Settings > [Integrations](overview.md#accessing-integrations)** page. 1. Click the **YouTrack** service, ensure it's active, and enter the required details on the page as described in the table below. - | Field | Description | - |:----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| - | **Project URL** | URL to the project in YouTrack which is being linked to this GitLab project. | - | **Issues URL** | URL to the issue in YouTrack project that is linked to this GitLab project. Note that the **Issues URL** requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | + | Field | Description | + |:----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | **Project URL** | URL to the project in YouTrack which is being linked to this GitLab project. | + | **Issues URL** | URL to the issue in YouTrack project that is linked to this GitLab project. Note that the **Issues URL** requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | 1. Click the **Save changes** button. -Once you have configured and enabled YouTrack, you'll see the YouTrack link on the GitLab project pages that takes you to the appropriate YouTrack project. +Once you have configured and enabled YouTrack, you see the YouTrack link on the GitLab project pages that takes you to the appropriate YouTrack project. ## Disable the internal issue tracker diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 116602fbbb9..e0f66013454 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 @@ -51,11 +51,54 @@ To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enter Watch a [video presentation](https://youtu.be/vjccjHI7aGI) of 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 allow for more than one issue board for a given project **(CORE)** 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. + +When you have ten or more boards available, a **Recent** section is also shown in the menu, with +shortcuts to your last four visited boards. + + + +When you're revisiting an issue board in a project or group with multiple boards, +GitLab automatically loads the last board you visited. + +### Create an issue board + +To create a new issue board: + +1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. +1. Click **Create new board**. +1. Enter the new board's name and select its scope: milestone, labels, assignee, or weight. + +### Delete an issue board + +To delete the currently active issue board: + +1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. +1. Click **Delete board**. +1. Click **Delete** to confirm. + ## Issue boards use cases You can tailor GitLab issue boards to your own preferred workflow. Here are some common use cases for issue boards. +For examples of using issue boards along with [epics](../group/epics/index.md) **(PREMIUM)**, +[issue health status](issues/index.md#health-status) **(ULTIMATE)**, and +[scoped labels](labels.md#scoped-labels) **(PREMIUM)** for various Agile frameworks, check: + +- The [How to use GitLab for Agile portfolio planning and project management](https://about.gitlab.com/blog/2020/11/11/gitlab-for-agile-portfolio-planning-project-management/) blog post (November 2020) +- <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +[Cross-project Agile work management with GitLab](https://www.youtube.com/watch?v=5J0bonGoECs) (15 min, July 2020) + ### Use cases for a single issue board With the GitLab Workflow you can discuss proposals in issues, label @@ -113,7 +156,7 @@ When finished with something, they move the card to **Frontend**. The Frontend t Cards finished by the UX team automatically appear in the **Frontend** column when they are ready for them. -NOTE: **Note:** +NOTE: For a broader use case, please see the blog post [GitLab Workflow, an Overview](https://about.gitlab.com/blog/2016/10/25/gitlab-workflow-an-overview/#gitlab-workflow-use-case-scenario). For a real use case example, you can read why @@ -122,7 +165,10 @@ to improve their workflow with multiple boards. #### Quick assignments -Create lists for each of your team members and quickly drag issues onto each team member's list. +To quickly assign issues to your team members: + +1. Create [assignee lists](#assignee-lists) for each team member. +1. Drag an issue onto the team member's list. ## Issue board terminology @@ -185,41 +231,6 @@ and vice versa. GitLab issue boards are available on GitLab Core and GitLab.com Free tiers, but some advanced functionality is present in [higher tiers only](https://about.gitlab.com/pricing/). -### 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 allow for more than one issue board for a given project or group. -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. - -When you have ten or more boards available, a **Recent** section is also shown in the menu, with -shortcuts to your last four visited boards. - - - -When you're revisiting an issue board in a project or group with multiple boards, -GitLab automatically loads the last board you visited. - -#### Create an issue board - -To create a new issue board: - -1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. -1. Click **Create new board**. -1. Enter the new board's name and select its scope: milestone, labels, assignee, or weight. - -#### Delete an issue board - -To delete the currently active issue board: - -1. Click the dropdown with the current board name in the upper left corner of the Issue Boards page. -1. Click **Delete board**. -1. Click **Delete** to confirm. - ### Configurable issue boards **(STARTER)** > [Introduced](https://about.gitlab.com/releases/2017/11/22/gitlab-10-2-released/#issue-boards-configuration) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.2. @@ -315,6 +326,9 @@ With swimlanes you can visualize issues grouped by epic. Your issue board keeps all the other features, but with a different visual organization of issues. This feature is available both at the project and group level. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a video overview, see [Epics Swimlanes Walkthrough - 13.6](https://www.youtube.com/watch?v=nHC7-kz5P2g) (November 2020). + To group issues by epic in an issue board: 1. Select the **Group by** dropdown button. @@ -380,19 +394,6 @@ status. If you're not able to do some of the things above, make sure you have the right [permissions](#permissions). -### First time using an issue board - -> The automatic creation of the **To Do** and **Doing** lists was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202144) in GitLab 13.5. - -The first time you open an issue board, you are presented with the default lists -(**Open**, **To Do**, **Doing**, and **Closed**). - -If the **To Do** and **Doing** labels don't exist in the project or group, they are created, and -their lists appear as empty. If any of them already exists, the list is filled with the issues that -have that label. - - - ### Create a new list Create a new list by clicking the **Add list** dropdown button in the upper right corner of the issue board. @@ -419,7 +420,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 +### Add issues to a list **(CORE ONLY)** + +> - 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)** 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 @@ -432,13 +439,30 @@ the list by filtering by the following: - Assignee - Author - Epic +- Iteration ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6) - Label - Milestone - My Reaction - Release - Weight - +#### Enable or disable adding issues to the list **(CORE ONLY)** + +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) +can enable it. + +To enable it: + +```ruby +Feature.enable(:add_issues_button) +``` + +To disable it: + +```ruby +Feature.disable(:add_issues_button) +``` ### Remove an issue from a list @@ -459,6 +483,7 @@ You can filter by the following: - Assignee - Author - Epic +- Iteration ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6) - Label - Milestone - My Reaction @@ -528,6 +553,22 @@ To select and move multiple cards:  +### First time using an issue board + +> - The automatic creation of the **To Do** and **Doing** lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202144) in GitLab 13.5. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/270583) in GitLab 13.7. In GitLab 13.7 and later, the **To Do** and **Doing** columns are not automatically created. + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/270583) in GitLab 13.7. +The **To Do** and **Doing** columns are no longer automatically created. + +In GitLab 13.5 and 13.6, the first time you open an issue board, you are presented with the default lists +(**Open**, **To Do**, **Doing**, and **Closed**). + +If the **To Do** and **Doing** labels don't exist in the project or group, they are created, and +their lists appear as empty. If any of them already exists, the list is filled with the issues that +have that label. + ## Tips A few things to remember: diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index a026854a947..d81fe19c5b9 100644 --- a/doc/user/project/issues/associate_zoom_meeting.md +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 --- # Associate a Zoom meeting with an issue @@ -10,13 +10,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w In order to communicate synchronously for incidents management, GitLab allows to associate a Zoom meeting with an issue. -Once you start a Zoom call for a fire-fight, you need a way to -associate the conference call with an issue, so that your team -members can join swiftly without requesting a link. +After you start a Zoom call for a fire-fight, you need a way to +associate the conference call with an issue. This is so that your +team members can join swiftly without requesting a link. -## Adding a zoom meeting to an issue +## Adding a Zoom meeting to an issue -To associate a zoom meeting with an issue, you can use GitLab's +To associate a Zoom meeting with an issue, you can use GitLab [quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). In an issue, leave a comment using the `/zoom` quick action followed by a valid Zoom link: @@ -26,23 +26,23 @@ In an issue, leave a comment using the `/zoom` quick action followed by a valid ``` If the Zoom meeting URL is valid and you have at least [Reporter permissions](../../permissions.md), -a system alert will notify you that the addition of the meeting URL was successful. -The issue's description will be automatically edited to include the Zoom link, and a button will -appear right under the issue's title. +a system alert notifies you of its successful addition. +The issue's description is automatically edited to include the Zoom link, and a button +appears right under the issue's title.  You are only allowed to attach a single Zoom meeting to an issue. If you attempt -to add a second Zoom meeting using the `/zoom` quick action, it won't work, you +to add a second Zoom meeting using the `/zoom` quick action, it doesn't work. You need to [remove it](#removing-an-existing-zoom-meeting-from-an-issue) first. ## Removing an existing Zoom meeting from an issue -Similarly to adding a zoom meeting, you can remove it with a quick action: +Similarly to adding a Zoom meeting, you can remove it with a quick action: ```shell /remove_zoom ``` If you have at least [Reporter permissions](../../permissions.md), -a system alert will notify you that the meeting URL was successfully removed. +a system alert notifies you that the meeting URL was successfully removed. diff --git a/doc/user/project/issues/automatic_issue_closing.md b/doc/user/project/issues/automatic_issue_closing.md index dab79327d6a..6fa2822aa9a 100644 --- a/doc/user/project/issues/automatic_issue_closing.md +++ b/doc/user/project/issues/automatic_issue_closing.md @@ -3,3 +3,6 @@ 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 index 04f1c8e1a4a..45b905f2fb5 100644 --- a/doc/user/project/issues/closing_issues.md +++ b/doc/user/project/issues/closing_issues.md @@ -3,3 +3,6 @@ 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 5bb8805159a..02cb0313a74 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 --- # Confidential issues @@ -46,7 +46,7 @@ system note in the issue's comments. ## Indications of a confidential issue -NOTE: **Note:** +NOTE: If you don't have [enough permissions](#permissions-and-access-to-confidential-issues), you won't be able to see the confidential issues at all. @@ -100,7 +100,7 @@ confidential information prematurely. When the confidential commits are ready to be made public, this can be done by opening a merge request from the private fork to the public upstream project. -TIP: **Best practice:** +NOTE: If you create a long-lived private fork in the same group or in a sub-group of the original upstream, all the users with Developer membership to the public project will also have the same permissions in the private project. This way, diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md index 8eec29716c1..53648b53ea3 100644 --- a/doc/user/project/issues/create_new_issue.md +++ b/doc/user/project/issues/create_new_issue.md @@ -3,3 +3,6 @@ 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/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index 2a75f8ad837..b5d3b71e679 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 --- # Crosslinking Issues @@ -31,7 +31,7 @@ git commit -m "this is my commit message. Related to https://gitlab.com/<usernam Of course, you can replace `gitlab.com` with the URL of your own GitLab instance. -NOTE: **Note:** +NOTE: Linking your first commit to your issue is going to be relevant for tracking your process with [GitLab Value Stream Analytics](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). It will measure the time taken for planning the implementation of that issue, diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index af9a6401474..023a8ee57bc 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Export Issues to CSV @@ -35,11 +35,11 @@ Among numerous use cases for exporting issues for CSV, we can name a few: ## Choosing which issues to include -After selecting a project, from the issues page you can narrow down which issues to export using the search bar, along with the All/Open/Closed tabs. All issues returned will be exported, including those not shown on the first page. +After selecting a project, from the issues page you can narrow down which issues to export using the search bar, along with the All/Open/Closed tabs. All issues returned are exported, including those not shown on the first page.  -You will be asked to confirm the number of issues and email address for the export, after which the email will begin being prepared. +GitLab asks you to confirm the number of issues and email address for the export, after which the email is prepared.  @@ -53,7 +53,7 @@ Exported issues are always sorted by `Issue ID`. > > **Weight** and **Locked** columns were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5300) in GitLab Starter 10.8. -Data will be encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row will be the headers, which are listed in the following table along with a description of the values: +Data wis 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 | |---------|-------------| @@ -82,4 +82,4 @@ Data will be encoded with a comma as the column delimiter, with `"` used to quot ## Limitations - Export Issues to CSV is not available at the Group's Issues List. -- As the issues will be sent as an email attachment, there is a limit on how much data can be exported. Currently this limit is 15MB to ensure successful delivery across a range of email providers. If this limit is reached we suggest narrowing the search before export, perhaps by exporting open and closed issues separately. +- As the issues are sent as an email attachment, there is a limit on how much data can be exported. Currently this limit is 15MB to ensure successful delivery across a range of email providers. If this limit is reached we suggest narrowing the search before export, perhaps by exporting open and closed issues separately. diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index 2cac88b1b29..0d10f028cbf 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Importing issues from CSV @@ -11,9 +11,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w Issues can be imported to a project by uploading a CSV file with the columns `title` and `description`. -The user uploading the CSV file will be set as the author of the imported issues. +The user uploading the CSV file is set as the author of the imported issues. -NOTE: **Note:** +NOTE: A permission level of [Developer](../../permissions.md), or higher, is required to import issues. diff --git a/doc/user/project/issues/deleting_issues.md b/doc/user/project/issues/deleting_issues.md index e50259e0dcf..d8e1485a2dc 100644 --- a/doc/user/project/issues/deleting_issues.md +++ b/doc/user/project/issues/deleting_issues.md @@ -3,3 +3,6 @@ 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 c19c9ca0615..3739070be01 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -1,7 +1,7 @@ --- stage: Create group: Knowledge -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" +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)** @@ -37,7 +37,7 @@ to be enabled: Design Management also requires that projects are using [hashed storage](../../../administration/raketasks/storage.md#migrate-to-hashed-storage). Since - GitLab 10.0, newly created projects use hashed storage by default. A GitLab admin can verify the storage type of a + GitLab 10.0, newly created projects use hashed storage by default. A GitLab administrator can verify the storage type of a project by navigating to **Admin Area > Projects** and then selecting the project in question. A project can be identified as hashed-stored if its *Gitaly relative path* contains `@hashed`. @@ -95,7 +95,7 @@ you can drag and drop designs onto the dedicated drop zone to upload them. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202634) in GitLab 12.10, you can also copy images from your file system and -paste them directly on GitLab's Design page as a new design. +paste them directly on the GitLab Design page as a new design. On macOS you can also take a screenshot and immediately copy it to the clipboard by simultaneously clicking <kbd>Control</kbd> + <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>3</kbd>, and then paste it as a design. @@ -170,7 +170,7 @@ Once selected, click the **Delete selected** button to confirm the deletion:  -NOTE: **Note:** +NOTE: Only the latest version of the designs can be deleted. Deleted designs are not permanently lost; they can be viewed by browsing previous versions. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index b3ebefadef0..63cd784333a 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Due dates diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 716377f2e45..05e7eb3021a 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -1,10 +1,10 @@ --- 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/#designated-technical-writers +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 +# Issues **(CORE)** Issues are the fundamental medium for collaborating on ideas and planning work in GitLab. @@ -35,7 +35,7 @@ you can also view all the issues collectively at the group level. See also [Always start a discussion with an issue](https://about.gitlab.com/blog/2016/03/03/start-with-an-issue/). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -To learn how GitLab's Strategic Marketing department uses GitLab issues with [labels](../labels.md) and +To learn how our Strategic Marketing department uses GitLab issues with [labels](../labels.md) and [issue boards](../issue_board.md), see the video on [Managing Commitments with Issues](https://www.youtube.com/watch?v=cuIHNintg1o&t=3). @@ -93,7 +93,7 @@ must be set. While you can view and manage the full details of an issue on the [issue page](#issue-page), you can also work with multiple issues at a time using the [Issues List](#issues-list), -[Issue Boards](#issue-boards), Issue references, and [Epics](#epics)**(PREMIUM)**. +[Issue Boards](#issue-boards), Issue references, and [Epics](#epics). **(PREMIUM)** Key actions for issues include: @@ -191,6 +191,7 @@ requires [GraphQL](../../../api/graphql/index.md) to be enabled. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36427) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. > - Health status of closed issues [can't be edited](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4 and later. > - Issue health status visible in issue lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45141) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7. To help you track the status of your issues, you can assign a status to each issue to flag work that's progressing as planned or needs attention to keep on schedule: @@ -207,16 +208,6 @@ until the issue is reopened. You can then see issue statuses in the [issue list](#issues-list) and the [Epic tree](../../group/epics/index.md#issue-health-status-in-epic-tree). -#### Disable issue health status - -This feature comes with the `:save_issuable_health_status` feature flag enabled by default. However, in some cases -this feature is incompatible with old configuration. To turn off the feature while configuration is -migrated, ask a GitLab administrator with Rails console access to run the following command: - -```ruby -Feature.disable(:save_issuable_health_status) -``` - ## Other Issue actions - [Create an issue from a template](../../project/description_templates.md#using-the-templates) diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index a5f60fbd515..2520a562f1e 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 Data and Actions @@ -10,14 +10,16 @@ Please read through the [GitLab Issue Documentation](index.md) for an overview o ## Parts of an Issue -The image below illustrates what an issue may look like. Note that certain parts will -look slightly different or will be absent, depending on the version of GitLab being used -and the permissions of the user viewing the issue. +The image below illustrates what an issue may look like. Certain parts +look slightly different or are absent, depending on the GitLab version +and the user's permissions. -You can find all the information for that issue on one screen. +You can find all of an issue's information on one page.  +The numbers in the image correspond to the following features: + - **1.** [Issue actions](#issue-actions) - **2.** [To Do](#to-do) - **3.** [Assignee](#assignee) @@ -47,10 +49,6 @@ You can find all the information for that issue on one screen. - **25.** [Submit comment, start a thread, or comment and close](#submit-comment-start-a-thread-or-comment-and-close) - **26.** [Zoom meetings](#zoom-meetings) -An issue starts with its status (open or closed), followed by its author, -and includes many other functionalities, numbered in the image above to -explain what they mean, one by one. - Many of the elements of the issue screen refresh automatically, such as the title and description, when they are changed by another user. Comments and system notes also update automatically in response to various actions and content updates. @@ -89,17 +87,17 @@ An issue can be assigned to: - Another person. - [Many people](#multiple-assignees). **(STARTER)** -The assignee(s) can be changed as often as needed. The idea is that the assignees are +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. -When assigned to someone, it will appear in their assigned issues list. +When assigned to someone, it appears in their assigned issues list. -TIP: **Tip:** +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)** -Often multiple people work on the same issue together, which can be especially difficult +Often, multiple people work on the same issue together. This can be difficult to track in large teams where there is shared ownership of an issue. In [GitLab Starter](https://about.gitlab.com/pricing/), you can @@ -116,10 +114,10 @@ Select a [milestone](../milestones/index.md) to attribute that issue to. ### Time tracking -Use [GitLab Quick Actions](../quick_actions.md) to [track estimates and time spent on issues](../time_tracking.md). -You can add an [estimate of the time it will take](../time_tracking.md#estimates) -to resolve the issue, and also add [the time spent](../time_tracking.md#time-spent) -on the resolution of the issue. +Use [GitLab Quick Actions](../quick_actions.md) to [track estimates and time +spent on issues](../time_tracking.md). You can add a [time estimate](../time_tracking.md#estimates) +for resolving the issue, and also add [the time spent](../time_tracking.md#time-spent) +to resolve the issue. ### Due date @@ -132,13 +130,12 @@ element. Due dates can be changed as many times as needed. 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). -Group Labels, which allow you to use the same labels for all projects within the same -group, can be also given to issues. They work exactly the same, but they are immediately +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 available to all projects in the group. -TIP: **Tip:** -If a label doesn't exist yet, you can click **Edit**, and it opens a dropdown menu -from which you can select **Create new label**. +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)** @@ -148,9 +145,8 @@ positive values or zero are allowed. ### Confidentiality -You can [set an issue to be confidential](confidential_issues.md). When set, unauthorized -users will not be able to access the issue, and will not see it listed in project -issue boards or the issue list. +You can [set an issue to be confidential](confidential_issues.md). Unauthorized users +cannot access the issue, and it is not listed in the project's issue boards nor list for them. ### Lock issue @@ -165,7 +161,7 @@ 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) -for the issue. This will automatically enable if you participate in the issue in any way. +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. @@ -180,9 +176,9 @@ for the issue. This will automatically enable if you participate in the issue in ### Edit -Clicking this icon opens the issue for editing, and you will have access to all the -same fields as when the issue was created. This icon will not display if the user -does not have permission to edit the issue. +Clicking this icon opens the issue for editing. All the fields which +were shown when the issue was created are displayed for editing. +This icon is only displayed if the user has permission to edit the issue. ### Description @@ -190,22 +186,20 @@ 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). **(STARTER)** ### Mentions You can mention a user or a group present in your GitLab instance with `@username` or -`@groupname` and they will be notified via to-dos and email, unless they have disabled -all notifications in their profile settings. This is controlled in the -[notification settings](../../profile/notifications.md). +`@groupname`. All mentioned users are notified via to-do items and emails, +unless they have disabled all notifications in their profile settings. +This is controlled in the [notification settings](../../profile/notifications.md). -Mentions for yourself (the current logged in user), will be highlighted in a different -color, allowing you to easily see which comments involve you, helping you focus on -them quickly. +Mentions for yourself (the current logged in user) are highlighted +in a different color, which allows you to quickly see which comments involve you. -TIP: **Tip:** Avoid mentioning `@all` in issues and merge requests, as it sends an email notification -to all the members of that project's group, which can be interpreted as spam. +to all the members of that project's group. This might be interpreted as spam. ### Related Issues @@ -217,18 +211,18 @@ You can also click the `+` to add more related issues. Merge requests that were mentioned in that issue's description or in the issue thread are listed as [related merge requests](crosslinking_issues.md#from-merge-requests) here. Also, if the current issue was mentioned as related in another merge request, that -merge request will be listed here. +merge request is also listed here. ### Award emoji -You can award an emoji to that issue. There are shortcuts to "thumbs_up" and "thumbs_down", -or you can click on the light gray "face" to choose a different reaction from the -dropdown list of available [GitLab Flavored Markdown Emoji](../../markdown.md#emoji). +You can award emojis to issues. You can select the "thumbs up" and "thumbs down", +or the gray "smiley-face" to choose from the list of available +[GitLab Flavored Markdown Emoji](../../markdown.md#emoji). -TIP: **Tip:** +NOTE: Posting "+1" as a comment in a thread spams all subscribed participants of that issue, clutters the threads, and is not recommended. Awarding an emoji is a way -to let them know your reaction without spamming them. +to let them know your reaction without notifying them. ### Show all activity @@ -241,21 +235,20 @@ and selecting either: Also: - You can mention a user or a group present in your GitLab instance with - `@username` or `@groupname` and they will be notified via to-do items - and email, unless they have [disabled all notifications](#notifications) + `@username` or `@groupname` and they are notified via to-do items + and emails, unless they have [disabled all notifications](#notifications) in their profile settings. -- Mentions for yourself (the current logged in user), will be highlighted - in a different color, allowing you to easily see which comments involve you, - helping you focus on them quickly. +- Mentions for yourself (the current logged-in user) are highlighted + in a different color, which allows you to quickly see which comments involve you.  ### Create Merge Request Create a new branch and [**Draft** merge request](../merge_requests/work_in_progress_merge_requests.md) -in one action. The branch will be named `issuenumber-title` by default, but you can -choose any name, and GitLab will verify that it is not already in use. The merge request -will automatically inherit the milestone and labels of the issue, and will be set to +in one action. The branch is named `issuenumber-title` by default, but you can +choose any name, and GitLab verifies that it is not already in use. The merge request +inherits the milestone and labels of the issue, and is set to automatically close the issue when it is merged.  @@ -288,11 +281,11 @@ supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-g ### Submit comment, start a thread, or comment and close -Once you write a comment, you can: +After you write a comment, you can: -- Click **Comment** and your comment will be published. +- Click **Comment** and to publish your comment. - Choose **Start thread** from the dropdown list and start a new [thread](../../discussions/index.md#threaded-discussions) - within that issue's main thread to discuss specific points. This invites other participants + 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 23c1520294d..4e2c8bfd7f1 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -2,7 +2,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/issue_weight.html' 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/#designated-technical-writers +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)** @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w 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 will cost. +value or complexity a given issue has or costs. You can set the weight of an issue during its creation, by simply changing the value in the dropdown menu. You can set it to a non-negative integer @@ -20,7 +20,7 @@ upper bound is essentially limitless). You can remove weight from an issue as well. -This value will appear on the right sidebar of an individual issue, as well as +This value appears on the right sidebar of an individual issue, as well as in the issues page next to a distinctive balance scale icon. As an added bonus, you can see the total sum of all issues on the milestone page. diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 62b388ec137..03060ca720c 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 --- # Managing issues @@ -99,7 +99,7 @@ When you click this link, an email address is generated and displayed, which sho by **you only**, to create issues in this project. You can save this address as a contact in your email client for easy access. -CAUTION: **Caution:** +WARNING: This is a private email address, generated just for you. **Keep it to yourself**, as anyone who knows it can create issues or merge requests as if they were you. If the address is compromised, or you'd like it to be regenerated for @@ -112,7 +112,7 @@ this project, where: - The email body becomes the issue description. - [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) are supported. -NOTE: **Note:** +NOTE: In GitLab 11.7, we updated the format of the generated email address. However the older format is still supported, allowing existing aliases or contacts to continue working. @@ -160,7 +160,7 @@ The "Move issue" button is at the bottom of the right-sidebar when viewing the i If you have advanced technical skills you can also bulk move all the issues from one project to another in the rails console. The below script will move all the issues from one project to another that are not in status **closed**. To access rails console run `sudo gitlab-rails console` on the GitLab server and run the below -script. Please be sure to change **project**, **admin_user** and **target_project** to your values. +script. Please be sure to change `project`, `admin_user`, and `target_project` to your values. We do also recommend [creating a backup](../../../raketasks/backup_restore.md#back-up-gitlab) before attempting any changes in the console. @@ -193,7 +193,7 @@ from its list and dropping it into the **Closed** list. ### Closing issues automatically -NOTE: **Note:** +NOTE: For performance reasons, automatic issue closing is disabled for the very first push from an existing repository. @@ -234,7 +234,7 @@ This translates to the following keywords: - Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving - Implement, Implements, Implemented, Implementing, implement, implements, implemented, implementing -Note that `%{issue_ref}` is a complex regular expression defined inside GitLab's +Note that `%{issue_ref}` is a complex regular expression defined inside the GitLab source code that can match references to: - A local issue (`#123`). diff --git a/doc/user/project/issues/moving_issues.md b/doc/user/project/issues/moving_issues.md index 8331f865b83..3b40affcdc3 100644 --- a/doc/user/project/issues/moving_issues.md +++ b/doc/user/project/issues/moving_issues.md @@ -3,3 +3,6 @@ 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 b1806460c08..bb9038062f7 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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)** diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index b040bcf3b03..82b2d4fde52 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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)** @@ -23,7 +23,7 @@ The relationship only shows up in the UI if the user can see both issues. When you try to close an issue that has open blockers, a warning is displayed. -TIP: **Tip:** +NOTE: To manage related issues through our API, visit the [issue links API documentation](../../../api/issue_links.md). ## Adding a related issue diff --git a/doc/user/project/issues/similar_issues.md b/doc/user/project/issues/similar_issues.md index 9cbac53ee41..79a50d5f812 100644 --- a/doc/user/project/issues/similar_issues.md +++ b/doc/user/project/issues/similar_issues.md @@ -3,3 +3,6 @@ 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 8a8359a4b02..b4cb1c383ba 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -1,13 +1,24 @@ --- 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/#designated-technical-writers +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 +# Sorting and ordering issue lists **(CORE)** -You can sort a list of issues several ways, including by issue creation date, milestone due date, -etc. The available sorting options can change based on the context of the list. +You can sort a list of issues several ways, including by: + +- Blocking +- Created date +- Due date +- Label priority +- Last updated +- Milestone due date +- Popularity +- Priority +- Weight + +The available sorting options can change based on the context of the list. For sorting by issue priority, see [Label Priority](../labels.md#label-priority). In group and project issue lists, it is also possible to order issues manually, @@ -18,19 +29,25 @@ similar to [issue boards](../issue_board.md#how-gitlab-orders-issues-in-a-list). > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/62178) in GitLab 12.2. When you select **Manual** sorting, you can change -the order by dragging and dropping the issues. The changed order will persist. Everyone who visits the same list will see the reordered list, with some exceptions. +the order by dragging and dropping the issues. The changed order persists, and +everyone who visits the same list sees the updated issue order, with some exceptions. Each issue is assigned a relative order value, representing its relative -order with respect to the other issues in the list. When you drag-and-drop reorder -an issue, its relative order value changes accordingly. +order with respect to the other issues on the list. When you drag-and-drop reorder +an issue, its relative order value changes. -In addition, any time that issue appears in a manually sorted list, -the updated relative order value will be used for the ordering. This means that -if issue `A` is drag-and-drop reordered to be above issue `B` by any user in -a given list inside your GitLab instance, any time those two issues are subsequently -loaded in any list in the same instance (could be a different project issue list or a -different group issue list, for example), that ordering will be maintained. +In addition, any time an issue appears in a manually sorted list, +the updated relative order value is used for the ordering. +So, if anyone drags issue `A` above issue `B` in your GitLab instance, +this ordering is maintained whenever they appear together in any list. This ordering also affects [issue boards](../issue_board.md#how-gitlab-orders-issues-in-a-list). Changing the order in an issue list changes the ordering in an issue board, and vice versa. + +## Sorting by blocking issues + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34247/) in GitLab 13.7. + +When you select to sort by **Blocking**, the issue list changes to sort descending by the +number of issues each issue is blocking. You can use this to determine the critical path for your backlog. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index c237f46b23a..2f8603e1db0 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Labels @@ -90,7 +90,7 @@ Once created, you can edit a label by clicking the pencil (**{pencil}**), or del a label by clicking the three dots (**{ellipsis_v}**) next to the **Subscribe** button and selecting **Delete**. -CAUTION: **Caution:** +WARNING: If you delete a label, it is permanently deleted. All references to the label are removed from the system and you cannot undo the deletion. #### Promote a project label to a group label @@ -109,7 +109,7 @@ with the old labels are assigned to the new group label. The new group label has the same ID as the previous project label. -CAUTION: **Caution:** +WARNING: Promoting a label is a permanent action, and cannot be reversed. To promote a project label to a group label: diff --git a/doc/user/project/maven_packages.md b/doc/user/project/maven_packages.md index 4679eed5433..5bfa08de2ed 100644 --- a/doc/user/project/maven_packages.md +++ b/doc/user/project/maven_packages.md @@ -3,3 +3,6 @@ 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/other_group_sees_shared_project.png b/doc/user/project/members/img/other_group_sees_shared_project.png Binary files differdeleted file mode 100644 index e4c93a13abb..00000000000 --- a/doc/user/project/members/img/other_group_sees_shared_project.png +++ /dev/null diff --git a/doc/user/project/members/img/other_group_sees_shared_project_v13_6.png b/doc/user/project/members/img/other_group_sees_shared_project_v13_6.png Binary files differnew file mode 100644 index 00000000000..e6e3f8f043b --- /dev/null +++ b/doc/user/project/members/img/other_group_sees_shared_project_v13_6.png diff --git a/doc/user/project/members/img/share_project_with_groups.png b/doc/user/project/members/img/share_project_with_groups.png Binary files differdeleted file mode 100644 index 0907438cb84..00000000000 --- a/doc/user/project/members/img/share_project_with_groups.png +++ /dev/null diff --git a/doc/user/project/members/img/share_project_with_groups_tab.png b/doc/user/project/members/img/share_project_with_groups_tab.png Binary files differdeleted file mode 100644 index fc489aae003..00000000000 --- a/doc/user/project/members/img/share_project_with_groups_tab.png +++ /dev/null diff --git a/doc/user/project/members/img/share_project_with_groups_tab_v13_6.png b/doc/user/project/members/img/share_project_with_groups_tab_v13_6.png Binary files differnew file mode 100644 index 00000000000..7d83659ef7a --- /dev/null +++ b/doc/user/project/members/img/share_project_with_groups_tab_v13_6.png diff --git a/doc/user/project/members/img/share_project_with_groups_v13_6.png b/doc/user/project/members/img/share_project_with_groups_v13_6.png Binary files differnew file mode 100644 index 00000000000..121e77671a3 --- /dev/null +++ b/doc/user/project/members/img/share_project_with_groups_v13_6.png diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index c66103604ed..85cb139c45b 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Members of a project @@ -53,7 +53,7 @@ that you'd like to give the user. Note that you can select more than one user.  -Once done, hit **Add users to project** and they will be immediately added to +Once done, select **Add users to project** and they are immediately added to your project with the permissions you gave them above.  @@ -71,7 +71,7 @@ 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 -notifying you that the import was successful will appear, and the new members +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. @@ -96,10 +96,13 @@ invitation, change their access level, or even delete them.  -Once the user accepts the invitation, they will be prompted to create a new +While unaccepted, the system automatically sends reminder emails on the second, fifth, +and tenth day after the invitation was initially sent. + +After the user accepts the invitation, they are prompted to create a new GitLab account using the same e-mail address the invitation was sent to. -Note: **Note:** +NOTE: Unaccepted invites are automatically deleted after 90 days. ## Project membership and requesting access @@ -123,7 +126,7 @@ After access is requested: Email is sent to the most recently active project maintainers. - Any project maintainer can approve or decline the request on the members page. -NOTE: **Note:** +NOTE: If a project does not have any maintainers, the notification is sent to the most recently active owners of the project's group. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 395f4353f47..edfe8ae3b5b 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Share Projects with other Groups @@ -24,35 +24,36 @@ This is where the group sharing feature can be of use. To share 'Project Acme' with the 'Engineering' group: -1. For 'Project Acme' use the left navigation menu to go to **Members** +1. For 'Project Acme' use the left navigation menu to go to **Members**. -  +  -1. Select the 'Share with group' tab -1. Add the 'Engineering' group with the maximum access level of your choice -1. Click **Share** to share it +1. Select the **Invite group** tab. +1. Add the 'Engineering' group with the maximum access level of your choice. +1. Optionally, select an expiring date. +1. Click **Invite**. -  +  -1. After sharing 'Project Acme' with 'Engineering', the project will be listed +1. After sharing 'Project Acme' with 'Engineering', the project is listed on the group dashboard -  +  Note that you can only share a project with: - groups for which you have an explicitly defined membership - groups that contain a nested subgroup or project for which you have an explicitly defined role -Admins are able to share projects with any group in the system. +Administrators are able to share projects with any group in the system. ## Maximum access level -In the example above, the maximum access level of 'Developer' for members from 'Engineering' means that users with higher access levels in 'Engineering' ('Maintainer' or 'Owner') will only have 'Developer' access to 'Project Acme'. +In the example above, the maximum access level of 'Developer' for members from 'Engineering' means that users with higher access levels in 'Engineering' ('Maintainer' or 'Owner') only have 'Developer' access to 'Project Acme'. ## Sharing public project with private group -When sharing a public project with a private group, owners and maintainers of the project will see the name of the group in the `members` page. Owners will also have the possibility to see members of the private group they don't have access to when mentioning them in the issue or merge request. +When sharing a public project with a private group, owners and maintainers of the project see the name of the group in the `members` page. Owners also have the possibility to see members of the private group they don't have access to when mentioning them in the issue or merge request. ## Share project with group lock diff --git a/doc/user/project/merge_requests.md b/doc/user/project/merge_requests.md index 1d7ebc856c3..5762177882e 100644 --- a/doc/user/project/merge_requests.md +++ b/doc/user/project/merge_requests.md @@ -3,3 +3,6 @@ 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/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index a07a155745e..c518113d3dd 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -62,14 +62,14 @@ The report for each URL is saved as an artifact that can be [viewed directly in A single `gl-accessibility.json` artifact is created and saved along with the individual HTML reports. It includes report data for all URLs scanned. -NOTE: **Note:** +NOTE: For GitLab 12.10 and earlier, the [artifact generated is named `accessibility.json`](https://gitlab.com/gitlab-org/ci-cd/accessibility/-/merge_requests/9). -NOTE: **Note:** +NOTE: For GitLab versions earlier than 12.9, you can use `include:remote` and use a link to the [current template in `master`](https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) -NOTE: **Note:** +NOTE: The job definition provided by the template does not support Kubernetes yet. It is not yet possible to pass configurations into Pa11y via CI configuration. To change anything, diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 4ba0b50a3cf..8eabef982c8 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- 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 26b3682990e..7bb64987a31 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts --- diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 040ca4b439b..04114968c80 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -44,11 +44,11 @@ between the source and target branches, and shows the information in the merge r For an example Performance job, see [Configuring Browser Performance Testing](#configuring-browser-performance-testing). -NOTE: **Note:** +NOTE: If the Browser Performance report has no data to compare, such as when you add the Browser Performance job in your `.gitlab-ci.yml` for the very first time, -the Browser Performance report widget won't show. It must have run at least -once on the target branch (`master`, for example), before it will display in a +the Browser Performance report widget doesn't show. It must have run at least +once on the target branch (`master`, for example), before it displays in a merge request targeting that branch.  @@ -72,7 +72,7 @@ using Docker-in-Docker. URL: https://example.com ``` -NOTE: **Note:** +NOTE: For versions before 12.4, see the information for [older GitLab versions](#gitlab-versions-123-and-older). If you are using a Kubernetes cluster, use [`template: Jobs/Browser-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Browser-Performance-Testing.gitlab-ci.yml) instead. @@ -81,7 +81,7 @@ The above example creates a `performance` job in your CI/CD pipeline and runs sitespeed.io against the webpage you defined in `URL` to gather key metrics. The example uses a CI/CD template that is included in all GitLab installations since -12.4, but it will not work with Kubernetes clusters. If you are using GitLab 12.3 +12.4, but it doesn't work with Kubernetes clusters. If you are using GitLab 12.3 or older, you must [add the configuration manually](#gitlab-versions-123-and-older) The template uses the [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance), @@ -115,7 +115,7 @@ performance: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27599) in GitLab 13.0. You can configure the sensitivity of degradation alerts to avoid getting alerts for minor drops in metrics. -This is done by setting the `DEGRADATION_THRESHOLD` variable. In the example below, the alert will only show up +This is done by setting the `DEGRADATION_THRESHOLD` variable. In the example below, the alert only shows up if the `Total Score` metric degrades by 5 points or more: ```yaml @@ -181,7 +181,7 @@ performance: ### GitLab versions 12.3 and older Browser Performance Testing has gone through several changes since it's introduction. -In this section we'll detail these changes and how you can run the test based on your +In this section we detail these changes and how you can run the test based on your GitLab version: - In GitLab 12.4 [a job template was made available](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml). diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index d65c005ee34..4e87876b036 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -35,7 +35,7 @@ request thread crosslinking 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. -NOTE: **Note:** +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. ## Cherry-picking a commit diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index d50056c9450..5a98338a81b 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -45,7 +45,7 @@ Watch a quick walkthrough of Code Quality in action: <iframe src="https://www.youtube.com/embed/B32LxtJKo9M" frameborder="0" allowfullscreen="true"> </iframe> </figure> -NOTE: **Note:** +NOTE: For one customer, the auditor found that having Code Quality, SAST, and Container Scanning all automated in GitLab CI/CD was almost better than a manual review! [Read more](https://about.gitlab.com/customers/bi_worldwide/). See also the Code Climate list of [Supported Languages for Maintainability](https://docs.codeclimate.com/docs/supported-languages-for-maintainability). @@ -84,8 +84,8 @@ include: - template: Code-Quality.gitlab-ci.yml ``` -The above example will create a `code_quality` job in your CI/CD pipeline which -will scan your source code for code quality issues. The report will be saved as a +The above example creates a `code_quality` job in your CI/CD pipeline which +scans your source code for code quality issues. The report is saved as a [Code Quality report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscodequality) that you can later download and analyze. @@ -131,18 +131,18 @@ stages: - test ``` -TIP: **Tip:** -This information will be automatically extracted and shown right in the merge request widget. +NOTE: +This information is automatically extracted and shown right in the merge request widget. -CAUTION: **Caution:** +WARNING: On self-managed instances, if a malicious actor compromises the Code Quality job -definition they will be able to execute privileged Docker commands on the runner +definition they could execute privileged Docker commands on the runner host. Having proper access control policies mitigates this attack vector by allowing access only to trusted actors. ### Disabling the code quality job -The `code_quality` job will not run if the `$CODE_QUALITY_DISABLED` environment +The `code_quality` job doesn't run if the `$CODE_QUALITY_DISABLED` environment variable is present. Please refer to the environment variables [documentation](../../../ci/variables/README.md) to learn more about how to define one. @@ -185,7 +185,7 @@ job1: - if: '$CI_COMMIT_TAG' # Run job1 in pipelines for tags ``` -To make these work together, you will need to overwrite the code quality `rules` +To make these work together, you need to overwrite the code quality `rules` so that they match your current `rules`. From the example above, it could look like: ```yaml @@ -228,6 +228,7 @@ with the following properties: | ---------------------- | -------------------------------------------------------------------------------------- | | `description` | A description of the code quality violation. | | `fingerprint` | A unique fingerprint to identify the code quality violation. For example, an MD5 hash. | +| `severity` | A severity string (can be `info`, `minor`, `major`, `critical`, or `blocker`). | | `location.path` | The relative path to the file containing the code quality violation. | | `location.lines.begin` | The line on which the code quality violation occurred. | @@ -238,6 +239,7 @@ Example: { "description": "'unused' is assigned a value but never used.", "fingerprint": "7815696ecbf1c96e6894b779456d330e", + "severity": "minor", "location": { "path": "lib/index.js", "lines": { @@ -248,22 +250,22 @@ Example: ] ``` -NOTE: **Note:** +NOTE: Although the Code Climate spec supports more properties, those are ignored by GitLab. -## Code Quality reports **(STARTER)** +## Code Quality reports -Once the Code Quality job has completed: +After the Code Quality job completes: -- The full list of code quality violations generated by a pipeline is shown in the - Code Quality tab of the Pipeline Details page. - Potential changes to code quality are shown directly in the merge request. The Code Quality widget in the merge request compares the reports from the base and head of the branch, - then lists any violations that will be resolved or created when the branch is merged. + then lists any violations that are resolved or created when the branch is merged. - The full JSON report is available as a [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)** ### Generating an HTML report @@ -341,13 +343,14 @@ is still used. 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. Future merge - requests will have something to compare to. + 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. - If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks), - nothing will be displayed. + 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). 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: diff --git a/doc/user/project/merge_requests/code_quality_diff.md b/doc/user/project/merge_requests/code_quality_diff.md index 0aa108a2e73..2b7b2574ef7 100644 --- a/doc/user/project/merge_requests/code_quality_diff.md +++ b/doc/user/project/merge_requests/code_quality_diff.md @@ -3,3 +3,6 @@ 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 index a062731ea35..5d61f2b36e8 100644 --- a/doc/user/project/merge_requests/container_scanning.md +++ b/doc/user/project/merge_requests/container_scanning.md @@ -3,3 +3,6 @@ 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 0495c864335..5adc4ab6b6e 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto description: "How to create Merge Requests in GitLab." disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html' @@ -46,7 +46,7 @@ the merge request.  -TIP: **Tip:** +NOTE: You can push one or more times to your branch in GitLab before creating the merge request. diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index 52c6f8a8d41..0de9f246ceb 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -1,7 +1,7 @@ --- stage: Manage group: Compliance -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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)** @@ -18,7 +18,7 @@ The following table shows what attributes will be present in the CSV. | Column | Description | |--------------------|--------------------------------------------------------------| -| MR ID | MR iid | +| MR ID | MR `iid` | | URL | A link to the merge request on GitLab | | Title | Merge request title | | State | Opened, Closed, Locked, or Merged | diff --git a/doc/user/project/merge_requests/dast.md b/doc/user/project/merge_requests/dast.md index 98a2906e560..37c0d5b4e37 100644 --- a/doc/user/project/merge_requests/dast.md +++ b/doc/user/project/merge_requests/dast.md @@ -3,3 +3,6 @@ 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 index bdc1c355016..dd5910121ed 100644 --- a/doc/user/project/merge_requests/dependency_scanning.md +++ b/doc/user/project/merge_requests/dependency_scanning.md @@ -3,3 +3,6 @@ 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/fail_fast_testing.md b/doc/user/project/merge_requests/fail_fast_testing.md index 60f81159394..80bdbce8d2c 100644 --- a/doc/user/project/merge_requests/fail_fast_testing.md +++ b/doc/user/project/merge_requests/fail_fast_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index b021fa6f336..a89acff4bfc 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 462b8f68ece..cb95daa2cab 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, reference description: "Getting started with Merge Requests." --- @@ -111,22 +111,23 @@ It is also possible to manage multiple assignees: - When creating a merge request. - Using [quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). -## Reviewer +### Reviewer > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. -> - It's [deployed behind a feature flag](../../../user/feature_flags.md), enabled 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-merge-request-reviewers). **(CORE ONLY)** +> - 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.1. +> - 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-merge-request-reviewers). **(CORE ONLY)** -CAUTION: **Warning:** +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. -GitLab's Merge Request Reviewers easily allow authors to request a review as well as see the status of the +GitLab Merge Request Reviewers easily allow authors to request a review as well as see the status of the review. By selecting one or more users from the **Reviewers** field in the merge request's right-hand sidebar, the assigned reviewers will receive a notification of the request to review the merge request. @@ -134,23 +135,29 @@ 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)** +#### Enable or disable Merge Request Reviewers **(CORE ONLY)** -Merge Request Reviewers is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. +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 enable it. +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: ```ruby +# For the instance Feature.disable(:merge_request_reviewers) +# For a single project +Feature.disable(:merge_request_reviewers, Project.find(<project id>)) ``` ### Merge requests to close issues diff --git a/doc/user/project/merge_requests/img/project_merge_requests_list_view.png b/doc/user/project/merge_requests/img/project_merge_requests_list_view.png Binary files differdeleted file mode 100644 index 2c86a1ad839..00000000000 --- a/doc/user/project/merge_requests/img/project_merge_requests_list_view.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png b/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png Binary files differnew file mode 100644 index 00000000000..625d47b1142 --- /dev/null +++ b/doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 69276f0677b..6af6cad5cdd 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, reference --- diff --git a/doc/user/project/merge_requests/license_management.md b/doc/user/project/merge_requests/license_management.md index ed81eb8ca10..4c598d851a9 100644 --- a/doc/user/project/merge_requests/license_management.md +++ b/doc/user/project/merge_requests/license_management.md @@ -3,3 +3,6 @@ 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/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 3ee88275aac..82b5d67ba2b 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -43,7 +43,7 @@ The key performance metrics that the merge request widget shows after the test c - TTFB P95: The 95th percentile for TTFB. - RPS: The average requests per second (RPS) rate the test was able to achieve. -NOTE: **Note:** +NOTE: If the Load Performance report has no data to compare, such as when you add the Load Performance job in your `.gitlab-ci.yml` for the very first time, the Load Performance report widget won't show. It must have run at least @@ -90,7 +90,7 @@ testing job in GitLab CI/CD. The easiest way to do this is to use the [`Verify/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Load-Performance-Testing.gitlab-ci.yml) template that is included with GitLab. -NOTE: **Note:** +NOTE: For large scale k6 tests you need to ensure the GitLab Runner instance performing the actual test is able to handle running the test. Refer to [k6's guidance](https://k6.io/docs/testing-guides/running-large-tests#hardware-considerations) for spec details. The [default shared GitLab.com runners](../../gitlab_com/#linux-shared-runners) @@ -119,7 +119,7 @@ An example configuration workflow: The above example creates a `load_performance` job in your CI/CD pipeline that runs the k6 test. -NOTE: **Note:** +NOTE: For Kubernetes setups a different template should be used: [`Jobs/Load-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Load-Performance-Testing.gitlab-ci.yml). k6 has [various options](https://k6.io/docs/using-k6/options) to configure how it will run tests, such as what throughput (RPS) to run with, diff --git a/doc/user/project/merge_requests/maintainer_access.md b/doc/user/project/merge_requests/maintainer_access.md index fe7e1f558c7..29afff289fd 100644 --- a/doc/user/project/merge_requests/maintainer_access.md +++ b/doc/user/project/merge_requests/maintainer_access.md @@ -3,3 +3,6 @@ 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 4b4c930c7af..01de98edeac 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, concepts --- @@ -58,7 +58,7 @@ or choose more than one. Single approval rules are available in GitLab Starter a while [multiple approval rules](#multiple-approval-rules) are available in [GitLab Premium](https://about.gitlab.com/pricing/) and above. -NOTE: **Note:** +NOTE: On GitLab.com, you can add a group as an approver if you're a member of that group or the group is public. @@ -155,7 +155,7 @@ 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 **No. approvals required**. The minimum value is `0`. + - 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) 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 @@ -167,7 +167,7 @@ To add or edit the default merge request approval rule: Any merge requests that were created before changing the rules will not be changed. They will keep the original approval rules, unless manually [overridden](#editing--overriding-approval-rules-per-merge-request). -NOTE: **Note:** +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 source (fork). @@ -191,7 +191,7 @@ the same steps as [Adding / editing a default approval rule](#adding--editing-a- 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. -To configure an approval to be optional, set the number of required approvals in **No. approvals required** to `0`. +To configure an approval to be optional, set the number of required approvals in **Approvals required** to `0`. You can also set an optional approval rule through the [Merge requests approvals API](../../../api/merge_request_approvals.md#update-merge-request-level-rule), by setting the `approvals_required` attribute to `0`. @@ -252,7 +252,7 @@ one of the following is possible:  -NOTE: **Note:** +NOTE: The merge request author is not allowed to approve their own merge request if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-their-own-merge-requests) is enabled in the project settings. @@ -273,7 +273,7 @@ Regardless of the approval rules you choose for your project, users can edit the request, overriding the rules you set as [default](#adding--editing-a-default-approval-rule). To prevent that from happening: -1. Uncheck the **Can override approvers and approvals required per merge request** checkbox. +1. Uncheck the **Allow overrides to approval lists per merge request (MR).** checkbox. 1. Click **Save changes**. #### Resetting approvals on push @@ -282,11 +282,11 @@ You can force all approvals on a merge request to be removed when new commits ar pushed to the source branch of the merge request. If disabled, approvals will persist even if there are changes added to the merge request. To enable this feature: -1. Check the **Remove all approvals in a merge request when new commits are pushed to its source branch** +1. Check the **Require new approvals when new commits are added to an MR.** checkbox. 1. Click **Save changes**. -NOTE: **Note:** +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. @@ -298,7 +298,7 @@ By default, projects are configured to prevent merge requests from being approve their own authors. To change this setting: 1. Go to your project's **Settings > General**, expand **Merge request approvals**. -1. Uncheck the **Prevent approval of merge requests by merge request author** checkbox. +1. Uncheck the **Prevent MR approval by the author.** checkbox. 1. Click **Save changes**. Note that users can edit the approval rules in every merge request and override pre-defined settings unless it's set [**not to allow** overrides](#prevent-overriding-default-approvals). @@ -310,14 +310,14 @@ Note that users can edit the approval rules in every merge request and override You can prevent users that have committed to a merge request from approving it. To enable this feature: -1. Check the **Prevent approval of merge requests by their committers** checkbox. +1. Check the **Prevent MR approvals from users who make commits to the MR.** checkbox. 1. Click **Save changes**. #### 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. -NOTE: **Note:** +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. @@ -327,7 +327,7 @@ the approval. This enables an Electronic Signature for approvals such as the one by [CFR Part 11](https://www.accessdata.fda.gov/scripts/cdrh/cfdocs/cfcfr/CFRSearch.cfm?CFRPart=11&showFR=1&subpartNode=21:1.0.1.1.8.3)). To enable this feature: -1. Check the **Require user password to approve** checkbox. +1. Check the **Require user password for approvals.** checkbox. 1. Click **Save changes**. ### Security approvals in merge requests **(ULTIMATE)** diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index bca9df9ae2b..4a596ed6139 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -15,7 +15,7 @@ Merge request dependencies allows a required order of merging between merge requests to be expressed. If a merge request "depends on" another, then it cannot be merged until its dependency is itself merged. -NOTE: **Note:** +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 **STARTER** project can be a dependency of a **PREMIUM** merge request, but not diff --git a/doc/user/project/merge_requests/merge_request_discussion_resolution.md b/doc/user/project/merge_requests/merge_request_discussion_resolution.md index a554d727ca4..f8d15f31875 100644 --- a/doc/user/project/merge_requests/merge_request_discussion_resolution.md +++ b/doc/user/project/merge_requests/merge_request_discussion_resolution.md @@ -3,3 +3,6 @@ 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 index e37dad098f1..48d32d2882f 100644 --- a/doc/user/project/merge_requests/merge_when_build_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_build_succeeds.md @@ -5,3 +5,6 @@ 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 5151b28361a..b813e4f7d28 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -35,6 +35,11 @@ is automatically merged. When the merge request is updated with new commits, the automatic merge is canceled to allow the new changes to be reviewed. +By default, all threads must be resolved before you see the **Merge when +pipeline succeeds** button. If someone adds a new comment after +the button is selected, but before the jobs in the CI pipeline are +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 diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md index b6c7ad0ce75..99e70f35d6d 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -22,7 +22,7 @@ for information on when this is available).  -NOTE: **Note:** +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 diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 6b302b0ff02..40a4631694b 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -12,12 +12,12 @@ by clicking the **Revert** button in merge requests and commit details. ## Reverting a merge request -NOTE: **Note:** +NOTE: The **Revert** button will only be available for merge requests created in GitLab 8.5 and later. However, you can still revert a merge request by reverting the merge commit from the list of Commits page. -NOTE: **Note:** +NOTE: The **Revert** button will only be shown for projects that use the merge method "Merge Commit", which can be set under the project's **Settings > General > Merge request**. [Fast-forward commits](fast_forward_merge.md) 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 aef68e0e771..e2d6ba9ea1c 100644 --- a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md +++ b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, reference --- @@ -18,7 +18,7 @@ View all the merge requests within a project by navigating to **Project > Merge 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). - + ## View merge requests for all projects in a group @@ -78,10 +78,7 @@ Click **Expand file** on any file to view the changes for that file. ### File-by-file diff navigation > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. -> - It's deployed behind a feature flag, enabled by default. -> - It's recommended for production use. -> - It's enabled on GitLab.com. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-file-by-file-diff-navigation). +> - [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 @@ -92,26 +89,16 @@ From there, when reviewing merge requests' **Changes** tab, you will see only on  -#### Enable or disable file-by-file diff navigation **(CORE ONLY)** +From [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) onwards, if you want to change +this behavior, you can do so from your **User preferences** (as explained above) or directly in a +merge request: -File-by-file diff navigation is under development but ready for production use. It is -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it for your instance. +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 or deselect the checkbox **Show one file at a time** to change the setting accordingly. -To enable it: - -```ruby -# Instance-wide -Feature.enable(:view_diffs_file_by_file) -``` - -To disable it: - -```ruby -# Instance-wide -Feature.disable(:view_diffs_file_by_file>) -``` +This change overrides the choice you made in your user preferences and persists until you clear your +browser's cookies or change this behavior again. ### Merge requests commit navigation @@ -145,7 +132,7 @@ specific commit page.  -TIP: **Tip:** +NOTE: You can append `?w=1` while on the diffs page of a merge request to ignore any whitespace changes. @@ -213,7 +200,7 @@ If there's an [environment](../../../ci/environments/index.md) and the applicati successfully deployed to it, the deployed environment and the link to the Review App will be shown as well. -NOTE: **Note:** +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. @@ -245,7 +232,7 @@ you can preview the changes submitted to a feature-branch through a merge reques 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. -With GitLab's [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the +With GitLab [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the merge request widget takes you directly to the pages changed, making it easier and faster to preview proposed modifications. @@ -296,7 +283,7 @@ Merge Request again. Here are some tips that will help you be more efficient with merge requests in the command line. -NOTE: **Note:** +NOTE: This section might move in its own document in the future. ### Copy the branch name for local checkout diff --git a/doc/user/project/merge_requests/sast.md b/doc/user/project/merge_requests/sast.md index 165290eb114..11f85749fb7 100644 --- a/doc/user/project/merge_requests/sast.md +++ b/doc/user/project/merge_requests/sast.md @@ -3,3 +3,6 @@ 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 index a062731ea35..5d61f2b36e8 100644 --- a/doc/user/project/merge_requests/sast_docker.md +++ b/doc/user/project/merge_requests/sast_docker.md @@ -3,3 +3,6 @@ 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 68f5478038a..5c466654b31 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -27,7 +27,7 @@ Into a single commit on merge:  -NOTE: **Note:** +NOTE: The squashed commit in this example is followed by a merge commit, because the merge method for this repository uses a merge commit. You can disable merge commits in **Project Settings > General > Merge requests > Merge method > Fast-forward merge**. @@ -36,7 +36,7 @@ The squashed commit's commit message will be either: - Taken from the first multi-line commit message in the merge. - The merge request's title if no multi-line commit message is found. -NOTE: **Note:** +NOTE: This only takes effect if there are at least 2 commits. As there is nothing to squash, the commit message does not change if there is only 1 commit. It can be customized before merging a merge request. @@ -129,7 +129,7 @@ submitted to your project: The Squash and Merge checkbox is displayed when you create a merge request and when you edit the description of an existing one, except when Squash Commit Options is set to **Do not allow** or **Require**. -NOTE: **Note:** +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. diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 039f0f7d5e1..c38b28f7718 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -51,7 +51,7 @@ from any job in any stage in the pipeline. The coverage will be displayed for ea Hovering over the coverage bar will provide further information, such as the number of times the line was checked by tests. -NOTE: **Note:** +NOTE: The Cobertura XML parser currently does not support the `sources` element and ignores it. It is assumed that the `filename` of a `class` element contains the full path relative to the project root. @@ -60,7 +60,7 @@ the `filename` of a `class` element contains the full path relative to the proje ### JavaScript example The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example uses [Mocha](https://mochajs.org/) -JavaScript testing and [NYC](https://github.com/istanbuljs/nyc) coverage-tooling to +JavaScript testing and [nyc](https://github.com/istanbuljs/nyc) coverage-tooling to generate the coverage artifact: ```yaml @@ -78,7 +78,7 @@ test: #### Maven example The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Java or Kotlin uses [Maven](https://maven.apache.org/) -to build the project and [Jacoco](https://www.eclemma.org/jacoco/) coverage-tooling to +to build the project and [JaCoCo](https://www.eclemma.org/jacoco/) coverage-tooling to generate the coverage artifact. You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image. @@ -118,7 +118,7 @@ coverage-jdk11: #### Gradle example The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Java or Kotlin uses [Gradle](https://gradle.org/) -to build the project and [Jacoco](https://www.eclemma.org/jacoco/) coverage-tooling to +to build the project and [JaCoCo](https://www.eclemma.org/jacoco/) coverage-tooling to generate the coverage artifact. You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image. @@ -154,3 +154,23 @@ coverage-jdk11: reports: cobertura: build/cobertura.xml ``` + +### Python example + +The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Python uses [pytest-cov](https://pytest-cov.readthedocs.io/) to collect test coverage data and [coverage.py](https://coverage.readthedocs.io/) to convert the report to use full relative paths. +The information isn't displayed without the conversion. + +This example assumes that the code for your package is in `src/` and your tests are in `tests.py`: + +```yaml +run tests: + stage: test + image: python:3 + script: + - pip install pytest pytest-cov + - pytest --cov=src/ tests.py + - coverage xml + artifacts: + reports: + cobertura: coverage.xml +``` diff --git a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md index b298c62a5e6..9661a02a767 100644 --- a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md +++ b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md @@ -1,7 +1,7 @@ --- stage: Verify group: Testing -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index description: "Test your code and display reports in merge requests" --- diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 0922ffb2943..4ad960413ef 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -22,8 +22,8 @@ can select an older one from version dropdown.  Merge request versions are based on push not on commit. So, if you pushed 5 -commits in a single push, it will be a single option in the dropdown. If you -pushed 5 times, that will count for 5 options. +commits in a single push, it displays as a single option in the dropdown. If you +pushed 5 times, that counts for 5 options. You can also compare the merge request version with an older one to see what has changed since then. @@ -42,12 +42,12 @@ changes appears as a system note. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2383) in GitLab 10.5. -When viewing the commit details page, GitLab will link to the merge request (or +When viewing the commit details page, GitLab links to the merge request (or merge requests, if it's in more than one) containing that commit. This only applies to commits that are in the most recent version of a merge -request - if a commit was in a merge request, then rebased out of that merge -request, they will not be linked. +request - if commits were in a merge request, then rebased out of that merge +request, they aren't linked. ## `HEAD` comparison mode for Merge Requests 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 2218d38fdad..7417320eea0 100644 --- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md +++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, concepts --- @@ -14,6 +14,12 @@ being merged, and it will stay disabled until the "Draft" flag has been removed.  +When [pipelines for merged results](../../../ci/merge_request_pipelines/pipelines_for_merged_results/index.md) +is enabled, draft merge requests run [merge request pipelines](../../../ci/merge_request_pipelines/index.md) +only. + +To run pipelines for merged results, you must [remove the draft status](#removing-the-draft-flag-from-a-merge-request). + ## 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. diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index ae03be5fa0f..3e266d054be 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -2,7 +2,7 @@ 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/#designated-technical-writers +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)** @@ -66,7 +66,7 @@ and you follow this workflow: A burndown chart is available for every project or group milestone that has been attributed a **start date** and a **due date**. -NOTE: **Note:** +NOTE: You're able to [promote project](index.md#promoting-project-milestones-to-group-milestones) to group milestones and still see the **burndown chart** for them, respecting license limitations. The chart indicates the project's progress throughout that milestone (for issues assigned to it). @@ -104,13 +104,7 @@ Reopened issues are considered as having been opened on the day after they were ## Burnup charts > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6. -> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-burnup-charts). **(STARTER ONLY)** - -CAUTION: **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/268350) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.7. Burnup charts show the assigned and completed work for a milestone. @@ -136,25 +130,6 @@ Burnup charts can show either the total number of issues or total weight for eac day of the milestone. Use the toggle above the charts to switch between total and weight. -### Enable or disable burnup charts **(STARTER ONLY)** - -Burnup charts 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(:burnup_charts) -``` - -To disable it: - -```ruby -Feature.disable(:burnup_charts) -``` - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/milestones/burndown_charts.md b/doc/user/project/milestones/burndown_charts.md index 5d9e6b67bb8..2985e5da2ab 100644 --- a/doc/user/project/milestones/burndown_charts.md +++ b/doc/user/project/milestones/burndown_charts.md @@ -1,5 +1,8 @@ --- -redirect_to: './burndown_and_burnup_charts.md' +redirect_to: 'burndown_and_burnup_charts.md' --- This document was moved to [another location](burndown_and_burnup_charts.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/milestones/img/milestones_new_group_milestone.png b/doc/user/project/milestones/img/milestones_new_group_milestone.png Binary files differdeleted file mode 100644 index 5bbe8e51f23..00000000000 --- a/doc/user/project/milestones/img/milestones_new_group_milestone.png +++ /dev/null diff --git a/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png b/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png Binary files differnew file mode 100644 index 00000000000..a865221c5d7 --- /dev/null +++ b/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png diff --git a/doc/user/project/milestones/img/milestones_new_project_milestone.png b/doc/user/project/milestones/img/milestones_new_project_milestone.png Binary files differindex 2d0bdce542d..9207c9f1f7c 100644 --- a/doc/user/project/milestones/img/milestones_new_project_milestone.png +++ b/doc/user/project/milestones/img/milestones_new_project_milestone.png diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 9c47f15cb8f..acf32bb0f92 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -2,10 +2,10 @@ type: index, 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/#designated-technical-writers +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 +# Milestones **(CORE)** Milestones in GitLab are a way to track issues and merge requests created to achieve a broader goal in a certain period of time. @@ -27,7 +27,7 @@ Similarly, milestones can be used as releases. To do so: 1. Set the milestone title to the version of your release, such as `Version 9.4`. 1. Add an issue to your release by associating the desired milestone from the issue's right-hand sidebar. -Additionally, you can integrate milestones with GitLab's [Releases feature](../releases/index.md#associate-milestones-with-a-release). +Additionally, you can integrate milestones with the [Releases feature](../releases/index.md#associate-milestones-with-a-release). ## Project milestones and group milestones @@ -46,14 +46,14 @@ For information about project and group milestones API, see: - [Project Milestones API](../../../api/milestones.md) - [Group Milestones API](../../../api/group_milestones.md) -NOTE: **Note:** -If you're in a group and click **Issues > Milestones**, you'll see group milestones and the milestones -of projects in this group. -If you're in a project and click **Issues > Milestones**, you'll only see this project's milestones. +NOTE: +If you're in a group and click **Issues > Milestones**, GitLab displays group milestones +and the milestones of projects in this group. +If you're in a project and click **Issues > Milestones**, GitLab displays only this project's milestones. ## Creating milestones -NOTE: **Note:** +NOTE: A permission level of [Developer or higher](../../permissions.md) is required to create milestones. ### New project milestone @@ -76,11 +76,11 @@ To create a **group milestone**: 1. Enter the title, an optional description, an optional start date, and an optional due date. 1. Click **New milestone**. - + ## Editing milestones -NOTE: **Note:** +NOTE: A permission level of [Developer or higher](../../permissions.md) is required to edit milestones. To edit a milestone: @@ -93,12 +93,21 @@ You can delete a milestone by clicking the **Delete** button. ### Promoting project milestones to group milestones -If you are expanding from a few projects to a larger number of projects within the same group, you may want to share the same milestone among multiple projects in the same group. If you previously created a project milestone and now want to make it available for other projects within the same group, you can promote it to a group milestone. +If you are expanding the number of projects in a group, you might want to share the same milestones +among this group's projects. You can also promote project milestones to group milestones in order to +make them available to other projects in the same group. -From the project milestone list page, you can promote a project milestone to a group milestone. This will merge all project milestones across all projects in this group with the same name into a single group milestones. All issues and merge requests that previously were assigned one of these project milestones will now be assigned the new group milestones. This action cannot be reversed and the changes are permanent. +From the project milestone list page, you can promote a project milestone to a group milestone. +This merges all project milestones across all projects in this group with the same name into a single +group milestones. All issues and merge requests that were previously assigned to one of these project +milestones is assigned the new group milestones. This action cannot be reversed and the changes are +permanent. -CAUTION: **Caution:** -From GitLab 12.4 and earlier, some information is lost when you promote a project milestone to a group milestone. Not all features on the project milestone view are available on the group milestone view. If you promote a project milestone to a group milestone, you will lose these features. See [Milestone view](#milestone-view) to see which features are missing from the group milestone view. +WARNING: +From GitLab 12.4 and earlier, some information is lost when you promote a project milestone to a +group milestone. Not all features on the project milestone view are available on the group milestone +view. If you promote a project milestone to a group milestone, you lose these features. Visit +[Milestone view](#milestone-view) to learn which features are missing from the group milestone view.  @@ -110,7 +119,7 @@ Every issue and merge request can be assigned a milestone. The milestones are vi ### Filtering in list pages -From the project issue/merge request list pages and the group issue/merge request list pages, you can [filter](../../search/index.md#issues-and-merge-requests) by both group milestones and project milestones. +From the project and group issue/merge request list pages, you can [filter](../../search/index.md#issues-and-merge-requests) by both group and project milestones. ### Filtering in issue boards @@ -125,7 +134,7 @@ When filtering by milestone, in addition to choosing a specific project mileston - **None**: Show issues or merge requests with no assigned milestone. - **Any**: Show issues or merge requests that have an assigned milestone. -- **Upcoming**: Show issues or merge requests that have been assigned the open milestone that has the next upcoming due date (i.e. nearest due date in the future). +- **Upcoming**: Show issues or merge requests that have been assigned the open milestone and has the nearest due date in the future. - **Started**: Show issues or merge requests that have an open assigned milestone with a start date that is before today. ## Milestone view @@ -148,13 +157,13 @@ There are also tabs below these that show the following: ### Project Burndown Charts **(STARTER)** -For project milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a [burndown chart](burndown_charts.md) is in the milestone view, showing the progress of completing a milestone. +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.  ### Group Burndown Charts **(STARTER)** -For group milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a [burndown chart](burndown_charts.md) is in the milestone view, showing the progress of completing a milestone. +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. ### 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 a7a72ca4d82..fd7c58f12b9 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -1,7 +1,7 @@ --- stage: Verify group: Continuous Integration -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 +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 --- @@ -34,9 +34,9 @@ The reasons to do it like that are: With the new behavior, any job that is triggered by the user, is also marked with their read permissions. When a user does a `git push` or changes files through -the web UI, a new pipeline will be usually created. This pipeline will be marked +the web UI, a new pipeline is usually created. This pipeline is marked as created by the pusher (local push or via the UI) and any job created in this -pipeline will have the read permissions of the pusher but not write permissions. +pipeline has the read permissions of the pusher but not write permissions. This allows us to make it really easy to evaluate the access for all projects that have [Git submodules](../../ci/git_submodules.md) or are using container images that the pusher @@ -47,14 +47,14 @@ is running. The access is revoked after the job is finished.** It is important to note that we have a few types of users: -- **Administrators**: CI jobs created by Administrators will not have access +- **Administrators**: CI jobs created by Administrators don't have access to all GitLab projects, but only to projects and container images of projects that the administrator is a member of. That means that if a project is either public or internal users have access anyway, but if a project is private, the - Administrator will have to be a member of it in order to have access to it + Administrator has to be a member of it in order to have access to it via another project's job. -- **External users**: CI jobs created by [external users](../permissions.md#external-users) will have +- **External users**: CI jobs created by [external users](../permissions.md#external-users) have access only to projects to which the user has at least Reporter access. This rules out accessing all internal projects by default. @@ -75,7 +75,9 @@ Let's consider the following scenario: A unique job token is generated for each job and provides the user read access all projects that would be normally accessible to the user creating that job. The unique job token does not have any write permissions, but there -is a [proposal to add support](https://gitlab.com/gitlab-org/gitlab/-/issues/35067). +is a [proposal to add support](https://gitlab.com/groups/gitlab-org/-/epics/3559). + +If you need your CI pipeline to push to the Package Registry, consider using [deploy tokens](deploy_tokens/index.md). We try to make sure that this token doesn't leak by: @@ -149,8 +151,8 @@ the container registry. ### Prerequisites to use the new permissions model -With the new permissions model in place, there may be times that your job will -fail. This is most likely because your project tries to access other project's +With the new permissions model in place, there may be times that your job +fails. This is most likely because your project tries to access other project's sources, and you don't have the appropriate permissions. In the job log look for information about 403 or forbidden access messages. @@ -158,7 +160,7 @@ In short here's what you need to do should you encounter any issues. As an administrator: -- **500 errors**: You will need to update [GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) to at +- **500 errors**: You need to update [GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) to at least 0.8.2. This is done automatically for Omnibus installations, you need to [check manually](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/update) for installations from source. - **500 errors**: Check if you have another web proxy sitting in front of NGINX (HAProxy, @@ -185,7 +187,7 @@ git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/<user>/<mydependent ``` It can also be used for system-wide authentication -(only do this in a Docker container, it will overwrite ~/.netrc): +(only do this in a Docker container, it overwrites `~/.netrc`): ```shell echo -e "machine gitlab.com\nlogin gitlab-ci-token\npassword ${CI_JOB_TOKEN}" > ~/.netrc @@ -201,18 +203,17 @@ To properly configure submodules with GitLab CI/CD, read the With the update permission model we also extended the support for accessing Container Registries for private projects. -> **Notes:** -> -> - GitLab Runner versions prior to 1.8 don't incorporate the introduced changes -> for permissions. This makes the `image:` directive not work with private -> projects automatically and it needs to be configured manually on the GitLab Runner host -> with a predefined account (for example administrator's personal account with -> access token created explicitly for this purpose). This issue is resolved with -> latest changes in GitLab Runner 1.8 which receives GitLab credentials with -> build data. -> - Starting from GitLab 8.12, if you have [2FA](../profile/account/two_factor_authentication.md) enabled in your account, you need -> to pass a [personal access token](../profile/personal_access_tokens.md) instead of your password in order to -> login to GitLab's Container Registry. +GitLab Runner versions prior to 1.8 don't incorporate the introduced changes +for permissions. This makes the `image:` directive not work with private +projects automatically and it needs to be configured manually on the GitLab Runner host +with a predefined account (for example administrator's personal account with +access token created explicitly for this purpose). This issue is resolved with +latest changes in GitLab Runner 1.8 which receives GitLab credentials with +build data. + +Starting from GitLab 8.12, if you have [2FA](../profile/account/two_factor_authentication.md) enabled in your account, you need +to pass a [personal access token](../profile/personal_access_tokens.md) instead of your password in order to +login to the Container Registry. Your jobs can access all container images that you would normally have access to. The only implication is that you can push to the Container Registry of the diff --git a/doc/user/project/operations/alert_management.md b/doc/user/project/operations/alert_management.md index 0feed7dbf40..e60e7d93d12 100644 --- a/doc/user/project/operations/alert_management.md +++ b/doc/user/project/operations/alert_management.md @@ -3,3 +3,6 @@ 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 index 2640f2cf98f..ef106181acc 100644 --- a/doc/user/project/operations/dashboard_settings.md +++ b/doc/user/project/operations/dashboard_settings.md @@ -3,3 +3,6 @@ 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 index 3c00c4a6c41..399ab0d53dc 100644 --- a/doc/user/project/operations/error_tracking.md +++ b/doc/user/project/operations/error_tracking.md @@ -3,3 +3,6 @@ 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 index b0f7cfc966a..03f2cad6d78 100644 --- a/doc/user/project/operations/feature_flags.md +++ b/doc/user/project/operations/feature_flags.md @@ -3,3 +3,6 @@ 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 index 9cec578bc5e..d19cf393883 100644 --- a/doc/user/project/operations/index.md +++ b/doc/user/project/operations/index.md @@ -3,3 +3,6 @@ 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 index 2640f2cf98f..ef106181acc 100644 --- a/doc/user/project/operations/linking_to_an_external_dashboard.md +++ b/doc/user/project/operations/linking_to_an_external_dashboard.md @@ -3,3 +3,6 @@ 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 index 87567f45560..dcf9894f9e1 100644 --- a/doc/user/project/operations/tracing.md +++ b/doc/user/project/operations/tracing.md @@ -3,3 +3,6 @@ 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 index 8378b8c78cd..13b5d69586a 100644 --- a/doc/user/project/packages/maven.md +++ b/doc/user/project/packages/maven.md @@ -3,3 +3,6 @@ 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 index 8378b8c78cd..13b5d69586a 100644 --- a/doc/user/project/packages/maven_packages.md +++ b/doc/user/project/packages/maven_packages.md @@ -3,3 +3,6 @@ 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 index 8378b8c78cd..13b5d69586a 100644 --- a/doc/user/project/packages/maven_repository.md +++ b/doc/user/project/packages/maven_repository.md @@ -3,3 +3,6 @@ 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 index e94599cf33a..f874b05e7e2 100644 --- a/doc/user/project/packages/npm_registry.md +++ b/doc/user/project/packages/npm_registry.md @@ -3,3 +3,6 @@ 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/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 810538ab460..4aa89ec6f8d 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -1,8 +1,8 @@ --- type: concepts stage: Release -group: Release 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/#designated-technical-writers +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # DNS records overview @@ -23,7 +23,7 @@ GitLab Pages site. Note that **how to** add DNS records depends on which server your domain is hosted on. Every control panel has its own place to do it. If you are -not an admin of your domain, and don't have access to your registrar, +not an administrator of your domain, and don't have access to your registrar, you'll need to ask for the technical support of your hosting service to do it for you. diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index 9b43dd58afe..f8173b4c004 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -1,8 +1,8 @@ --- disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pages/getting_started_part_three.html' stage: Release -group: Release 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/#designated-technical-writers +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Custom domains and SSL/TLS Certificates @@ -84,7 +84,7 @@ server running on your instance).  -CAUTION: **Caution:** +WARNING: Note that if you use your root domain for your GitLab Pages website **only**, and if your domain registrar supports this feature, you can add a DNS apex `CNAME` record instead of an `A` record. The main @@ -157,7 +157,7 @@ Once you have added all the DNS records: As soon as your domain becomes active, your website will be available through your domain name. -CAUTION: **Caution:** +WARNING: Considering GitLab instances with domain verification enabled, if the domain cannot be verified for 7 days, it will be removed from the GitLab project. @@ -167,7 +167,7 @@ from the GitLab project. > - Domain verification is **required for GitLab.com users**; for GitLab self-managed instances, your GitLab administrator has the option to [disabled custom domain verification](../../../../administration/pages/index.md#custom-domain-verification). -> - [DNS propagation may take some time (up to 24h)](https://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/domain-names-dns-changes/), +> - [DNS propagation may take some time (up to 24h)](https://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/complete-guide-to-dns-records/), although it's usually a matter of minutes to complete. Until it does, verification will fail and attempts to visit your domain will respond with a 404. > - Once your domain has been verified, leave the verification record @@ -190,6 +190,22 @@ Expect the output: _gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN>. 300 IN TXT "gitlab-pages-verification-code=<YOUR-VERIFICATION-CODE>" ``` +In some cases it can help to add the verification code with the same domain name as you are trying to register. + +For a root domain: + +| From | DNS Record | To | +| ------------------------------------------------- | ---------- | ---------------------- | +| `example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `_gitlab-pages-verification-code.example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | + +For a subdomain: + +| From | DNS Record | To | +| ------------------------------------------------- | ---------- | ---------------------- | +| `www.example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | +| `_gitlab-pages-verification-code.www.example.com` | TXT | `gitlab-pages-verification-code=00112233445566778899aabbccddeeff` | + ### Adding more domain aliases You can add more than one alias (custom domains and subdomains) to the same project. @@ -280,7 +296,7 @@ To make your website's visitors even more secure, you can choose to force HTTPS for GitLab Pages. By doing so, all attempts to visit your website via HTTP will be automatically redirected to HTTPS via 301. -It works with both GitLab's default domain and with your custom +It works with both the GitLab default domain and with your custom domain (as long as you've set a valid certificate for it). To enable this setting: 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 24b202dfdbd..3dea35153e4 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 @@ -2,8 +2,8 @@ type: reference description: "Automatic Let's Encrypt SSL certificates for GitLab Pages." stage: Release -group: Release 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/#designated-technical-writers +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Pages integration with Let's Encrypt @@ -18,7 +18,7 @@ GitLab does it for you, out-of-the-box. [Let's Encrypt](https://letsencrypt.org) is a free, automated, and open source Certificate Authority. -CAUTION: **Caution:** +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). ## Requirements @@ -33,7 +33,7 @@ Before you can enable automatic provisioning of an SSL certificate for your doma and verified your ownership. - Verified your website is up and running, accessible through your custom domain. -GitLab's Let's Encrypt integration is enabled and available on GitLab.com. +The GitLab integration with Let's Encrypt is enabled and available on GitLab.com. For **self-managed** GitLab instances, make sure your administrator has [enabled it](../../../../administration/pages/index.md#lets-encrypt-integration). 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 f30361e6669..dc73a664324 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 @@ -1,8 +1,8 @@ --- type: concepts stage: Release -group: Release 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/#designated-technical-writers +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # SSL/TLS Certificates @@ -16,8 +16,8 @@ up your Pages project with your custom (sub)domain, if you want it secured by HTTPS, you will have to issue a certificate for that (sub)domain and install it on your project. -NOTE: **Note:** -Certificates are NOT required to add to your custom +NOTE: +Certificates are **not** required to add to your custom (sub)domain on your GitLab Pages project, though they are highly recommendable. @@ -56,7 +56,7 @@ reiterating the importance of HTTPS. ## Issuing Certificates -GitLab Pages accepts certificates provided in the [PEM](https://knowledge.digicert.com/quovadis) format, issued by +GitLab Pages accepts certificates provided in the [PEM](https://knowledge.digicert.com/quovadis.html) format, issued by [Certificate Authorities](https://en.wikipedia.org/wiki/Certificate_authority) or as [self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate). Note that [self-signed certificates are typically not used](https://www.mcafee.com/blogs/other-blogs/mcafee-labs/self-signed-certificates-secure-so-why-ban/) for public websites for security reasons and to ensure that browsers trust your site's certificate. diff --git a/doc/user/project/pages/getting_started/fork_sample_project.md b/doc/user/project/pages/getting_started/fork_sample_project.md index 250e90f0302..2cf118c9066 100644 --- a/doc/user/project/pages/getting_started/fork_sample_project.md +++ b/doc/user/project/pages/getting_started/fork_sample_project.md @@ -3,3 +3,6 @@ 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 index f19334a1764..2fc833fbd34 100644 --- a/doc/user/project/pages/getting_started/new_or_existing_website.md +++ b/doc/user/project/pages/getting_started/new_or_existing_website.md @@ -3,3 +3,6 @@ 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 index bc706105606..0dab1f6ee19 100644 --- a/doc/user/project/pages/getting_started/pages_bundled_template.md +++ b/doc/user/project/pages/getting_started/pages_bundled_template.md @@ -3,3 +3,6 @@ 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_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index 906ffe43285..6dd431e02b0 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -1,8 +1,8 @@ --- type: reference, howto stage: Release -group: Release 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/#designated-technical-writers +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Create a Pages website by using a CI/CD template 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 7dc3d2197b5..525bbde4671 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 @@ -1,13 +1,13 @@ --- type: reference, howto stage: Release -group: Release 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/#designated-technical-writers +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Create a Pages website from a forked sample -GitLab provides [sample projects for the most popular Static Site Generators](https://gitlab.com/pages). +GitLab provides [sample projects for the most popular Static Site Generators (SSG)](https://gitlab.com/pages). You can fork one of the sample projects and run the CI/CD pipeline to generate a Pages website. Fork a sample project when you want to test GitLab Pages or start a new project that's already diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index e030326ac5f..230e88f35f5 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -1,7 +1,7 @@ --- stage: Release -group: Release 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/#designated-technical-writers +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Create a GitLab Pages website from scratch diff --git a/doc/user/project/pages/getting_started/pages_new_project_template.md b/doc/user/project/pages/getting_started/pages_new_project_template.md index cfa4e0910db..eec8349abe6 100644 --- a/doc/user/project/pages/getting_started/pages_new_project_template.md +++ b/doc/user/project/pages/getting_started/pages_new_project_template.md @@ -1,8 +1,8 @@ --- type: reference, howto stage: Release -group: Release 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/#designated-technical-writers +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Create a Pages website from a new project template diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md index e45befe004e..361323a9073 100644 --- a/doc/user/project/pages/getting_started_part_four.md +++ b/doc/user/project/pages/getting_started_part_four.md @@ -3,3 +3,6 @@ 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 5ef0c4cc7b9..f549c4e6e7d 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -1,7 +1,7 @@ --- stage: Release -group: Release 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/#designated-technical-writers +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 @@ -33,7 +33,7 @@ Pages domains are `*.gitlab.io`. | Project pages owned by a group | `projectname` | `http(s)://groupname.example.io/projectname`| | Project pages owned by a subgroup | `subgroup/projectname` | `http(s)://groupname.example.io/subgroup/projectname`| -CAUTION: **Warning:** +WARNING: There are some known [limitations](introduction.md#limitations) regarding namespaces served under the general domain name and HTTPS. Make sure to read that section. @@ -80,6 +80,9 @@ To understand Pages domains clearly, read the examples below. ## URLs and baseurls +NOTE: +The `baseurl` option might be called named differently in some static site generators. + Every Static Site Generator (SSG) default configuration expects to find your website under a (sub)domain (`example.com`), not in a subdirectory of that domain (`example.com/subdir`). Therefore, @@ -96,7 +99,7 @@ baseurl: "/blog" ``` On the contrary, if you deploy your website after forking one of -our [default examples](https://gitlab.com/pages), the baseurl will +our [default examples](https://gitlab.com/pages), the `baseurl` will already be configured this way, as all examples there are project websites. If you decide to make yours a user or group website, you'll have to remove this configuration from your project. For the Jekyll @@ -106,6 +109,9 @@ example we've just mentioned, you'd have to change Jekyll's `_config.yml` to: baseurl: "" ``` +If you're using the [plain HTML example](https://gitlab.com/pages/plain-html), +you don't need to set a `baseurl`. + ## Custom domains GitLab Pages supports custom domains and subdomains, served under HTTP or HTTPS. diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index 4bf5300aa13..9d7f401ca91 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -3,3 +3,6 @@ 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 index 70e84f5d486..4b2b186ca28 100644 --- a/doc/user/project/pages/getting_started_part_two.md +++ b/doc/user/project/pages/getting_started_part_two.md @@ -3,3 +3,6 @@ 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 f5cd6991869..846d30e898c 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -1,8 +1,8 @@ --- description: 'Learn how to use GitLab Pages to deploy a static website at no additional cost.' stage: Release -group: Release 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/#designated-technical-writers +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 @@ -83,9 +83,9 @@ to build your site and publish it to the GitLab Pages server. The sequence of scripts that GitLab CI/CD runs to accomplish this task is created from a file named `.gitlab-ci.yml`, which you can [create and modify](getting_started/pages_from_scratch.md) at will. A specific `job` called `pages` in the configuration file will make GitLab aware that you are deploying a GitLab Pages website. -You can either use GitLab's [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-default-domain-names), +You can either use the GitLab [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-default-domain-names), `*.gitlab.io`, or your own domain (`example.com`). In that case, you'll -need admin access to your domain's registrar (or control panel) to set it up with Pages. +need administrator access to your domain's registrar (or control panel) to set it up with Pages. The following diagrams show the workflows you might follow to get started with Pages. @@ -103,7 +103,7 @@ To restrict access to your website, enable [GitLab Pages Access Control](pages_a If you're using a self-managed instance (Core, Starter, Premium, or Ultimate), your websites will be published on your own server, according to the -[Pages admin settings](../../../administration/pages/index.md) chosen by your sysadmin, +[Pages settings](../../../administration/pages/index.md) chosen by your sysadmin, who can make them public or internal. ## Pages examples diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 6dbc12cc2ec..5a284bf57c3 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -1,7 +1,7 @@ --- stage: Release -group: Release 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/#designated-technical-writers +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Exploring GitLab Pages @@ -280,4 +280,4 @@ No, you don't. You can create your project first and it will be accessed under ## Known issues -For a list of known issues, visit GitLab's [public issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name[]=Category%3APages). +For a list of known issues, visit the GitLab [public issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name[]=Category%3APages). diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md index 13ea57939f8..f2b75354bf8 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -1,19 +1,19 @@ --- stage: Release -group: Release 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/#designated-technical-writers +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 description: "How to secure GitLab Pages websites with Let's Encrypt (manual process, deprecated)." --- # Let's Encrypt for GitLab Pages (manual process, deprecated) -CAUTION: **Warning:** +WARNING: This method is still valid but was **deprecated** in favor of the [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) introduced in GitLab 12.1. If you have a GitLab Pages website served under your own domain, -you might want to secure it with a SSL/TSL certificate. +you might want to secure it with a SSL/TLS certificate. [Let's Encrypt](https://letsencrypt.org) is a free, automated, and open source Certificate Authority. @@ -67,7 +67,7 @@ might be slightly different. Follow the sudo certbot certonly -a manual -d example.com --register-unsafely-without-email ``` - TIP: **Tip:** + NOTE: Read through CertBot's documentation on their [command line options](https://certbot.eff.org/docs/using.html#certbot-command-line-options). diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index b3705a5835a..9d17277fe9e 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -1,8 +1,8 @@ --- type: reference, howto stage: Release -group: Release 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/#designated-technical-writers +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Pages Access Control diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index 60fbf368061..8c189614102 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -1,7 +1,7 @@ --- stage: Release -group: Release 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/#designated-technical-writers +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Create redirects for GitLab Pages @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/24) in GitLab Pages 1.25.0 and GitLab 13.4 behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/367) in GitLab 13.5. -CAUTION: **Warning:** +WARNING: This feature might not be available to you. Check the **version history** note above for details. In GitLab Pages, you can configure rules to forward one URL to another using diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md index c23eaebcbe9..cf5f33534cd 100644 --- a/doc/user/project/pipelines/job_artifacts.md +++ b/doc/user/project/pipelines/job_artifacts.md @@ -3,3 +3,6 @@ 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 index a92464d6817..52352a29c5a 100644 --- a/doc/user/project/pipelines/schedules.md +++ b/doc/user/project/pipelines/schedules.md @@ -3,3 +3,6 @@ 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 index af4cbe13aba..f19f28743a8 100644 --- a/doc/user/project/pipelines/settings.md +++ b/doc/user/project/pipelines/settings.md @@ -3,3 +3,6 @@ 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 7265fd330e3..5754a3b7a9d 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -21,8 +21,8 @@ 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: **Note:** -A GitLab admin is allowed to push to the protected branches. +NOTE: +A GitLab administrator is allowed to push to the protected branches. See the [Changelog](#changelog) section for changes over time. @@ -74,6 +74,33 @@ 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. +### 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. + +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, +for example. + +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, +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. + +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. + + + ## 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. @@ -143,7 +170,7 @@ From time to time, it may be required to delete or clean up branches that are protected. User with [Maintainer permissions](../permissions.md) and up can manually delete protected -branches via GitLab's web interface: +branches via the GitLab web interface: 1. Visit **Repository > Branches** 1. Click on the delete icon next to the branch you wish to delete @@ -197,6 +224,10 @@ 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. diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 5dd2a72c91e..7e09c526312 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index db9e2f270e0..8af4307c013 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -17,7 +17,7 @@ Currently, there are push options available for: - [Skipping CI jobs](#push-options-for-gitlab-cicd) - [Merge requests](#push-options-for-merge-requests) -NOTE: **Note:** +NOTE: Git push options are only available with Git 2.10 or newer. For Git versions 2.10 to 2.17 use `--push-option`: diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 46db7293711..9f849051f40 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -2,7 +2,7 @@ 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/#designated-technical-writers +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 Quick Actions @@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > quick actions when updating the description of issues, epics, and merge requests. Quick actions are textual shortcuts for common actions on issues, epics, merge requests, -and commits that are usually done by clicking buttons or dropdowns in GitLab's UI. +and commits that are usually done by clicking buttons or dropdowns in the GitLab UI. You can enter these commands in the description or in comments of issues, epics, merge requests, and commits. Each command should be on a separate line in order to be properly detected and executed. @@ -34,6 +34,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/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)** | +| `/clone <path/to/project> [--with_notes]`| ✓ | | | Clone the issue to given project, or the current one if no arguments are given ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9421) in GitLab 13.7). Copies as much data as possible as long as the target project contains equivalent labels, milestones, and so on. Does not copy comments or system notes unless `--with_notes` is provided as an argument. | | `/close` | ✓ | ✓ | ✓ | Close. | | `/confidential` | ✓ | | | Make confidential. | | `/copy_metadata <!merge_request>` | ✓ | ✓ | | Copy labels and milestone from another merge request in the project. | diff --git a/doc/user/project/releases.md b/doc/user/project/releases.md index baa7a295273..6dd5a6f0b0d 100644 --- a/doc/user/project/releases.md +++ b/doc/user/project/releases.md @@ -3,3 +3,6 @@ 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 674fe8b22b8..7b412270938 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -1,8 +1,8 @@ --- type: reference, howto stage: Release -group: Release 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/#designated-technical-writers +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 --- # Releases @@ -79,6 +79,16 @@ To create a new release through the GitLab UI: [release notes](#release-notes-description), or [assets links](#links). 1. Click **Create release**. +### Create release from GitLab CI + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19298) in GitLab 12.7. + +You can [create a release directly from the GitLab CI pipeline](../../../ci/yaml/README.md#release) +by using a `release` node in the job definition. + +The release is created only if the job processes without error. If the Rails API returns an error +during release creation, the release job fails. + ### Schedule a future release > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38105) in GitLab 12.1. @@ -213,7 +223,7 @@ To set a deploy freeze window in the UI, complete these steps:  -CAUTION: **Caution:** +WARNING: To edit or delete a deploy freeze, use the [Freeze Periods API](../../../api/freeze_periods.md). If a project contains multiple freeze periods, all periods apply. If they overlap, the freeze covers the @@ -460,7 +470,7 @@ In the API: > [Introduced](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/6) in GitLab 12.10. The Release CLI is a command-line tool for managing GitLab Releases from the command line or from -GitLab's CI/CD configuration file, `.gitlab-ci.yml`. +the GitLab CI/CD configuration file, `.gitlab-ci.yml`. With it, you can create, update, modify, and delete releases right through the terminal. diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index a937b6ed959..ffd4b383bcb 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: concepts, howto --- diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index 99319efbb7f..4f996df5fef 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -1,7 +1,7 @@ --- stage: Create 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/#designated-technical-writers +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 disqus_identifier: 'https://docs.gitlab.com/ee/workflow/file_finder.html' --- @@ -40,7 +40,7 @@ the `app/controllers/admin/deploy_keys_controller.rb` file. Using a fuzzy search, we start by typing letters that get us closer to the file. -TIP: **Tip:** +NOTE: To narrow down your search, include `/` in your search terms.  diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index b0aa7569579..75e1aea632f 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 disqus_identifier: 'https://docs.gitlab.com/ee/workflow/forking_workflow.html' --- @@ -26,18 +26,18 @@ Forking a project is, in most cases, a two-step process. 1. Click a namespace to fork to. Only namespaces you have Developer and higher [permissions](../../permissions.md) for are shown. - NOTE: **Note:** + NOTE: The project path must be unique within the namespace.  The fork is created. The permissions you have in the namespace are the permissions you will have in the fork. -CAUTION: **Caution:** +WARNING: In GitLab 12.6 and later, when project owners [reduce a project's visibility](../../../public_access/public_access.md#reducing-visibility), it **removes the relationship** between a project and all its forks. -CAUTION: **Caution:** +WARNING: When a public project with the repository feature set to "Members only" is forked, the repository will be public in the fork. The owner of the fork will need to manually change the visibility. This is being @@ -52,7 +52,7 @@ The main difference is that with repository mirroring your remote fork will be a Without mirroring, to work locally you'll have to use `git pull` to update your local repository with the upstream project, then push the changes back to your fork to update it. -CAUTION: **Caution:** +WARNING: With mirroring, before approving a merge request, you'll likely be asked to sync; hence automating it is recommended. Read more about [How to keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/). @@ -63,7 +63,7 @@ When you are ready to send your code back to the upstream project, [create a merge request](../merge_requests/creating_merge_requests.md). For **Source branch**, choose your forked project's branch. For **Target branch**, choose the original project's branch. -NOTE: **Note:** +NOTE: When creating a merge request, if the forked project's visibility is more restrictive than the parent project (for example the fork is private, the parent is public), the target branch will default to the forked project's default branch. This prevents potentially exposing the private code of the forked project.  diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index a423f58ba21..4322c79daa7 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto description: "Documentation on Git file blame." --- diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index 6cc05d2192f..51cc6bb3483 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto description: "Documentation on Git file history." --- diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 646d708d896..57e9d814c95 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: concepts, howto --- @@ -15,7 +15,7 @@ commits are labeled **Verified** if the identity of the committer can be verified. To verify the identity of a committer, GitLab requires their public GPG key. -NOTE: **Note:** +NOTE: The term GPG is used for all OpenPGP/PGP/GPG related material and implementations. @@ -53,7 +53,7 @@ started: gpg --full-gen-key ``` - NOTE: **Note:** + NOTE: In some cases like Gpg4win on Windows and other macOS versions, the command here may be `gpg --gen-key`. @@ -142,7 +142,7 @@ started: ## Adding a GPG key to your account -NOTE: **Note:** +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. diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 40bf40a3dba..e1d84baec4d 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts, howto --- @@ -48,7 +48,7 @@ to your repository's root. **From the user interface:** -GitLab's UI allows you to perform lots of Git commands without having to +The GitLab UI allows you to perform lots of Git commands without having to touch the command line. Even if you use the command line regularly, sometimes it's easier to do so [via GitLab UI](web_editor.md): @@ -67,7 +67,7 @@ To get started with the command line, please read through the ### Find files -Use GitLab's [file finder](file_finder.md) to search for files in a repository. +Use the GitLab [file finder](file_finder.md) to search for files in a repository. ### Supported markup languages and extensions @@ -141,7 +141,7 @@ their filenames include `openapi` or `swagger` and their extension is `yaml`, Then, to render them: -1. Navigate to the OpenAPI file in your repository in GitLab's UI. +1. Navigate to the OpenAPI file in your repository in the GitLab UI. 1. Click the "Display OpenAPI" button which is located between the "Display source" and "Edit" buttons (when an OpenAPI file is found, it replaces the "Display rendered file" button). @@ -189,7 +189,7 @@ updated every 15 minutes at most, so may not reflect recent activity. The displa The project size may differ slightly from one instance to another due to compression, housekeeping, and other factors. -[Repository size limit](../../admin_area/settings/account_and_limit_settings.md) may be set by admins. +[Repository size limit](../../admin_area/settings/account_and_limit_settings.md) may be set by administrators. GitLab.com's repository size limit [is set by GitLab](../../gitlab_com/index.md#account-and-limit-settings). ## Contributors diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 69a32841981..91fe9049b53 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +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 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 9f4dfe54c47..fb798738160 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 @@ -1,7 +1,7 @@ --- stage: Create group: Gitaly -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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -18,12 +18,12 @@ We **recommend [`git filter-repo`](https://github.com/newren/git-filter-repo/blo over [`git filter-branch`](https://git-scm.com/docs/git-filter-branch) and [BFG](https://rtyley.github.io/bfg-repo-cleaner/). -DANGER: **Warning:** +WARNING: Rewriting repository history is a destructive operation. Make sure to back up your repository before 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: **Note:** +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). @@ -87,7 +87,7 @@ download all the advertised refs. git push origin --force 'refs/heads/*' ``` - [Protected branches](../protected_branches.md) will cause this to fail. To proceed, you must + [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: @@ -96,7 +96,7 @@ download all the advertised refs. git push origin --force 'refs/tags/*' ``` - [Protected tags](../protected_tags.md) will cause this to fail. To proceed, you must remove tag + [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`. @@ -109,7 +109,7 @@ download all the advertised refs. 1. Run a [repository cleanup](#repository-cleanup). -NOTE: **Note:** +NOTE: Project statistics are cached for performance. You may need to wait 5-10 minutes to see a reduction in storage utilization. @@ -131,7 +131,7 @@ To purge files from GitLab storage: tar xzf project-backup.tar.gz ``` - This will contain a `project.bundle` file, which was created by + 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: @@ -141,12 +141,12 @@ To purge files from GitLab storage: ``` 1. Using `git filter-repo`, purge any files from the history of your repository. Because we are - trying to remove internal refs, we will rely on the `commit-map` produced by each run to tell us + trying to remove internal refs, we rely on the `commit-map` produced by each run to tell us which internal refs to remove. - NOTE: **Note:** + NOTE: `git filter-repo` creates a new `commit-map` file every run, and overwrite the `commit-map` from - the previous run. You will need this file from **every** run. Do the next step every time you run + 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: @@ -178,7 +178,7 @@ To purge files from GitLab storage: git push origin --force 'refs/heads/*' ``` - [Protected branches](../protected_branches.md) will cause this to fail. To proceed, you must + [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: @@ -187,7 +187,7 @@ To purge files from GitLab storage: git push origin --force 'refs/tags/*' ``` - [Protected tags](../protected_tags.md) will cause this to fail. To proceed, you must remove tag + [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`. @@ -202,19 +202,19 @@ To purge files from GitLab storage: ## Repository cleanup -NOTE: **Note:** -Safely cleaning the repository requires it to be made read-only for the duration -of the operation. This happens automatically, but submitting the cleanup request -will fail if any writes are ongoing, so cancel any outstanding `git push` -operations before continuing. - > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19376) in GitLab 11.6. -Repository cleanup allows you to upload a text file of objects and GitLab will remove internal Git +Repository cleanup allows you to upload a text file of objects and GitLab removes internal Git references to these objects. You can use [`git filter-repo`](https://github.com/newren/git-filter-repo) to produce a list of objects (in a `commit-map` file) that can be used with repository cleanup. +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45058) in GitLab 13.6, +safely cleaning the repository requires it to be made read-only for the duration +of the operation. This happens automatically, but submitting the cleanup request +fails if any writes are ongoing, so cancel any outstanding `git push` +operations before continuing. + To clean up a repository: 1. Go to the project for the repository. @@ -230,25 +230,30 @@ To clean up a repository: 1. Click **Start cleanup**. -This will: +This: -- Remove any internal Git references to old commits. -- Run `git gc` against the repository to remove unreferenced objects. Repacking your repository will temporarily - cause the size of your repository to increase significantly, because the old pack files are not removed until the +- Removes any internal Git references to old commits. +- 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. -- Unlink any unused LFS objects currently attached to your project, freeing up storage space. -- Recalculate the size of your repository on disk. +- Unlinks any unused LFS objects currently 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. -You will receive 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 +dormant for at least 30 minutes. When using repository cleanup, note: - Project statistics are cached. You may need to wait 5-10 minutes to see a reduction in storage utilization. -- Housekeeping prunes loose objects older than 2 weeks. This means objects added in the last 2 weeks - will not be removed immediately. If you have access to the - [Gitaly](../../../administration/gitaly/index.md) server, you may run `git gc --prune=now` to +- The cleanup prunes loose objects older than 30 minutes. This means objects added or referenced in the last 30 minutes + are not be removed immediately. If you have access to the + [Gitaly](../../../administration/gitaly/index.md) server, you may slip that delay and run `git gc --prune=now` to prune all loose objects immediately. -- This process will remove some copies of the rewritten commits from GitLab's cache and database, +- This process removes some copies of the rewritten commits from the GitLab cache and database, but there are still numerous gaps in coverage and some of the copies may persist indefinitely. [Clearing the instance cache](../../../administration/raketasks/maintenance.md#clear-redis-cache) may help to remove some of them, but it should not be depended on for security purposes! @@ -289,8 +294,8 @@ size of the repository, because the earlier commits and blobs still exist. Inste history. We recommend the open-source community-maintained tool [`git filter-repo`](https://github.com/newren/git-filter-repo). -NOTE: **Note:** -Until `git gc` runs on the GitLab side, the "removed" commits and blobs will still exist. You also +NOTE: +Until `git gc` runs on the GitLab side, the "removed" commits and blobs still exist. You also must be able to push the rewritten history to GitLab, which may be impossible if you've already exceeded the maximum size limit. @@ -302,9 +307,9 @@ increased, your only option is to: 1. Prune all the unneeded stuff locally. 1. Create a new project on GitLab and start using that instead. -CAUTION: **Caution:** +WARNING: This process is not suitable for removing sensitive data like password or keys from your repository. -Information about commits, including file content, is cached in the database, and will remain +Information about commits, including file content, is cached in the database, and remain visible even after they have been removed from the repository. ## Troubleshooting diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 1f9835f4f59..96694a9e954 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers +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 disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- @@ -11,8 +11,7 @@ Repository mirroring allows for mirroring of repositories to and from external s used to mirror branches, tags, and commits between repositories. A repository mirror at GitLab will be updated automatically. You can also manually trigger an update -at most once every 5 minutes. Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/237891) -for discussions on how to potentially reduce the delay. +at most once every 5 minutes on GitLab.com with [the limit set by the administrator on self-managed instances](../../../administration/instance_limits.md#pull-mirroring-interval). ## Overview @@ -30,7 +29,7 @@ Users with at least [Developer access](../../permissions.md) to the project can immediate update, unless: - The mirror is already being updated. -- 5 minutes haven't elapsed since its last update. +- The [limit for pull mirroring interval seconds](../../../administration/instance_limits.md#pull-mirroring-interval) has not elapsed since its last update. For security reasons, in [GitLab 12.10 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/27166), the URL to the original repository is only displayed to users with @@ -117,14 +116,14 @@ skipped, allowing `master` and `stable` to be updated. The mirror status will reflect that `develop` has diverged and was skipped, and be marked as a failed update. -NOTE: **Note:** +NOTE: After the mirror is created, this option can currently only be modified via the [API](../../../api/remote_mirrors.md). ## Setting up a push mirror from GitLab to GitHub **(CORE)** To set up a mirror from GitLab to GitHub, you need to follow these steps: -1. Create a [GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with the `public_repo` box checked. +1. Create a [GitHub personal access token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) with the `public_repo` box checked. 1. Fill in the **Git repository URL** field using this format: `https://<your_github_username>@github.com/<your_github_group>/<your_github_project>.git`. 1. Fill in **Password** field with your GitHub personal access token. 1. Click the **Mirror repository** button. @@ -137,11 +136,11 @@ The repository will push soon. To force a push, click the **Update now** (**{ret AWS CodeCommit push mirroring is currently the best way to connect GitLab repositories to AWS CodePipeline, as GitLab is not yet supported as one of their Source Code Management (SCM) providers. -Each new AWS Codepipeline needs significant AWS infrastructure setup. It also requires an individual pipeline per branch. +Each new AWS CodePipeline needs significant AWS infrastructure setup. It also requires an individual pipeline per branch. If AWS CodeDeploy is the final step of a CodePipeline, you can, instead, leverage GitLab CI/CD pipelines and simply use the AWS CLI in the final job in `.gitlab-ci.yml` to deploy to CodeDeploy. -NOTE: **Note:** +NOTE: GitLab-to-AWS-CodeCommit push mirroring cannot use SSH authentication until [GitLab issue 34014](https://gitlab.com/gitlab-org/gitlab/-/issues/34014) is resolved. To set up a mirror from GitLab to AWS CodeCommit: @@ -177,7 +176,7 @@ To set up a mirror from GitLab to AWS CodeCommit: 1. Click the **Security credentials** tab. 1. Under **HTTPS Git credentials for AWS CodeCommit** click **Generate credentials**. - NOTE: **Note:** + NOTE: This Git user ID and password is specific to communicating with CodeCommit. Do not confuse it with the IAM user ID or AWS keys of this user. @@ -256,7 +255,7 @@ Changes pushed to the upstream repository will be pulled into the GitLab reposit - Automatically within a certain period of time. - When a [forced update](#forcing-an-update) is initiated. -CAUTION: **Caution:** +WARNING: If you do manually update a branch in the GitLab repository, the branch will become diverged from upstream and GitLab will no longer automatically update this branch to prevent any changes from being lost. Also note that deleted branches and tags in the upstream repository will not be reflected in the GitLab repository. @@ -301,7 +300,7 @@ To get started: 1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** section. 1. Enter an `ssh://` URL for mirroring. -NOTE: **Note:** +NOTE: SCP-style URLs (that is, `git@example.com:group/project.git`) are not supported at this time. Entering the URL adds two buttons to the page: @@ -320,7 +319,7 @@ fingerprints in the open for you to check: - [AWS CodeCommit](https://docs.aws.amazon.com/codecommit/latest/userguide/regions.html#regions-fingerprints) - [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/) -- [GitHub](https://docs.github.com/en/github/authenticating-to-github/githubs-ssh-key-fingerprints) +- [GitHub](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/githubs-ssh-key-fingerprints) - [GitLab.com](../../gitlab_com/index.md#ssh-host-keys-fingerprints) - [Launchpad](https://help.launchpad.net/SSHFingerprints) - [Savannah](http://savannah.gnu.org/maintenance/SshAccess/) @@ -337,7 +336,7 @@ $ cat /etc/ssh/ssh_host*pub | ssh-keygen -E md5 -l -f - 2048 MD5:3f:72:be:3d:62:03:5c:62:83:e8:6e:14:34:3a:85:1d root@example.com (RSA) ``` -NOTE: **Note:** +NOTE: You may need to exclude `-E md5` for some older versions of SSH. When mirroring the repository, GitLab will now check that at least one of the @@ -364,7 +363,7 @@ If you need to change the key at any time, you can remove and re-add the mirror to generate a new key. You'll have to update the other repository with the new key to keep the mirror running. -NOTE: **Note:** +NOTE: The generated keys are stored in the GitLab database, not in the filesystem. Therefore, SSH public key authentication for mirrors cannot be used in a pre-receive hook. @@ -375,7 +374,7 @@ SSH public key authentication for mirrors cannot be used in a pre-receive hook. You can choose to always update your local branches with remote versions, even if they have diverged from the remote. -CAUTION: **Caution:** +WARNING: 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. @@ -421,7 +420,7 @@ update button which is available on the **Mirroring repositories** section of th ## Bidirectional mirroring **(STARTER)** -CAUTION: **Caution:** +WARNING: Bidirectional mirroring may cause conflicts. If you configure a GitLab repository to both pull from, and push to, the same remote source, there @@ -464,7 +463,7 @@ To do this: ### Preventing conflicts using a `pre-receive` hook -CAUTION: **Warning:** +WARNING: The solution proposed will negatively impact the performance of Git push operations because they will be proxied to the upstream Git repository. @@ -547,7 +546,7 @@ Note that this sample has a few limitations: ### Mirroring with Perforce Helix via Git Fusion **(STARTER)** -CAUTION: **Warning:** +WARNING: Bidirectional mirroring should not be used as a permanent configuration. Refer to [Migrating from Perforce Helix](../import/perforce.md) for alternative migration approaches. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 5b82cdbd9e9..24bfeee5e7f 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -1,7 +1,7 @@ --- stage: Create 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/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -32,7 +32,7 @@ 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). +the Web IDE's. For details, see the documentation for [Command Palette](../web_ide/index.md#command-palette). ### Template dropdowns @@ -53,7 +53,7 @@ has already been created, which creates a link to the license itself.  -NOTE: **Note:** +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. @@ -94,7 +94,7 @@ the target branch. Click **Create directory** to finish. ## Create a new branch -There are multiple ways to create a branch from GitLab's web interface. +There are multiple ways to create a branch from the GitLab web interface. ### Create a new branch from an issue @@ -106,7 +106,7 @@ The new branch, and later its merge request, will be marked as related to this i Once merged, the MR will automatically close the issue. You can see a **Create merge request** dropdown below the issue description. -NOTE: **Note:** +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. diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 9b420d84f50..639bca0d354 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -1,7 +1,7 @@ --- 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: concepts, howto --- @@ -28,10 +28,10 @@ For a commit or tag to be *verified* by GitLab: which is usually up to three years. - The signing time is equal or later than commit time. -NOTE: **Note:** +NOTE: Certificate revocation lists are checked on a daily basis via background worker. -NOTE: **Note:** +NOTE: Self signed certificates without `authorityKeyIdentifier`, `subjectKeyIdentifier`, and `crlDistributionPoints` are not supported. We recommend using certificates from a PKI that are in line with diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index f533f8807d2..9d75c4ab071 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -2,7 +2,7 @@ type: reference, howto stage: Plan 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/#designated-technical-writers +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 --- # Requirements Management **(ULTIMATE)** @@ -30,9 +30,11 @@ For an overview, see [GitLab 12.10 Introduces Requirements Management](https://w A paginated list of requirements is available in each project, and there you can create a new requirement. +Users with Reporter or higher [permissions](../../permissions.md) can create requirements. + To create a requirement: -1. From your project page, go to **{requirements}** **Requirements**. +1. From your project page, go to **Requirements**. 1. Select **New requirement**. 1. Enter a title and description and select **Create requirement**. @@ -54,8 +56,9 @@ next to the requirement title. > The ability to mark a requirement as Satisfied [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218607) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.5. -You can edit a requirement (if you have the necessary privileges) from the requirements -list page. +You can edit a requirement from the requirements list page. + +Users with Reporter or higher [permissions](../../permissions.md) can edit requirements. To edit a requirement: @@ -66,9 +69,11 @@ To edit a requirement: ## Archive a requirement -You can archive an open requirement (if you have the necessary privileges) while +You can archive an open requirement while you're in the **Open** tab. +Users with Reporter or higher [permissions](../../permissions.md) can archive requirements. + To archive a requirement, select **Archive** (**{archive}**). As soon as a requirement is archived, it no longer appears in the **Open** tab. @@ -77,6 +82,8 @@ As soon as a requirement is archived, it no longer appears in the **Open** tab. You can view the list of archived requirements in the **Archived** tab. +Users with Reporter or higher [permissions](../../permissions.md) can reopen archived requirements. +  To reopen an archived requirement, select **Reopen**. @@ -94,7 +101,7 @@ You can search for a requirement from the requirements list page based on the fo To search for a requirement: -1. In a project, go to **{requirements}** **Requirements > List**. +1. In a project, go to **Requirements > List**. 1. Select the **Search or filter results** field. A dropdown menu appears. 1. Select the requirement author from the dropdown or enter plain text to search by requirement title. 1. Press <kbd>Enter</kbd> on your keyboard to filter the list. @@ -188,3 +195,65 @@ requirements_confirmation: reports: requirements: tmp/requirements.json ``` + +## Import requirements from a CSV file + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/246857) in GitLab 13.7. + +You can import requirements to a project by uploading a CSV file with the columns +`title` and `description`. + +The user uploading the CSV file will be set as the author of the imported requirements. + +Users with Reporter or higher [permissions](../../permissions.md) can import requirements. + +### Import the file + +Before you import your file: + +- Consider importing a test file containing only a few requirements. There is no way to undo a large + import without using the GitLab API. +- Ensure your CSV file meets the [file format](#csv-file-format) requirements. + +To import requirements: + +1. Navigate to a project's Requirements page. + - If the project already has existing requirements, click the import icon (**{import}**) at the + top right. + - For a project without any requirements, click **Import CSV** in the middle of the page. +1. Select the file and click **Import requirements**. + +The file is processed in the background and a notification email is sent +to you after the import is complete. + +### CSV file format + +When importing requirements from a CSV file, it must be formatted in a certain way: + +- **Header row:** CSV files must include the following headers: + `title` and `description`. The headers are case insensitive. +- **Columns:** data from columns other than `title` and `description` is not imported. +- **Separators:** the column separator is automatically detected from the header row. + Supported separator characters are: commas (`,`), semicolons (`;`), and tabs (`\t`). + The row separator can be either `CRLF` or `LF`. +- **Double-quote character:** the double-quote (`"`) character is used to quote fields, + enabling the use of the column separator in a field (see the third line in the + sample CSV data below). To insert a double-quote (`"`) in a quoted + field, use two double-quote characters in succession (`""`). +- **Data rows:** below the header row, succeeding rows must follow the same column + order. The title text is required, while the description is optional and can be left empty. + +Sample CSV data: + +```plaintext +title,description +My Requirement Title,My Requirement Description +Another Title,"A description, with a comma" +"One More Title","One More Description" +``` + +### File size + +The limit depends on the configuration value of Max Attachment Size for the GitLab instance. + +For GitLab.com, it is set to 10 MB. diff --git a/doc/user/project/security_dashboard.md b/doc/user/project/security_dashboard.md index a3da1ec97d3..d9440e8deea 100644 --- a/doc/user/project/security_dashboard.md +++ b/doc/user/project/security_dashboard.md @@ -3,3 +3,6 @@ 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 34a075df990..4f3ca12c582 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -1,10 +1,10 @@ --- stage: Plan 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/#designated-technical-writers +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 +# Service Desk **(CORE)** > - [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. @@ -59,7 +59,7 @@ users will only see the thread through email. ## Configuring Service Desk -NOTE: **Note:** +NOTE: Service Desk is enabled on GitLab.com. You can skip step 1 below; you only need to enable it per project. @@ -76,7 +76,7 @@ Follow these steps to do so: address's format. The older format is still supported, however, allowing existing aliases or contacts to continue working. - DANGER: **Warning:** + WARNING: This email address can be used by anyone to create an issue on this project, whether or not they have access to your GitLab instance. We recommend **putting this behind an alias** so it can be changed if needed, and **[enabling Akismet](../../integration/akismet.md)** on your GitLab @@ -129,10 +129,12 @@ this name in the `From` header. The default display name is `GitLab Support Bot` ### Using custom email address **(CORE ONLY)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. - -NOTE: **Note:** -This feature is disabled by default. For steps to enable it, see [Enable custom email address](#enable-custom-email-address). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. +> - It was [deployed behind a feature flag](../feature_flags.md), disabled by default. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) on GitLab 13.7. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-custom-email-address). **(CORE ONLY)** If the `service_desk_email` feature flag is enabled in your configuration, then it's possible to create Service Desk issues by sending emails to the @@ -198,18 +200,27 @@ In this case, suppose the `mygroup/myproject` project Service Desk settings has suffix set to `support`, and a user sends an email to `project_contact+mygroup-myproject-support@example.com`. As a result, a new Service Desk issue is created from this email in the `mygroup/myproject` project. -#### Enable custom email address +The configuration options are the same as for configuring +[incoming email](../../administration/incoming_email.md#set-it-up). + +#### Disable custom email address **(CORE ONLY)** + +Service Desk custom email 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. -This feature comes with the `service_desk_custom_address` feature flag disabled by default. -To turn on the feature, ask a GitLab administrator with Rails console access to run the following -command: +To enable it: ```ruby Feature.enable(:service_desk_custom_address) ``` -The configuration options are the same as for configuring -[incoming email](../../administration/incoming_email.md#set-it-up). +To disable it: + +```ruby +Feature.disable(:service_desk_custom_address) +``` ## Using Service Desk diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 3e493f02392..53233cc347e 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -1,7 +1,7 @@ --- stage: Manage group: Import -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -42,7 +42,7 @@ Note the following: - Exports are stored in a temporary [shared directory](../../../development/shared_files.md) and are deleted every 24 hours by a specific worker. - Group members are exported as project members, as long as the user has - maintainer or admin access to the group where the exported project lives. + maintainer or administrator access to the group where the exported project lives. - Project members with owner access will be imported as maintainers. - Imported users can be mapped by their primary email on self-managed instances, if an administrative user (not an owner) does the import. Otherwise, a supplementary comment is left to mention that the original author and @@ -51,6 +51,9 @@ Note the following: then new branches associated with such merge requests will be created within a project during the import/export. Thus, the number of branches in the exported project could be bigger than in the original project. +- Deploy keys allowed to push to protected branches are not exported. Therefore, + you will need to recreate this association by first enabling these deploy keys in your + imported project and then updating your protected branches accordingly. ## Version history @@ -114,8 +117,9 @@ The following items will be exported: - LFS objects - Issue boards - Pipelines history +- Push Rules -The following items will NOT be exported: +The following items will **not** be exported: - Build traces and artifacts - Container registry images @@ -123,10 +127,9 @@ The following items will NOT be exported: - Webhooks - Any encrypted tokens - Merge Request Approvers -- Push Rules - Awards -NOTE: **Note:** +NOTE: For more details on the specific data persisted in a project export, see the [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/import_export/project/import_export.yml) file. @@ -170,14 +173,14 @@ To export a project and its data, follow these steps: 1. Click on **Import project** to begin importing. Your newly imported project page will appear soon. -NOTE: **Note:** +NOTE: If use of the `Internal` visibility level [is restricted](../../../public_access/public_access.md#restricting-the-use-of-public-or-internal-projects), all imported projects are given the visibility of `Private`. -NOTE: **Note:** +NOTE: The maximum import file size can be set by the Administrator, default is 50MB. -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 Area UI](../../admin_area/settings/account_and_limit_settings.md). ### Project import status @@ -188,12 +191,14 @@ As described in the API documentation, the query may return an import error or e 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). -## Rate limits +## Rate Limits + +To help avoid abuse, by default, users are rate limited to: -To help avoid abuse, users are rate limited to: +| Request Type | Limit | +| ---------------- | ---------------------------------------- | +| Export | 6 projects per minute | +| Download export | 1 download per group per minute | +| Import | 6 projects per minute | -| Request Type | Limit | -| ---------------- | ----------------------------------------- | -| Export | 30 projects per 5 minutes | -| Download export | 10 downloads per project every 10 minutes | -| Import | 30 projects per 5 minutes | +Please note that GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) from the defaults. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 4b368fc20d6..41f404de4f2 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -1,13 +1,13 @@ --- 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/#designated-technical-writers" +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, index, howto --- # Project settings -NOTE: **Note:** +NOTE: Only project maintainers and administrators have the [permissions](../../permissions.md#project-members-permissions) to access a project settings. @@ -31,13 +31,13 @@ The project description also partially supports [standard Markdown](../../markdo You can select a framework label to identify that your project has certain compliance requirements or needs additional oversight. Available labels include: -- GDPR - General Data Protection Regulation -- HIPAA - Health Insurance Portability and Accountability Act -- PCI-DSS - Payment Card Industry-Data Security Standard -- SOC 2 - Service Organization Control 2 -- SOX - Sarbanes-Oxley +- GDPR (General Data Protection Regulation) +- HIPAA (Health Insurance Portability and Accountability Act) +- PCI-DSS (Payment Card Industry-Data Security Standard) +- SOC 2 (Service Organization Control 2) +- SOX (Sarbanes-Oxley) -NOTE: **Note:** +NOTE: Compliance framework labels do not affect your project settings. ### Sharing and permissions @@ -52,7 +52,7 @@ If you set **Project Visibility** to public, you can limit access to some featur to **Only Project Members**. In addition, you can select the option to [Allow users to request access](../members/index.md#project-membership-and-requesting-access). -CAUTION: **Caution:** +WARNING: If you [reduce a project's visibility level](../../../public_access/public_access.md#reducing-visibility), that action unlinks all forks of that project. @@ -68,11 +68,13 @@ Use the switches to enable or disable the following features: | **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) | | **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality | +| **Analytics** | ✓ | Enables [analytics](../../analytics/) | | **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/) | | **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md) | | **Pages** | ✓ | Allows you to [publish static websites](../pages/) | | **Metrics Dashboard** | ✓ | Control access to [metrics dashboard](../integrations/prometheus.md) -| **Requirements** | ✓ | Control access to [Requirements Management](../requirements/index.md) +| **Requirements** | ✓ | Control access to [Requirements Management](../requirements/index.md) | +| **Operations Dashboard** | ✓ | Control access to [operations dashboard](../../../operations/index.md) Some features depend on others: @@ -81,7 +83,7 @@ Some features depend on others: - **Issue Boards** - [**Service Desk**](#service-desk) - NOTE: **Note:** + NOTE: When the **Issues** option is disabled, you can still access **Milestones** from merge requests. @@ -186,7 +188,7 @@ Next, to unarchive the project: #### Renaming a repository -NOTE: **Note:** +NOTE: Only project maintainers and administrators have the [permissions](../../permissions.md#project-members-permissions) to rename a repository. Not to be confused with a project's name where it can also be changed from the [general project settings](#general-project-settings). @@ -198,8 +200,8 @@ To rename a repository: 1. Navigate to your project's **Settings > General**. 1. Under **Advanced**, click **Expand**. -1. Under "Rename repository", change the "Path" to your liking. -1. Hit **Rename project**. +1. Under **Change path**, update the repository's path. +1. Click **Change path**. 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 @@ -207,7 +209,7 @@ old URL won't be able to push or pull. Read more about what happens with the #### Transferring an existing project into another namespace -NOTE: **Note:** +NOTE: Only project owners and administrators have the [permissions](../../permissions.md#project-members-permissions) to transfer a project. @@ -229,13 +231,13 @@ 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). -NOTE: **Note:** +NOTE: GitLab administrators can use the administration interface to move any project to any namespace if needed. #### Delete a project -NOTE: **Note:** +NOTE: Only project owners and administrators have [permissions](../../permissions.md#project-members-permissions) to delete a project. To delete a project: @@ -253,7 +255,7 @@ 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). -CAUTION: **Warning:** +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. @@ -274,7 +276,7 @@ If you want to use the fork for yourself and don't need to send [merge requests](../merge_requests/index.md) to the upstream project, you can safely remove the fork relationship. -CAUTION: **Caution:** +WARNING: Once removed, the fork relationship cannot be restored. You will no longer be able to send merge requests to the source, and if anyone has forked your project, their fork will also lose the relationship. To do so: @@ -283,7 +285,7 @@ To do so: 1. Under **Remove fork relationship**, click the likewise-labeled button. 1. Confirm the action by typing the project's path as instructed. -NOTE: **Note:** +NOTE: Only project owners have the [permissions](../../permissions.md#project-members-permissions) to remove a fork relationship. diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 9f8cf2ff41a..494f0b725e3 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -1,20 +1,23 @@ --- stage: Manage group: Access -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- # Project access tokens -NOTE: **Note:** -Project access tokens are supported for self-managed instances on Core and above. They are also supported on GitLab.com Bronze and above. +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/)). > - [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. -> - [Became available on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/235765) in 13.5. > - 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. + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. Project access tokens are scoped to a project and can be used to authenticate with the [GitLab API](../../../api/README.md#personalproject-access-tokens). You can also use project access tokens with Git to authenticate over HTTP. @@ -69,9 +72,39 @@ the following table. | Scope | Description | | ------------------ | ----------- | -| `api` | Grants complete read/write access to the scoped project API. | -| `read_api` | Grants read access to the scoped project API. | +| `api` | Grants complete read/write access to the scoped project API, including the Package Registry](../../packages/package_registry/index.md). | +| `read_api` | Grants read access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | | `read_registry` | Allows read-access (pull) to [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | | `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). | | `read_repository` | Allows read-only access (pull) to the repository. | | `write_repository` | Allows read-write access (pull, push) to the repository. | + +### Enable or disable project access tokens + +Project access tokens 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 disable it for your instance, globally or by project. + +To disable it globally: + +```ruby +Feature.disable(:resource_access_token) +``` + +To disable it for a specific project: + +```ruby +Feature.disable(:resource_access_token, project) +``` + +To enable it globally: + +```ruby +Feature.enable(:resource_access_token) +``` + +To enable it for a specific project: + +```ruby +Feature.enable(:resource_access_token, project) +``` diff --git a/doc/user/project/slash_commands.md b/doc/user/project/slash_commands.md index 1280524bc9b..5844861c91e 100644 --- a/doc/user/project/slash_commands.md +++ b/doc/user/project/slash_commands.md @@ -3,3 +3,6 @@ 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 c2d4c77a469..07f122a7828 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -1,7 +1,7 @@ --- stage: Create -group: Static Site 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/#designated-technical-writers" +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 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." --- @@ -11,6 +11,7 @@ description: "The static site editor enables users to edit content on static web > - [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. +> - 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 prior knowledge of the underlying templating language, site architecture, or @@ -53,10 +54,16 @@ click of a button:  -When an editor submits their changes, in the background, GitLab automatically -creates a new branch, commits their changes, and opens a merge request. The -editor lands directly on the merge request, and then they can assign it to -a colleague for review. +When an editor submits their changes, these are the following actions that GitLab +performs automatically in the background: + +1. Creates a new branch. +1. Commits their changes. + 1. Fixes formatting according to the [Handbook Markdown Style Guide](https://about.gitlab.com/handbook/markdown-guide/) + style guide and add them through another commit. +1. Opens a merge request against the default branch. + +The editor can then navigate to the merge request to assign it to a colleague for review. ## Set up your project @@ -162,7 +169,7 @@ title, layout template, or author, but can be used to pass any kind of metadata 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. -To edit the front matter from the Static Site Editor you can use the GitLab's regular file editor, +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: 1. Click the **Page settings** button on the bottom-right to reveal a web form with the data you diff --git a/doc/user/project/status_page/index.md b/doc/user/project/status_page/index.md index 20bb23f1d6b..513c410a6f9 100644 --- a/doc/user/project/status_page/index.md +++ b/doc/user/project/status_page/index.md @@ -3,3 +3,6 @@ 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 b88e1ed2d37..c94795578ef 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -3,7 +3,7 @@ type: reference disqus_identifier: 'https://docs.gitlab.com/ee/workflow/time_tracking.html' 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/#designated-technical-writers +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 --- # Time Tracking @@ -49,7 +49,7 @@ you need to enter an estimate of 3 days, 5 hours and 10 minutes, you would write `/estimate 3d 5h 10m`. Time units that we support are listed at the bottom of this help page. -Every time you enter a new time estimate, any previous time estimates will be +Every time you enter a new time estimate, any previous time estimates are overridden by this new value. There should only be one valid estimate in an issue or a merge request. @@ -59,12 +59,12 @@ To remove an estimation entirely, use `/remove_estimate`. To enter a time spent, use `/spend 3d 5h 10m`. -Every new time spent entry will be added to the current total time spent for the +Every new time spent entry is added to the current total time spent for the issue or the merge request. -You can remove time by entering a negative amount: `/spend -3d` will remove 3 +You can remove time by entering a negative amount: for example, `/spend -3d` removes three days from the total time spent. You can't go below 0 minutes of time spent, -so GitLab will automatically reset the time spent if you remove a larger amount +so GitLab automatically resets the time spent if you remove a larger amount of time compared to the time that was entered already. To remove all the time spent at once, use `/remove_time_spent`. diff --git a/doc/user/project/web_ide/img/solarized_light_theme_v13_0.png b/doc/user/project/web_ide/img/solarized_light_theme_v13_0.png Binary files differindex b4b14f1fc7f..6257d78d29e 100644 --- a/doc/user/project/web_ide/img/solarized_light_theme_v13_0.png +++ b/doc/user/project/web_ide/img/solarized_light_theme_v13_0.png diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 2b9db1c952d..29b24028e48 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -1,7 +1,7 @@ --- stage: Create 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/#designated-technical-writers" +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 --- @@ -66,7 +66,7 @@ Monaco uses the [Monarch](https://microsoft.github.io/monaco-editor/monarch.html If you are missing Syntax Highlighting support for any language, we prepared a short guide on how to [add support for a missing language Syntax Highlighting.](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/ide/lib/languages/README.md) -NOTE: **Note:** +NOTE: Single file editing is based on the [Ace Editor](https://ace.c9.io). ### Themes @@ -262,8 +262,8 @@ quickly share your project with others. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/268288) in GitLab 12.9, third-party assets and libraries required for Live Preview are hosted at `https://sandbox-prod.gitlab-static.net` when it is enabled. However, some libraries are still served from other third-party services which may or may not be desirable in your environment. -The Live Preview feature needs to be enabled in the GitLab instances -admin settings. Live Preview is enabled for all projects on +The Live Preview feature needs to be enabled in the GitLab instance's +Admin Area. Live Preview is enabled for all projects on GitLab.com  @@ -286,9 +286,9 @@ below. > - [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. -CAUTION: **Warning:** +WARNING: Interactive Web Terminals for the Web IDE is currently in **Beta**. -Shared runners [do not yet support Interactive Web Terminals](https://gitlab.com/gitlab-org/gitlab/-/issues/24674), +GitLab.com shared runners [do not yet support Interactive Web Terminals](https://gitlab.com/gitlab-org/gitlab/-/issues/24674), so you would need to use your own private runner to make use of this feature. [Interactive Web Terminals](../../../ci/interactive_web_terminal/index.md) @@ -313,7 +313,7 @@ terminal blocks the job from finishing for the duration configured in [`[session_server].session_timeout`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section) until you close the terminal window. -NOTE: **Note:** +NOTE: Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart). The [File Sync](#file-syncing-to-web-terminal) feature is supported on Kubernetes runners only. @@ -394,7 +394,7 @@ 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 environment. -NOTE: **Note:** +NOTE: Only file changes in the Web IDE are synced to the terminal. Changes made in the terminal are **not** synced to the Web IDE. This feature is only available for Kubernetes runners. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index e082e091dec..7802f2ba95e 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -1,7 +1,7 @@ --- stage: Create group: Knowledge -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" +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 --- @@ -34,7 +34,7 @@ message. ## Creating a new wiki page -NOTE: **Note:** +NOTE: Requires Developer [permissions](../../permissions.md). Create a new page by clicking the **New page** button that can be found @@ -64,7 +64,7 @@ When you're ready, click the **Create page** and the new page will be created. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475) in GitLab 11.3. -Starting with GitLab 11.3, any file that is uploaded to the wiki via GitLab's +Starting with GitLab 11.3, any file that is uploaded to the wiki via the GitLab interface will be stored in the wiki Git repository, and it will be available if you clone the wiki repository locally. All uploaded files prior to GitLab 11.3 are stored in GitLab itself. If you want them to be part of the wiki's Git @@ -208,7 +208,7 @@ On the project's Wiki page, there is a right side navigation that renders the fu To customize the sidebar, you can create a file named `_sidebar` to fully replace the default navigation. -CAUTION: **Warning:** +WARNING: Unless you link the `_sidebar` file from your custom nav, to edit it you'll have to access it directly from the browser's address bar by typing: `https://gitlab.com/<namespace>/<project_name>/-/wikis/_sidebar` (for self-managed GitLab instances, replace `gitlab.com` with your instance's URL). @@ -226,4 +226,4 @@ Example for `_sidebar` (using Markdown format): - [Sidebar](_sidebar) ``` -Support for displaying a generated TOC with a custom side navigation is planned. +Support for displaying a generated table of contents with a custom side navigation is planned. diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index ea3ca7a28d7..16ff8538630 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Reserved project and group names diff --git a/doc/user/search/advanced_global_search.md b/doc/user/search/advanced_global_search.md index 3152229c39f..1898bdf06a9 100644 --- a/doc/user/search/advanced_global_search.md +++ b/doc/user/search/advanced_global_search.md @@ -1,7 +1,7 @@ --- stage: Enablement group: Global Search -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -9,7 +9,7 @@ type: reference > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109) in GitLab [Starter](https://about.gitlab.com/pricing/) 8.4. -NOTE: **GitLab.com availability:** +NOTE: Advanced Search (powered by Elasticsearch) is enabled for Bronze and above on GitLab.com since 2020-07-10. Leverage Elasticsearch for faster, more advanced code search across your entire @@ -43,11 +43,7 @@ The Advanced Search can be useful in various scenarios. ### Faster searches -If you are dealing with huge amount of data and want to keep GitLab's search -fast, Advanced Search will help you achieve that. - -NOTE: **Note:** -Between versions 12.10 and 13.4, Advanced Search response times have improved by 80%. +Advanced Search is based on Elasticsearch, which is a purpose built full text search engine that can be horizontally scaled so that it can provide search results in 1-2 seconds in most cases. ### Promote innersourcing @@ -66,7 +62,7 @@ project you have access to. You can also use the [Advanced Search Syntax](advanced_search_syntax.md) which provides some useful queries. -NOTE: **Note:** +NOTE: Elasticsearch has only data for the default branch. That means that if you go to the repository tree and switch the branch from the default to something else, then the "Code" tab in the search result page will be served by the basic diff --git a/doc/user/search/advanced_search_syntax.md b/doc/user/search/advanced_search_syntax.md index c1414fb9ebe..fe2371947b4 100644 --- a/doc/user/search/advanced_search_syntax.md +++ b/doc/user/search/advanced_search_syntax.md @@ -1,7 +1,7 @@ --- stage: Enablement group: Global Search -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference --- @@ -9,7 +9,7 @@ type: reference > - Introduced in [GitLab Enterprise Starter](https://about.gitlab.com/pricing/) 9.2 -NOTE: **GitLab.com availability:** +NOTE: Advanced Search (powered by Elasticsearch) is enabled for Bronze and above on GitLab.com since 2020-07-10. Use advanced queries for more targeted search results. @@ -25,19 +25,6 @@ want to have more specific search results. Advanced Search only supports searching the [default branch](../project/repository/branches/index.md#default-branch). -## Use cases - -Let's say for example that the product you develop relies on the code of another -product that's hosted under some other group. - -Since under your GitLab instance there are hosted hundreds of different projects, -you need the search results to be as efficient as possible. You have a feeling -of what you want to find (e.g., a function name), but at the same you're also -not so sure. - -In that case, using the advanced search syntax in your query will yield much -better results. - ## Using the Advanced Search Syntax The Advanced Search Syntax supports fuzzy or exact search queries with prefixes, @@ -93,3 +80,10 @@ Examples: - Finding `success` in all files excluding `.po|pot` files: [`success -filename:*.po*`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=success+-filename%3A*.po*&group_id=9970&project_id=278964) - Finding `import` excluding minified JavaScript (`.min.js`) files: [`import -extension:min.js`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=import+-extension%3Amin.js&group_id=9970&project_id=278964) - Finding `docs` for all files outside the `docs/` folder: [`docs -path:docs/`](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=blobs&repository_ref=&search=docs+-path%3Adocs%2F&group_id=9970&project_id=278964) + +### Search by issue or merge request ID + +You can search a specific issue or merge request by its ID with a special prefix. + +- To search by issue ID, use prefix `#` followed by issue ID. For example, [#23456](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=issues&repository_ref=&search=%2323456&group_id=9970&project_id=278964) +- To search by merge request ID, use prefix `!` followed by merge request ID. For example [!23456](https://gitlab.com/search?utf8=%E2%9C%93&snippets=&scope=merge_requests&repository_ref=&search=%2123456&group_id=9970&project_id=278964) diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 79c6cf3b07d..8c3d941192c 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -1,7 +1,7 @@ --- stage: Create 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/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: index, reference, howto --- diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index 6361aa856fe..282e3296735 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 disqus_identifier: 'https://docs.gitlab.com/ee/workflow/shortcuts.html' --- @@ -47,14 +47,14 @@ for example comments, replies, issue descriptions, and merge request description | <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 `[]()`). | -NOTE: **Note:** +NOTE: The shortcuts for editing in text fields are always enabled, even when other keyboard shortcuts are disabled as explained above. ## Project These shortcuts are available from any page within a project. You must type them -relatively quickly to work, and they will take you to another page in the project. +relatively quickly to work, and they take you to another page in the project. | Keyboard Shortcut | Description | | --------------------------- | ----------- | @@ -87,7 +87,7 @@ These shortcuts are available when viewing issues and merge requests. | <kbd>a</kbd> | Change assignee. | | <kbd>m</kbd> | Change milestone. | | <kbd>l</kbd> | Change label. | -| <kbd>r</kbd> | Start writing a comment. If any text is selected, it will be quoted in the comment. Can't be used to reply within a thread. | +| <kbd>r</kbd> | Start writing a comment. If any text is selected, it is quoted in the comment. Can't be used to reply within a thread. | | <kbd>n</kbd> | Move to next unresolved discussion (merge requests only). | | <kbd>p</kbd> | Move to previous unresolved discussion (merge requests only). | | <kbd>]</kbd> or <kbd>j</kbd> | Move to next file (merge requests only). | @@ -153,6 +153,6 @@ These shortcuts are available when viewing [Epics](group/epics/index.md): | Keyboard Shortcut | Description | | ----------------- | ----------- | -| <kbd>r</kbd> | Start writing a comment. If any text is selected, it will be quoted in the comment. Can't be used to reply within a thread. | +| <kbd>r</kbd> | Start writing a comment. If any text is selected, it is quoted in the comment. Can't be used to reply within a thread. | | <kbd>e</kbd> | Edit description. | | <kbd>l</kbd> | Change label. | diff --git a/doc/user/snippets.md b/doc/user/snippets.md index 2d0c9d4f943..33aa0bd253b 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -1,7 +1,7 @@ --- stage: Create 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/#designated-technical-writers" +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 --- @@ -52,7 +52,7 @@ part of the dropdown (**This project**). From there, add the **Title**, **Description**, and a **File** name with the appropriate extension (for example, `example.rb`, `index.html`). -CAUTION: **Warning:** +WARNING: Make sure to add the file name to get code highlighting and to avoid this [copy-pasting bug](https://gitlab.com/gitlab-org/gitlab/-/issues/22870). diff --git a/doc/user/todos.md b/doc/user/todos.md index 69c0736bdff..7d5a66a1632 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -2,7 +2,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/todos.html' 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/#designated-technical-writers +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)** @@ -62,7 +62,7 @@ item. To-do item triggers aren't affected by [GitLab notification email settings](profile/notifications.md). -NOTE: **Note:** +NOTE: When a user no longer has access to a resource related to a to-do item (such as an issue, merge request, epic, project, or group), for security reasons GitLab deletes any related to-do items within the next hour. Deletion is delayed to @@ -72,7 +72,7 @@ prevent data loss, in the case where a user's access is accidentally revoked. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7926) in GitLab 9.0. -If you're mentioned at the start of a line, the to-do item you receive will be +If you're mentioned at the start of a line, the to-do item you receive is listed as *directly addressed*. For example, in the following comment: ```markdown @@ -104,7 +104,7 @@ You can also add the following to your To-Do List by clicking the **Add a to do* ## Marking a to-do item as done -Any action to an issue or merge request (or epic **(ULTIMATE)**) will mark its +Any action to an issue or merge request (or epic **(PREMIUM)**) marks its corresponding to-do item as done. Actions that dismiss to-do items include: diff --git a/doc/user/upgrade_email_bypass.md b/doc/user/upgrade_email_bypass.md index 97d4b5e6a0a..e50b6959a70 100644 --- a/doc/user/upgrade_email_bypass.md +++ b/doc/user/upgrade_email_bypass.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +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 --- # Updating to GitLab 13.2: Email confirmation issues @@ -27,7 +27,7 @@ sent within five minutes, with a link for users to re-confirm the subject email ## Do the confirmation emails expire? -The links in these re-confirmation emails expire after one day by default. Users who click an expired link will be asked to request a new re-confirmation email. Any user can request a new re-confirmation email from `http://gitlab.example.com/users/confirmation/new`. +The links in these re-confirmation emails expire after one day by default. Users who click an expired link are asked to request a new re-confirmation email. Any user can request a new re-confirmation email from `http://gitlab.example.com/users/confirmation/new`. ## Generate a list of affected users @@ -60,7 +60,7 @@ User.where(confirmed_at: nil).where('LENGTH(confirmation_token) = 32') A regular user might receive a message that says "You have to confirm your email address before continuing". This message could includes a 404 or 422 error code, when the user tries to sign in. -NOTE: **Note:** +NOTE: We hope to improve the [sign-in experience for an unverified user](https://gitlab.com/gitlab-org/gitlab/-/issues/29279) in a future release. When an affected user commits code to a Git repository, that user may see the following message: @@ -107,21 +107,21 @@ Once connected, run the following commands to confirm all user accounts: User.where('LENGTH(confirmation_token) = 32').where(confirmed_at: nil).find_each { |u| u.confirmed_at = Time.now; u.save } ``` -CAUTION: **Caution:** +WARNING: The command described in this section may activate users who have not properly confirmed their email addresses. ## What about LDAP users? -LDAP Users will remain confirmed if all of the following conditions are met: +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. -NOTE: **Note:** -Confirmation timestamps (primary vs. secondary) will be different. +NOTE: +Confirmation timestamps (primary vs. secondary) are different. -Users will be unconfirmed by the background migration if any of the following conditions are met: +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. diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md new file mode 100644 index 00000000000..5f637c8d5cb --- /dev/null +++ b/doc/user/usage_quotas.md @@ -0,0 +1,94 @@ +--- +type: howto +stage: Fulfillment +group: Provision +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#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. +> - Moved to GitLab Free. + +A project's repository has a free storage quota of 10 GB. When a project's repository reaches +the quota it is locked. You cannot push changes to a locked project. To monitor the size of each +repository in a namespace, including a breakdown for each project, you can +[view storage usage](#view-storage-usage). To allow a project's repository to exceed the free quota +you must purchase additional storage. For more details, see [Excess storage usage](#excess-storage-usage). + +## View storage usage + +To help manage storage, a namespace's owner can view: + +- Total storage used in the namespace +- Total storage used per project +- Breakdown of storage use per project, by storage type. + +To view storage usage, from the namespace's page go to **Settings > Usage Quotas** and select the +**Storage** tab. The Usage Quotas statistics are updated every 90 minutes. + +If your namespace shows `N/A` as the total storage usage, push a commit to any project in that +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)** + +> - [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 recommended for production use. + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +The following storage usage statistics are available to an owner: + +- Total namespace storage used: Total amount of storage used across projects in this namespace. +- Total excess storage used: Total amount of storage used that exceeds their allocated storage. +- Purchased storage available: Total storage that has been purchased but is not yet used. + +## Excess storage usage + +Excess storage usage is the amount that a project's repository exceeds the free storage quota. If no +purchased storage is available the project is locked. You cannot push changes to a locked project. +To unlock a project you must [purchase more storage](../subscriptions/gitlab_com/index.md#purchase-more-storage) +for the namespace. When the purchase is completed, locked projects are automatically unlocked. The +amount of purchased storage available must always be greater than zero. + +The **Storage** tab of the **Usage Quotas** page warns you of the following: + +- Purchased storage available is running low. +- Projects that are at risk of being locked if purchased storage available is zero. +- Projects that are locked because purchased storage available is zero. Locked projects are + marked with an information icon (**{information-o}**) beside their name. + +### Excess storage example + +The following example describes an excess storage scenario for namespace _Example Company_: + +| Repository | Storage used | Excess storage | Quota | Status | +|------------|--------------|----------------|--------|-------------------| +| Red | 10 GB | 0 GB | 10 GB | Locked **{lock}** | +| Blue | 8 GB | 0 GB | 10 GB | Not locked | +| Green | 10 GB | 0 GB | 10 GB | Locked **{lock}** | +| Yellow | 2 GB | 0 GB | 10 GB | Not locked | +| **Totals** | **30 GB** | **0 GB** | - | - | + +The Red and Green projects are locked because their repositories have reached the quota. In this +example, no additional storage has yet been purchased. + +To unlock the Red and Green projects, 50 GB additional storage is purchased. + +Assuming the Green and Red projects' repositories grow past the 10 GB quota, the purchased storage +available decreases. All projects remain unlocked because 40 GB purchased storage is available: +50 GB (purchased storage) - 10 GB (total excess storage used). + +| Repository | Storage used | Excess storage | Quota | Status | +|------------|--------------|----------------|---------|-------------------| +| Red | 15 GB | 5 GB | 10 GB | Not locked | +| Blue | 14 GB | 4 GB | 10 GB | Not locked | +| Green | 11 GB | 1 GB | 10 GB | Not locked | +| Yellow | 5 GB | 0 GB | 10 GB | Not locked | +| **Totals** | **45 GB** | **10 GB** | - | - | |
