diff options
Diffstat (limited to 'doc/user')
329 files changed, 4444 insertions, 2458 deletions
diff --git a/doc/user/abuse_reports.md b/doc/user/abuse_reports.md index e6c86cc8f2e..155f45f087f 100644 --- a/doc/user/abuse_reports.md +++ b/doc/user/abuse_reports.md @@ -1,3 +1,9 @@ +--- +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 +--- + # Abuse reports You can report abuse from other GitLab users to GitLab administrators. diff --git a/doc/user/admin_area/activating_deactivating_users.md b/doc/user/admin_area/activating_deactivating_users.md index 8b3a7682841..96b39ae7116 100644 --- a/doc/user/admin_area/activating_deactivating_users.md +++ b/doc/user/admin_area/activating_deactivating_users.md @@ -44,7 +44,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:** -A deactivated user does not consume a [seat](../../subscriptions/self_managed/index.md#choose-the-number-of-users). +A deactivated user does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). ## Activating a user @@ -62,8 +62,8 @@ To do this: Users can also be activated using the [GitLab API](../../api/users.md#activate-user). NOTE: **Note:** -Activating a user will change the user's state to active and it consumes a -[seat](../../subscriptions/self_managed/index.md#choose-the-number-of-users). +Activating a user changes the user's state to active and consumes a +[seat](../../subscriptions/self_managed/index.md#billable-users). TIP: **Tip:** 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/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index f04bd69b76b..d1f80e63c04 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -1,4 +1,10 @@ -# DevOps Report +--- +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 +--- + +# DevOps Report **(CORE)** > - [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. @@ -10,6 +16,8 @@ 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 displays the usage of GitLab's major features on your instance over diff --git a/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6.png b/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6.png Binary files differnew file mode 100644 index 00000000000..da9e4c64e12 --- /dev/null +++ b/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6.png diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md index f79245c7325..792d0245290 100644 --- a/doc/user/admin_area/analytics/index.md +++ b/doc/user/admin_area/analytics/index.md @@ -1,3 +1,9 @@ +--- +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 +--- + # Instance-level analytics > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41416) in GitLab 11.2. @@ -6,6 +12,6 @@ Administrators have access to instance-wide analytics, as shown in **Admin Area There are several kinds of statistics: -- [DevOps Report](dev_ops_report.md): Provides an overview of your entire instance's feature usage. -- [Instance Statistics](instance_statistics.md): Shows how much data your instance contains, and how that is changing. -- [User Cohorts](user_cohorts.md): Display the monthly cohorts of new users and their activities over time. +- [DevOps Report](dev_ops_report.md): Provides an overview of your entire instance's feature usage. **(CORE)** +- [Instance Statistics](instance_statistics.md): Shows how much data your instance contains, and how that is changing. **(CORE)** +- [User Cohorts](user_cohorts.md): Display the monthly cohorts of new users and their activities over time. **(CORE)** diff --git a/doc/user/admin_area/analytics/instance_statistics.md b/doc/user/admin_area/analytics/instance_statistics.md index bac0e845d2c..0d62d30435d 100644 --- a/doc/user/admin_area/analytics/instance_statistics.md +++ b/doc/user/admin_area/analytics/instance_statistics.md @@ -1,9 +1,23 @@ -# Instance Statistics +--- +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 +--- -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235754) in GitLab 13.4. +# Instance Statistics **(CORE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235754) in GitLab 13.5 behind a feature flag, disabled by default. +> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46962) in GitLab 13.6. +> - It's enabled on GitLab.com. +> - It's recommended for production use. + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. Instance Statistics gives you an overview of how much data your instance contains, and how quickly this volume is changing over time. +To see Instance Statistics, go to **Admin Area > Analytics > Instance Statistics**. + ## Total counts At the top of the page, Instance Statistics shows total counts for: @@ -16,3 +30,31 @@ At the top of the page, Instance Statistics shows total counts for: - Pipelines These figures can be useful for understanding how much data your instance contains in total. + +## Past year trend charts + +Instance Statistics also displays line charts that show total counts per month, over the past 12 months, +in the categories shown in [Total counts](#total-counts). + +These charts help you visualize how rapidly these records are being created on your instance. + + + +### Enable or disable Instance Statistics + +In GitLab version 13.5 only, Instance Statistics was under development and not ready for production use. +It was deployed behind a feature flag that was **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to enable it. + +To enable it: + +```ruby +Feature.enable(:instance_statistics) +``` + +To disable it: + +```ruby +Feature.disable(:instance_statistics) +``` diff --git a/doc/user/admin_area/analytics/user_cohorts.md b/doc/user/admin_area/analytics/user_cohorts.md index faf8caa7e00..c9b62e258ae 100644 --- a/doc/user/admin_area/analytics/user_cohorts.md +++ b/doc/user/admin_area/analytics/user_cohorts.md @@ -1,10 +1,18 @@ -# Cohorts +--- +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 +--- + +# Cohorts **(CORE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/23361) in GitLab 9.1. As a benefit of having the [usage ping active](../settings/usage_statistics.md), GitLab lets you analyze the users' activities over time of your GitLab installation. +To see User Cohorts, go to **Admin Area > Analytics > Cohorts**. + ## Overview How do we read the user cohorts table? Let's take an example with the following diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index 55dabce7342..23a6de38e17 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -1,4 +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 type: howto disqus_identifier: 'https://docs.gitlab.com/ee/customization/branded_login_page.html' --- @@ -76,7 +79,7 @@ to activate it in the GitLab instance. You can also click on the **Sign-in page* to review the saved appearance settings: NOTE: **Note:** -You can add also add a [customized help message](settings/help_page.md) below the sign in message. +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 diff --git a/doc/user/admin_area/approving_users.md b/doc/user/admin_area/approving_users.md index 486d0b6a25d..430ad4f8899 100644 --- a/doc/user/admin_area/approving_users.md +++ b/doc/user/admin_area/approving_users.md @@ -9,7 +9,7 @@ type: howto > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4491) in GitLab 13.5. -When [Require admin approval for new sign-ups](settings/sign_up_restrictions.md#require-admin-approval-for-new-sign-ups) is enabled, any user that signs up for an account using the registration form is placed under a **Pending approval** state. +When [Require admin approval for new sign-ups](settings/sign_up_restrictions.md#require-administrator-approval-for-new-sign-ups) is enabled, any user that signs up for an account using the registration form is placed under a **Pending approval** state. A user pending approval is functionally identical to a [blocked](blocking_unblocking_users.md) user. @@ -18,7 +18,7 @@ A user pending approval: - Will not be able to sign in. - Cannot access Git repositories or the API. - Will not receive any notifications from GitLab. -- Does not consume a [seat](../../subscriptions/self_managed/index.md#choose-the-number-of-users). +- Does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). ## Approving a user @@ -33,4 +33,4 @@ Approving a user: 1. Activates their account. 1. Changes the user's state to active and it consumes a -[seat](../../subscriptions/self_managed/index.md#choose-the-number-of-users). +[seat](../../subscriptions/self_managed/index.md#billable-users). diff --git a/doc/user/admin_area/blocking_unblocking_users.md b/doc/user/admin_area/blocking_unblocking_users.md index d8dde317d38..989182db423 100644 --- a/doc/user/admin_area/blocking_unblocking_users.md +++ b/doc/user/admin_area/blocking_unblocking_users.md @@ -23,17 +23,17 @@ or directly from the Admin Area. To do this: A blocked user: -- Will not be able to login. +- Cannot log in. - Cannot access Git repositories or the API. -- Will not receive any notifications from GitLab. -- Will not be able to use [slash commands](../../integration/slash_commands.md). +- Does not receive any notifications from GitLab. +- Cannot use [slash commands](../../integration/slash_commands.md). -Personal projects, and group and user history of the blocked user will be left intact. +Personal projects, and group and user history of the blocked user are left intact. Users can also be blocked using the [GitLab API](../../api/users.md#block-user). NOTE: **Note:** -A blocked user does not consume a [seat](../../subscriptions/self_managed/index.md#choose-the-number-of-users). +A blocked user does not consume a [seat](../../subscriptions/self_managed/index.md#billable-users). ## Unblocking a user @@ -47,5 +47,5 @@ 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:** -Unblocking a user will change the user's state to active and it consumes a -[seat](../../subscriptions/self_managed/index.md#choose-the-number-of-users). +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 7e1a4faee75..0bbdf5bc5e7 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -1,4 +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 type: reference, howto --- @@ -62,12 +65,17 @@ To add a broadcast message: 1. Navigate to the **Admin Area > Messages** page. 1. Add the text for the message to the **Message** field. Markdown and emoji are supported. -1. If required, click the **Customize colors** link to edit the background color and font color of the message. +1. Select one of the suggested background colors, or add the hex code of a different color. The default color is orange. 1. If required, add a **Target Path** to only show the broadcast message on URLs matching that path. You can use the wildcard character `*` to match multiple URLs, for example `/users/*/issues`. 1. Select a date for the message to start and end. 1. Click the **Add broadcast message** button. 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:** 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. diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index b17d0ab3dd5..fc04f9786b6 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -40,10 +40,13 @@ If you see a **Revoke** button, you can revoke that user's PAT. Whether you see | Revoked | Yes | No | Not applicable; token is already revoked | | Revoked | No | No | Not applicable; token is already revoked | +When a PAT is revoked from the credentials inventory, the instance notifies the user by email. + ## Delete a user's SSH key > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225248) in GitLab 13.5. You can **Delete** a user's SSH key by navigating to the credentials inventory's SSH Keys tab. +The instance then notifies the user.  diff --git a/doc/user/admin_area/img/appearance_sign_in_preview_v12_3.png b/doc/user/admin_area/img/appearance_sign_in_preview_v12_3.png Binary files differindex 59c190393d1..d05bda71545 100644 --- a/doc/user/admin_area/img/appearance_sign_in_preview_v12_3.png +++ b/doc/user/admin_area/img/appearance_sign_in_preview_v12_3.png diff --git a/doc/user/admin_area/img/appearance_sign_in_v12_3.png b/doc/user/admin_area/img/appearance_sign_in_v12_3.png Binary files differindex 7e2337bbae8..0caa29aae2c 100644 --- a/doc/user/admin_area/img/appearance_sign_in_v12_3.png +++ b/doc/user/admin_area/img/appearance_sign_in_v12_3.png diff --git a/doc/user/admin_area/img/mr_approval_settings_compliance_project_v13_1.png b/doc/user/admin_area/img/mr_approval_settings_compliance_project_v13_1.png Binary files differdeleted file mode 100644 index 04d01f2662f..00000000000 --- a/doc/user/admin_area/img/mr_approval_settings_compliance_project_v13_1.png +++ /dev/null diff --git a/doc/user/admin_area/img/scope_mr_approval_settings_v13_1.png b/doc/user/admin_area/img/scope_mr_approval_settings_v13_1.png Binary files differdeleted file mode 100644 index fe85d567a57..00000000000 --- a/doc/user/admin_area/img/scope_mr_approval_settings_v13_1.png +++ /dev/null diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 0ddbe17580a..fd8c72ad081 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -1,4 +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 type: reference --- @@ -143,22 +146,16 @@ you must provide the complete email address. #### Users statistics -The **Users statistics** page provides an overview of user accounts by role, such as _Users with -highest role Maintainer_. +The **Users statistics** page provides an overview of user accounts by role. These statistics are +calculated daily, so user changes made since the last update are not reflected. The following totals are also included: -- Active users +- Billable users - Blocked users - Total users -GitLab billing is based on the number of **Active users**, calculated as **Total users** - -**Blocked users**. For details of active users, see -[Choosing the number of users](../../subscriptions/self_managed/index.md#choose-the-number-of-users). - -NOTE: **Note:** -Users statistics are calculated daily, so user changes made since the last update won't be -reflected in the statistics. +GitLab billing is based on the number of [**Billable users**](../../subscriptions/self_managed/index.md#billable-users). ### Administering Groups diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index c37a61d6748..2b0496b381a 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -8,14 +8,22 @@ type: howto # Activate GitLab EE with a license **(STARTER ONLY)** To activate all GitLab Enterprise Edition (EE) functionality, you need to upload -a license. After you've received your license from GitLab Inc., you can upload it -by **signing into your GitLab instance as an admin** or adding it at -installation time. +a license. It's only possible to activate GitLab Enterprise Edition, so first verify which edition +you are running. To verify, sign in to GitLab and browse to `/help`. The GitLab edition and version +are listed at the top of the **Help** page. + +If you are running GitLab Community Edition (CE), upgrade your installation to +GitLab Enterprise Edition (EE). For more details, see [Upgrading between editions](../../update/README.md#upgrading-between-editions). +If you have questions or need assistance upgrading from GitLab CE to EE please [contact GitLab Support](https://about.gitlab.com/support/#contact-support). The license is a base64-encoded ASCII text file with a `.gitlab-license` extension. You can obtain the file by [purchasing a license](https://about.gitlab.com/pricing/) or by signing up for a [free trial](https://about.gitlab.com/free-trial/). +After you've received your license from GitLab Inc., you can upload it +by **signing into your GitLab instance as an admin** or adding it at +installation time. + As of GitLab Enterprise Edition 9.4.0, a newly-installed instance without an uploaded license only has the Core features active. A trial license activates all Ultimate features, but after @@ -108,8 +116,9 @@ To remove a license from a self-managed instance: ## License history -You can upload and view more than one license, -but only the latest license is used as the active license. +You can upload and view more than one license, but only the latest license in the current date +range is used as the active license. When you upload a future-dated license, it +doesn't take effect until its applicable date. ## Troubleshooting diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 2a38ccb31f0..88c98248435 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -1,4 +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 type: concepts, howto --- 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 957f84206e9..97c74483cc3 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -18,6 +18,12 @@ 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. +## Max push size + +You can change the maximum push size for your repository. +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 push size (MB)`. + ## Max import size You can change the maximum file size for imports in GitLab. @@ -76,12 +82,13 @@ and **will** be rejected if the sum of their sizes exceeds the maximum allowed repository size. NOTE: **Note:** -The repository size limit includes repository files and LFS, and does not include artifacts. +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:** -GitLab.com repository size [is set by GitLab](../../gitlab_com/index.md#account-and-limit-settings). +For GitLab.com repository size limits, see [accounts and limit settings](../../gitlab_com/index.md#account-and-limit-settings). ## Troubleshooting diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 0b250e07412..80bca6f5b2c 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -1,4 +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 type: reference --- diff --git a/doc/user/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md index ca983edd4fa..c0237c3da73 100644 --- a/doc/user/admin_area/settings/help_page.md +++ b/doc/user/admin_area/settings/help_page.md @@ -1,4 +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 type: howto --- diff --git a/doc/user/admin_area/settings/img/custom_sign_in_page_v13_6.png b/doc/user/admin_area/settings/img/custom_sign_in_page_v13_6.png Binary files differnew file mode 100644 index 00000000000..5eb2134187a --- /dev/null +++ b/doc/user/admin_area/settings/img/custom_sign_in_page_v13_6.png diff --git a/doc/user/admin_area/settings/img/disable_signup_v12_7.png b/doc/user/admin_area/settings/img/disable_signup_v12_7.png Binary files differdeleted file mode 100644 index be1a070a804..00000000000 --- a/doc/user/admin_area/settings/img/disable_signup_v12_7.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/respond_to_terms.png b/doc/user/admin_area/settings/img/respond_to_terms.png Binary files differindex d0d086c3498..f91480d1ce7 100644 --- a/doc/user/admin_area/settings/img/respond_to_terms.png +++ b/doc/user/admin_area/settings/img/respond_to_terms.png diff --git a/doc/user/admin_area/settings/img/sign_up_restrictions_v13_5.png b/doc/user/admin_area/settings/img/sign_up_restrictions_v13_5.png Binary files differdeleted file mode 100644 index ebbfad77e69..00000000000 --- a/doc/user/admin_area/settings/img/sign_up_restrictions_v13_5.png +++ /dev/null diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index bc8df63e33f..21d495de5b7 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -1,4 +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 type: index --- @@ -20,7 +23,7 @@ Access the default page for admin area settings by navigating to **Admin Area > | [Account and limit](account_and_limit_settings.md) **(STARTER)** | Set projects and maximum size limits, session duration, user options, and check feature availability for namespace plan. | | [Diff limits](../diff_limits.md) | Diff content limits. | | [Sign-up restrictions](sign_up_restrictions.md) | Configure the way a user creates a new account. | -| [Sign in restrictions](sign_in_restrictions.md) | Set requirements for a user to sign-in. Enable mandatory two-factor authentication. | +| [Sign in restrictions](sign_in_restrictions.md) | Set requirements for a user to sign in. Enable mandatory two-factor authentication. | | [Terms of Service and Privacy Policy](terms.md) | Include a Terms of Service agreement and Privacy Policy that all users must accept. | | [External Authentication](external_authorization.md#configuration) | External Classification Policy Authorization | | [Web terminal](../../../administration/integration/terminal.md#limiting-websocket-connection-time) | Set max session time for web terminal. | diff --git a/doc/user/admin_area/settings/project_integration_management.md b/doc/user/admin_area/settings/project_integration_management.md index 748d608676d..c09bb6f3c67 100644 --- a/doc/user/admin_area/settings/project_integration_management.md +++ b/doc/user/admin_area/settings/project_integration_management.md @@ -8,51 +8,87 @@ info: To determine the technical writer assigned to the Stage/Group associated w Project integrations can be configured and enabled by project administrators. As a GitLab instance administrator, you can set default configuration parameters for a given integration that all projects -can inherit and use. This enables the integration for all projects that are not already using custom +can inherit and use, enabling the integration for all projects that are not already using custom settings. You can update these default settings at any time, changing the settings used for all projects that -are set to use instance-level defaults. Updating the default settings also enables the integration +are set to use instance-level or group-level defaults. Updating the default settings also enables the integration for all projects that didn't have it already enabled. -Only the complete settings for an integration can be inherited. Per-field inheritance is -[planned](https://gitlab.com/groups/gitlab-org/-/epics/2137) as is -[group-level management](https://gitlab.com/groups/gitlab-org/-/epics/2543) of integration settings. +Only the complete settings for an integration can be inherited. Per-field inheritance is [planned](https://gitlab.com/groups/gitlab-org/-/epics/2137). ## Manage instance-level default settings for a project integration **(CORE ONLY)** -> [Introduced in](https://gitlab.com/groups/gitlab-org/-/epics/2137) GitLab 13.3. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2137) in GitLab 13.3 for project-level integrations. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2543) in GitLab 13.6 for group-level integrations. 1. Navigate to **Admin Area > Settings > Integrations**. -1. Select a project integration. +1. Select an integration. 1. Enter configuration details and click **Save changes**. CAUTION: **Caution:** -This may affect all or most of the projects on your GitLab instance. Please review the details +This may affect all or most of the groups and projects on your GitLab instance. Please review the details below. If this is the first time you are setting up instance-level settings for an integration: -- The integration is enabled for all projects that don't already have this integration configured, +- The integration is enabled for all groups and projects that don't already have this integration configured, if you have the **Enable integration** toggle turned on in the instance-level settings. -- Projects that already have the integration configured are not affected, but can choose to use the +- Groups and projects that already have the integration configured are not affected, but can choose to use the inherited settings at any time. When you make further changes to the instance defaults: -- They are immediately applied to all projects that have the integration set to use default settings. -- They are immediately applied to newer projects, created since you last saved defaults for the +- They are immediately applied to all groups and projects that have the integration set to use default settings. +- They are immediately applied to newer groups and projects, created since you last saved defaults for the integration. If your instance-level default setting has the **Enable integration** toggle turned - on, the integration is automatically enabled for all such projects. -- Projects with custom settings selected for the integration are not immediately affected and may + on, the integration is automatically enabled for all such groups and projects. +- Groups and projects with custom settings selected for the integration are not immediately affected and may choose to use the latest defaults at any time. Only the complete settings for an integration can be inherited. Per-field inheritance is [planned](https://gitlab.com/groups/gitlab-org/-/epics/2137). This would allow -administrators to update settings inherited by projects without enabling the -integration on all non-configured projects by default. +administrators to update settings inherited by groups and projects without enabling the +integration on all non-configured groups and projects by default. -## Use instance-level default settings for a project integration +## Manage group-level default settings for a project integration + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2543) in GitLab 13.6. + +1. Navigate to the group's **Settings > Integrations**. +1. Select an integration. +1. Enter configuration details and click **Save changes**. + +CAUTION: **Caution:** +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: + +- The integration is enabled for all subgroups and projects belonging to the group that don't already have + this integration configured, if you have the **Enable integration** toggle turned on in the group-level + settings. +- Subgroups and projects that already have the integration configured are not affected, but can choose to use + the inherited settings at any time. + +When you make further changes to the group defaults: + +- They are immediately applied to all subgroups and projects belonging to the group that have the integration + set to use default settings. +- They are immediately applied to newer subgroups and projects, created since you last saved defaults for the + integration. If your group-level default setting has the **Enable integration** toggle turned on, + the integration is automatically enabled for all such subgroups and projects. + +- Subgroups and projects with custom settings selected for the integration are not immediately affected and + may choose to use the latest defaults at any time. + +Only the complete settings for an integration can be inherited. Per-field inheritance +is [planned](https://gitlab.com/groups/gitlab-org/-/epics/2137). This would allow +administrators to update settings inherited by subgroups and projects without enabling the +integration on all non-configured groups and projects by default. + +## Use instance-level or group-level default settings for a project integration + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2543) in GitLab 13.6 for group-level settings. 1. Navigate to **Project > Settings > Integrations**. 1. Choose the integration you want to enable or update. @@ -60,9 +96,9 @@ integration on all non-configured projects by default. 1. Ensure the toggle is set to **Enable integration**. 1. Click **Save changes**. -## Use custom settings for a project integration +## Use custom settings for a group or project integration -1. Navigate to project's **Settings > Integrations**. +1. Navigate to project or group's **Settings > Integrations**. 1. Choose the integration you want to enable or update. 1. From the drop-down, select **Use custom settings**. 1. Ensure the toggle is set to **Enable integration** and enter all required settings. diff --git a/doc/user/admin_area/settings/protected_paths.md b/doc/user/admin_area/settings/protected_paths.md index 0cfaf5843d0..bb6fff9650d 100644 --- a/doc/user/admin_area/settings/protected_paths.md +++ b/doc/user/admin_area/settings/protected_paths.md @@ -1,4 +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 type: reference --- 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 45dcc9119ac..96cd71033d0 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,4 +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 type: reference --- diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 311b79af7e3..7ab1d396e8b 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -1,4 +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 type: reference --- @@ -47,8 +50,21 @@ All users that are not logged-in will be redirected to the page represented by t All users will be redirect to the page represented by the configured "After sign out path" after sign out if value is not empty. -If a "Sign in text" in Markdown format is provided, then every user will be presented with -this message after logging-in. +In the Sign-in restrictions section, scroll to the "Sign-in text" text box. 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: + +```markdown +# Custom sign-in text + +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 +GitLab instance: + + <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index f57cf7c2045..5ea034ff4d2 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -1,52 +1,75 @@ --- +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 type: reference --- # Sign-up restrictions **(CORE ONLY)** -You can use sign-up restrictions to: +You can enforce the following restrictions on sign ups: -- Disable new sign-ups. -- Require admin approval for new sign-ups. +- Disable new sign ups. +- Require administrator approval for new sign ups. - Require user email confirmation. -- Denylist or allowlist email addresses belonging to specific domains. +- Allow or deny sign ups using specific email domains. -NOTE: **Note:** -These restrictions are only applied during sign-up from an external user. An admin can add a user through the admin panel with a disallowed domain. Also, note that the users can change their email addresses after sign-up to -disallowed domains. +## Disable new sign ups -## Disable new signups +By default, any user visiting your GitLab domain can sign up for an account. For customers running +public-facing GitLab instances, we **highly** recommend that you consider disabling new sign ups if +you do not expect public users to sign up for an account. -When this setting is enabled, any user visiting your GitLab domain will be able to sign up for an account. +To disable sign ups: - +1. Go to **Admin Area > Settings > General** and expand **Sign-up restrictions**. +1. Clear the **Sign-up enabled** checkbox, then select **Save changes**. -You can restrict new users from signing up by themselves for an account in your instance by disabling this setting. +## Require administrator approval for new sign ups -### Recommendations +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4491) in GitLab 13.5. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/267568) in GitLab 13.6. -For customers running public-facing GitLab instances, we highly recommend that you -consider disabling new sign-ups if you do not expect public users to sign up for an -account. +When this setting is enabled, any user visiting your GitLab domain and signing up for a new account must be explicitly [approved](../approving_users.md#approving-a-user) by an administrator before they can start using their account. This setting is enabled by default for newly created instances. This setting is only applicable if sign ups are enabled. -Alternatively, you could also consider setting up a -[allowlist](#allowlist-email-domains) or [denylist](#denylist-email-domains) on -email domains to prevent malicious users from creating accounts. +To require administrator approval for new sign ups: -## Require admin approval for new sign-ups +1. Go to **Admin Area > Settings > General** and expand **Sign-up restrictions**. +1. Select the **Require admin approval for new sign-ups** checkbox, then select **Save changes**. -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4491) in GitLab 13.5. +## Require email confirmation -When this setting is enabled, any user visiting your GitLab domain and signing up for a new account will have to be explicitly [approved](../approving_users.md#approving-a-user) by an administrator before they can start using their account. +You can send confirmation emails during sign up and require that users confirm +their email address before they are allowed to sign in. - +To enforce confirmation of the email address used for new sign ups: -## Require email confirmation +1. Go to **Admin Area > Settings > General** and expand **Sign-up restrictions**. +1. Select the **Enable email restrictions for sign ups** checkbox, then select **Save changes**. -You can send confirmation emails during sign-up and require that users confirm -their email address before they are allowed to sign in. +## User cap **(CORE ONLY)** + +> [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 +[approved](../approving_users.md#approving-a-user) by an administrator before they can start using +their account. + +## Soft email confirmation + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47003) in GitLab 12.2. +> - It's [deployed behind a feature flag](../../..//user/feature_flags.md), disabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-soft-email-confirmation). + +CAUTION: **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 +them to sign in without an immediate confirmation when an email confirmation is required. +GitLab shows the user a reminder to confirm their email address, and the user can't +create or update pipelines until their email address is confirmed. ## Minimum password length limit @@ -55,40 +78,61 @@ their email address before they are allowed to sign in. You can [change](../../../security/password_length_limits.md#modify-minimum-password-length-using-gitlab-ui) the minimum number of characters a user must have in their password using the GitLab UI. -## Allowlist email domains +## Allow or deny sign ups using specific email domains + +You can specify an inclusive or exclusive list of email domains which can be used for user sign up. + +These restrictions are only applied during sign up from an external user. An administrator can add a +user through the admin panel with a disallowed domain. Also, note that the users can change their +email addresses to disallowed domains after sign up. + +### Allowlist email domains > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/598) in GitLab 7.11.0 You can restrict users only to sign up using email addresses matching the given domains list. -## Denylist email domains +### Denylist email domains > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5259) in GitLab 8.10. -With this feature enabled, you can block email addresses of a specific domain -from creating an account on your GitLab server. This is particularly useful -to prevent malicious users from creating spam accounts with disposable email -addresses. - -## Settings +You can block users from signing up when using an email addresses of specific domains. This can +reduce the risk of malicious users creating spam accounts with disposable email addresses. -To access this feature: +### Create email domain allowlist or denylist -1. Navigate to the **Admin Area > Settings > General**. -1. Expand the **Sign-up restrictions** section. +To create an email domain allowlist or denylist: -For the denylist, you can enter the list manually or upload a `.txt` file that -contains list entries. +1. Go to **Admin Area > Settings > General** and expand **Sign-up restrictions**. +1. For the allowlist, you must enter the list manually. For the denylist, you can enter the list + manually or upload a `.txt` file that contains list entries. -For the allowlist, you must enter the list manually. - -Both the allowlist and denylist accept wildcards. For example, you can use + Both the allowlist and denylist accept wildcards. For example, you can use `*.company.com` to accept every `company.com` subdomain, or `*.io` to block all -domains ending in `.io`. Domains should be separated by a whitespace, +domains ending in `.io`. Domains must be separated by a whitespace, semicolon, comma, or a new line. - +  + +### Enable or disable soft email confirmation + +Soft email confirmation 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 disable it. + +To enable it: + +```ruby +Feature.enable(:soft_email_confirmation) +``` + +To disable it: + +```ruby +Feature.disable(:soft_email_confirmation) +``` <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index 77c172aa927..95c32af5716 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -1,4 +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 type: reference --- diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index 29ca3bf5ab2..f0e53115cb1 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.md @@ -1,4 +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 type: reference --- diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 140d149555a..d4080b3921a 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -1,4 +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 type: reference --- 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 5d49d88d254..af3e0c5b63b 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,4 +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 type: reference --- @@ -19,6 +22,43 @@ These limits are disabled by default.  +## Use an HTTP header to bypass rate limiting + +> [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/622) in GitLab 13.6. + +Depending on the needs of your organization, you may want to enable rate limiting +but have some requests bypass the rate limiter. + +You can do this by marking requests that should bypass the rate limiter with a custom +header. You must do this somewhere in a load balancer or reverse proxy in front of +GitLab. For example: + +1. Pick a name for your bypass header. For example, `Gitlab-Bypass-Rate-Limiting`. +1. Configure your load balancer to set `Gitlab-Bypass-Rate-Limiting: 1` on requests + that should bypass GitLab rate limiting. +1. Configure your load balancer to either: + - Erase `Gitlab-Bypass-Rate-Limiting`. + - Set `Gitlab-Bypass-Rate-Limiting` to a value other than `1` on all requests that + should be affected by rate limiting. +1. Set the environment variable `GITLAB_THROTTLE_BYPASS_HEADER`. + - For [Omnibus](https://docs.gitlab.com/omnibus/settings/environment-variables.html), + set `'GITLAB_THROTTLE_BYPASS_HEADER' => 'Gitlab-Bypass-Rate-Limiting'` in `gitlab_rails['env']`. + - For source installations, set `export GITLAB_THROTTLE_BYPASS_HEADER=Gitlab-Bypass-Rate-Limiting` + in `/etc/default/gitlab`. + +It is important that your load balancer erases or overwrites the bypass +header on all incoming traffic, because otherwise you must trust your +users to not set that header and bypass the GitLab rate limiter. + +Note that the bypass only works if the header is set to `1`. + +Requests that bypassed the rate limiter because of the bypass header +will be 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. + <!-- ## 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 95a87378e18..3740dc95c12 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -78,7 +78,7 @@ CAUTION: **Warning:** The default behavior of [Delayed Project deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/32935) in GitLab 12.6 was changed to [Immediate deletion](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) in GitLab 13.2. -Projects within a group can be deleted after a delayed period, by [configuring in Group Settings](../../group/index.md#enabling-delayed-project-removal). +Projects within a group (but not a personal namespace) can be deleted after a delayed period, by [configuring in Group Settings](../../group/index.md#enabling-delayed-project-removal). The default period is 7 days, and can be changed. Setting this period to 0 will enable immediate removal of projects or groups. diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index 89acb430a9f..dc956765794 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -1,7 +1,7 @@ --- 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: Analytics +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 --- diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 54b4c702c5c..29df25d76af 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Analytics +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 --- @@ -26,6 +26,7 @@ The following analytics features are available at the group level: - [Insights](../group/insights/index.md). **(ULTIMATE)** - [Issue](../group/issues_analytics/index.md). **(PREMIUM)** - [Productivity](productivity_analytics.md) **(PREMIUM)** +- [Repositories](../group/repositories_analytics/index.md) **(PREMIUM)** - [Value Stream](value_stream_analytics.md). **(PREMIUM)** ## Project-level analytics @@ -34,7 +35,7 @@ The following analytics features are available at the project level: - [CI/CD](../../ci/pipelines/index.md#pipeline-success-and-duration-charts). **(STARTER)** - [Code Review](code_review_analytics.md). **(STARTER)** -- [Insights](../group/insights/index.md). **(ULTIMATE)** +- [Insights](../project/insights/index.md). **(ULTIMATE)** - [Issue](../group/issues_analytics/index.md). **(PREMIUM)** - [Merge Request](merge_request_analytics.md), enabled with the `project_merge_request_analytics` [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-locally-in-development). **(STARTER)** diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index 04a5fa71e19..5402d9a20a0 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -1,7 +1,7 @@ --- 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: Analytics +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 --- @@ -57,9 +57,11 @@ Data table displaying a maximum of the 100 most recent merge requests merged for You can filter the data that is presented on the page based on the following parameters: - Author -- Assignees -- Labels -- Milestones +- Assignee +- Label +- Milestone +- Source branch +- Target branch To filter results: diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index 951be1c550b..da3fe00a901 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Analytics +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 --- diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index 6d2de951a55..3fc5478d466 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Analytics +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 --- diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index 86525587b30..244e37ba3ab 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Analytics +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 --- @@ -105,7 +105,7 @@ Each stage of Value Stream Analytics is further described in the table below. | --------- | --------------- | | 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 issue closing pattern is not present in the merge request description, the MR 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. | @@ -299,7 +299,7 @@ To recover a default stage that was previously hidden: 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](#overview) that follow +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. @@ -339,12 +339,14 @@ Feature.disable(:value_stream_analytics_create_multiple_value_streams) > - [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. +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 @@ -377,7 +379,7 @@ 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, +For Value Stream Analytics functionality introduced in GitLab 12.3 and later, users must have Reporter access or above. ## More resources diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 145422f8736..57c5f8bc1fa 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -8,9 +8,10 @@ type: reference, howto # Web API Fuzz Testing **(ULTIMATE)** You can add web API fuzzing to your [GitLab CI/CD](../../../ci/README.md) -pipelines. This helps you discover bugs and potential security issues that other QA processes may miss. -API fuzzing performs fuzz testing of API operation parameters. -Fuzz testing sets operation parameters to unexpected values in an effort to cause unexpected behavior and errors in the API backend. +pipelines. This helps you discover bugs and potential security issues that other QA processes may +miss. API fuzzing performs fuzz testing of API operation parameters. Fuzz testing sets operation +parameters to unexpected values in an effort to cause unexpected behavior and errors in the API +backend. We recommend that you use fuzz testing in addition to [GitLab Secure](../index.md)'s other security scanners and your own test processes. If you're using [GitLab CI/CD](../../../ci/README.md), @@ -23,7 +24,10 @@ you can run fuzz tests as part your CI/CD workflow. - SOAP - GraphQL - Form bodies, JSON, or XML -- An OpenAPI definition, or HTTP Archive (HAR) of requests to test +- One of the following assets to provide APIs to test: + - OpenAPI v2 API definition + - HTTP Archive (HAR) of API requests to test + - Postman Collection v2.0 or v2.1 ## When fuzzing scans run @@ -48,15 +52,17 @@ changes, other pipelines, or other scanners) during a scan could cause inaccurat ## Configuration -There are two ways to perform scans. See the configuration section for the one you wish to use: +There are three ways to perform scans. See the configuration section for the one you wish to use: - [OpenAPI v2 specification](#openapi-specification) - [HTTP Archive (HAR)](#http-archive-har) +- [Postman Collection v2.0 or v2.1](#postman-collection) Examples of both configurations can be found here: - [Example OpenAPI v2 specification project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/openapi) - [Example HTTP Archive (HAR) project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/har) +- [Example Postman Collection project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing/postman-api-fuzzing-example) ### OpenAPI Specification @@ -133,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: **Danger:** +DANGER: **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. @@ -224,7 +230,98 @@ 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: **Danger:** +DANGER: **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. + +### Postman Collection + +The [Postman API Client](https://www.postman.com/product/api-client/) is a popular tool that +developers and testers use to call various types of APIs. The API definitions +[can be exported as a Postman Collection file](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-postman-data) +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 +test with valid data. The API fuzzer extracts all the API definitions and uses them to perform +testing. + +DANGER: **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. + +Follow these steps to configure API fuzzing to use a Postman Collection file that provides +information about the target API to test: + +1. To use API fuzzing, you must [include](../../../ci/yaml/README.md#includetemplate) + the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml) + that's provided as part of your GitLab installation. To do so, add the following to your + `.gitlab-ci.yml` file: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + ``` + +1. Add the configuration file [`gitlab-api-fuzzing-config.yml`](https://gitlab.com/gitlab-org/security-products/analyzers/api-fuzzing/-/blob/master/gitlab-api-fuzzing-config.yml) + to your repository's root as `.gitlab-api-fuzzing.yml`. + +1. The [configuration file](#configuration-files) has several testing profiles defined with varying + amounts of fuzzing. We recommend that you start with the `Quick-10` profile. Testing with this + profile completes quickly, allowing for easier configuration validation. + + Provide the profile by adding the `FUZZAPI_PROFILE` variable to your `.gitlab-ci.yml` file, + substituting `Quick-10` for the profile you choose: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + ``` + +1. Add the `FUZZAPI_POSTMAN_COLLECTION` variable and set it to the Postman Collection's location: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_POSTMAN_COLLECTION: postman-collection_serviceA.json + ``` + +1. The target API instance's base URL is also required. Provide it by using the `FUZZAPI_TARGET_URL` + variable or an `environment_url.txt` file. + + Adding the URL in an `environment_url.txt` file at your project's root is great for testing in + dynamic environments. To run API fuzzing against an app dynamically created during a GitLab CI/CD + pipeline, have the app persist its domain in an `environment_url.txt` file. API fuzzing + automatically parses that file to find its scan target. You can see an + [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). + + Here's an example of using `FUZZAPI_TARGET_URL`: + + ```yaml + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_POSTMAN_COLLECTION: postman-collection_serviceA.json + FUZZAPI_TARGET_URL: http://test-deployment/ + ``` + +This is a minimal configuration for API Fuzzing. From here you can: + +- [Run your first scan](#running-your-first-scan). +- [Add authentication](#authentication). +- Learn how to [handle false positives](#handling-false-positives). + +DANGER: **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. @@ -398,6 +495,7 @@ increases as the numbers go up. To use a configuration file, add it to your repo | `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. | @@ -540,6 +638,86 @@ variables: FUZZAPI_OVERRIDES_INTERVAL: 300 ``` +### Header Fuzzing + +Header fuzzing is disabled by default due to the high number of false positives that occur with many +technology stacks. When header fuzzing is enabled, you must specify a list of headers to include in +fuzzing. + +Each profile in the default configuration file has an entry for `GeneralFuzzingCheck`. This check +performs header fuzzing. Under the `Configuration` section, you must change the `HeaderFuzzing` and +`Headers` settings to enable header fuzzing. + +This snippet shows the `Quick-10` profile's default configuration with header fuzzing disabled: + +```yaml +- Name: Quick-10 + DefaultProfile: Empty + Routes: + - Route: *Route0 + Checks: + - Name: FormBodyFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + HeaderFuzzing: false + Headers: + - Name: JsonFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + - Name: XmlFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true +``` + +`HeaderFuzzing` is a boolean that turns header fuzzing on and off. The default setting is `false` +for off. To turn header fuzzing on, change this setting to `true`: + +```yaml + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + HeaderFuzzing: true + Headers: +``` + +`Headers` is a list of headers to fuzz. Only headers listed are fuzzed. For example, to fuzz a +custom header `X-Custom` used by your APIs, add an entry for it using the syntax +`- Name: HeaderName`, substituting `HeaderName` with the header to fuzz: + +```yaml + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + HeaderFuzzing: true + Headers: + - Name: X-Custom +``` + +You now have a configuration to fuzz the header `X-Custom`. Use the same notation to list additional +headers: + +```yaml + - Name: GeneralFuzzingCheck + Configuration: + FuzzingCount: 10 + UnicodeFuzzing: true + HeaderFuzzing: true + Headers: + - Name: X-Custom + - Name: X-AnotherHeader +``` + +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 diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 9e7f98dd4fc..eef15a9c424 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Defend +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 --- @@ -76,6 +76,7 @@ How you enable container scanning depends on your GitLab version: that comes with your GitLab installation. - GitLab versions earlier than 11.9: Copy and use the job from the [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml). +- GitLab 13.6 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263482) better support for [FIPS](https://csrc.nist.gov/publications/detail/fips/140/2/final) by upgrading the `CS_MAJOR_VERSION` from `2` to `3`. To include the `Container-Scanning.gitlab-ci.yml` template (GitLab 11.9 and later), add the following to your `.gitlab-ci.yml` file: @@ -144,6 +145,26 @@ variables: CLAIR_OUTPUT: High ``` +Version `3` of the `container_scanning` Docker image uses [`centos:centos8`](https://hub.docker.com/_/centos) +as the new base. It also removes the use of the [start.sh](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/merge_requests/77) +script and instead executes the analyzer by default. Any customizations made to the +`container_scanning` job's [`before_script`](../../../ci/yaml/README.md#before_script) +and [`after_script`](../../../ci/yaml/README.md#after_script) +blocks may not work with the new version. To roll back to the previous [`alpine:3.11.3`](https://hub.docker.com/_/alpine)-based +Docker image, you can specify the major version through the [`CS_MAJOR_VERSION`](#available-variables) +variable. + +This example [includes](../../../ci/yaml/README.md#include) the container scanning template and +enables version `2` of the analyzer: + +```yaml +include: + - template: Container-Scanning.gitlab-ci.yml + +variables: + CS_MAJOR_VERSION: '2' +``` + <!-- NOTE: The container scanning tool references the following heading in the code, so if you" make a change to this heading, make sure to update the documentation URLs used in the" container scanning tool (https://gitlab.com/gitlab-org/security-products/analyzers/klar)" --> @@ -164,6 +185,8 @@ scanning by using the following environment variables: | `CLAIR_VULNERABILITIES_DB_URL` | `clair-vulnerabilities-db` | (**DEPRECATED - use `CLAIR_DB_CONNECTION_STRING` instead**) This variable is explicitly set in the [services section](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) of the `Container-Scanning.gitlab-ci.yml` file and defaults to `clair-vulnerabilities-db`. This value represents the address that the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) is running on and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone container scanning tool](#running-the-standalone-container-scanning-tool) section. | | `CI_APPLICATION_REPOSITORY` | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | Docker repository URL for the image to be scanned. | | `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | +| `CS_MAJOR_VERSION` | `3` | The major version of the Docker image tag. | +| `DOCKER_IMAGE` | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | The Docker image to be scanned. If set, this variable overrides the `$CI_APPLICATION_REPOSITORY` and `$CI_APPLICATION_TAG` variables. | | `DOCKER_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access secure Docker registries using HTTPS with bad (or self-signed) SSL certificates. | | `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. | | `DOCKER_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. | @@ -415,11 +438,11 @@ automatically generates. To enable remediation support, the scanning tool _must_ have access to the `Dockerfile` specified by the [`DOCKERFILE_PATH`](#available-variables) environment variable. To ensure that the scanning tool has access to this -file, it's necessary to set [`GIT_STRATEGY: fetch`](../../../ci/yaml/README.md#git-strategy) in +file, it's necessary to set [`GIT_STRATEGY: fetch`](../../../ci/runners/README.md#git-strategy) in your `.gitlab-ci.yml` file by following the instructions described in this document's [overriding the container scanning template](#overriding-the-container-scanning-template) section. -Read more about the [solutions for vulnerabilities](../index.md#solutions-for-vulnerabilities-auto-remediation). +Read more about the [solutions for vulnerabilities](../index.md#automatic-remediation-for-vulnerabilities). ## Troubleshooting diff --git a/doc/user/application_security/coverage_fuzzing/img/coverage_fuzzing_report_v13_6.png b/doc/user/application_security/coverage_fuzzing/img/coverage_fuzzing_report_v13_6.png Binary files differnew file mode 100644 index 00000000000..bed3ca4c9df --- /dev/null +++ b/doc/user/application_security/coverage_fuzzing/img/coverage_fuzzing_report_v13_6.png diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 9508407ccae..4c5afcee3d0 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -30,6 +30,7 @@ Docker image with the fuzz engine to run your app. | Swift | [libfuzzer](https://github.com/apple/swift/blob/master/docs/libFuzzerIntegration.md) | [swift-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/swift-fuzzing-example) | | Rust | [cargo-fuzz (libFuzzer support)](https://github.com/rust-fuzz/cargo-fuzz) | [rust-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/rust-fuzzing-example) | | Java | [JQF](https://github.com/rohanpadhye/JQF) | [java-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/java-fuzzing-example) | +| Java | [javafuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/javafuzz) (recommended) | [javafuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/javafuzz-fuzzing-example) | ## Configuration @@ -221,6 +222,34 @@ This essentially creates two steps: The `covfuzz-ci.yml` is the same as that in the [original synchronous example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example#running-go-fuzz-from-ci). +## Interacting with the vulnerabilities + +After a vulnerability is found, you can [interact with it](../index.md#interacting-with-the-vulnerabilities). +The merge request widget lists the vulnerability and contains a button for downloading the fuzzing +artifacts. By clicking one of the detected vulnerabilities, you can see its details. + + + +You can also view the vulnerability from the [Security Dashboard](../security_dashboard/index.md), +which shows an overview of all the security vulnerabilities in your groups, projects, and pipelines. + +Clicking the vulnerability opens a modal that provides additional information about the +vulnerability: + +- Status: The vulnerability's status. As with any type of vulnerability, a coverage fuzzing + vulnerability can be Detected, Confirmed, Dismissed, or Resolved. +- Project: The project in which the vulnerability exists. +- Crash type: The type of crash or weakness in the code. This typically maps to a [CWE](https://cwe.mitre.org/). +- Crash state: A normalized version of the stacktrace, containing the last three functions of the + crash (without random addresses). +- Stacktrace snippet: The last few lines of the stacktrace, which shows details about the crash. +- Identifier: The vulnerability's identifier. This maps to either a [CVE](https://cve.mitre.org/) + or [CWE](https://cwe.mitre.org/). +- Severity: The vulnerability's severity. This can be Critical, High, Medium, Low, Info, or Unknown. +- Scanner: The scanner that detected the vulnerability (for example, Coverage Fuzzing). +- Scanner Provider: The engine that did the scan. For Coverage Fuzzing, this can be any of the + engines listed in [Supported fuzzing engines and languages](#supported-fuzzing-engines-and-languages). + ### Glossary - Seed corpus: The set of test cases given as initial input to the fuzz target. This usually speeds diff --git a/doc/user/application_security/dast/img/dast_on_demand_v13_2.png b/doc/user/application_security/dast/img/dast_on_demand_v13_2.png Binary files differdeleted file mode 100644 index 045221d713c..00000000000 --- a/doc/user/application_security/dast/img/dast_on_demand_v13_2.png +++ /dev/null diff --git a/doc/user/application_security/dast/img/dast_single_v13_0.png b/doc/user/application_security/dast/img/dast_single_v13_0.png Binary files differindex 91ed4d916ab..1d528fa0ace 100644 --- a/doc/user/application_security/dast/img/dast_single_v13_0.png +++ b/doc/user/application_security/dast/img/dast_single_v13_0.png diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index fffaf4ad26b..2f1ed2faf90 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -161,6 +161,12 @@ 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 +of your application is likely not accessible without authentication. It is also recommended +that you periodically confirm the scanner's authentication is still working as this tends to break over +time due to authentication changes to the application. + Create masked variables to pass the credentials that DAST uses. To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui). Note that the key of the username variable must be `DAST_USERNAME` @@ -185,7 +191,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: **Danger:** +DANGER: **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. @@ -423,7 +429,51 @@ A URL scan allows you to specify which parts of a website are scanned by DAST. #### Define the URLs to scan -To specify the paths to scan, add a comma-separated list of the paths to the `DAST_PATHS` +URLs to scan can be specified by either of the following methods: + +- Use `DAST_PATHS_FILE` environment variable to specify the name of a file containing the paths. +- Use `DAST_PATHS` environment variable to list the paths. + +##### Use DAST_PATHS_FILE environment variable + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. + +To define the URLs to scan in a file, create a plain text file with one path per line. + +```txt +page1.html +/page2.html +category/shoes/page1.html +``` + +To scan the URLs in that file, set the environment variable `DAST_PATHS_FILE` to the path of that file. + +```yaml +include: + - template: DAST.gitlab-ci.yml + +variables: + DAST_PATHS_FILE: url_file.txt +``` + +By default, DAST scans do not clone the project repository. If the file is checked in to the project, instruct the DAST job to clone the project by setting GIT_STRATEGY to fetch. The file is expected to be in the `/zap/wrk` directory. + +```yaml +dast: + script: + - mkdir -p /zap/wrk + - cp url_file.txt /zap/wrk/url_file.txt + - /analyze -t $DAST_WEBSITE + variables: + GIT_STRATEGY: fetch + DAST_PATHS_FILE: url_file.txt +``` + +##### Use DAST_PATHS environment variable + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. + +To specify the paths to scan in an environment variable, add a comma-separated list of the paths to the `DAST_PATHS` environment variable. Note that you can only scan paths of a single host. ```yaml @@ -434,10 +484,13 @@ variables: DAST_PATHS=/page1.html,/category1/page1.html,/page3.html ``` -When using `DAST_PATHS`, note the following: +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_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, you should create multiple DAST jobs and split the paths over each job. + greater than this, use `DAST_PATHS_FILE`. #### Full Scan @@ -476,6 +529,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_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. | @@ -489,15 +543,16 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `DAST_API_HOST_OVERRIDE` | string | Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080` | | `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). For example, `HTTP Parameter Override` has a rule ID of `10026`. **Note:** In earlier versions of GitLab the excluded rules were executed but alerts they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | | `DAST_REQUEST_HEADERS` | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | -| `DAST_DEBUG` | boolean | Enable debug message output. Default: `false` | -| `DAST_SPIDER_MINS` | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. | -| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. | -| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. | -| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. | -| `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false` | -| `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` | -| `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html` | -| `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. | +| `DAST_DEBUG` | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_SPIDER_MINS` | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1.| +| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_USE_AJAX_SPIDER` | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | +| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line and be within `/zap/wrk`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | +| `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` | ### DAST command-line options @@ -548,7 +603,7 @@ variables: ### Cloning the project's repository The DAST job does not require the project's repository to be present when running, so by default -[`GIT_STRATEGY`](../../../ci/yaml/README.md#git-strategy) is set to `none`. +[`GIT_STRATEGY`](../../../ci/runners/README.md#git-strategy) is set to `none`. ### Debugging DAST jobs @@ -713,10 +768,6 @@ To delete a scanner profile: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.2. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.3. -> - It's deployed behind a feature flag, enabled by default. -> - It's enabled on GitLab.com. -> - It's able to be enabled or disabled per-project. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-on-demand-scans). An on-demand DAST scan runs outside the DevOps life cycle. Changes in your repository don't trigger the scan. You must start it manually. @@ -747,35 +798,6 @@ To run an on-demand DAST scan, you need: The on-demand DAST scan runs and the project's dashboard shows the results. -### Enable or disable On-demand Scans - -The On-demand DAST Scans feature is enabled by default. You can disable on-demand scans -instance-wide, or disable it for specific projects if you prefer. - -To run on-demand DAST scans, an administrator must enable the -`security_on_demand_scans_feature_flag` feature flag. - -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable or enable the feature flags. - -To disable On-demand DAST Scans: - -```ruby -# Instance-wide -Feature.disable(:security_on_demand_scans_feature_flag) -# or by project -Feature.disable(:security_on_demand_scans_feature_flag, Project.find(<project id>)) -``` - -To enable On-demand DAST Scans: - -```ruby -# Instance-wide -Feature.enable(:security_on_demand_scans_feature_flag) -# or by project -Feature.enable(:security_on_demand_scans_feature_flag, Project.find(<project ID>)) -``` - ## Reports The DAST tool outputs a report file in JSON format by default. However, this tool can also generate reports in diff --git a/doc/user/application_security/dependency_list/img/dependency_list_v12_3.png b/doc/user/application_security/dependency_list/img/dependency_list_v12_3.png Binary files differdeleted file mode 100644 index 8eeadb34504..00000000000 --- a/doc/user/application_security/dependency_list/img/dependency_list_v12_3.png +++ /dev/null diff --git a/doc/user/application_security/dependency_list/img/dependency_list_v12_4.png b/doc/user/application_security/dependency_list/img/dependency_list_v12_4.png Binary files differdeleted file mode 100644 index 4687987b763..00000000000 --- a/doc/user/application_security/dependency_list/img/dependency_list_v12_4.png +++ /dev/null diff --git a/doc/user/application_security/dependency_list/img/yarn_dependency_path_v13_6.png b/doc/user/application_security/dependency_list/img/yarn_dependency_path_v13_6.png Binary files differnew file mode 100644 index 00000000000..78e324f43c4 --- /dev/null +++ b/doc/user/application_security/dependency_list/img/yarn_dependency_path_v13_6.png diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 1f730e5f205..ddd059707d4 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -32,7 +32,7 @@ Dependencies are displayed with the following information: | --------- | ----------- | | Component | The dependency's name and version | | Packager | The packager used to install the dependency | -| Location | A link to the packager-specific lock file in your project that declared the dependency | +| Location | A link to the packager-specific lock file in your project that declared the dependency. It also shows the [dependency path](#dependency-paths) to a top-level dependency, if any, and if supported. | | License | Links to dependency's software licenses | Dependencies shown are initially sorted by the severity of their known vulnerabilities, if any. They @@ -44,6 +44,18 @@ If a dependency has known vulnerabilities, you can view them by clicking the arr dependency's name or the badge that indicates how many known vulnerabilities exist. For each vulnerability, its severity and description then appears below it. +### Dependency Paths + +The dependency list shows the path between a dependency and a top-level dependency it's connected +to, if any. There are many possible paths connecting a transient dependency to top-level +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/) + ## Licenses > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10536) in GitLab Ultimate 12.3. diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index b90bb37c60f..1b164c9cecd 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -53,7 +53,7 @@ is **not** `19.03.0`. See [troubleshooting information](#error-response-from-dae ## Supported languages and package managers GitLab relies on [`rules`](../../../ci/yaml/README.md#rules) to start relevant analyzers depending on the languages detected in the repository. -The current detection logic limits the maximum search depth to two levels. For example, the `gemnasium-dependency_scanning` job is enabled if a repository contains either a `Gemfile` or `api/Gemfile` file, but not if the only supported dependency file is `api/client/Gemfile`. +The current detection logic limits the maximum search depth to two levels. For example, the `gemnasium-dependency_scanning` job is enabled if a repository contains either a `Gemfile` or `api/Gemfile` file, but not if the only supported dependency file is `api/client/Gemfile`. The following languages and dependency managers are supported: @@ -71,11 +71,11 @@ The following languages and dependency managers are supported: Plans are underway for supporting the following languages, dependency managers, and dependency files. For details, see the issue link for each. -| Package Managers | Languages | Supported files | Scan tools | -| ------------------- | --------- | --------------- | ------------ | +| Package Managers | Languages | Supported files | Scan tools | Issue | +| ------------------- | --------- | --------------- | ---------- | ----- | | [Pipenv](https://pipenv.pypa.io/en/latest/) | Python | `Pipfile.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#11756](https://gitlab.com/gitlab-org/gitlab/-/issues/11756) | | [Poetry](https://python-poetry.org/) | Python | `poetry.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#7006](https://gitlab.com/gitlab-org/gitlab/-/issues/7006) | -| [sbt](https://www.scala-sbt.org/) 1.3+ ([Coursier](https://get-coursier.io/))| Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#249526](https://gitlab.com/gitlab-org/gitlab/-/issues/249526) | +| [sbt](https://www.scala-sbt.org/) 1.3+ ([Coursier](https://get-coursier.io/))| Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#271345](https://gitlab.com/gitlab-org/gitlab/-/issues/271345) | ## Contribute your scanner @@ -201,7 +201,7 @@ Once a vulnerability is found, you can interact with it. Read more on how to Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. Read more about the -[solutions for vulnerabilities](../index.md#solutions-for-vulnerabilities-auto-remediation). +[solutions for vulnerabilities](../index.md#automatic-remediation-for-vulnerabilities). ## Security Dashboard @@ -356,9 +356,11 @@ 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. -- Host an offline Git copy of the [gemnasium-db advisory database](https://gitlab.com/gitlab-org/security-products/gemnasium-db/). - This is required because, in an offline environment, the Gemnasium analyzer can't fetch the latest - advisories from the online repository. +- 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 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. + - _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. diff --git a/doc/user/application_security/img/security_configuration_page_v13_2.png b/doc/user/application_security/img/security_configuration_page_v13_2.png Binary files differdeleted file mode 100644 index 016328948cc..00000000000 --- a/doc/user/application_security/img/security_configuration_page_v13_2.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..2dd44909dfe --- /dev/null +++ b/doc/user/application_security/img/security_widget_v13_6.png diff --git a/doc/user/application_security/img/vulnerability_page_merge_request_button_dropdown_v13_1.png b/doc/user/application_security/img/vulnerability_page_merge_request_button_dropdown_v13_1.png Binary files differnew file mode 100644 index 00000000000..05ca74c3d5c --- /dev/null +++ b/doc/user/application_security/img/vulnerability_page_merge_request_button_dropdown_v13_1.png diff --git a/doc/user/application_security/img/vulnerability_page_merge_request_button_v13_1.png b/doc/user/application_security/img/vulnerability_page_merge_request_button_v13_1.png Binary files differnew file mode 100644 index 00000000000..a3034a7db04 --- /dev/null +++ b/doc/user/application_security/img/vulnerability_page_merge_request_button_v13_1.png diff --git a/doc/user/application_security/img/vulnerability_solution.png b/doc/user/application_security/img/vulnerability_solution.png Binary files differdeleted file mode 100644 index 63e9c1473b6..00000000000 --- a/doc/user/application_security/img/vulnerability_solution.png +++ /dev/null diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 413a9f894e2..30852d1bbcd 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -1,4 +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 type: reference, howto --- @@ -18,7 +21,7 @@ For an overview of application security with GitLab, see ## Quick start Get started quickly with Dependency Scanning, License Scanning, Static Application Security -Testing (SAST), and Secret Detection by adding the following to your `.gitlab-ci.yml`: +Testing (SAST), and Secret Detection by adding the following to your [`.gitlab-ci.yml`](../../ci/yaml/README.md): ```yaml include: @@ -67,12 +70,26 @@ GitLab uses the following tools to scan and report known vulnerabilities found i | [Dependency List](dependency_list/index.md) **(ULTIMATE)** | View your project's dependencies and their known vulnerabilities. | | [Dependency Scanning](dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | | [Dynamic Application Security Testing (DAST)](dast/index.md) **(ULTIMATE)** | Analyze running web applications for known vulnerabilities. | -| [API fuzzing](api_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities in web APIs with fuzzing. | -| [Secret Detection](secret_detection/index.md) **(ULTIMATE)** | Analyze Git history for leaked secrets. | +| [API fuzzing](api_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities in web APIs with fuzzing. | +| [Secret Detection](secret_detection/index.md) | Analyze Git history for leaked secrets. | | [Security Dashboard](security_dashboard/index.md) **(ULTIMATE)** | View vulnerabilities in all your projects and groups. | | [Static Application Security Testing (SAST)](sast/index.md) | Analyze source code for known vulnerabilities. | | [Coverage fuzzing](coverage_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities with coverage-guided fuzzing. | +### Use security scanning tools with Pipelines for Merge Requests + +The security scanning tools can all be added to pipelines with [templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Security). +See each tool for details on how to use include each template in your CI/CD configuration. + +By default, the application security jobs are configured to run for branch pipelines only. +To use them with [pipelines for merge requests](../../ci/merge_request_pipelines/index.md), +you may need to override the default `rules:` configuration to add: + +```yaml +rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" +``` + ## Security Scanning with Auto DevOps When [Auto DevOps](../../topics/autodevops/) is enabled, all GitLab Security scanning tools will be configured using default settings. @@ -93,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` (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). | | [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. | @@ -106,6 +123,24 @@ latest versions of the scanning tools without having to do anything. There are s with this approach, however, and there is a [plan to resolve them](https://gitlab.com/gitlab-org/gitlab/-/issues/9725). +## Viewing security scan information in merge requests **(CORE)** + +> - [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. +> - 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:** +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. + + + ## Interacting with the vulnerabilities > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.8. @@ -119,7 +154,7 @@ information with several options: - [Create issue](#creating-an-issue-for-a-vulnerability): Create a new issue with the title and description pre-populated with information from the vulnerability report. By default, such issues are [confidential](../project/issues/confidential_issues.md). -- [Solution](#solutions-for-vulnerabilities-auto-remediation): For some vulnerabilities, +- [Automatic Remediation](#automatic-remediation-for-vulnerabilities): For some vulnerabilities, a solution is provided for how to fix the vulnerability.  @@ -141,21 +176,21 @@ To view details of DAST vulnerabilities: 1. Click on the vulnerability's description. The following details are provided: - | Field | Description | -|:-----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Description | Description of the vulnerability. | -| 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 Headers | Headers of the request. | -| Response Status | Response status received from the application. | -| Response Headers | Headers of the response received from the application. | +| Field | Description | +|:-----------------|:------------------------------------------------------------------ | +| Description | Description of the vulnerability. | +| 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 Headers | Headers of the request. | +| Response Status | Response status received from the application. | +| Response Headers | Headers of the response received from the application. | | Evidence | Evidence of the data found that verified the vulnerability. Often a snippet of the request or response, this can be used to help verify that the finding is a vulnerability. | -| Identifiers | Identifiers of the vulnerability. | -| Severity | Severity of the vulnerability. | -| Scanner Type | Type of vulnerability report. | -| Links | Links to further details of the detected vulnerability. | -| Solution | Details of a recommended solution to the vulnerability (optional). | +| Identifiers | Identifiers of the vulnerability. | +| Severity | Severity of the vulnerability. | +| Scanner Type | Type of vulnerability report. | +| Links | Links to further details of the detected vulnerability. | +| Solution | Details of a recommended solution to the vulnerability (optional). | #### Hide sensitive information in headers @@ -198,38 +233,60 @@ Pressing the "Dismiss Selected" button will dismiss all the selected vulnerabili  -### Solutions for vulnerabilities (auto-remediation) +### Creating an issue for a vulnerability + +You can create an issue for a vulnerability by visiting the vulnerability's page and clicking +**Create issue**, which you can find in the **Related issues** section. + + + +This creates a [confidential issue](../project/issues/confidential_issues.md) in the project the +vulnerability came from, and pre-populates it with some useful information taken from the vulnerability +report. Once the issue is created, you are redirected to it so you can edit, assign, or comment on +it. + +Upon returning to the group security dashboard, the vulnerability now has an associated issue next +to the name. + + + +### Automatic remediation for vulnerabilities > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5656) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.7. Some vulnerabilities can be fixed by applying the solution that GitLab -automatically generates. The following scanners are supported: +automatically generates. Although the feature name is Automatic Remediation, this feature is also commonly called Auto-Remediation, Auto Remediation, or Suggested Solutions. The following scanners are supported: - [Dependency Scanning](dependency_scanning/index.md): Automatic Patch creation is only available for Node.js projects managed with `yarn`. - [Container Scanning](container_scanning/index.md) +When an automatic solution is available, the button in the header shows **Resolve with merge request**: + + + +Selecting the button creates a merge request with the solution. + #### Manually applying the suggested patch -Some vulnerabilities can be fixed by applying a patch that is automatically -generated by GitLab. To apply the fix: +To manually apply the patch that GitLab generated for a vulnerability: + +1. Select the **Resolve with merge request** dropdown, then select **Download patch to resolve**: + +  -1. Click the vulnerability. -1. Download and review the patch file `remediation.patch`. 1. Ensure your local project has the same commit checked out that was used to generate the patch. 1. Run `git apply remediation.patch`. 1. Verify and commit the changes to your branch. - - #### Creating a merge request from a vulnerability > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9224) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. In certain cases, GitLab allows you to create a merge request that automatically remediates the vulnerability. Any vulnerability that has a -[solution](#solutions-for-vulnerabilities-auto-remediation) can have a merge +[solution](#automatic-remediation-for-vulnerabilities) can have a merge request created to automatically solve the issue. If this action is available, the vulnerability page or modal contains a **Create merge request** button. @@ -237,25 +294,6 @@ Click this button to create a merge request to apply the solution onto the sourc  -### Creating an issue for a vulnerability - -You can create an issue for a vulnerability by visiting the vulnerability's page and clicking -**Create issue**, which you can find in the **Related issues** section. - - - -This creates a [confidential issue](../project/issues/confidential_issues.md) in the project the -vulnerability came from, and pre-populates it with some useful information taken from the vulnerability -report. Once the issue is created, you are redirected to it so you can edit, assign, or comment on -it. CVE identifiers can be requested from GitLab by clicking the -[_CVE ID Request_ button](cve_id_request.md) that is enabled for maintainers of -public projects on GitLab.com - -Upon returning to the group security dashboard, the vulnerability now has an associated issue next -to the name. - - - ### Managing related issues for a vulnerability Issues can be linked to a vulnerability using the related issues block on the vulnerability page. @@ -320,7 +358,7 @@ appears:  -If at least one security scanner is enabled, you will be able to enable the `Vulnerability-Check` approval rule. If a license scanning job is enabled, you will be able to enable the `License-Check` rule. +If at least one security scanner is enabled, you can enable the `Vulnerability-Check` approval rule. If a license scanning job is enabled, you can enable the `License-Check` rule.  @@ -566,3 +604,36 @@ Additionally, we provide a dedicated project containing the versioned legacy tem This can be useful for offline setups or anyone wishing to use [Auto DevOps](../../topics/autodevops/index.md). Instructions are available in the [legacy template project](https://gitlab.com/gitlab-org/auto-devops-v12-10). + +#### Vulnerabilities are found, but the job succeeds. How can I have a pipeline fail instead? + +This is the current default behavior, because the job's status indicates success or failure of the analyzer itself. +Analyzer results are displayed in the [job logs](../../ci/jobs/index.md#expand-and-collapse-job-log-sections), +[Merge Request widget](sast/index.md) +or [Security Dashboard](security_dashboard/index.md). +There is [an open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/235772) in which changes to this behavior are being discussed. + +### Enable or disable the basic security widget **(CORE ONLY)** + +The basic security widget is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +# For the instance +Feature.enable(:core_security_mr_widget) +# For a single project +Feature.enable(:core_security_mr_widget, Project.find(<project id>)) +``` + +To disable it: + +```ruby +# For the instance +Feature.disable(:core_security_mr_widget) +# For a single project +Feature.disable(:core_security_mr_widget, Project.find(<project id>)) +``` diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 3a7c0148388..35582aa20ed 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -66,8 +66,7 @@ external links exposed in the UI. These links might not be accessible within an ### Automatic remediation for vulnerabilities -The [automatic remediation for vulnerabilities](../index.md#solutions-for-vulnerabilities-auto-remediation) feature -(auto-remediation) is available for offline Dependency Scanning and Container Scanning, but may not work +The [automatic remediation for vulnerabilities](../index.md#automatic-remediation-for-vulnerabilities) feature is available for offline Dependency Scanning and Container Scanning, but may not work depending on your instance's configuration. We can only suggest solutions, which are generally more current versions that have been patched, when we are able to access up-to-date registry services hosting the latest versions of that dependency or image. @@ -214,3 +213,28 @@ do ssh $GITLAB_HOST "sudo docker push ${registry}/analyzers/${i}:2" done ``` + +### Using GitLab Secure with AutoDevOps in an offline environment + +You can use GitLab AutoDevOps for Secure scans in an offline environment. However, you must first do +these steps: + +1. Load the container images into the local registry. GitLab Secure leverages analyzer container + images to do the various scans. These images must be available as part of running AutoDevOps. + Before running AutoDevOps, follow the [above steps](#using-the-official-gitlab-template) + to load those container images into the local container registry. + +1. Set the pipeline variable to ensure that AutoDevOps looks in the right place for those images. + The AutoDevOps templates leverage the `SECURE_ANALYZERS_PREFIX` variable to identify the location + of analyzer images. This variable is discussed above in [Using the secure bundle created](#using-the-secure-bundle-created). + Ensure that you set this variable to the correct value for where you loaded the analyzer images. + You could consider doing this with a pipeline variable or by [modifying](../../../topics/autodevops/customize.md#customizing-gitlab-ciyml) + the `.gitlab-ci.yml` file directly. + +Once these steps are complete, GitLab has local copies of the Secure analyzers and is set up to use +them instead of an Internet-hosted container image. This allows you to run Secure in AutoDevOps in +an offline environment. + +Note that these steps are specific to GitLab Secure with AutoDevOps. Using other stages with +AutoDevOps may require other steps covered in the +[Auto DevOps documentation](../../../topics/autodevops/). diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 6167c0445f9..4cbd4496dea 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -4,7 +4,10 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# SAST Analyzers **(ULTIMATE)** +# SAST Analyzers **(CORE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. +> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to GitLab Core in 13.3. SAST relies on underlying third party tools that are wrapped into what we call "Analyzers". An analyzer is a @@ -33,7 +36,7 @@ SAST supports the following official analyzers: - [`sobelow`](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) (Sobelow (Elixir Phoenix)) - [`spotbugs`](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) (SpotBugs with the Find Sec Bugs plugin (Ant, Gradle and wrapper, Grails, Maven and wrapper, SBT)) -The analyzers are published as Docker images that SAST will use to launch +The analyzers are published as Docker images that SAST uses to launch dedicated containers for each analysis. SAST is pre-configured with a set of **default images** that are maintained by @@ -77,12 +80,12 @@ variables: SAST_DEFAULT_ANALYZERS: "bandit,flawfinder" ``` -`bandit` runs first. When merging the reports, SAST will -remove the duplicates and will keep the `bandit` entries. +`bandit` runs first. When merging the reports, SAST +removes the duplicates and keeps the `bandit` entries. ### Disabling default analyzers -Setting `SAST_DEFAULT_ANALYZERS` to an empty string will disable all the official +Setting `SAST_DEFAULT_ANALYZERS` to an empty string disables all the official default analyzers. In `.gitlab-ci.yml` define: ```yaml @@ -121,7 +124,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) | Property / Tool | Apex | Bandit | Brakeman | ESLint security | SpotBugs | Flawfinder | Gosec | Kubesec Scanner | MobSF | NodeJsScan | PHP CS Security Audit | Security code Scan (.NET) | Sobelow | | --------------------------------------- | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :---------------------: | :-------------------------: | :----------------: | -| Severity | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | +| Severity | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | | Title | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Description | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | | File | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -129,11 +132,11 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) | End line | ✓ | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | Start column | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | | End column | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| External ID (e.g. CVE) | 𐄂 | 𐄂 | ⚠ | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | +| External ID (for example, CVE) | 𐄂 | 𐄂 | ⚠ | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | URLs | ✓ | 𐄂 | ✓ | 𐄂 | ⚠ | 𐄂 | ⚠ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | Internal doc/explanation | ✓ | ⚠ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | | Solution | ✓ | 𐄂 | 𐄂 | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Affected item (e.g. class or package) | ✓ | 𐄂 | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | +| Affected item (for example, class or package) | ✓ | 𐄂 | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | Confidence | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | x | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | | Source code extract | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | | Internal ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | @@ -143,4 +146,4 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) - 𐄂 => we don't have that data or it would need to develop specific or inefficient/unreliable logic to obtain it. The values provided by these tools are heterogeneous so they are sometimes -normalized into common values (e.g., `severity`, `confidence`, etc). +normalized into common values (for example, `severity`, `confidence`, and so on). diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 9e4d4112ae8..49e194a9319 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -32,8 +32,8 @@ The results are sorted by the priority of the vulnerability: 1. Everything else A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish -for any reason, the security dashboard doesn't show SAST scanner output. For example, if the SAST -job finishes but the DAST job fails, the security dashboard doesn't show SAST results. On failure, +for any reason, the security dashboard does not show SAST scanner output. For example, if the SAST +job finishes but the DAST job fails, the security dashboard does not show SAST results. On failure, the analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code). ## Use cases @@ -71,9 +71,9 @@ You can also [view our language roadmap](https://about.gitlab.com/direction/secu | C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7 | | Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.1 | | Go | [Gosec](https://github.com/securego/gosec) | 10.7 | -| Groovy ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.3 (Gradle) & 11.9 (Ant, Maven, SBT) | +| Groovy ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.3 (Gradle) & 11.9 (Ant, Maven, SBT) | | Helm Charts | [Kubesec](https://github.com/controlplaneio/kubesec) | 13.1 | -| Java ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (Ant, SBT) | +| Java ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (Ant, SBT) | | Java (Android) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | | JavaScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.8 | | Kotlin (Android) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | @@ -84,7 +84,7 @@ You can also [view our language roadmap](https://about.gitlab.com/direction/secu | Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/PyCQA/bandit) | 10.3 | | React | [ESLint react plugin](https://github.com/yannickcr/eslint-plugin-react) | 12.5 | | Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3 | -| Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) | +| Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) | | Swift (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | | TypeScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.9, [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/36059) with ESLint in 13.2 | @@ -107,10 +107,11 @@ as shown in the following table: | [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | | [Customize SAST Settings](#customizing-the-sast-settings) | **{check-circle}** | **{check-circle}** | | View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | -| [Presentation of JSON Report in Merge Request](#overview) | **{dotted-circle}** | **{check-circle}** | +| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | | [Interaction with Vulnerabilities](#interacting-with-the-vulnerabilities) | **{dotted-circle}** | **{check-circle}** | | [Access to Security Dashboard](#security-dashboard) | **{dotted-circle}** | **{check-circle}** | | [Configure SAST in the UI](#configure-sast-in-the-ui) | **{dotted-circle}** | **{check-circle}** | +| [Customize SAST Rulesets](#customize-rulesets) | **{dotted-circle}** | **{check-circle}** | ## Contribute your scanner @@ -162,7 +163,7 @@ page: 1. Enter the custom SAST values. Custom values are stored in the `.gitlab-ci.yml` file. For variables not in the SAST Configuration page, their values are left unchanged. Default values are inherited from the GitLab SAST template. -1. Optionally, expand the **SAST analyzers** section, select individual [SAST analyzers](./analyzers.md) and enter custom analyzer values. +1. Optionally, expand the **SAST analyzers** section, select individual [SAST analyzers](analyzers.md) and enter custom analyzer values. 1. Click **Create Merge Request**. 1. Review and merge the merge request. @@ -205,15 +206,21 @@ spotbugs-sast: FAIL_NEVER: 1 ``` -### Custom rulesets +### Customize rulesets **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235382) in GitLab 13.5. -You can customize the default scanning rules provided with SAST's NodeJS-Scan and Gosec analyzers. -Customization allows you to exclude rules and modify the behavior of existing rules. +You can customize the default scanning rules provided by our SAST analyzers. + +Ruleset customization supports two capabilities: + +1. Disabling predefined rules +1. Modifying the default behavior of a given analyzer + +These capabilities can be used simultaneously. To customize the default scanning rules, create a file containing custom rules. These rules -are passed through to the analyzer's underlying scanner tool. +are passed through to the analyzer's underlying scanner tools. To create a custom ruleset: @@ -221,6 +228,25 @@ To create a custom ruleset: 1. Create a custom ruleset file named `sast-ruleset.toml` in the `.gitlab` directory. 1. In the `sast-ruleset.toml` file, do one of the following: + - Disable predefined rules belonging to SAST analyzers. In this example, the disabled rules + belong to `eslint` and `sobelow` and have the corresponding identifiers `type` and `value`: + + ```toml + [eslint] + [[eslint.ruleset]] + disable = true + [eslint.ruleset.identifier] + type = "eslint_rule_id" + value = "security/detect-object-injection" + + [sobelow] + [[sobelow.ruleset]] + disable = true + [sobelow.ruleset.identifier] + type = "sobelow_rule_id" + value = "sql_injection" + ``` + - Define a custom analyzer configuration. In this example, customized rules are defined for the `nodejs-scan` scanner: @@ -285,7 +311,7 @@ you can use the `MAVEN_CLI_OPTS` environment variable. Read more on [how to use private Maven repositories](../index.md#using-private-maven-repos). -#### Enabling Kubesec analyzer +### Enabling Kubesec analyzer > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12752) in GitLab Ultimate 12.6. @@ -300,7 +326,7 @@ variables: SCAN_KUBERNETES_MANIFESTS: "true" ``` -#### Pre-compilation +### Pre-compilation 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 @@ -398,7 +424,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` will use 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` will scan. 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. | @@ -426,7 +452,7 @@ to the underlying SAST analyzer images if [the SAST vendored template](#configuration) is used. CAUTION: **Caution:** -Variables having names starting with these prefixes will **not** be propagated to the SAST Docker container and/or +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 @@ -642,7 +668,7 @@ security reports without requiring internet access. ### Configure certificate checking of packages If a SAST job invokes a package manager, you must configure its certificate verification. In an -offline environment, certificate verification with an external source isn't possible. Either use a +offline environment, certificate verification with an external source is not possible. Either use a self-signed certificate or disable certificate verification. Refer to the package manager's documentation for instructions. diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index bb10e9d7315..025a37f684d 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -5,9 +5,10 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Secret Detection **(ULTIMATE)** +# Secret Detection -> [Introduced](https://about.gitlab.com/releases/2019/03/22/gitlab-11-9-released/#detect-secrets-and-credentials-in-the-repository) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. +> - [Introduced](https://about.gitlab.com/releases/2019/03/22/gitlab-11-9-released/#detect-secrets-and-credentials-in-the-repository) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. +> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) in 13.3. A recurring problem when developing applications is that developers may unintentionally commit secrets and credentials to their remote repositories. If other people have access to the source, @@ -30,6 +31,29 @@ GitLab displays identified secrets visibly in a few places: - Detecting unintentional commit of secrets like keys, passwords, and API tokens. - Performing a single or recurring scan of the full history of your repository for secrets. +## Supported secrets + +Secret Detection detects a variety of common secrets by default. You can also customize the secret detection patterns using [custom rulesets](#custom-rulesets). + +The [default ruleset provided by Gitleaks](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks/gitleaks.toml) includes the following key types: + +- Cloud services: + - Amazon Web Services (AWS) + - Google Cloud Platform (GCP) +Encryption keys: + - PKCS8 + - RSA + - SSH + - PGP +- Social media platforms: + - Facebook API + - Twitter API +- Cloud SaaS vendors: + - GitHub API + - Slack Token + - Stripe API + - Generic API key strings starting with `api-` + ## Requirements To run Secret Detection jobs, by default, you need GitLab Runner with the @@ -59,7 +83,7 @@ as shown in the following table: | [Configure Secret Detection Scanners](#configuration) | **{check-circle}** | **{check-circle}** | | [Customize Secret Detection Settings](#customizing-settings) | **{check-circle}** | **{check-circle}** | | View [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** | **{check-circle}** | -| [Presentation of JSON Report in Merge Request](#overview) | **{dotted-circle}** | **{check-circle}** | +| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | | [Interaction with Vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | | [Access to Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | @@ -102,6 +126,18 @@ The results are saved as a that you can later download and analyze. Due to implementation limitations, we always take the latest Secret Detection artifact available. +### Post-processing + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/46390) 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. + +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). + ### Customizing settings The Secret Detection scan settings can be changed through [environment variables](#available-variables) @@ -142,7 +178,7 @@ Secret Detection can be customized by defining available variables: | `SECRET_DETECTION_EXCLUDED_PATHS` | "" | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225273) in GitLab 13.3. | | `SECRET_DETECTION_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. | -### Custom rulesets +### Custom rulesets **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211387) in GitLab 13.5. diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png Binary files differdeleted file mode 100644 index 8fab4e39175..00000000000 --- a/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_6.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_6.png Binary files differnew file mode 100644 index 00000000000..6ccae80e80e --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_6.png diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_export_csv_v12_10.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_export_csv_v12_10.png Binary files differdeleted file mode 100644 index 07b41b471d4..00000000000 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard_export_csv_v12_10.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 5fa8ebb80e0..1b038ef76a0 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -9,15 +9,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab provides a comprehensive set of features for viewing and managing vulnerabilities: -- Security dashboards: An overview of the security status in your instance, groups, and projects. -- Vulnerability reports: Detailed lists of all vulnerabilities for the instance, group, project, or +- Security dashboards: An overview of the security status in your instance, [groups](#group-security-dashboard), and + [projects](#project-security-dashboard). +- [Vulnerability reports](#vulnerability-report): Detailed lists of all vulnerabilities for the instance, group, project, or pipeline. This is where you triage and manage vulnerabilities. -- Security Center: A dedicated area for vulnerability management at the instance level. This +- [Security Center](#instance-security-center): A dedicated area for vulnerability management at the instance level. This includes a security dashboard, vulnerability report, and settings. -You can also drill down into a vulnerability and get extra information. This includes the project it -comes from, any related file(s), and metadata that helps you analyze the risk it poses. You can also -dismiss a vulnerability or create an issue for it. +You can also drill down into a vulnerability and get extra information on the +[Vulnerability Page](../vulnerabilities/index.md). This view includes the project it +comes from, any related file(s), and metadata that helps you analyze the risk it poses. +You can also confirm, dismiss, or resolve a vulnerability, create an issue for it, +and in some cases, generate a merge request to fix the vulnerability. To benefit from these features, you must first configure one of the [security scanners](../index.md). @@ -30,7 +33,7 @@ The vulnerability report displays vulnerabilities detected by scanners such as: - [Dynamic Application Security Testing](../dast/index.md) - [Dependency Scanning](../dependency_scanning/index.md) - [Static Application Security Testing](../sast/index.md) -- And others! +- And [others](../index.md#security-scanning-tools)! ## Requirements @@ -60,43 +63,67 @@ job finishes but the DAST job fails, the security dashboard doesn't show SAST re the analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code). +You can filter the vulnerabilities list by selecting from the **Severity** and **Scanner** dropdowns. + ## Project Security Dashboard +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235558) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. + +At the project level, the Security Dashboard displays a chart with the number of vulnerabilities over time. +Access it by navigating to **Security & Compliance > Security Dashboard**. Currently, we display historical +data up to 365 days. + + + +Filter the historical data by clicking on the corresponding legend name. The image above, for example, shows +only the graph for vulnerabilities with **high** severity. + +### Vulnerability Report + > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6165) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.1. -At the project level, the Security Dashboard displays the vulnerabilities merged into your project's -[default branch](../../project/repository/branches/index.md#default-branch). Access it by navigating -to **Security & Compliance > Security Dashboard**. By default, the Security Dashboard displays all -detected and confirmed vulnerabilities. +The vulnerabilities that exist in your project's +[default branch](../../project/repository/branches/index.md#default-branch) are accessed by navigating to +**Security & Compliance > Vulnerability Report**. By default, the Vulnerability Report is filtered to +display all detected and confirmed vulnerabilities. -The Security Dashboard 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. +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 **Failed jobs** tab of the pipeline page. -The Security Dashboard next displays the total number of vulnerabilities by severity (for example, +The Vulnerability Report next displays the total number of vulnerabilities by severity (for example, Critical, High, Medium, Low, Info, Unknown). Below this, a table shows each vulnerability's status, severity, and description. Clicking a vulnerability takes you to its [Vulnerability Details](../vulnerabilities) page to view more information about that vulnerability. - + You can filter the vulnerabilities by one or more of the following: -- Status -- Severity -- Scanner +| Filter | Available Options | +| --- | --- | +| Status | Detected, Confirmed, Dismissed, Resolved | +| Severity | Critical, High, Medium, Low, Info, Unknown | +| Scanner | [Available Scanners](../index.md#security-scanning-tools) | + +You can filter the vulnerabilities list by selecting from the **Status**, **Severity**, and +**Scanner** dropdowns. In the **Scanner** dropdown, select individual scanners or scanner groups to +toggle those scanners. The **Scanner** dropdown includes both GitLab scanners, and in GitLab 13.6 +and later, custom scanners. You can also dismiss vulnerabilities in the table: 1. Select the checkbox for each vulnerability you want to dismiss. 1. In the menu that appears, select the reason for dismissal and click **Dismiss Selected**. - + ## Group Security Dashboard > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6709) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. -The group Security Dashboard gives an overview of the vulnerabilities in the default branches of the +The group Security Dashboard gives an overview of the vulnerabilities found in the default branches of the projects in a group and its subgroups. Access it by navigating to **Security > Security Dashboard** after selecting your group. By default, the Security Dashboard displays all detected and confirmed vulnerabilities. If you don't see the vulnerabilities over time graph, the likely cause is that you @@ -111,20 +138,21 @@ enabled in a group. There is a timeline chart that shows how many open vulnerabilities your projects had at various points in time. You can display the vulnerability trends over a 30, 60, or 90-day time frame (the default is 90 days). Hover over the chart to get -more details about the open vulnerabilities at a specific time. +more details about the open vulnerabilities at a specific time. Aggregated data beyond 90 days can be accessed by querying our [VulnerabilitiesCountByDay GraphQL API](../../../api/graphql/reference/index.md#vulnerabilitiescountbyday). This data is retained for 365 days. Next to the timeline chart is a list of projects, grouped and sorted by the severity of the vulnerability found: -- F: One or more "critical" -- D: One or more "high" or "unknown" -- C: One or more "medium" -- B: One or more "low" -- A: Zero vulnerabilities +| Grade | Description | +| F | One or more "critical" | +| D | One or more "high" or "unknown" | +| C | One or more "medium" | +| B | One or more "low" | +| A | Zero vulnerabilities | Projects with no vulnerability tests configured will not appear in the list. Additionally, dismissed vulnerabilities are excluded. -Navigate to the group's [vulnerability report](#vulnerability-report) to view the vulnerabilities found. +Navigate to the group's [vulnerability report](#vulnerability-report-1) to view the vulnerabilities found. ## Instance Security Center @@ -232,10 +260,17 @@ into the default branch. You can filter which vulnerabilities the vulnerability report displays by: -- Status -- Severity -- Scanner -- Project +| Filter | Available Options | +| --- | --- | +| Status | Detected, Confirmed, Dismissed, Resolved | +| Severity | Critical, High, Medium, Low, Info, Unknown | +| Scanner | [Available Scanners](../index.md#security-scanning-tools) | +| Project | Projects configured in the Security Center settings | + +You can filter the vulnerabilities list by selecting from the **Status**, **Severity**, and +**Scanner**, and **Project** dropdowns. In the **Scanner** dropdown, select individual scanners or +scanner groups to toggle those scanners. The **Scanner** dropdown includes both GitLab scanners, and +in GitLab 13.6 and later, custom scanners. Clicking any vulnerability in the table takes you to its [Vulnerability Details](../vulnerabilities) page to see more information on that vulnerability. diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 391666a077e..f85d4f0140c 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -1,6 +1,6 @@ --- type: reference, howto -stage: Defend +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 --- diff --git a/doc/user/application_security/vulnerabilities/img/vulnerability_page_download_patch_button_v13_1.png b/doc/user/application_security/vulnerabilities/img/vulnerability_page_download_patch_button_v13_1.png Binary files differdeleted file mode 100644 index b925c342a11..00000000000 --- a/doc/user/application_security/vulnerabilities/img/vulnerability_page_download_patch_button_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index ee3fd6c4dd4..95bb1ff1a67 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -11,10 +11,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w Each security vulnerability in a project's [Security Dashboard](../security_dashboard/index.md#project-security-dashboard) has an individual page which includes: -- Details of the vulnerability. +- Details for the vulnerability. - The status of the vulnerability within the project. - Available actions for the vulnerability. -- Issues related to the vulnerability. +- Any issues related to the vulnerability. On the vulnerability page, you can interact with the vulnerability in several different ways: @@ -25,22 +25,22 @@ several different ways: title and description pre-populated with information from the vulnerability report. By default, such issues are [confidential](../../project/issues/confidential_issues.md). - [Link issues](#link-issues-to-the-vulnerability) - Link existing issues to vulnerability. -- [Solution](#automatic-remediation-for-vulnerabilities) - For some vulnerabilities, - a solution is provided for how to fix the vulnerability. +- [Automatic remediation](#automatic-remediation-for-vulnerabilities) - For some vulnerabilities, + a solution is provided for how to fix the vulnerability automatically. ## Changing vulnerability status You can switch the status of a vulnerability using the **Status** dropdown to one of the following values: -| Status | Description | -|-----------|-------------------------------------------------------------------| -| Detected | The default state for a newly discovered vulnerability | -| Confirmed | A user has seen this vulnerability and confirmed it to be real | -| Dismissed | A user has seen this vulnerability and dismissed it | -| Resolved | The vulnerability has been fixed and is no longer in the codebase | +| Status | Description | +|-----------|------------------------------------------------------------------------------------------------------------------| +| Detected | The default state for a newly discovered vulnerability | +| Confirmed | A user has seen this vulnerability and confirmed it to be accurate | +| Dismissed | A user has seen this vulnerability and dismissed it because it is not accurate or otherwise will not be resolved | +| Resolved | The vulnerability has been fixed and is no longer valid | -A timeline shows you when the vulnerability status has changed, +A timeline shows you when the vulnerability status has changed and allows you to comment on a change. ## Creating an issue for a vulnerability @@ -48,7 +48,7 @@ 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 +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 issue page so you can edit, assign, or comment on the issue. @@ -61,4 +61,4 @@ that the resolution of one issue would resolve multiple vulnerabilities. ## Automatic remediation for vulnerabilities You can fix some vulnerabilities by applying the solution that GitLab automatically -generates for you. [Read more about the automatic remediation for vulnerabilities feature](../index.md#solutions-for-vulnerabilities-auto-remediation). +generates for you. [Read more about the automatic remediation for vulnerabilities feature](../index.md#automatic-remediation-for-vulnerabilities). diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 196c3e9fb43..74c679d9bb9 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -24,9 +24,11 @@ tasks in a secure and cloud-native way. It enables: Many more features are planned. Please [review our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329). -## Architecture +## GitLab Agent GitOps workflow -### GitLab Agent GitOps workflow +The GitLab Agent uses multiple GitLab projects to provide a flexible workflow +that can suit various needs. This diagram shows these repositories and the main +actors involved in a deployment: ```mermaid sequenceDiagram @@ -44,11 +46,6 @@ sequenceDiagram end ``` -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 - There are several components that work in concert for the Agent to accomplish GitOps deployments: - A properly-configured Kubernetes cluster. @@ -57,51 +54,93 @@ There are several components that work in concert for the Agent to accomplish Gi - A manifest repository that contains a `manifest.yaml`, which is tracked by the Agent and can be auto-generated. Any changes to `manifest.yaml` are applied to the cluster. +These repositories might be the same GitLab project or separate projects. + +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 + The setup process involves a few steps to enable GitOps deployments: -1. Installing the Agent server. -1. Defining a configuration directory. -1. Creating an Agent record in GitLab. -1. Generating and copying a Secret token used to connect to the Agent. -1. Installing the Agent into the cluster. -1. Creating a `manifest.yaml`. +1. [Install the Agent server](#install-the-kubernetes-agent-server). +1. [Define a configuration repository](#define-a-configuration-repository). +1. [Create an Agent record in GitLab](#create-an-agent-record-in-gitlab). +1. [Generate and copy a Secret token used to connect to the Agent](#create-the-kubernetes-secret). +1. [Install the Agent into the cluster](#install-the-agent-into-the-cluster). +1. [Create a `manifest.yaml`](#create-a-manifestyaml). + +### Upgrades and version compatibility + +As the GitLab Kubernetes Agent is a new product, we are constantly adding new features +to it. As a result, while shipped features are production ready, its internal API is +neither stable nor versioned yet. For this reason, GitLab only guarantees compatibility +between corresponding major.minor (X.Y) versions of GitLab and its cluster side +component, `agentk`. + +Upgrade your agent installations together with GitLab upgrades. To decide which version of `agentk`to install follow: + +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) -### Install the Agent server +The available `agentk` versions can be found in +[its container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/eyJuYW1lIjoiZ2l0bGFiLW9yZy9jbHVzdGVyLWludGVncmF0aW9uL2dpdGxhYi1hZ2VudC9hZ2VudGsiLCJ0YWdzX3BhdGgiOiIvZ2l0bGFiLW9yZy9jbHVzdGVyLWludGVncmF0aW9uL2dpdGxhYi1hZ2VudC9yZWdpc3RyeS9yZXBvc2l0b3J5LzEyMjMyMDUvdGFncz9mb3JtYXQ9anNvbiIsImlkIjoxMjIzMjA1LCJjbGVhbnVwX3BvbGljeV9zdGFydGVkX2F0IjpudWxsfQ==). -The GitLab Kubernetes Agent can be deployed using [Omnibus +### Install the Kubernetes Agent Server + +The GitLab Kubernetes Agent Server (KAS) can be deployed using [Omnibus GitLab](https://docs.gitlab.com/omnibus/) or the [GitLab 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:** -GitLab plans to include the Agent on [GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/3834). +GitLab plans to include the KAS on [GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/3834). + +#### Install with Omnibus When using the [Omnibus GitLab](https://docs.gitlab.com/omnibus/) package: 1. Edit `/etc/gitlab/gitlab.rb`: -```plaintext -gitlab_kas['enable'] = true -``` + ```plaintext + gitlab_kas['enable'] = true + ``` 1. [Reconfigure GitLab](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). -When installing or upgrading the GitLab Helm chart, consider the following Helm 2 example. -(If you're using Helm 3, you must modify this example.) You must set `global.kas.enabled=true` -for the Agent to be properly installed and configured: +To configure any additional options related to GitLab Kubernetes Agent Server, +refer to the **Enable GitLab KAS** section of the +[`gitlab.rb.template`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/files/gitlab-config-template/gitlab.rb.template). + +#### Install with the Helm chart + +When installing or upgrading the GitLab Helm chart, consider the following Helm v3 example. +If you're using Helm v2, you must modify this example. See our [notes regarding deploy with Helm](https://docs.gitlab.com/charts/installation/deployment.html#deploy-using-helm). + +You must set `global.kas.enabled=true` for the KAS to be properly installed and configured: ```shell +helm repo add gitlab https://charts.gitlab.io/ helm repo update -helm upgrade --force --install gitlab gitlab/gitlab \ - --timeout 600 \ +helm upgrade --install gitlab gitlab/gitlab \ + --timeout 600s \ --set global.hosts.domain=<YOUR_DOMAIN> \ --set global.hosts.externalIP=<YOUR_IP> \ --set certmanager-issuer.email=<YOUR_EMAIL> \ - --set name=gitlab-instance \ --set global.kas.enabled=true ``` +To specify other options related to the KAS sub-chart, create a `gitlab.kas` sub-section +of your `values.yaml` file: + +```shell +gitlab: + kas: + # put your KAS custom options here +``` + +For details, read [Using the GitLab-KAS chart](https://docs.gitlab.com/charts/charts/gitlab/kas/). + ### Define a configuration repository Next, you need a GitLab repository to contain your Agent configuration. The minimal @@ -111,12 +150,33 @@ repository layout looks like this: .gitlab/agents/<agent-name>/config.yaml ``` -The `config.yaml` file contents should look like this: +Your `config.yaml` file can specify multiple manifest projects in the +section `manifest_projects`: + +```yaml +gitops: + manifest_projects: + - id: "path-to/your-manifest-project-number1" + ... +``` + +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-awesome-project" + - 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}' ``` ### Create an Agent record in GitLab @@ -125,20 +185,24 @@ Next, create an GitLab Rails Agent record so the Agent can associate itself with the configuration repository project. Creating this record also creates a Secret needed to configure the Agent in subsequent steps. You can create an Agent record either: -- Through the Rails console, by running `rails c`: +- Through the Rails console: ```ruby - project = ::Project.find_by_full_path("path-to/your-awesome-project") + project = ::Project.find_by_full_path("path-to/your-configuration-project") + # agent-name should be the same as specified above in the config.yaml agent = ::Clusters::Agent.create(name: "<agent-name>", project: project) token = ::Clusters::AgentToken.create(agent: agent) token.token # this will print out the token you need to use on the next step ``` + For full details, read [Starting a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session). + - Through GraphQL: **(PREMIUM ONLY)** ```graphql mutation createAgent { - createClusterAgent(input: { projectPath: "path-to/your-awesome-project", name: "<agent-name>" }) { + # agent-name should be the same as specified above in the config.yaml + createClusterAgent(input: { projectPath: "path-to/your-configuration-project", name: "<agent-name>" }) { clusterAgent { id name @@ -160,7 +224,7 @@ the Agent in subsequent steps. You can create an Agent record either: ``` NOTE: **Note:** - GraphQL only displays the token once, after creating it. + GraphQL only displays the token one time after creating it. If you are new to using the GitLab GraphQL API, refer to the [Getting started with the GraphQL API page](../../../api/graphql/getting_started.md), @@ -170,7 +234,7 @@ the Agent in subsequent steps. You can create an Agent record either: After generating the token, you must apply it to the Kubernetes cluster. -1. If you haven't previous defined or created a namespace, run the following command: +1. If you haven't previously defined or created a namespace, run the following command: ```shell kubectl create namespace <YOUR-DESIRED-NAMESPACE> @@ -188,43 +252,40 @@ Next, install the in-cluster component of the Agent. This example file contains Kubernetes resources required for the Agent to be installed. You can modify this example [`resources.yml` file](#example-resourcesyml-file) in the following ways: -- You can replace `gitlab-agent` with `<YOUR-DESIRED-NAMESPACE>`. -- For the `kas-address` (Kubernetes Agent Server), the agent can use the WebSockets - or gRPC protocols to connect to the Agent Server. Depending on your cluster - configuration and GitLab architecture, you may need to use one or the other. - For the `gitlab-kas` Helm chart, an Ingress is created for the Agent Server using - the `/-/kubernetes-agent` endpoint. This can be used for the WebSockets protocol connection. - - Specify the `grpc` scheme (such as `grpc://gitlab-kas:5005`) to use gRPC directly. - Encrypted gRPC is not supported yet. Follow the +- Replace `namespace: gitlab-agent` with `namespace: <YOUR-DESIRED-NAMESPACE>`. +- You can configure `kas-address` (Kubernetes Agent Server) in several 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 + `kas-address`, where `GitLab.host.tld` is your GitLab hostname. + - Specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent`) + to use an unencrypted WebSockets connection. + - 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` + is the name of the service created by `gitlab-kas` chart, and `your-namespace` + is the namespace where the chart was installed. Encrypted gRPC is not supported yet. + Follow the [Support TLS for gRPC communication issue](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) for progress updates. - - Specify the `ws` scheme (such as `ws://gitlab-kas-ingress:80/-/kubernetes-agent`) - to use an unencrypted WebSockets connection. - - Specify the `wss` scheme (such as `wss://gitlab-kas-ingress:443/-/kubernetes-agent`) - to use an encrypted WebSockets connection. This is the recommended option if - installing the Agent into a separate cluster from your Agent Server. -- If you defined your own secret name, replace `gitlab-agent-token` with your secret name. +- If you defined your own secret name, replace `gitlab-agent-token` with your + secret name in the `secretName:` section. To apply this file, run the following command: ```shell -kubectl apply -n gitlab-agent -f ./resources.yml +kubectl apply -n <YOUR-DESIRED-NAMESPACE> -f ./resources.yml ``` To review your configuration, run the following command: ```shell -$ kubectl get pods --all-namespaces +$ kubectl get pods -n <YOUR-DESIRED-NAMESPACE> NAMESPACE NAME READY STATUS RESTARTS AGE gitlab-agent gitlab-agent-77689f7dcb-5skqk 1/1 Running 0 51s -kube-system coredns-f9fd979d6-n6wcw 1/1 Running 0 14m -kube-system etcd-minikube 1/1 Running 0 14m -kube-system kube-apiserver-minikube 1/1 Running 0 14m -kube-system kube-controller-manager-minikube 1/1 Running 0 14m -kube-system kube-proxy-j6zdh 1/1 Running 0 14m -kube-system kube-scheduler-minikube 1/1 Running 0 14m -kube-system storage-provisioner 1/1 Running 0 14m ``` #### Example `resources.yml` file @@ -256,7 +317,7 @@ spec: args: - --token-file=/config/token - --kas-address - - grpc://host.docker.internal:5005 # {"$openapi":"kas-address"} + - wss://gitlab.host.tld:443/-/kubernetes-agent volumeMounts: - name: token-volume mountPath: /config @@ -331,7 +392,9 @@ 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. +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). Each time you commit and push a change to this file, the Agent logs the change: @@ -341,7 +404,7 @@ Each time you commit and push a change to this file, the Agent logs the change: #### Example `manifest.yaml` file -This file creates a simple NGINX deployment. +This file creates an NGINX deployment. ```yaml apiVersion: apps/v1 @@ -368,7 +431,128 @@ spec: ## Example projects +The following example projects can help you get started with the Kubernetes Agent. + +### Simple NGINX deployment + This basic GitOps example deploys NGINX: - [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent) - [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) + +### Deploying GitLab Runner with the Agent + +These instructions assume that the Agent is already set up as described in the +[Get started with GitOps](#get-started-with-gitops-and-the-gitlab-agent): + +1. Check the possible + [Runner chart YAML values](https://gitlab.com/gitlab-org/charts/gitlab-runner/blob/master/values.yaml) + on the Runner chart documentation, and create a `runner-chart-values.yaml` file + with the configuration that fits your needs, such as: + + ```yaml + ## The GitLab Server URL (with protocol) that want to register the runner against + ## ref: https://docs.gitlab.com/runner/commands/README.html#gitlab-runner-register + ## + gitlabUrl: https://gitlab.my.domain.com/ + + ## The Registration Token for adding new Runners to the GitLab Server. This must + ## be retrieved from your GitLab Instance. + ## ref: https://docs.gitlab.com/ce/ci/runners/README.html + ## + runnerRegistrationToken: "XXXXXXYYYYYYZZZZZZ" + + ## For RBAC support: + rbac: + create: true + + ## Run all containers with the privileged flag enabled + ## This will allow the docker:dind image to run if you need to run Docker + ## commands. Please read the docs before turning this on: + ## ref: https://docs.gitlab.com/runner/executors/kubernetes.html#using-dockerdind + runners: + privileged: true + ``` + +1. Create a single manifest file to install the Runner chart with your cluster agent: + + ```shell + helm template --namespace gitlab gitlab-runner -f runner-chart-values.yaml gitlab/gitlab-runner > manifest.yaml + ``` + +1. Push your `manifest.yaml` to your manifest repository. + +## Troubleshooting + +If you face any issues while using GitLab Kubernetes Agent, you can read the +service logs with the following commands: + +- KAS pod logs - Tail these logs with the + `kubectl logs -f -l=app=kas -n <YOUR-GITLAB-NAMESPACE>` + command. In Omnibus GitLab, the logs reside in `/var/log/gitlab/gitlab-kas/`. +- Agent pod logs - Tail these logs with the + `kubectl logs -f -l=app=gitlab-agent -n <YOUR-DESIRED-NAMESPACE>` command. + +### KAS logs - GitOps: failed to get project info + +```plaintext +{"level":"warn","time":"2020-10-30T08:37:26.123Z","msg":"GitOps: failed to get project info","agent_id":4,"project_id":"root/kas-manifest001","error":"error kind: 0; status: 404"} +``` + +This error is shown if the specified manifest project `root/kas-manifest001` +doesn't exist, or if a project is private. To fix it, make sure the project exists +and its visibility is [set to public](../../../public_access/public_access.md). + +### KAS logs - Configuration file not found + +```plaintext +time="2020-10-29T04:44:14Z" level=warning msg="Config: failed to fetch" agent_id=2 error="configuration file not found: \".gitlab/agents/test-agent/config.yaml\ +``` + +This error is shown if the path to the configuration project was specified incorrectly, +or if the path to `config.yaml` inside the project is not valid. + +### Agent logs - Transport: Error while dialing failed to WebSocket dial + +```plaintext +{"level":"warn","time":"2020-11-04T10:14:39.368Z","msg":"GetConfiguration failed","error":"rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://gitlab-kas:443/-/kubernetes-agent\\\": dial tcp: lookup gitlab-kas on 10.60.0.10:53: no such host\""} +``` + +This error is shown if there are some connectivity issues between the address +specified as `kas-address`, and your Agent pod. To fix it, make sure that you +specified the `kas-address` correctly. + +### Agent logs - ValidationError(Deployment.metadata + +```plaintext +{"level":"info","time":"2020-10-30T08:56:54.329Z","msg":"Synced","project_id":"root/kas-manifest001","resource_key":"apps/Deployment/kas-test001/nginx-deployment","sync_result":"error validating data: [ValidationError(Deployment.metadata): unknown field \"replicas\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"selector\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"template\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta]"} +``` + +This error is shown if your `manifest.yaml` file is malformed, and Kubernetes can't +create specified objects. Make sure that your `manifest.yaml` file is valid. You +may try using it to create objects in Kubernetes directly for more troubleshooting. + +### Agent logs - Error while dialing failed to WebSocket dial: failed to send handshake request + +```plaintext +{"level":"warn","time":"2020-10-30T09:50:51.173Z","msg":"GetConfiguration failed","error":"rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent\\\": net/http: HTTP/1.x transport connection broken: malformed HTTP response \\\"\\\\x00\\\\x00\\\\x06\\\\x04\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x05\\\\x00\\\\x00@\\\\x00\\\"\""} +``` + +This error is shown if you configured `wss` as `kas-address` on the agent side, +but KAS on the server side is not available via `wss`. To fix it, make sure the +same schemes are configured on both sides. + +It's not possible to set the `grpc` scheme due to the issue +[It is not possible to configure KAS to work with `grpc` without directly editing GitLab KAS deployment](https://gitlab.com/gitlab-org/gitlab/-/issues/276888). To use `grpc` while the +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 + +```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\""} +``` + +This error is shown if the version of the agent is newer that the version of KAS. +To fix it, make sure that both `agentk` and KAS use the same versions. diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 4e0e2991acb..67a53fa773f 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -64,21 +64,35 @@ supported by GitLab before installing any of the applications. > - 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. -GitLab's integration uses Helm 2 with a local -[Tiller](https://v2.helm.sh/docs/glossary/#tiller) server for managing -applications. 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. This server can now be safely removed. +- 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. @@ -93,7 +107,7 @@ The chart used to install this application depends on the version of GitLab used - 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://gi2wthub.com/helm/charts/tree/master/stable/cert-manager) +- 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 @@ -625,10 +639,13 @@ To install applications using GitLab CI/CD: - template: Managed-Cluster-Applications.gitlab-ci.yml ``` - The job provided by this template connects to the cluster using tools provided + The job provided by this template connects to the `*` (default) cluster using tools provided in a custom Docker image. It requires that you have a runner registered with the Docker, Kubernetes, or Docker Machine executor. + To install to a specific cluster, read + [Use the template with a custom environment](#use-the-template-with-a-custom-environment). + 1. Add a `.gitlab/managed-apps/config.yaml` file to define which applications you would like to install. Define the `installed` key as `true` to install the application and `false` to uninstall the @@ -647,6 +664,47 @@ 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). +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 +fail. Upgrade to GitLab 13.6, or alternatively, you can +use the following `.gitlab-ci.yml`, which has been tested on GitLab +13.5: + +```yaml +include: + - template: Managed-Cluster-Applications.gitlab-ci.yml + +apply: + image: "registry.gitlab.com/gitlab-org/cluster-integration/cluster-applications:v0.34.1" +``` + +### Use the template with a custom environment + +If you only want apps to be installed on a specific cluster, or if your cluster's +scope does not match `production`, you can override the environment name in your `.gitlab-ci.yml` +file: + +```yaml +include: + - template: Managed-Cluster-Applications.gitlab-ci.yml + +apply: + except: + variables: + - '$CI_JOB_NAME == "apply"' + +.managed-apps: + extends: apply + +example-install: + extends: .managed-apps + environment: + name: example/production +``` + ### Important notes Note the following: @@ -717,7 +775,7 @@ certManager: You can customize the installation of cert-manager by defining a `.gitlab/managed-apps/cert-manager/values.yaml` file in your cluster management project. Refer to the -[chart](https://hub.helm.sh/charts/jetstack/cert-manager) for the +[chart](https://github.com/jetstack/cert-manager) for the available configuration options. Support for installing the Cert Manager managed application is provided by the @@ -797,7 +855,7 @@ least 2 people from the ### Install PostHog using GitLab CI/CD -[PostHog](https://www.posthog.com) 🦔 is a developer-friendly, open-source product analytics platform. +[PostHog](https://posthog.com) 🦔 is a developer-friendly, open-source product analytics platform. To install PostHog into the `gitlab-managed-apps` namespace of your cluster, define the `.gitlab/managed-apps/config.yaml` file with: @@ -954,15 +1012,15 @@ CAUTION: **Caution:** 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/stable/troubleshooting/#ensure-pod-is-managed-by-cilium) +[managed](https://docs.cilium.io/en/v1.8/operations/troubleshooting/#ensure-managed-pod) by the correct networking plugin. NOTE: **Note:** Major upgrades might require additional setup steps. For more information, see -the official [upgrade guide](https://docs.cilium.io/en/stable/install/upgrade/). +the official [upgrade guide](https://docs.cilium.io/en/v1.8/operations/upgrade/). By default, Cilium's -[audit mode](https://docs.cilium.io/en/v1.8/gettingstarted/policy-creation/?highlight=policy-audit#enable-policy-audit-mode) +[audit mode](https://docs.cilium.io/en/v1.8/gettingstarted/policy-creation/#enable-policy-audit-mode) is enabled. In audit mode, Cilium doesn't drop disallowed packets. You can use `policy-verdict` log to observe policy-related decisions. You can disable audit mode by adding the following to diff --git a/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_3_1.png b/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_3_1.png Binary files differdeleted file mode 100644 index 89f4e917567..00000000000 --- a/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_3_1.png +++ /dev/null diff --git a/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_6.png b/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_6.png Binary files differnew file mode 100644 index 00000000000..b2ac4f95e0d --- /dev/null +++ b/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_6.png diff --git a/doc/user/compliance/compliance_dashboard/index.md b/doc/user/compliance/compliance_dashboard/index.md index 5c05725d95b..151c61b50d8 100644 --- a/doc/user/compliance/compliance_dashboard/index.md +++ b/doc/user/compliance/compliance_dashboard/index.md @@ -17,7 +17,7 @@ for merging into production. To access the Compliance Dashboard for a group, navigate to **{shield}** **Security & Compliance > Compliance** on the group's menu. - + NOTE: **Note:** The Compliance Dashboard shows only the latest MR on each project. @@ -63,14 +63,24 @@ This column has four states: If you do not see the success icon in your Compliance dashboard; please review the above criteria for the Merge Requests project to make sure it complies with the separation of duties described above. -## Chain of Custody report +## Chain of Custody report **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213364) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. The Chain of Custody report allows customers to export a list of merge commits within the group. The data provides a comprehensive view with respect to merge commits. It includes the merge commit SHA, merge request author, merge request ID, merge user, pipeline ID, group name, project name, and merge request approvers. +Depending on the merge strategy, the merge commit SHA can either be a merge commit, squash commit or a diff head commit. To download the Chain of Custody report, navigate to **{shield}** **Security & Compliance > Compliance** on the group's menu and click **List of all merge commits** +### Commit-specific Chain of Custody Report **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267629) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. + +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:** 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/license_compliance/img/license_compliance_add_license_v13_0.png b/doc/user/compliance/license_compliance/img/license_compliance_add_license_v13_0.png Binary files differdeleted file mode 100644 index 1366c569f17..00000000000 --- a/doc/user/compliance/license_compliance/img/license_compliance_add_license_v13_0.png +++ /dev/null diff --git a/doc/user/compliance/license_compliance/img/license_compliance_decision_v13_0.png b/doc/user/compliance/license_compliance/img/license_compliance_decision_v13_0.png Binary files differdeleted file mode 100644 index 42bf8bd1ed5..00000000000 --- a/doc/user/compliance/license_compliance/img/license_compliance_decision_v13_0.png +++ /dev/null diff --git a/doc/user/compliance/license_compliance/img/license_compliance_pipeline_tab_v13_0.png b/doc/user/compliance/license_compliance/img/license_compliance_pipeline_tab_v13_0.png Binary files differdeleted file mode 100644 index 49c66832f00..00000000000 --- a/doc/user/compliance/license_compliance/img/license_compliance_pipeline_tab_v13_0.png +++ /dev/null diff --git a/doc/user/compliance/license_compliance/img/license_compliance_search_v13_0.png b/doc/user/compliance/license_compliance/img/license_compliance_search_v13_0.png Binary files differdeleted file mode 100644 index 5a4216dd645..00000000000 --- a/doc/user/compliance/license_compliance/img/license_compliance_search_v13_0.png +++ /dev/null diff --git a/doc/user/compliance/license_compliance/img/license_compliance_settings_v13_0.png b/doc/user/compliance/license_compliance/img/license_compliance_settings_v13_0.png Binary files differdeleted file mode 100644 index 91f1eec2a23..00000000000 --- a/doc/user/compliance/license_compliance/img/license_compliance_settings_v13_0.png +++ /dev/null diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 894c0e14862..65c009f947f 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -37,10 +37,7 @@ compliance report will be shown properly.  -If you are a project or group Maintainer, you can click on a license to be given -the choice to allow it or deny it. - - +You can click on a license to see more information. When GitLab detects a **Denied** license, you can view it in the [license list](#license-list). @@ -62,7 +59,6 @@ The following languages and package managers are supported. | .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)| -| Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage) | | [License Finder](https://github.com/pivotal/LicenseFinder) | NOTE: **Note:** Java 8 and Gradle 1.x projects are not supported. @@ -78,6 +74,7 @@ which means that the reported licenses might be incomplete or inaccurate. | 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)| @@ -144,7 +141,7 @@ License Compliance can be configured using environment variables. | `ASDF_PYTHON_VERSION` | no | Version of Python to use for the scan. | | `ASDF_RUBY_VERSION` | no | Version of Ruby to use for the scan. | | `GRADLE_CLI_OPTS` | no | Additional arguments for the gradle executable. If not supplied, defaults to `--exclude-task=test`. | -| `LICENSE_FINDER_CLI_OPTS` | no | Additional arguments for the `license_finder` executable. For example, if your project has both Golang and Ruby code stored in different directories and you want to only scan the Ruby code, you can update your `.gitlab-ci-yml` template to specify which project directories to scan, like `LICENSE_FINDER_CLI_OPTS: '--debug --aggregate-paths=. ruby'`. | +| `LICENSE_FINDER_CLI_OPTS` | no | Additional arguments for the `license_finder` executable. For example, if you have multiple projects in nested directories, you can update your `.gitlab-ci-yml` template to specify a recursive scan, like `LICENSE_FINDER_CLI_OPTS: '--recursive'`. | | `LM_JAVA_VERSION` | no | Version of Java. If set to `11`, Maven and Gradle use Java 11 instead of Java 8. | | `LM_PYTHON_VERSION` | no | Version of Python. If set to `3`, dependencies are installed using Python 3 instead of Python 2.7. | | `MAVEN_CLI_OPTS` | no | Additional arguments for the mvn executable. If not supplied, defaults to `-DskipTests`. | @@ -444,7 +441,7 @@ documentation for a list of settings that you can apply. The `license_scanning` job runs in a [Debian 10](https://www.debian.org/releases/buster/) Docker image. The supplied image ships with some build tools such as [CMake](https://cmake.org/) and [GCC](https://gcc.gnu.org/). However, not all project types are supported by default. To install additional tools needed to -compile dependencies, use a [`before_script`](../../../ci/yaml/README.md#before_script-and-after_script) +compile dependencies, use a [`before_script`](../../../ci/yaml/README.md#before_script) to install the necessary build tools using the [`apt`](https://wiki.debian.org/PackageManagementTools) package manager. For a comprehensive list, consult [the Conan documentation](https://docs.conan.io/en/latest/introduction.html#all-platforms-all-build-systems-and-compilers). @@ -775,11 +772,11 @@ or using the appropriate [`ASDF_<tool>_VERSION`](https://asdf-vm.com/#/core-conf activate the appropriate version. For example, the following `.tool-versions` file will activate version `12.16.3` of [Node.js](https://nodejs.org/) -and version `2.6.6` of [Ruby](https://www.ruby-lang.org/). +and version `2.7.2` of [Ruby](https://www.ruby-lang.org/). ```plaintext nodejs 12.16.3 -ruby 2.6.6 +ruby 2.7.2 ``` The next example shows how to activate the same versions of the tools mentioned above by using environment variables defined in your @@ -792,7 +789,7 @@ include: license_scanning: variables: ASDF_NODEJS_VERSION: '12.16.3' - ASDF_RUBY_VERSION: '2.6.6' + ASDF_RUBY_VERSION: '2.7.2' ``` A full list of variables can be found in [environment variables](#available-variables). diff --git a/doc/user/discussions/img/discussions_resolved.png b/doc/user/discussions/img/discussions_resolved.png Binary files differdeleted file mode 100644 index 3fd496f6da5..00000000000 --- a/doc/user/discussions/img/discussions_resolved.png +++ /dev/null diff --git a/doc/user/discussions/img/mr_review_unresolve2.png b/doc/user/discussions/img/mr_review_unresolve2.png Binary files differdeleted file mode 100644 index 79da61bb556..00000000000 --- a/doc/user/discussions/img/mr_review_unresolve2.png +++ /dev/null diff --git a/doc/user/discussions/img/new_issue_for_discussion.png b/doc/user/discussions/img/new_issue_for_discussion.png Binary files differdeleted file mode 100644 index 819d872a9a2..00000000000 --- a/doc/user/discussions/img/new_issue_for_discussion.png +++ /dev/null diff --git a/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved.png b/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved.png Binary files differdeleted file mode 100644 index 928c7d33898..00000000000 --- a/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved.png +++ /dev/null diff --git a/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved_msg.png b/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved_msg.png Binary files differdeleted file mode 100644 index 9044926b0eb..00000000000 --- a/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved_msg.png +++ /dev/null diff --git a/doc/user/discussions/img/preview_issue_for_discussion.png b/doc/user/discussions/img/preview_issue_for_discussion.png Binary files differdeleted file mode 100644 index 30c273ca4c5..00000000000 --- a/doc/user/discussions/img/preview_issue_for_discussion.png +++ /dev/null diff --git a/doc/user/discussions/img/preview_issue_for_discussions.png b/doc/user/discussions/img/preview_issue_for_discussions.png Binary files differdeleted file mode 100644 index 3d906e1b0b0..00000000000 --- a/doc/user/discussions/img/preview_issue_for_discussions.png +++ /dev/null diff --git a/doc/user/discussions/img/resolve_discussion_button.png b/doc/user/discussions/img/resolve_discussion_button.png Binary files differdeleted file mode 100644 index ab454f661e0..00000000000 --- a/doc/user/discussions/img/resolve_discussion_button.png +++ /dev/null diff --git a/doc/user/discussions/img/resolve_discussion_issue_notice.png b/doc/user/discussions/img/resolve_discussion_issue_notice.png Binary files differdeleted file mode 100644 index ed50dc1de91..00000000000 --- a/doc/user/discussions/img/resolve_discussion_issue_notice.png +++ /dev/null diff --git a/doc/user/discussions/img/resolve_discussion_open_issue.png b/doc/user/discussions/img/resolve_discussion_open_issue.png Binary files differdeleted file mode 100644 index 9d0a14671d6..00000000000 --- a/doc/user/discussions/img/resolve_discussion_open_issue.png +++ /dev/null diff --git a/doc/user/feature_highlight.md b/doc/user/feature_highlight.md index 9b52c178493..31eb0e6375d 100644 --- a/doc/user/feature_highlight.md +++ b/doc/user/feature_highlight.md @@ -1,3 +1,9 @@ +--- +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 +--- + # Feature highlight > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/16379) in GitLab 10.5 diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index ec0c207e190..54f14c71c93 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -1,3 +1,9 @@ +--- +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 +--- + # GitLab.com settings In this page you will find information about the settings that are used on @@ -85,6 +91,7 @@ which is part of [GitLab CI/CD](#gitlab-cicd). ## GitLab CI/CD Below are the current settings regarding [GitLab CI/CD](../../ci/README.md). +Any settings or feature limits not listed here are using the defaults listed in the related documentation. | Setting | GitLab.com | Default | | ----------- | ----------------- | ------------- | @@ -94,7 +101,6 @@ Below are the current settings regarding [GitLab CI/CD](../../ci/README.md). | [Max jobs in active pipelines](../../administration/instance_limits.md#number-of-jobs-in-active-pipelines) | `500` for Free tier, unlimited otherwise | Unlimited | [Max CI/CD subscriptions to a project](../../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project) | `2` | Unlimited | | [Max pipeline schedules in projects](../../administration/instance_limits.md#number-of-pipeline-schedules) | `10` for Free tier, `50` for all paid tiers | Unlimited | -| [Max number of instance level variables](../../administration/instance_limits.md#number-of-instance-level-variables) | `25` | `25` | | [Scheduled Job Archival](../../user/admin_area/settings/continuous_integration.md#archive-jobs) | 3 months | Never | | Max test cases per [unit test report](../../ci/unit_test_reports.md) | `500_000` | Unlimited | @@ -107,7 +113,7 @@ or over the repository size limit, you can [reduce your repository size with Git | Setting | GitLab.com | Default | | ----------- | ----------- | ------------- | -| Repository size including LFS | 10 GB | Unlimited | +| [Repository size including LFS](../admin_area/settings/account_and_limit_settings.md) | 10 GB | Unlimited | | Maximum import size | 5 GB | 50 MB | NOTE: **Note:** @@ -146,7 +152,7 @@ Shared runners provided by GitLab are **not** configurable. Consider [installing 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 2000 CI minutes per month per group for private projects. More minutes +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/). @@ -264,26 +270,23 @@ sentry_dsn = "X" ### Windows shared runners (beta) -The Windows shared runners are currently in -[beta](https://about.gitlab.com/handbook/product/#beta) and should not be used -for production workloads. +The Windows shared runners are in [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) +and shouldn't be used for production workloads. -During the beta period, the -[shared runner pipeline quota](../admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota) -will apply for groups and projects in the same way as Linux runners. -This may change when the beta period ends, as discussed in this -[related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30834). +During this beta period, the [shared runner pipeline quota](../admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota) +applies for groups and projects in the same manner as Linux runners. This may +change when the beta period ends, as discussed in this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30834). -Windows shared runners on GitLab.com automatically autoscale by -launching virtual machines on the Google Cloud Platform. This solution uses -a new [autoscaling driver](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/tree/master/docs/readme.md) +Windows shared runners on GitLab.com autoscale by launching virtual machines on +the Google Cloud Platform. This solution uses an +[autoscaling driver](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/tree/master/docs/readme.md) developed by GitLab for the [custom executor](https://docs.gitlab.com/runner/executors/custom.html). -Windows shared runners execute your CI/CD jobs on `n1-standard-2` instances with 2 -vCPUs and 7.5GB RAM. You can find a full list of available Windows packages in the -[package documentation](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/gcp/windows-containers/blob/master/cookbooks/preinstalled-software/README.md). +Windows shared runners execute your CI/CD jobs on `n1-standard-2` instances with +2 vCPUs and 7.5 GB RAM. You can find a full list of available Windows packages in +the [package documentation](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/gcp/windows-containers/blob/master/cookbooks/preinstalled-software/README.md). We want to keep iterating to get Windows shared runners in a stable state and -[generally available](https://about.gitlab.com/handbook/product/#generally-available-ga). +[generally available](https://about.gitlab.com/handbook/product/gitlab-the-product/#generally-available-ga). You can follow our work towards this goal in the [related epic](https://gitlab.com/groups/gitlab-org/-/epics/2162). @@ -292,7 +295,7 @@ You can follow our work towards this goal in the The full contents of our `config.toml` are: NOTE: **Note:** -Settings that are not public are shown as `X`. +Settings that aren't public are shown as `X`. ```toml concurrent = X @@ -406,7 +409,7 @@ test: - 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 - commands to [`before_script`](../../ci/yaml/README.md#before_script-and-after_script) or [`script`](../../ci/yaml/README.md#script) to install the required + commands to [`before_script`](../../ci/yaml/README.md#before_script) or [`script`](../../ci/yaml/README.md#script) to install the required software. Note that each job runs on a new VM instance, so the installation of additional software packages needs to be repeated for each job in your pipeline. @@ -429,7 +432,7 @@ and the following environment variables: | `SIDEKIQ_MEMORY_KILLER_CHECK_INTERVAL` | - | `3` | | `SIDEKIQ_MEMORY_KILLER_GRACE_TIME` | - | `900` | | `SIDEKIQ_MEMORY_KILLER_SHUTDOWN_WAIT` | - | `30` | -| `SIDEKIQ_LOG_ARGUMENTS` | `1` | - | +| `SIDEKIQ_LOG_ARGUMENTS` | `1` | `1` | NOTE: **Note:** The `SIDEKIQ_MEMORY_KILLER_MAX_RSS` setting is `16000000` on Sidekiq import @@ -627,6 +630,13 @@ You can view more information in our runbooks such as: - Our [current log retention policies](https://gitlab.com/gitlab-com/runbooks/-/tree/master/docs/logging#retention) - A [diagram of our logging infrastructure](https://gitlab.com/gitlab-com/runbooks/-/tree/master/docs/logging#logging-infrastructure-overview) +### Job Logs + +By default, GitLab does not expire job logs. Job logs are retained indefinitely, +and can't be configured on GitLab.com to expire. You can erase job logs +[manually with the Jobs API](../../api/jobs.md#erase-a-job) or by +[deleting a pipeline](../../ci/pipelines/index.md#delete-a-pipeline). + ## GitLab.com at scale In addition to the GitLab Enterprise Edition Omnibus install, GitLab.com uses diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index a689b7c380b..cf55a1f688b 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -1,7 +1,7 @@ --- type: reference stage: Manage -group: Analytics +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 --- # Contribution Analytics **(STARTER)** diff --git a/doc/user/group/dependency_proxy/img/group_dependency_proxy.png b/doc/user/group/dependency_proxy/img/group_dependency_proxy.png Binary files differdeleted file mode 100644 index 035aff0b6c4..00000000000 --- a/doc/user/group/dependency_proxy/img/group_dependency_proxy.png +++ /dev/null diff --git a/doc/user/group/epics/img/containing_epic.png b/doc/user/group/epics/img/containing_epic.png Binary files differindex dc13d55e2bc..1ba5a30708f 100644 --- a/doc/user/group/epics/img/containing_epic.png +++ b/doc/user/group/epics/img/containing_epic.png diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index f380b36cc00..e98c4b416fe 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Plan -group: Portfolio Management +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 --- diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index c09032bffb2..5895b611bb3 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -1,7 +1,7 @@ --- type: howto stage: Plan -group: Portfolio Management +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 --- @@ -23,9 +23,9 @@ selected group. From your group page: To create an epic from the epic list, in a group: 1. Go to **{epic}** **Epics**. -1. Click **New epic**. +1. Select **New epic**. 1. Enter a descriptive title. -1. Click **Create epic**. +1. Select **Create epic**. ### Access the New Epic form @@ -33,8 +33,8 @@ To create an epic from the epic list, in a group: 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, click **New Epic**. -- From anywhere, in the top menu, click **plus** (**{plus-square}**) **> New epic**. +- From an epic in your group, select **New Epic**. +- From anywhere, in the top menu, select **plus** (**{plus-square}**) **> New epic**.  @@ -63,13 +63,13 @@ After you create an epic, you can edit change the following details: To edit an epic's title or description: -1. Click the **Edit title and description** **{pencil}** button. +1. Select the **Edit title and description** **{pencil}** button. 1. Make your changes. -1. Click **Save changes**. +1. Select **Save changes**. To edit an epics' start date, due date, or labels: -1. Click **Edit** next to each section in the epic sidebar. +1. Select **Edit** next to each section in the epic sidebar. 1. Select the dates or labels for your epic. ## Bulk-edit epics @@ -82,7 +82,7 @@ You can edit multiple epics at once. To learn how to do it, visit 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, click the **Delete** button to delete the epic. +When editing the description of an epic, select the **Delete** button to delete the epic. A modal appears to confirm your action. Deleting an epic releases all existing issues from their associated epic in the system. @@ -92,7 +92,7 @@ Deleting an epic releases all existing issues from their associated epic in the Whenever you decide that there is no longer need for that epic, close the epic by: -- Clicking the **Close epic** button. +- Selecting the **Close epic** button.  @@ -129,7 +129,7 @@ that of Issues and Merge Requests) based on following parameters:  -To search, go to the list of epics and click the field **Search or filter results**. +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 text to search by epic title or description. When done, press <kbd>Enter</kbd> on your keyboard to filter the list. @@ -168,7 +168,7 @@ To make an epic confidential: ### Add a new issue to an epic -You can add an existing issue to an epic, or, create a new issue that's +You can add an existing issue to an epic, or create a new issue that's automatically added to the epic. #### Add an existing issue to an epic @@ -183,15 +183,15 @@ current parent. To add a new issue to an epic: -1. Click the **Add** dropdown button. -1. Click **Add a new issue**. +1. On the epic's page, under **Epics and Issues**, select the **Add** dropdown button. +1. Select **Add an existing issue**. 1. Identify the issue to be added, using either of the following methods: - Paste the link of the issue. - Search for the desired issue by entering part of the issue's title, then selecting the desired match (introduced in [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/9126)). If there are multiple issues to be added, press <kbd>Spacebar</kbd> and repeat this step. -1. Click **Add**. +1. Select **Add**. #### Create an issue from an epic @@ -202,11 +202,11 @@ while dividing work into smaller parts. To create an issue from an epic: -1. On the epic's page, under **Epics and Issues**, click the **Add** dropdown button and select - **Create new issue**. +1. On the epic's page, under **Epics and Issues**, select the **Add** dropdown button. +1. Select **Add a new issue**. 1. Under **Title**, enter the title for the new issue. 1. From the **Project** dropdown, select the project in which the issue should be created. -1. Click **Create issue**. +1. Select **Create issue**. ### Remove an issue from an epic @@ -215,9 +215,9 @@ After you remove an issue from an epic, the issue will no longer be associated w To remove an issue from an epic: -1. Click the **Remove** (**{close}**) button next to the issue you want to remove. +1. Select the **Remove** (**{close}**) button next to the issue you want to remove. The **Remove issue** warning appears. -1. Click **Remove**. +1. Select **Remove**.  @@ -285,15 +285,15 @@ For more on epic templates, see [Epic Templates - Repeatable sets of issues](htt To add a child epic to an epic: -1. Click the **Add** dropdown button. -1. Click **Add a new epic**. +1. Select the **Add** dropdown button. +1. Select **Add a new epic**. 1. Identify the epic to be added, using either of the following methods: - Paste the link of the epic. - Search for the desired issue by entering part of the epic's title, then selecting the desired match (introduced in [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/9126)). If there are multiple epics to be added, press <kbd>Spacebar</kbd> and repeat this step. -1. Click **Add**. +1. Select **Add**. ### Move child epics between epics @@ -325,5 +325,5 @@ To reorder child epics assigned to an epic: To remove a child epic from a parent epic: -1. Click on the <kbd>x</kbd> button in the parent epic's list of epics. -1. Click **Remove** in the **Remove epic** warning message. +1. Select the <kbd>x</kbd> button in the parent epic's list of epics. +1. Select **Remove** in the **Remove epic** warning message. diff --git a/doc/user/group/img/add_new_members.png b/doc/user/group/img/add_new_members.png Binary files differdeleted file mode 100644 index 8bd9e2374bc..00000000000 --- a/doc/user/group/img/add_new_members.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..4255eeb72c7 --- /dev/null +++ b/doc/user/group/img/add_new_members_v13_6.png diff --git a/doc/user/group/img/create_new_project_from_group.png b/doc/user/group/img/create_new_project_from_group.png Binary files differdeleted file mode 100644 index df98091334c..00000000000 --- a/doc/user/group/img/create_new_project_from_group.png +++ /dev/null diff --git a/doc/user/group/img/create_new_project_from_group_v13_6.png b/doc/user/group/img/create_new_project_from_group_v13_6.png Binary files differnew file mode 100644 index 00000000000..72d19817686 --- /dev/null +++ b/doc/user/group/img/create_new_project_from_group_v13_6.png diff --git a/doc/user/group/img/manual_permissions_v13_1.png b/doc/user/group/img/manual_permissions_v13_1.png Binary files differdeleted file mode 100644 index 0ada9a4839c..00000000000 --- a/doc/user/group/img/manual_permissions_v13_1.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 differnew file mode 100644 index 00000000000..6d26061b049 --- /dev/null +++ b/doc/user/group/img/manual_permissions_v13_6.png diff --git a/doc/user/group/img/restrict-by-email.gif b/doc/user/group/img/restrict-by-email.gif Binary files differnew file mode 100644 index 00000000000..d1ebeb07a0a --- /dev/null +++ b/doc/user/group/img/restrict-by-email.gif diff --git a/doc/user/group/img/restrict-by-ip.gif b/doc/user/group/img/restrict-by-ip.gif Binary files differnew file mode 100644 index 00000000000..6292a58e748 --- /dev/null +++ b/doc/user/group/img/restrict-by-ip.gif diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 2c838724cb3..e09c685147a 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -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. @@ -235,7 +235,7 @@ There are two different ways to add a new project to a group: - Select a group, and then click **New project**. You can then continue [creating your project](../../gitlab-basics/create-project.md). -  +  - While you are creating a project, select a group namespace you've already created from the dropdown menu. @@ -375,9 +375,9 @@ In GitLab [8.15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/822) and 1. Go to your group's **Members** page. 1. Select the pencil icon in the row for the user you are editing. -1. Select the orange `Change permissions` button. +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. @@ -394,13 +394,6 @@ milestones. ## Group wikis **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. -> - 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-group-wikis). - -CAUTION: **Warning:** -This feature might not be available to you. Check the **version history** note above for details. Group wikis work the same way as [project wikis](../project/wiki/index.md), please refer to those docs for details on usage. @@ -414,27 +407,13 @@ There are a few limitations compared to project wikis: - Local Git access is not supported yet. - 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 + repository moves API. -You can follow [this epic](https://gitlab.com/groups/gitlab-org/-/epics/2782) for updates. - -### Enable or disable group wikis **(CORE ONLY)** - -Group wikis are under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can opt to disable it for your instance. - -To enable it: +For updates, you can follow: -```ruby -Feature.enable(:group_wikis) -``` - -To disable it: - -```ruby -Feature.disable(:group_wikis) -``` +- [The epic tracking feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). +- [The issue for adding the ability to move group wikis using the API](https://gitlab.com/gitlab-org/gitlab/-/issues/219003). ## Group Security Dashboard **(ULTIMATE)** @@ -513,6 +492,23 @@ 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. +### Group repository settings + +You can change settings that are specific to repositories in your group. + +#### Custom initial branch name **(CORE ONLY)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43290) in GitLab 13.6. + +By default, when you create a new project in GitLab, the initial branch is called `master`. +For groups, a group administrator can customize the initial branch name to something +else. This way, every new project created under that group from then on will start from the custom branch name rather than `master`. To do so: + +1. Go to the **Group page > Settings > Repository** and expand **Default initial + branch name**. +1. Change the default initial branch to a custom name of your choice. +1. **Save Changes**. + ### Remove a group To remove a group and its contents: @@ -525,7 +521,10 @@ To remove a group and its contents: This action either: - Removes the group, and also queues a background job to delete all projects in that group. -- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium or Silver](https://about.gitlab.com/pricing/premium/) or higher tiers, marks a group for deletion. The deletion will happen 7 days later by default, but this can be changed in the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). +- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium or Silver](https://about.gitlab.com/pricing/premium/) or higher tiers, this action adds a background job to mark a group for deletion. By default, the job schedules the deletion 7 days in the future. You can modify this waiting period through the [instance settings](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). + +Since [GitLab 13.6](https://gitlab.com/gitlab-org/gitlab/-/issues/39504), if the user who sets up the deletion leaves or is otherwise removed from the group before the +actual deletion happens, the job is cancelled, and the group is no longer scheduled for deletion. ### Restore a group **(PREMIUM)** @@ -608,6 +607,8 @@ To enable this feature: 1. Expand the **Permissions, LFS, 2FA** section, and enter IP address ranges into **Allow access to the following IP addresses** field. 1. Click **Save changes**. + + #### Allowed domain restriction **(PREMIUM)** >- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7297) in [GitLab Premium and Silver](https://about.gitlab.com/pricing/) 12.2. @@ -636,6 +637,8 @@ To enable this feature: 1. Expand the **Permissions, LFS, 2FA** section, and enter the domain names into **Restrict membership by email** field. 1. Click **Save changes**. + + This will enable the domain-checking for all new users added to the group from this moment on. #### Group file templates **(PREMIUM)** @@ -742,6 +745,7 @@ To enable prevent project forking: - **Audit Events**: View [Audit Events](../../administration/audit_events.md) for the group. **(STARTER ONLY)** - **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)** @@ -794,7 +798,7 @@ With [GitLab Issue Analytics](issues_analytics/index.md), you can see a bar char 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. -## Dependency Proxy **(PREMIUM)** +## 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 dd1f8914392..50dfb0e5ccd 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Manage -group: Analytics +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 --- diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index 69512f90fca..dea1eaba819 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -1,7 +1,7 @@ --- type: reference stage: Manage -group: Analytics +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 --- diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 2eb50f07de3..90050e217ee 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - It's enabled on GitLab.com. > - It's able to be enabled or disabled per-group. > - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-iterations). **(CORE ONLY)** +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-iterations). **(STARTER ONLY)** Iterations are a way to track issues over a period of time. This allows teams to track velocity and volatility metrics. Iterations can be used with [milestones](../../project/milestones/index.md) @@ -50,7 +50,7 @@ To create an iteration: ## Edit an iteration -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218277) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218277) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2. NOTE: **Note:** You need Developer [permissions](../../permissions.md) or higher to edit an iteration. @@ -73,7 +73,23 @@ An iteration report displays a list of all the issues assigned to an iteration a To view an iteration report, go to the iterations list page and click an iteration's title. -## Disable Iterations **(CORE ONLY)** +### 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)** + +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). + +Burndown charts help track completion progress of total scope, and burnup charts track the daily +total count and weight of issues added to and completed in a given timebox. + +## Disable iterations **(STARTER ONLY)** GitLab Iterations feature is deployed with a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) @@ -97,6 +113,30 @@ 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 c9a10146440..fe5e7979592 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -12,6 +12,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w CAUTION: **Warning:** This feature might not be available to you. Check the **version history** note above for details. +## Latest project test coverage list + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267624) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. + +To see the latest code coverage for each project in your group: + +1. Go to **Analytics > Repositories** in the group (not from a project). +1. In the **Latest test coverage results** section, use the **Select projects** dropdown to choose the projects you want to check. + +## Download historic test coverage data + +> [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: 1. Go to your group's **Analytics > Repositories** page diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index c185055f6b2..f9d49c1236e 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -1,7 +1,7 @@ --- type: reference stage: Plan -group: Portfolio Management +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 --- diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md index 7497d036d31..50f062bafa9 100644 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ b/doc/user/group/saml_sso/group_managed_accounts.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w CAUTION: **Caution:** 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/gitlab-org/gitlab/-/issues/218631) that does not require separate accounts. +[identity model](https://gitlab.com/groups/gitlab-org/-/epics/4345) that does not require separate accounts. We recommend that group administrators who haven't yet implemented this feature wait for the new solution. diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 3cb566c7f77..94d2c9afb24 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -88,8 +88,6 @@ We intend to add a similar SSO requirement for [Git and API activity](https://gi 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. -To disallow users to contribute outside of the top-level group, please see [Group Managed Accounts](group_managed_accounts.md). - ## Providers NOTE: **Note:** @@ -107,7 +105,7 @@ When [configuring your identify provider](#configuring-your-identity-provider), ### Azure setup notes <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For a demo of the Azure SAML setup including SCIM, see [SCIM Provisioning on Azure Using SAML SSO for Groups Demo](https://youtu.be/24-ZxmTeEBU). +For a demo of the Azure SAML setup including SCIM, see [SCIM Provisioning on Azure Using SAML SSO for Groups Demo](https://youtu.be/24-ZxmTeEBU). Please note that the video is outdated in regards to objectID mapping and the [SCIM documentation should be followed](scim_setup.md#azure-configuration-steps). | GitLab Setting | Azure Field | |--------------|----------------| @@ -136,7 +134,7 @@ For a demo of the Okta SAML setup including SCIM, see [Demo: Okta Group SAML & S Under Okta's **Single sign-on URL** field, check the option **Use this for Recipient URL and Destination URL**. -We recommend: +For NameID, the following settings are recommended; for SCIM, the following settings are required: - **Application username** (NameID) set to **Custom** `user.getInternalProperty("id")`. - **Name ID Format** set to **Persistent**. diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index c6444ada165..7c089a289c6 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -121,8 +121,12 @@ Once synchronized, changing the field mapped to `id` and `externalId` may cause ### Okta configuration steps -The SAML application that was created during [Single sign-on](index.md#okta-setup-notes) setup for [Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/overview/) now needs to be set up for SCIM. -Before proceeding, be sure to complete the [GitLab configuration](#gitlab-configuration) process. +Before you start this section, complete the [GitLab configuration](#gitlab-configuration) process. +Make sure that you've also set up a SAML application for [Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/overview/), +as described in the [Okta setup notes](index.md#okta-setup-notes) + +Make sure that the Okta setup matches our documentation exactly, especially the NameID +configuration. Otherwise, the Okta SCIM app may not work properly. 1. Sign in to Okta. 1. If you see an **Admin** button in the top right, click the button. This will @@ -212,39 +216,7 @@ When the user is added back to the SCIM app, GitLab cannot create a new user bec Solution: Have a user sign in directly to GitLab, then [manually link](#user-access-and-linking-setup) their account. -### Azure - -#### How do I verify my SCIM configuration is correct? - -Review the following: - -- Ensure that the SCIM value for `id` matches the SAML value for `NameId`. -- Ensure that the SCIM value for `externalId` matches the SAML value for `NameId`. - -Review the following SCIM parameters for sensible values: - -- `userName` -- `displayName` -- `emails[type eq "work"].value` - -#### Testing Azure connection: invalid credentials - -When testing the connection, you may encounter an error: **You appear to have entered invalid credentials. Please confirm you are using the correct information for an administrative account**. If `Tenant URL` and `secret token` are correct, check whether your group path contains characters that may be considered invalid JSON primitives (such as `.`). Removing such characters from the group path typically resolves the error. - -#### Azure: (Field) can't be blank sync error - -When checking the Audit Logs 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. - -As a workaround, try an alternate mapping: - -1. Follow the Azure mapping instructions from above. -1. Delete the `name.formatted` target attribute entry. -1. Change the `displayName` source attribute to have `name.formatted` target attribute. - -#### How do I diagnose why a user is unable to sign in +### How do I diagnose why a user is unable to sign in Ensure that the user has been added to the SCIM app. @@ -254,9 +226,9 @@ The **Identity** (`extern_uid`) value stored by GitLab is updated by SCIM whenev This value is also used by SCIM to match users on the `id`, and is updated by SCIM whenever the `id` or `externalId` values change. -It is important that this SCIM `id` and SCIM `externalId` are configured to the same value as the SAML `NameId`. SAML responses can be traced using [debugging tools](./index.md#saml-debugging-tools), and any errors can be checked against our [SAML troubleshooting docs](./index.md#troubleshooting). +It is important that this SCIM `id` and SCIM `externalId` are configured to the same value as the SAML `NameId`. SAML responses can be traced using [debugging tools](index.md#saml-debugging-tools), and any errors can be checked against our [SAML troubleshooting docs](index.md#troubleshooting). -#### How do I verify user's SAML NameId matches the SCIM externalId +### How do I verify user's SAML NameId matches the SCIM externalId Group owners can see the list of users and the `externalId` stored for each user in the group SAML SSO Settings page. @@ -264,7 +236,7 @@ A possible alternative is to use the [SCIM API](../../../api/scim.md#get-a-list- To see how the `external_uid` compares to the value returned as the SAML NameId, you can have the user use a [SAML Tracer](index.md#saml-debugging-tools). -#### Update or fix mismatched SCIM externalId and SAML NameId +### Update or fix mismatched SCIM externalId and 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. @@ -277,15 +249,47 @@ that provider may create duplicate users. If the `externalId` for a user is not correct, and also doesn't match the SAML NameID, you can address the problem in the following ways: -- You can have users unlink and relink themselves, based on the ["SAML authentication failed: User has already been taken"](./index.md#message-saml-authentication-failed-user-has-already-been-taken) section. +- You can have users unlink and relink themselves, based on the ["SAML authentication failed: User has already been taken"](index.md#message-saml-authentication-failed-user-has-already-been-taken) section. - You can unlink all users simultaneously, by removing all users from the SAML app while provisioning is turned on. - It may be possible to use the [SCIM API](../../../api/scim.md#update-a-single-saml-user) to manually correct the `externalId` stored for users to match the SAML `NameId`. To look up a user, you'll need to know the desired value that matches the `NameId` as well as the current `externalId`. It is important not to update these to incorrect values, since this will cause users to be unable to sign in. It is also important not to assign a value to the wrong user, as this would cause users to get signed into the wrong account. -#### I need to change my SCIM app +### I need to change my SCIM app -Individual users can follow the instructions in the ["SAML authentication failed: User has already been taken"](./index.md#i-need-to-change-my-saml-app) section. +Individual users can follow the instructions in the ["SAML authentication failed: User has already been taken"](index.md#i-need-to-change-my-saml-app) section. Alternatively, users can be removed from the SCIM app which will delink all removed users. Sync can then be turned on for the new SCIM app to [link existing users](#user-access-and-linking-setup). + +### Azure + +#### How do I verify my SCIM configuration is correct? + +Review the following: + +- Ensure that the SCIM value for `id` matches the SAML value for `NameId`. +- Ensure that the SCIM value for `externalId` matches the SAML value for `NameId`. + +Review the following SCIM parameters for sensible values: + +- `userName` +- `displayName` +- `emails[type eq "work"].value` + +#### Testing Azure connection: invalid credentials + +When testing the connection, you may encounter an error: **You appear to have entered invalid credentials. Please confirm you are using the correct information for an administrative account**. If `Tenant URL` and `secret token` are correct, check whether your group path contains characters that may be considered invalid JSON primitives (such as `.`). Removing such characters from the group path typically resolves the error. + +#### (Field) can't be blank sync error + +When checking the Audit Logs 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. + +As a workaround, try an alternate mapping: + +1. Follow the Azure mapping instructions from above. +1. Delete the `name.formatted` target attribute entry. +1. Change the `displayName` source attribute to have `name.formatted` target attribute. diff --git a/doc/user/group/settings/img/new_group_navigation_v13_1.png b/doc/user/group/settings/img/new_group_navigation_v13_1.png Binary files differindex 98d45a694b6..307175727c7 100644 --- a/doc/user/group/settings/img/new_group_navigation_v13_1.png +++ b/doc/user/group/settings/img/new_group_navigation_v13_1.png diff --git a/doc/user/group/subgroups/img/create_subgroup_button.png b/doc/user/group/subgroups/img/create_subgroup_button.png Binary files differdeleted file mode 100644 index d1355d4b2c3..00000000000 --- a/doc/user/group/subgroups/img/create_subgroup_button.png +++ /dev/null diff --git a/doc/user/group/subgroups/img/create_subgroup_button_v13_6.png b/doc/user/group/subgroups/img/create_subgroup_button_v13_6.png Binary files differnew file mode 100644 index 00000000000..013aee6b0b4 --- /dev/null +++ b/doc/user/group/subgroups/img/create_subgroup_button_v13_6.png diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 6de38354c5e..268014a3cd2 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -1,4 +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 type: reference, howto, concepts --- @@ -80,7 +83,10 @@ By default, groups created in: - GitLab 12.2 or later allow both Owners and Maintainers to create subgroups. - GitLab 12.1 or earlier only allow Owners to create subgroups. -This setting can be for any group by an Owner or Administrator. +The setting can be changed for any group by: + +- A group owner. Select the group, and navigate to **Settings > General > Permissions, LFS, 2FA**. +- An administrator. Navigate to **Admin Area > Overview > Groups**, select the group, and choose **Edit**. For more information check the [permissions table](../../permissions.md#group-members-permissions). For a list @@ -93,10 +99,9 @@ creation is disabled by an administrator in their settings. To create a subgroup: -1. In the group's dashboard expand the **New project** split button, select - **New subgroup** and click the **New subgroup** button. +1. In the group's dashboard click the **New subgroup** button. -  +  1. Create a new group like you would normally do. Notice that the immediate parent group namespace is fixed under **Group path**. The visibility level can differ from diff --git a/doc/user/img/unordered_check_list_render_gfm.png b/doc/user/img/unordered_check_list_render_gfm.png Binary files differdeleted file mode 100644 index 2ce0fb95645..00000000000 --- a/doc/user/img/unordered_check_list_render_gfm.png +++ /dev/null diff --git a/doc/user/index.md b/doc/user/index.md index 32a1c235882..8701b5e038b 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -1,4 +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 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.' --- @@ -69,6 +72,17 @@ With GitLab Enterprise Edition, you can also: You can also [integrate](project/integrations/overview.md) GitLab with numerous third-party applications, such as Mattermost, Microsoft Teams, HipChat, Trello, Slack, Bamboo CI, Jira, and a lot more. +## User types + +There are several types of users in GitLab: + +- Regular users and GitLab.com users. <!-- Note: further description TBA --> +- [Groups](group/index.md) of users. +- GitLab [admin area](admin_area/index.md) user. +- [GitLab Administrator](../administration/index.md) with full access to + self-managed instances' features and settings. +- [Internal users](../development/internal_users.md). + ## Projects In GitLab, you can create [projects](project/index.md) to host @@ -84,18 +98,6 @@ it all at once, from one single project. - [Milestones](project/milestones/index.md): Work on multiple issues and merge requests towards the same target date with Milestones. -## GitLab CI/CD - -Use built-in [GitLab CI/CD](../ci/README.md) to test, build, and deploy your applications -directly from GitLab. No third-party integrations needed. - -- [GitLab Auto Deploy](../topics/autodevops/stages.md#auto-deploy): Deploy your application out-of-the-box with GitLab Auto Deploy. -- [Review Apps](../ci/review_apps/index.md): Live-preview the changes introduced by a merge request with Review Apps. -- [GitLab Pages](project/pages/index.md): Publish your static site directly from - GitLab with GitLab Pages. You can build, test, and deploy any Static Site Generator with Pages. -- [GitLab Container Registry](packages/container_registry/index.md): Build and deploy Docker - images with Container Registry. - ## Account There is a lot you can customize and configure @@ -151,6 +153,11 @@ requests you're assigned to. you have quick access to. You can also gather feedback on them through [Discussions](#discussions). +## GitLab CI/CD + +Use built-in [GitLab CI/CD](../ci/README.md) to test, build, and deploy your applications +directly from GitLab. No third-party integrations needed. + ## Features behind feature flags Understand what [features behind feature flags](feature_flags.md) mean. diff --git a/doc/user/infrastructure/img/terraform_list_view_v13_5.png b/doc/user/infrastructure/img/terraform_list_view_v13_5.png Binary files differnew file mode 100644 index 00000000000..b23dfa6289e --- /dev/null +++ b/doc/user/infrastructure/img/terraform_list_view_v13_5.png diff --git a/doc/user/infrastructure/img/terraform_plan_widget_v13_0.png b/doc/user/infrastructure/img/terraform_plan_widget_v13_0.png Binary files differdeleted file mode 100644 index 62bf4b279b2..00000000000 --- a/doc/user/infrastructure/img/terraform_plan_widget_v13_0.png +++ /dev/null diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index cee6e21a5c5..4af18873798 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -13,35 +13,7 @@ workflows to tie into GitLab's authentication and authorization. These features lowering the barrier to entry for teams to adopt Terraform, collaborate effectively within GitLab, and support Terraform best practices. -## Quick Start - -Use the following `.gitlab-ci.yml` to set up a simple Terraform project integration -for GitLab versions 13.5 and greater: - -```yaml -include: - - template: Terraform.latest.gitlab-ci.yml - -variables: - # If not using GitLab's HTTP backend, remove this line and specify TF_HTTP_* variables - TF_STATE_NAME: default - TF_CACHE_KEY: default -``` - -This template uses `.latest.`, instead of stable, and may include breaking changes. -This template also includes some opinionated decisions, which you can override: - -- Including the latest [GitLab Terraform Image](https://gitlab.com/gitlab-org/terraform-images). -- Using the [GitLab managed Terraform State](#gitlab-managed-terraform-state) as - the Terraform state storage backend. -- Creating [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml): - `init`, `validate`, `build`, and `deploy`. These stages - [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.latest.gitlab-ci.yml) - `init`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on `master`. - -## GitLab managed Terraform State - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. +## GitLab Managed Terraform state [Terraform remote backends](https://www.terraform.io/docs/backends/index.html) enable you to store the state file in a remote, shared store. GitLab uses the @@ -57,507 +29,36 @@ Amazon S3 or Google Cloud Storage. Its features include: - Locking and unlocking state. - Remote Terraform plan and apply execution. -To get started with a GitLab-managed Terraform State, there are two different options: - -- [Use a local machine](#get-started-using-local-development). -- [Use GitLab CI](#get-started-using-gitlab-ci). - -## Permissions for using Terraform - -In GitLab version 13.1, [Maintainer access](../permissions.md) was required to use a -GitLab managed Terraform state backend. In GitLab versions 13.2 and greater, -[Maintainer access](../permissions.md) is required to lock, unlock and write to the state -(using `terraform apply`), while [Developer access](../permissions.md) is required to read -the state (using `terraform plan -lock=false`). - -## Get started using local development - -If you plan to only run `terraform plan` and `terraform apply` commands from your -local machine, this is a simple way to get started: - -1. Create your project on your GitLab instance. -1. Navigate to **Settings > General** and note your **Project name** - and **Project ID**. -1. Define the Terraform backend in your Terraform project to be: - - ```hcl - terraform { - backend "http" { - } - } - ``` - -1. Create a [Personal Access Token](../profile/personal_access_tokens.md) with - the `api` scope. - -1. On your local machine, run `terraform init`, passing in the following options, - replacing `<YOUR-STATE-NAME>`, `<YOUR-PROJECT-ID>`, `<YOUR-USERNAME>` and - `<YOUR-ACCESS-TOKEN>` with the relevant values. This command initializes your - Terraform state, and stores that state within your GitLab project. The name of - your state can contain only uppercase and lowercase letters, decimal digits, - hyphens, and underscores. This example uses `gitlab.com`: - - ```shell - terraform init \ - -backend-config="address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>" \ - -backend-config="lock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>/lock" \ - -backend-config="unlock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>/lock" \ - -backend-config="username=<YOUR-USERNAME>" \ - -backend-config="password=<YOUR-ACCESS-TOKEN>" \ - -backend-config="lock_method=POST" \ - -backend-config="unlock_method=DELETE" \ - -backend-config="retry_wait_min=5" - ``` - -You can now run `terraform plan` and `terraform apply` as you normally would. - -## Get started using GitLab CI - -If you don't want to start with local development, you can also use GitLab CI to -run your `terraform plan` and `terraform apply` commands. - -Next, [configure the backend](#configure-the-backend). - -## Configure the backend - -After executing the `terraform init` command, you must configure the Terraform backend -and the CI YAML file: - -1. In your Terraform project, define the [HTTP backend](https://www.terraform.io/docs/backends/types/http.html) - by adding the following code block in a `.tf` file (such as `backend.tf`) to - define the remote backend: - - ```hcl - terraform { - backend "http" { - } - } - ``` - -1. In the root directory of your project repository, configure a - `.gitlab-ci.yaml` file. This example uses a pre-built image which includes a - `gitlab-terraform` helper. For supported Terraform versions, see the [GitLab - Terraform Images project](https://gitlab.com/gitlab-org/terraform-images). - - ```yaml - image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest - ``` - -1. In the `.gitlab-ci.yaml` file, define some environment variables to ease - development. In this example, `TF_ROOT` is the directory where the Terraform - commands must be executed, `TF_ADDRESS` is the URL to the state on the GitLab - instance where this pipeline runs, and the final path segment in `TF_ADDRESS` - is the name of the Terraform state. Projects may have multiple states, and - this name is arbitrary, so in this example we set it to `example-production` - which corresponds with the directory we're using as our `TF_ROOT`, and we - ensure that the `.terraform` directory is cached between jobs in the pipeline - using a cache key based on the state name (`example-production`): - - ```yaml - variables: - TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production - TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production - - cache: - key: example-production - paths: - - ${TF_ROOT}/.terraform - ``` - -1. In a `before_script`, change to your `TF_ROOT`: - - ```yaml - before_script: - - cd ${TF_ROOT} - - stages: - - prepare - - validate - - build - - deploy - - init: - stage: prepare - script: - - gitlab-terraform init - - validate: - stage: validate - script: - - gitlab-terraform validate - - plan: - stage: build - script: - - gitlab-terraform plan - - gitlab-terraform plan-json - artifacts: - name: plan - paths: - - ${TF_ROOT}/plan.cache - reports: - terraform: ${TF_ROOT}/plan.json - - apply: - stage: deploy - environment: - name: production - script: - - gitlab-terraform apply - dependencies: - - plan - when: manual - only: - - master - ``` - -1. Push your project to GitLab, which triggers a CI job pipeline. This pipeline - runs the `gitlab-terraform init`, `gitlab-terraform validate`, and - `gitlab-terraform plan` commands. - -The output from the above `terraform` commands should be viewable in the job logs. - -CAUTION: **Caution:** -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. - -## Example project - -See [this reference project](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-aws) using GitLab and Terraform to deploy a basic AWS EC2 within a custom VPC. - -## Copy Terraform state between backends - -Terraform supports copying the state when the backend is changed or -reconfigured. This can be useful if you need to migrate from another backend to -GitLab managed Terraform state. It's also useful if you need to change the state -name as in the following example: - -```shell -PROJECT_ID="<gitlab-project-id>" -TF_USERNAME="<gitlab-username>" -TF_PASSWORD="<gitlab-personal-access-token>" -TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/old-state-name" - -terraform init \ - -backend-config=address=${TF_ADDRESS} \ - -backend-config=lock_address=${TF_ADDRESS}/lock \ - -backend-config=unlock_address=${TF_ADDRESS}/lock \ - -backend-config=username=${TF_USERNAME} \ - -backend-config=password=${TF_PASSWORD} \ - -backend-config=lock_method=POST \ - -backend-config=unlock_method=DELETE \ - -backend-config=retry_wait_min=5 -``` - -```plaintext -Initializing the backend... - -Successfully configured the backend "http"! Terraform will automatically -use this backend unless the backend configuration changes. - -Initializing provider plugins... - -Terraform has been successfully initialized! - -You may now begin working with Terraform. Try running "terraform plan" to see -any changes that are required for your infrastructure. All Terraform commands -should now work. - -If you ever set or change modules or backend configuration for Terraform, -rerun this command to reinitialize your working directory. If you forget, other -commands will detect it and remind you to do so if necessary. -``` - -Now that `terraform init` has created a `.terraform/` directory that knows where -the old state is, you can tell it about the new location: - -```shell -TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/new-state-name" - -terraform init \ - -backend-config=address=${TF_ADDRESS} \ - -backend-config=lock_address=${TF_ADDRESS}/lock \ - -backend-config=unlock_address=${TF_ADDRESS}/lock \ - -backend-config=username=${TF_USERNAME} \ - -backend-config=password=${TF_PASSWORD} \ - -backend-config=lock_method=POST \ - -backend-config=unlock_method=DELETE \ - -backend-config=retry_wait_min=5 -``` - -```plaintext -Initializing the backend... -Backend configuration changed! - -Terraform has detected that the configuration specified for the backend -has changed. Terraform will now check for existing state in the backends. - - -Acquiring state lock. This may take a few moments... -Do you want to copy existing state to the new backend? - Pre-existing state was found while migrating the previous "http" backend to the - newly configured "http" backend. No existing state was found in the newly - configured "http" backend. Do you want to copy this state to the new "http" - backend? Enter "yes" to copy and "no" to start with an empty state. - - Enter a value: yes - - -Successfully configured the backend "http"! Terraform will automatically -use this backend unless the backend configuration changes. - -Initializing provider plugins... - -Terraform has been successfully initialized! - -You may now begin working with Terraform. Try running "terraform plan" to see -any changes that are required for your infrastructure. All Terraform commands -should now work. - -If you ever set or change modules or backend configuration for Terraform, -rerun this command to reinitialize your working directory. If you forget, other -commands will detect it and remind you to do so if necessary. -``` - -If you type `yes`, it copies your state from the old location to the new -location. You can then go back to running it from within GitLab CI. - -## Output Terraform Plan information into a merge request - -Using the [GitLab Terraform Report artifact](../../ci/pipelines/job_artifacts.md#artifactsreportsterraform), -you can expose details from `terraform plan` runs directly into a merge request widget, -enabling you to see statistics about the resources that Terraform creates, -modifies, or destroys. +Read more on setting up and [using GitLab Managed Terraform states](terraform_state.md) -Let's explore how to configure a GitLab Terraform Report artifact. You can -either use a pre-built image which includes a `gitlab-terraform` helper as -above, where `gitlab-terraform plan-json` outputs the required artifact, or you -can configure this manually as follows: +## Terraform integration in Merge Requests -1. For simplicity, let's define a few reusable variables to allow us to - refer to these files multiple times: +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. - ```yaml - variables: - PLAN: plan.cache - PLAN_JSON: plan.json - ``` +Read more on setting up and [using the merge request integrations](mr_integration.md). -1. Install `jq`, a - [lightweight and flexible command-line JSON processor](https://stedolan.github.io/jq/). -1. Create an alias for a specific `jq` command that parses out the information we - want to extract from the `terraform plan` output: - - ```yaml - before_script: - - apk --no-cache add jq - - 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:** - 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 - by adding a `shopt` command to your script: - - ```yaml - before_script: - - shopt -s expand_aliases - - 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)}'" - ``` - -1. Define a `script` that runs `terraform plan` and `terraform show`. These commands - pipe the output and convert the relevant bits into a store variable `PLAN_JSON`. - This JSON is used to create a - [GitLab Terraform Report artifact](../../ci/pipelines/job_artifacts.md#artifactsreportsterraform). - The Terraform report obtains a Terraform `tfplan.json` file. The collected - Terraform plan report is uploaded to GitLab as an artifact, and is shown in merge requests. - - ```yaml - plan: - stage: build - script: - - terraform plan -out=$PLAN - - terraform show --json $PLAN | convert_report > $PLAN_JSON - artifacts: - reports: - terraform: $PLAN_JSON - ``` - - For a full example using the pre-built image, see [Example `.gitlab-ci.yaml` - file](#example-gitlab-ciyaml-file). - - For an example displaying multiple reports, see [`.gitlab-ci.yaml` multiple reports file](#multiple-terraform-plan-reports). - -1. Running the pipeline displays the widget in the merge request, like this: - -  - -1. Clicking the **View Full Log** button in the widget takes you directly to the - plan output present in the pipeline logs: - -  +## Quick Start -### Example `.gitlab-ci.yaml` file +Use the following `.gitlab-ci.yml` to set up a simple Terraform project integration +for GitLab versions 13.5 and greater: ```yaml -default: - image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest - - cache: - key: example-production - paths: - - ${TF_ROOT}/.terraform +include: + - template: Terraform.latest.gitlab-ci.yml variables: - TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production - TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production - -before_script: - - cd ${TF_ROOT} - -stages: - - prepare - - validate - - build - - deploy - -init: - stage: prepare - script: - - gitlab-terraform init - -validate: - stage: validate - script: - - gitlab-terraform validate - -plan: - stage: build - script: - - gitlab-terraform plan - - gitlab-terraform plan-json - artifacts: - name: plan - paths: - - ${TF_ROOT}/plan.cache - reports: - terraform: ${TF_ROOT}/plan.json - -apply: - stage: deploy - environment: - name: production - script: - - gitlab-terraform apply - dependencies: - - plan - when: manual - only: - - master -``` - -### Multiple Terraform Plan reports - -Starting with GitLab version 13.2, you can display multiple reports on the Merge Request -page. The reports also display the `artifacts: name:`. See example below for a suggested setup. - -```yaml -default: - image: - name: registry.gitlab.com/gitlab-org/gitlab-build-images:terraform - entrypoint: - - '/usr/bin/env' - - 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' - - cache: - paths: - - .terraform - -stages: - - build - -.terraform-plan-generation: - stage: build - variables: - PLAN: plan.tfplan - JSON_PLAN_FILE: tfplan.json - before_script: - - cd ${TERRAFORM_DIRECTORY} - - terraform --version - - terraform init - - apk --no-cache add jq - script: - - terraform validate - - terraform plan -out=${PLAN} - - terraform show --json ${PLAN} | jq -r '([.resource_changes[]?.change.actions?]|flatten)|{"create":(map(select(.=="create"))|length),"update":(map(select(.=="update"))|length),"delete":(map(select(.=="delete"))|length)}' > ${JSON_PLAN_FILE} - artifacts: - reports: - terraform: ${TERRAFORM_DIRECTORY}/${JSON_PLAN_FILE} - -review_plan: - extends: .terraform-plan-generation - variables: - TERRAFORM_DIRECTORY: "review/" - # Review will not include an artifact name - -staging_plan: - extends: .terraform-plan-generation - variables: - TERRAFORM_DIRECTORY: "staging/" - artifacts: - name: Staging - -production_plan: - extends: .terraform-plan-generation - variables: - TERRAFORM_DIRECTORY: "production/" - artifacts: - name: Production + # If not using GitLab's HTTP backend, remove this line and specify TF_HTTP_* variables + TF_STATE_NAME: default + TF_CACHE_KEY: default ``` -## Using a GitLab managed Terraform state backend as a remote data source - -You can use a GitLab-managed Terraform state as a -[Terraform data source](https://www.terraform.io/docs/providers/terraform/d/remote_state.html). -To use your existing Terraform state backend as a data source, provide the following details -as [Terraform input variables](https://www.terraform.io/docs/configuration/variables.html): - -- **address**: The URL of the remote state backend you want to use as a data source. - For example, `https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME>`. -- **username**: The username to authenticate with the data source. If you are using a [Personal Access Token](../profile/personal_access_tokens.md) for - authentication, this is your GitLab username. If you are using GitLab CI, this is `'gitlab-ci-token'`. -- **password**: The password to authenticate with the data source. If you are using a Personal Access Token for - authentication, this is the token value. If you are using GitLab CI, it is the contents of the `${CI_JOB_TOKEN}` CI variable. - -An example setup is shown below: - -1. Create a file named `example.auto.tfvars` with the following contents: - - ```plaintext - example_remote_state_address=https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME> - example_username=<GitLab username> - example_access_token=<GitLab Personal Acceess Token> - ``` - -1. Define the data source by adding the following code block in a `.tf` file (such as `data.tf`): - - ```hcl - data "terraform_remote_state" "example" { - backend = "http" - - config = { - address = var.example_remote_state_address - username = var.example_username - password = var.example_access_token - } - } - ``` - -Outputs from the data source can now be referenced within your Terraform resources -using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`. +This template uses `.latest.`, instead of stable, and may include breaking changes. +This template also includes some opinionated decisions, which you can override: -You need at least [developer access](../permissions.md) to the target project -to read the Terraform state. +- Including the latest [GitLab Terraform Image](https://gitlab.com/gitlab-org/terraform-images). +- Using the [GitLab managed Terraform State](#gitlab-managed-terraform-state) as + the Terraform state storage backend. +- Creating [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml): + `init`, `validate`, `build`, and `deploy`. These stages + [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.latest.gitlab-ci.yml) + `init`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on `master`. diff --git a/doc/user/infrastructure/mr_integration.md b/doc/user/infrastructure/mr_integration.md new file mode 100644 index 00000000000..7d9a036cac8 --- /dev/null +++ b/doc/user/infrastructure/mr_integration.md @@ -0,0 +1,205 @@ +--- +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 +--- + +# 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. + +## Output Terraform Plan information into a merge request + +Using the [GitLab Terraform Report artifact](../../ci/pipelines/job_artifacts.md#artifactsreportsterraform), +you can expose details from `terraform plan` runs directly into a merge request widget, +enabling you to see statistics about the resources that Terraform creates, +modifies, or destroys. + +## Setup + +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: + +1. For simplicity, let's define a few reusable variables to allow us to + refer to these files multiple times: + + ```yaml + variables: + PLAN: plan.cache + PLAN_JSON: plan.json + ``` + +1. Install `jq`, a + [lightweight and flexible command-line JSON processor](https://stedolan.github.io/jq/). +1. Create an alias for a specific `jq` command that parses out the information we + want to extract from the `terraform plan` output: + + ```yaml + before_script: + - apk --no-cache add jq + - 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:** + 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 + by adding a `shopt` command to your script: + + ```yaml + before_script: + - shopt -s expand_aliases + - 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)}'" + ``` + +1. Define a `script` that runs `terraform plan` and `terraform show`. These commands + pipe the output and convert the relevant bits into a store variable `PLAN_JSON`. + This JSON is used to create a + [GitLab Terraform Report artifact](../../ci/pipelines/job_artifacts.md#artifactsreportsterraform). + The Terraform report obtains a Terraform `tfplan.json` file. The collected + Terraform plan report is uploaded to GitLab as an artifact, and is shown in merge requests. + + ```yaml + plan: + stage: build + script: + - terraform plan -out=$PLAN + - terraform show --json $PLAN | convert_report > $PLAN_JSON + artifacts: + reports: + terraform: $PLAN_JSON + ``` + + For a full example using the pre-built image, see [Example `.gitlab-ci.yaml` + file](#example-gitlab-ciyaml-file). + + For an example displaying multiple reports, see [`.gitlab-ci.yaml` multiple reports file](#multiple-terraform-plan-reports). + +1. Running the pipeline displays the widget in the merge request, like this: + +  + +1. Clicking the **View Full Log** button in the widget takes you directly to the + plan output present in the pipeline logs: + +  + +### Example `.gitlab-ci.yaml` file + +```yaml +default: + image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest + + cache: + key: example-production + paths: + - ${TF_ROOT}/.terraform + +variables: + TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production + TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production + +before_script: + - cd ${TF_ROOT} + +stages: + - prepare + - validate + - build + - deploy + +init: + stage: prepare + script: + - gitlab-terraform init + +validate: + stage: validate + script: + - gitlab-terraform validate + +plan: + stage: build + script: + - gitlab-terraform plan + - gitlab-terraform plan-json + artifacts: + name: plan + paths: + - ${TF_ROOT}/plan.cache + reports: + terraform: ${TF_ROOT}/plan.json + +apply: + stage: deploy + environment: + name: production + script: + - gitlab-terraform apply + dependencies: + - plan + when: manual + only: + - master +``` + +### Multiple Terraform Plan reports + +Starting with GitLab version 13.2, you can display multiple reports on the Merge Request +page. The reports also display the `artifacts: name:`. See example below for a suggested setup. + +```yaml +default: + image: + name: registry.gitlab.com/gitlab-org/gitlab-build-images:terraform + entrypoint: + - '/usr/bin/env' + - 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' + + cache: + paths: + - .terraform + +stages: + - build + +.terraform-plan-generation: + stage: build + variables: + PLAN: plan.tfplan + JSON_PLAN_FILE: tfplan.json + before_script: + - cd ${TERRAFORM_DIRECTORY} + - terraform --version + - terraform init + - apk --no-cache add jq + script: + - terraform validate + - terraform plan -out=${PLAN} + - terraform show --json ${PLAN} | jq -r '([.resource_changes[]?.change.actions?]|flatten)|{"create":(map(select(.=="create"))|length),"update":(map(select(.=="update"))|length),"delete":(map(select(.=="delete"))|length)}' > ${JSON_PLAN_FILE} + artifacts: + reports: + terraform: ${TERRAFORM_DIRECTORY}/${JSON_PLAN_FILE} + +review_plan: + extends: .terraform-plan-generation + variables: + TERRAFORM_DIRECTORY: "review/" + # Review will not include an artifact name + +staging_plan: + extends: .terraform-plan-generation + variables: + TERRAFORM_DIRECTORY: "staging/" + artifacts: + name: Staging + +production_plan: + extends: .terraform-plan-generation + variables: + TERRAFORM_DIRECTORY: "production/" + artifacts: + name: Production +``` diff --git a/doc/user/infrastructure/terraform_state.md b/doc/user/infrastructure/terraform_state.md new file mode 100644 index 00000000000..ef36f0217be --- /dev/null +++ b/doc/user/infrastructure/terraform_state.md @@ -0,0 +1,360 @@ +--- +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 +--- + +# GitLab managed Terraform State + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. + +[Terraform remote backends](https://www.terraform.io/docs/backends/index.html) +enable you to store the state file in a remote, shared store. GitLab uses the +[Terraform HTTP backend](https://www.terraform.io/docs/backends/types/http.html) +to securely store the state files in local storage (the default) or +[the remote store of your choice](../../administration/terraform_state.md). + +The GitLab managed Terraform state backend can store your Terraform state easily and +securely, and spares you from setting up additional remote resources like +Amazon S3 or Google Cloud Storage. Its features include: + +- Supporting encryption of the state file both in transit and at rest. +- Locking and unlocking state. +- Remote Terraform plan and apply execution. + +## Permissions for using Terraform + +In GitLab version 13.1, [Maintainer access](../permissions.md) was required to use a +GitLab managed Terraform state backend. In GitLab versions 13.2 and greater, +[Maintainer access](../permissions.md) is required to lock, unlock and write to the state +(using `terraform apply`), while [Developer access](../permissions.md) is required to read +the state (using `terraform plan -lock=false`). + +## Set up GitLab-managed Terraform state + +To get started with a GitLab-managed Terraform state, there are two different options: + +- [Use a local machine](#get-started-using-local-development). +- [Use GitLab CI](#get-started-using-gitlab-ci). + +Terraform States can be found by navigating to a Project's **{cloud-gear}** **Operations > Terraform** page. + +### Get started using local development + +If you plan to only run `terraform plan` and `terraform apply` commands from your +local machine, this is a simple way to get started: + +1. Create your project on your GitLab instance. +1. Navigate to **Settings > General** and note your **Project name** + and **Project ID**. +1. Define the Terraform backend in your Terraform project to be: + + ```hcl + terraform { + backend "http" { + } + } + ``` + +1. Create a [Personal Access Token](../profile/personal_access_tokens.md) with + the `api` scope. + +1. On your local machine, run `terraform init`, passing in the following options, + replacing `<YOUR-STATE-NAME>`, `<YOUR-PROJECT-ID>`, `<YOUR-USERNAME>` and + `<YOUR-ACCESS-TOKEN>` with the relevant values. This command initializes your + Terraform state, and stores that state within your GitLab project. The name of + your state can contain only uppercase and lowercase letters, decimal digits, + hyphens, and underscores. This example uses `gitlab.com`: + + ```shell + terraform init \ + -backend-config="address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>" \ + -backend-config="lock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>/lock" \ + -backend-config="unlock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-STATE-NAME>/lock" \ + -backend-config="username=<YOUR-USERNAME>" \ + -backend-config="password=<YOUR-ACCESS-TOKEN>" \ + -backend-config="lock_method=POST" \ + -backend-config="unlock_method=DELETE" \ + -backend-config="retry_wait_min=5" + ``` + +You can now run `terraform plan` and `terraform apply` as you normally would. + +### Get started using GitLab CI + +If you don't want to start with local development, you can also use GitLab CI to +run your `terraform plan` and `terraform apply` commands. + +Next, [configure the backend](#configure-the-backend). + +#### Configure the backend + +After executing the `terraform init` command, you must configure the Terraform backend +and the CI YAML file: + +1. In your Terraform project, define the [HTTP backend](https://www.terraform.io/docs/backends/types/http.html) + by adding the following code block in a `.tf` file (such as `backend.tf`) to + define the remote backend: + + ```hcl + terraform { + backend "http" { + } + } + ``` + +1. In the root directory of your project repository, configure a + `.gitlab-ci.yaml` file. This example uses a pre-built image which includes a + `gitlab-terraform` helper. For supported Terraform versions, see the [GitLab + Terraform Images project](https://gitlab.com/gitlab-org/terraform-images). + + ```yaml + image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest + ``` + +1. In the `.gitlab-ci.yaml` file, define some environment variables to ease + development. In this example, `TF_ROOT` is the directory where the Terraform + commands must be executed, `TF_ADDRESS` is the URL to the state on the GitLab + instance where this pipeline runs, and the final path segment in `TF_ADDRESS` + is the name of the Terraform state. Projects may have multiple states, and + this name is arbitrary, so in this example we set it to `example-production` + which corresponds with the directory we're using as our `TF_ROOT`, and we + ensure that the `.terraform` directory is cached between jobs in the pipeline + using a cache key based on the state name (`example-production`): + + ```yaml + variables: + TF_ROOT: ${CI_PROJECT_DIR}/environments/example/production + TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/example-production + + cache: + key: example-production + paths: + - ${TF_ROOT}/.terraform + ``` + +1. In a `before_script`, change to your `TF_ROOT`: + + ```yaml + before_script: + - cd ${TF_ROOT} + + stages: + - prepare + - validate + - build + - deploy + + init: + stage: prepare + script: + - gitlab-terraform init + + validate: + stage: validate + script: + - gitlab-terraform validate + + plan: + stage: build + script: + - gitlab-terraform plan + - gitlab-terraform plan-json + artifacts: + name: plan + paths: + - ${TF_ROOT}/plan.cache + reports: + terraform: ${TF_ROOT}/plan.json + + apply: + stage: deploy + environment: + name: production + script: + - gitlab-terraform apply + dependencies: + - plan + when: manual + only: + - master + ``` + +1. Push your project to GitLab, which triggers a CI job pipeline. This pipeline + runs the `gitlab-terraform init`, `gitlab-terraform validate`, and + `gitlab-terraform plan` commands. + +The output from the above `terraform` commands should be viewable in the job logs. + +CAUTION: **Caution:** +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. + +### Example project + +See [this reference project](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-aws) using GitLab and Terraform to deploy a basic AWS EC2 within a custom VPC. + +## Using a GitLab managed Terraform state backend as a remote data source + +You can use a GitLab-managed Terraform state as a +[Terraform data source](https://www.terraform.io/docs/providers/terraform/d/remote_state.html). +To use your existing Terraform state backend as a data source, provide the following details +as [Terraform input variables](https://www.terraform.io/docs/configuration/variables.html): + +- **address**: The URL of the remote state backend you want to use as a data source. + For example, `https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME>`. +- **username**: The username to authenticate with the data source. If you are using a [Personal Access Token](../profile/personal_access_tokens.md) for + authentication, this is your GitLab username. If you are using GitLab CI, this is `'gitlab-ci-token'`. +- **password**: The password to authenticate with the data source. If you are using a Personal Access Token for + authentication, this is the token value. If you are using GitLab CI, it is the contents of the `${CI_JOB_TOKEN}` CI variable. + +An example setup is shown below: + +1. Create a file named `example.auto.tfvars` with the following contents: + + ```plaintext + example_remote_state_address=https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME> + example_username=<GitLab username> + example_access_token=<GitLab Personal Acceess Token> + ``` + +1. Define the data source by adding the following code block in a `.tf` file (such as `data.tf`): + + ```hcl + data "terraform_remote_state" "example" { + backend = "http" + + config = { + address = var.example_remote_state_address + username = var.example_username + password = var.example_access_token + } + } + ``` + +Outputs from the data source can now be referenced within your Terraform resources +using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`. + +You need at least [developer access](../permissions.md) to the target project +to read the Terraform state. + +## Migrating to GitLab Managed Terraform state + +Terraform supports copying the state when the backend is changed or +reconfigured. This can be useful if you need to migrate from another backend to +GitLab managed Terraform state. Using a local terminal is recommended to run the commands needed for migrating to GitLab Managed Terraform state. + +The following example demonstrates how to change the state name, the same workflow is needed to migrate to GitLab Managed Terraform state from a different state storage backend. + +### Setting up the initial backend + +```shell +PROJECT_ID="<gitlab-project-id>" +TF_USERNAME="<gitlab-username>" +TF_PASSWORD="<gitlab-personal-access-token>" +TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/old-state-name" + +terraform init \ + -backend-config=address=${TF_ADDRESS} \ + -backend-config=lock_address=${TF_ADDRESS}/lock \ + -backend-config=unlock_address=${TF_ADDRESS}/lock \ + -backend-config=username=${TF_USERNAME} \ + -backend-config=password=${TF_PASSWORD} \ + -backend-config=lock_method=POST \ + -backend-config=unlock_method=DELETE \ + -backend-config=retry_wait_min=5 +``` + +```plaintext +Initializing the backend... + +Successfully configured the backend "http"! Terraform will automatically +use this backend unless the backend configuration changes. + +Initializing provider plugins... + +Terraform has been successfully initialized! + +You may now begin working with Terraform. Try running "terraform plan" to see +any changes that are required for your infrastructure. All Terraform commands +should now work. + +If you ever set or change modules or backend configuration for Terraform, +rerun this command to reinitialize your working directory. If you forget, other +commands will detect it and remind you to do so if necessary. +``` + +### Changing the backend + +Now that `terraform init` has created a `.terraform/` directory that knows where +the old state is, you can tell it about the new location: + +```shell +TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/new-state-name" + +terraform init \ + -backend-config=address=${TF_ADDRESS} \ + -backend-config=lock_address=${TF_ADDRESS}/lock \ + -backend-config=unlock_address=${TF_ADDRESS}/lock \ + -backend-config=username=${TF_USERNAME} \ + -backend-config=password=${TF_PASSWORD} \ + -backend-config=lock_method=POST \ + -backend-config=unlock_method=DELETE \ + -backend-config=retry_wait_min=5 +``` + +```plaintext +Initializing the backend... +Backend configuration changed! + +Terraform has detected that the configuration specified for the backend +has changed. Terraform will now check for existing state in the backends. + + +Acquiring state lock. This may take a few moments... +Do you want to copy existing state to the new backend? + Pre-existing state was found while migrating the previous "http" backend to the + newly configured "http" backend. No existing state was found in the newly + configured "http" backend. Do you want to copy this state to the new "http" + backend? Enter "yes" to copy and "no" to start with an empty state. + + Enter a value: yes + + +Successfully configured the backend "http"! Terraform will automatically +use this backend unless the backend configuration changes. + +Initializing provider plugins... + +Terraform has been successfully initialized! + +You may now begin working with Terraform. Try running "terraform plan" to see +any changes that are required for your infrastructure. All Terraform commands +should now work. + +If you ever set or change modules or backend configuration for Terraform, +rerun this command to reinitialize your working directory. If you forget, other +commands will detect it and remind you to do so if necessary. +``` + +If you type `yes`, it copies your state from the old location to the new +location. You can then go back to running it from within GitLab CI. + +## Managing state files + +NOTE: **Note:** +We are currently working on [providing a graphical interface for managing state files](https://gitlab.com/groups/gitlab-org/-/epics/4563). + + + +The state files attached to a project can be found under Operations / Terraform. + +## Removing a State file + +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>" +``` diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index c370f9d8725..68af74b69fe 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -1,3 +1,9 @@ +--- +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 +--- + # Instance-level Kubernetes clusters > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39840) in GitLab 11.11. diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 8b65da4ab94..4bdf72673a1 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -425,6 +425,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]` | | 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"` | @@ -438,6 +439,26 @@ GFM recognizes the following: | repository file line references | `[README](doc/README#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) + ``` + 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 recognized and formatted with text `#123`. @@ -532,7 +553,7 @@ If this snippet was placed on a page at `<your_wiki>/documentation/main`, it would link to `<your_wiki>/documentation/related`: ```markdown -[Link to Related Page](./related) +[Link to Related Page](related) ``` If this snippet was placed on a page at `<your_wiki>/documentation/related/content`, @@ -546,7 +567,7 @@ If this snippet was placed on a page at `<your_wiki>/documentation/main`, it would link to `<your_wiki>/documentation/related.md`: ```markdown -[Link to Related Page](./related.md) +[Link to Related Page](related.md) ``` If this snippet was placed on a page at `<your_wiki>/documentation/related/content`, diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 5a2ff410253..9e2dfd9ad96 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -1,3 +1,9 @@ +--- +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 +--- + # Operations Dashboard **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5781) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/9218) to [GitLab Premium](https://about.gitlab.com/pricing/) in 11.10. diff --git a/doc/user/packages/composer_repository/img/project_id_v13_5.png b/doc/user/packages/composer_repository/img/project_id_v13_5.png Binary files differdeleted file mode 100644 index 45861b6ff1b..00000000000 --- a/doc/user/packages/composer_repository/img/project_id_v13_5.png +++ /dev/null diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index d4fb662c3a6..6e5563d0d4e 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -77,7 +77,7 @@ Prerequisites: - A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api`. NOTE: **Note:** - [Deploy tokens](./../../project/deploy_tokens/index.md) are + [Deploy tokens](../../project/deploy_tokens/index.md) are [not yet supported](https://gitlab.com/gitlab-org/gitlab/-/issues/240897) for use with Composer. To publish the package: @@ -140,7 +140,7 @@ Prerequisites: - A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to, at minimum, `read_api`. NOTE: **Note:** - [Deploy tokens](./../../project/deploy_tokens/index.md) are + [Deploy tokens](../../project/deploy_tokens/index.md) are [not yet supported](https://gitlab.com/gitlab-org/gitlab/-/issues/240897) for use with Composer. To install a package: diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 10c820a86be..f6f8d6d61b6 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -12,23 +12,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w Publish Conan packages in your project’s Package Registry. Then install the packages whenever you need to use them as a dependency. -To publish Conan packages to the Package Registry, add the -Package Registry as a remote and authenticate with it. +To publish Conan packages to the Package Registry, add the Package Registry as a +remote and authenticate with it. -Then you can run `conan` commands and publish your package to the Package Registry. +Then you can run `conan` commands and publish your package to the +Package Registry. ## Build a Conan package -This section explains how to install Conan and build a package for your C/C++ project. +This section explains how to install Conan and build a package for your C/C++ +project. -If you already use Conan and know how to build your own packages, go to the [next section](#add-the-package-registry-as-a-conan-remote). +If you already use Conan and know how to build your own packages, go to the +[next section](#add-the-package-registry-as-a-conan-remote). ### Install Conan -Download the Conan package manager to your local development environment by following -the instructions at [conan.io](https://conan.io/downloads.html). +Download the Conan package manager to your local development environment by +following the instructions at [conan.io](https://conan.io/downloads.html). -When installation is complete, verify you can use Conan in your terminal by running: +When installation is complete, verify you can use Conan in your terminal by +running: ```shell conan --version @@ -42,15 +46,16 @@ Conan version 1.20.5 ### Install CMake -When you develop with C++ and Conan, you have a range of compilers to choose from. -This example uses the CMake compiler. +When you develop with C++ and Conan, you can select from many available +compilers. This example uses the CMake compiler. To 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 running: +When installation is complete, verify you can use CMake in your terminal by +running: ```shell cmake --version @@ -60,8 +65,8 @@ The CMake version is printed in the output. ### Create a project -To test the Package Registry, you need a C++ project. If you don't already have one, you can clone the -Conan [hello world starter project](https://github.com/conan-io/hello). +To test the Package Registry, you need a C++ project. If you don't already have +one, you can clone the Conan [hello world starter project](https://github.com/conan-io/hello). ### Build a package @@ -74,22 +79,26 @@ To build a package: conan new Hello/0.1 -t ``` -1. Create a package for the recipe by running `conan create` with the Conan user and channel: +1. Create a package for the recipe by running `conan create` with the Conan user + and channel: ```shell conan create . mycompany/beta ``` 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). + 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). A package with the recipe `Hello/0.1@mycompany/beta` is created. -For more details on creating and managing Conan packages, see the [Conan docs](https://docs.conan.io/en/latest/creating_packages.html). +For more details about creating and managing Conan packages, see the +[Conan documentation](https://docs.conan.io/en/latest/creating_packages.html). ## Add the Package Registry as a Conan remote -To run `conan` commands, you must add the Package Registry as a Conan remote for your project or instance. +To run `conan` commands, you must add the Package Registry as a Conan remote for +your project or instance. ### Add a remote for your project @@ -143,9 +152,9 @@ To add the remote: #### Package recipe naming convention for instance remotes -The standard Conan recipe convention is `package_name/version@user/channel`, -but if you're using an [instance remote](#add-a-remote-for-your-instance), the recipe -`user` must be the plus sign (`+`) separated project path. +The standard Conan recipe convention is `package_name/version@user/channel`, but +if you're using an [instance remote](#add-a-remote-for-your-instance), the +recipe `user` must be the plus sign (`+`) separated project path. Example recipe names: @@ -156,58 +165,68 @@ Example recipe names: | `gitlab-org/gitlab-ce` | `my-package/1.0.0@gitlab-org+gitlab-ce/stable` | Yes | | `gitlab-org/gitlab-ce` | `my-package/1.0.0@foo/stable` | No | -[Project remotes](#add-a-remote-for-your-project) have a more flexible naming convention. +[Project remotes](#add-a-remote-for-your-project) have a more flexible naming +convention. ## Authenticate to the Package Registry -To authenticate to the Package Registry, you need either a personal access token or deploy token. +To authenticate to the Package Registry, you need either a personal access token +or deploy token. -- If you use a [personal access token](../../../user/profile/personal_access_tokens.md), set the scope to `api`. -- If you use a [deploy token](./../../project/deploy_tokens/index.md), set the scope to `read_package_registry`, `write_package_registry`, or both. +- If you use a [personal access token](../../../user/profile/personal_access_tokens.md), + set the scope to `api`. +- If you use a [deploy token](../../project/deploy_tokens/index.md), set the + scope to `read_package_registry`, `write_package_registry`, or both. ### Add your credentials to the GitLab remote -Associate your token with the GitLab remote, so that you don't have to explicitly -add a token to every Conan command. +Associate your token with the GitLab remote, so that you don't have to +explicitly add a token to every Conan command. Prerequisites: - You must have an authentication token. -- The Conan remote [must be set](#add-the-package-registry-as-a-conan-remote). +- The Conan remote [must be configured](#add-the-package-registry-as-a-conan-remote). -In a terminal, run this command. In this example, the remote name is `gitlab`. Use the name of your remote. +In a terminal, run this command. In this example, the remote name is `gitlab`. +Use the name of your remote. ```shell conan user <gitlab_username or deploy_token_username> -r gitlab -p <personal_access_token or deploy_token> ``` -Now when you run commands with `--remote=gitlab`, your username and password are automatically included in the requests. +Now when you run commands with `--remote=gitlab`, your username and password are +included in the requests. -Alternately, you can explicitly include your credentials in any given command. For example: +Alternatively, you can explicitly include your credentials in any given command. +For example: ```shell 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:** -Your authentication with GitLab expires on a regular basis, -so occasionally you may need to re-enter your personal access token. +Because your authentication with GitLab expires on a regular basis, you may +occasionally need to re-enter your personal access token. ### Set a default remote for your project (optional) -If you want to interact with the GitLab Package Registry without having to specify a remote, -you can tell Conan to always use the Package Registry for your packages. +If you want to interact with the GitLab Package Registry without having to +specify a remote, you can tell Conan to always use the Package Registry for your +packages. -In a terminal, run this command. +In a terminal, run this command: ```shell conan remote add_ref Hello/0.1@mycompany/beta gitlab ``` NOTE: **Note:** -The package recipe includes the version, so the default remote for `Hello/0.1@user/channel` does not work for `Hello/0.2@user/channel`. +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`. -If you do not set a default user or remote, you can still include the user and remote in your commands: +If you don't set a default user or remote, you can still include the user and +remote in your commands: ```shell `CONAN_LOGIN_USERNAME=<gitlab_username or deploy_token_username> CONAN_PASSWORD=<personal_access_token or deploy_token> <conan command> --remote=gitlab @@ -215,17 +234,18 @@ If you do not set a default user or remote, you can still include the user and r ## Publish a Conan package -Publish a Conan package to the Package Registry, so that anyone who can access the project can use the package as a dependency. +Publish a Conan package to the Package Registry, so that anyone who can access +the project can use the package as a dependency. Prerequisites: -To publish a Conan package, you need: - -- The Package Registry [set as a remote](#add-the-package-registry-as-a-conan-remote). -- [Authentication](#authenticate-to-the-package-registry) set up with the Package Registry. -- A local [Conan package](https://docs.conan.io/en/latest/creating_packages/getting_started.html). +- The Conan remote [must be configured](#add-the-package-registry-as-a-conan-remote). +- [Authentication](#authenticate-to-the-package-registry) with the + Package Registry must be configured. +- A local [Conan package](https://docs.conan.io/en/latest/creating_packages/getting_started.html) + must exist. - For an instance remote, the package must meet the [naming convention](#package-recipe-naming-convention-for-instance-remotes). -- A project ID, which is on the project's homepage. +- You must have the project ID, which is on the project's homepage. To publish the package, use the `conan upload` command: @@ -237,11 +257,11 @@ conan upload Hello/0.1@mycompany/beta --all > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11678) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. -To work with Conan commands in [GitLab CI/CD](./../../../ci/README.md), you can use -`CI_JOB_TOKEN` in place of the personal access token in your commands. +To work with Conan commands in [GitLab CI/CD](../../../ci/README.md), you can +use `CI_JOB_TOKEN` in place of the personal access token in your commands. -You can provide the `CONAN_LOGIN_USERNAME` and `CONAN_PASSWORD` with each -Conan command in your `.gitlab-ci.yml` file. For example: +You can provide the `CONAN_LOGIN_USERNAME` and `CONAN_PASSWORD` with each Conan +command in your `.gitlab-ci.yml` file. For example: ```yaml image: conanio/gcc7 @@ -255,24 +275,26 @@ create_package: - CONAN_LOGIN_USERNAME=ci_user CONAN_PASSWORD=${CI_JOB_TOKEN} conan upload <package-name>/0.1@<group-name>+<project-name>/stable --all --remote=gitlab ``` -Additional Conan images to use as the basis of your CI file are available -in the [Conan docs](https://docs.conan.io/en/latest/howtos/run_conan_in_docker.html#available-docker-images). +Additional Conan images to use as the basis of your CI file are available in the +[Conan docs](https://docs.conan.io/en/latest/howtos/run_conan_in_docker.html#available-docker-images). ## Install a Conan package -Install a Conan package from the Package Registry so you can use it as a dependency. +Install a Conan package from the Package Registry so you can use it as a +dependency. -Conan packages are often installed as dependencies by using the `conanfile.txt` file. +Conan packages are often installed as dependencies by using the `conanfile.txt` +file. Prerequisites: -To install a Conan package, you need: - -- The Package Registry [set as a remote](#add-the-package-registry-as-a-conan-remote). -- [Authentication](#authenticate-to-the-package-registry) set up with the Package Registry. +- The Conan remote [must be configured](#add-the-package-registry-as-a-conan-remote). +- [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 `conanfile.txt`. - Or, in the root of your project, create a file called `conanfile.txt`. +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`. 1. Add the Conan recipe to the `[requires]` section of the file: @@ -284,7 +306,8 @@ To install a Conan package, you need: cmake ``` -1. At the root of your project, create a `build` directory and change to that directory: +1. At the root of your project, create a `build` directory and change to that + directory: ```shell mkdir build && cd build @@ -298,7 +321,7 @@ To install a Conan package, you need: NOTE: **Note:** If you try to install the package you just created in this tutorial, the package -already exists on your local machine, so this command has no effect. +already exists on your local computer, so this command has no effect. ## Remove a Conan package @@ -310,19 +333,22 @@ There are two ways to remove a Conan package from the GitLab Package Registry. conan remove Hello/0.2@user/channel --remote=gitlab ``` - You must explicitly include the remote in this command, otherwise the package is only removed from your - local system cache. + You must explicitly include the remote in this command, otherwise the package + is removed only from your local system cache. NOTE: **Note:** - This command removes all recipe and binary package files from the Package Registry. + This command removes all recipe and binary package files from the + Package Registry. - From the GitLab user interface: - Go to your project's **Packages & Registries > Package Registry**. Remove the package by clicking the red trash icon. + Go to your project's **Packages & Registries > Package Registry**. Remove the + package by clicking the red trash icon. ## Search for Conan packages in the Package Registry -To search by full or partial package name, or by exact recipe, run the `conan search` command. +To search by full or partial package name, or by exact recipe, run the +`conan search` command. - To search for all packages with a specific package name: @@ -336,7 +362,8 @@ To search by full or partial package name, or by exact recipe, run the `conan se conan search He* --remote=gitlab ``` -The scope of your search includes all projects you have permission to access. This includes your private projects as well as all public projects. +The scope of your search includes all projects you have permission to access. +This includes your private projects as well as all public projects. ## Fetch Conan package information from the Package Registry @@ -351,7 +378,9 @@ conan info Hello/0.1@mycompany/beta The GitLab Conan repository supports the following Conan CLI commands: - `conan upload`: Upload your recipe and package files to the Package Registry. -- `conan install`: Install a Conan package from the Package Registry, this includes using the `conanfile.txt` file. -- `conan search`: Search the Package Registry for public packages, and private packages you have permission to view. +- `conan install`: Install a Conan package from the Package Registry, which + includes using the `conanfile.txt` file. +- `conan search`: Search the Package Registry for public packages, and private + packages you have permission to view. - `conan info`: View the information on a given package from the Package Registry. - `conan remove`: Delete the package from the Package Registry. diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index baadd3c91a7..1cb6c951bd9 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -447,7 +447,7 @@ For the project where it's defined, tags matching the regex pattern are removed. The underlying layers and images remain. To delete the underlying layers and images that aren't associated with any tags, administrators can use -[garbage collection](../../../administration/packages/container_registry.md#removing-unused-layers-not-referenced-by-manifests) with the `-m` switch. +[garbage collection](../../../administration/packages/container_registry.md#removing-untagged-manifests-and-unreferenced-layers) with the `-m` switch. ### Enable the cleanup policy @@ -468,7 +468,7 @@ Cleanup policies can be run on all projects, with these exceptions: ``` There are performance risks with enabling it for all projects, especially if you - are using an [external registry](./index.md#use-with-external-container-registries). + are using an [external registry](index.md#use-with-external-container-registries). - For self-managed GitLab instances, you can enable or disable the cleanup policy for a specific project. @@ -522,7 +522,7 @@ To create a cleanup policy in the UI: | **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. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | + | **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). | 1. Click **Set cleanup policy**. @@ -544,6 +544,8 @@ Here are examples of regex patterns you may want to use: .* ``` + This is the default value for the expiration regex. + - Match tags that start with `v`: ```plaintext @@ -578,7 +580,7 @@ See the API documentation for further details: [Edit project](../../../api/proje ### Use with external container registries -When using an [external container registry](./../../../administration/packages/container_registry.md#use-an-external-container-registry-with-gitlab-as-an-auth-endpoint), +When using an [external container registry](../../../administration/packages/container_registry.md#use-an-external-container-registry-with-gitlab-as-an-auth-endpoint), running a cleanup policy on a project may have some performance risks. If a project runs a policy to remove thousands of tags the GitLab background jobs may get backed up or fail completely. diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index 3fa21ef486b..e1fae770a5d 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -4,9 +4,10 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Dependency Proxy **(PREMIUM)** +# Dependency Proxy -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. +> - [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. The GitLab Dependency Proxy is a local proxy you can use for your frequently-accessed upstream images. @@ -41,6 +42,9 @@ 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: diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 0c961b5c86f..f489c7c800f 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -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/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: @@ -85,12 +85,12 @@ Example request that uses a personal access token: ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" \ - https://gitlab.example.com/api/v4/projects/24/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 -To work with generic packages in [GitLab CI/CD](./../../../ci/README.md), you can use +To work with generic packages in [GitLab CI/CD](../../../ci/README.md), you can use `CI_JOB_TOKEN` in place of the personal access token in your commands. For example: @@ -137,3 +137,9 @@ Feature.disable(:generic_packages) # For a single project Feature.disable(:generic_packages, Project.find(<project id>)) ``` + +### Generic package sample project + +The [Write CI-CD Variables in Pipeline](https://gitlab.com/guided-explorations/cfg-data/write-ci-cd-variables-in-pipeline) project contains a working example you can use to create, upload, and download generic packages in GitLab CI/CD. + +It also demonstrates how to manage a semantic version for the generic package: storing it in a CI/CD variable, retrieving it, incrementing it, and writing it back to the CI/CD variable when tests for the download work correctly. diff --git a/doc/user/packages/go_proxy/index.md b/doc/user/packages/go_proxy/index.md index bd3b5b49ebd..81edc3afcfd 100644 --- a/doc/user/packages/go_proxy/index.md +++ b/doc/user/packages/go_proxy/index.md @@ -4,11 +4,11 @@ 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 --- -# GitLab Go Proxy +# Go proxy for GitLab > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27376) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.1. > - It's deployed behind a feature flag, disabled by default. -> - It's disabled on GitLab.com. +> - It's disabled for GitLab.com. > - It's not recommended for production use. > - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-the-go-proxy). > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. @@ -16,14 +16,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w With the Go proxy for GitLab, every project in GitLab can be fetched with the [Go proxy protocol](https://proxy.golang.org/). -## Prerequisites +## Enable the Go proxy -### Enable the Go proxy +The Go proxy for GitLab is under development, and isn't ready for production use +due to [potential performance issues with large repositories](https://gitlab.com/gitlab-org/gitlab/-/issues/218083). -The Go proxy for GitLab is under development and not ready for production use, due to -[potential performance issues with large repositories](https://gitlab.com/gitlab-org/gitlab/-/issues/218083). - -It is deployed behind a feature flag that is **disabled by default**. +It's 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 for your instance. @@ -47,57 +45,46 @@ Feature.enable(:go_proxy, Project.find(1)) Feature.disable(:go_proxy, Project.find(2)) ``` -### Enable the Package Registry - -The Package Registry is enabled for new projects by default. If you cannot find -the **Packages > List** entry under your project's sidebar, verify -the following: - -1. Your GitLab administrator has - [enabled support for the Package Registry](../../../administration/packages/index.md). -1. The Package Registry is [enabled for your project](../index.md). - NOTE: **Note:** -GitLab does not currently display Go modules in the **Packages Registry** of a project. -Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/213770) for details. +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. ## Add GitLab as a Go proxy -NOTE: **Note:** -To use a Go proxy, you must be using Go 1.13 or later. - -The available proxy endpoints are: +To use GitLab as a Go proxy, you must be using Go 1.13 or later. -- Project - can fetch modules defined by a project - `/api/v4/projects/:id/packages/go` +The available proxy endpoint is for fetching modules by project: `/api/v4/projects/:id/packages/go` -To use the Go proxy for GitLab to fetch Go modules from GitLab, add the -appropriate proxy endpoint to `GOPROXY`. For details on setting Go environment -variables, see [Set environment variables](#set-environment-variables). For -details on configuring `GOPROXY`, see [Dependency Management in Go > -Proxies](../../../development/go_guide/dependencies.md#proxies). +To fetch Go modules from GitLab, add the project-specific endpoint to `GOPROXY`. -For example, adding the project-specific endpoint to `GOPROXY` will tell Go -to initially query that endpoint and fall back to the default behavior: +Go queries the endpoint and falls back to the default behavior: ```shell -go env -w GOPROXY='https://gitlab.com/api/v4/projects/1234/packages/go,https://proxy.golang.org,direct' +go env -w GOPROXY='https://gitlab.example.com/api/v4/projects/1234/packages/go,https://proxy.golang.org,direct' ``` -With this configuration, Go fetches dependencies as follows: +With this configuration, Go fetches dependencies in this order: -1. Attempt to fetch from the project-specific Go proxy. -1. Attempt to fetch from [proxy.golang.org](https://proxy.golang.org). -1. Fetch directly with version control system operations (such as `git clone`, +1. Go attempts to fetch from the project-specific Go proxy. +1. Go attempts to fetch from [proxy.golang.org](https://proxy.golang.org). +1. Go fetches directly with version control system operations (like `git clone`, `svn checkout`, and so on). -If `GOPROXY` is not specified, Go follows steps 2 and 3, which corresponds to -setting `GOPROXY` to `https://proxy.golang.org,direct`. If `GOPROXY` only -contains the project-specific endpoint, Go will only query that endpoint. +If `GOPROXY` isn't specified, Go follows steps 2 and 3, which corresponds to +setting `GOPROXY` to `https://proxy.golang.org,direct`. If `GOPROXY` +contains only the project-specific endpoint, Go queries only that endpoint. + +For details about how to set Go environment variables, see +[Set environment variables](#set-environment-variables). + +For details about configuring `GOPROXY`, see +[Dependency Management in Go > Proxies](../../../development/go_guide/dependencies.md#proxies). ## Fetch modules from private projects -`go` does not support transmitting credentials over insecure connections. The -steps below work only if GitLab is configured for HTTPS. +`go` doesn't support transmitting credentials over insecure connections. The +following steps work only if GitLab is configured for HTTPS: 1. Configure Go to include HTTP basic authentication credentials when fetching from the Go proxy for GitLab. @@ -107,31 +94,38 @@ steps below work only if GitLab is configured for HTTPS. ### Enable request authentication Create a [personal access token](../../profile/personal_access_tokens.md) with -the `api` or `read_api` scope and add it to -[`~/.netrc`](https://ec.haxx.se/usingcurl/usingcurl-netrc): +the scope set to `api` or `read_api`. -```netrc +Open your [`~/.netrc`](https://ec.haxx.se/usingcurl/usingcurl-netrc) file +and add the following text. Replace the variables in `< >` with your values. + +```plaintext machine <url> login <username> password <token> ``` -`<url>` should be the URL of the GitLab instance, for example `gitlab.com`. -`<username>` and `<token>` should be your username and the personal access -token, respectively. +- `<url>`: The GitLab URL, for example `gitlab.com`. +- `<username>`: Your username. +- `<token>`: Your personal access token. ### Disable checksum database queries -When downloading dependencies, by default Go 1.13 and later validate fetched -sources against the checksum database `sum.golang.org`. If the checksum of the -fetched sources does not match the checksum from the database, Go will not build -the dependency. This causes private modules to fail to build, as -`sum.golang.org` cannot fetch the source of private modules and thus cannot -provide a checksum. To resolve this issue, `GONOSUMDB` should be set to a -comma-separated list of private projects. For details on setting Go environment -variables, see [Set environment variables](#set-environment-variables). For more -details on disabling this feature of Go, see [Dependency Management in Go > -Checksums](../../../development/go_guide/dependencies.md#checksums). +When downloading dependencies with Go 1.13 and later, fetched sources are +validated against the checksum database `sum.golang.org`. + +If the checksum of the fetched sources doesn't match the checksum from the +database, Go doesn't build the dependency. + +Private modules fail to build because `sum.golang.org` can't fetch the source +of private modules, and so it cannot provide a checksum. + +To resolve this issue, set `GONOSUMDB` to a comma-separated list of private +projects. For details about setting Go environment variables, see +[Set environment variables](#set-environment-variables). For more details about +disabling this feature of Go, see +[Dependency Management in Go > Checksums](../../../development/go_guide/dependencies.md#checksums). -For example, to disable checksum queries for `gitlab.com/my/project`, set `GONOSUMDB`: +For example, to disable checksum queries for `gitlab.com/my/project`, set +`GONOSUMDB`: ```shell go env -w GONOSUMDB='gitlab.com/my/project,<previous value>' @@ -139,32 +133,36 @@ go env -w GONOSUMDB='gitlab.com/my/project,<previous value>' ## Working with Go -If you are unfamiliar with managing dependencies in Go, or Go in general, -consider reviewing the following documentation: +If you're unfamiliar with managing dependencies in Go, or Go in general, review +the following documentation: - [Dependency Management in Go](../../../development/go_guide/dependencies.md) - [Go Modules Reference](https://golang.org/ref/mod) -- [Documentation (golang.org)](https://golang.org/doc/) -- [Learn (learn.go.dev)](https://learn.go.dev/) +- [Documentation (`golang.org`)](https://golang.org/doc/) +- [Learn (`learn.go.dev`)](https://learn.go.dev/) ### Set environment variables -Go uses environment variables to control various features. These can be managed -in all the usual ways, but Go 1.14 will read and write Go environment variables -from and to a special Go environment file, `~/.go/env` by default. If `GOENV` is -set to a file, Go will read and write that file instead. If `GOENV` is not set -but `GOPATH` is set, Go will read and write `$GOPATH/env`. +Go uses environment variables to control various features. You can manage these +variables in all the usual ways. However, Go 1.14 reads and writes Go +environment variables to and from a special Go environment file, `~/.go/env` by +default. + +- If `GOENV` is set to a file, Go reads and writes to and from that file instead. +- If `GOENV` is not set but `GOPATH` is set, Go reads and writes `$GOPATH/env`. Go environment variables can be read with `go env <var>` and, in Go 1.14 and -later, can be written with `go env -w <var>=<value>`. For example, `go env -GOPATH` or `go env -w GOPATH=/go`. +later, can be written with `go env -w <var>=<value>`. For example, +`go env GOPATH` or `go env -w GOPATH=/go`. ### Release a module Go modules and module versions are defined by source repositories, such as Git, -SVN, Mercurial, and so on. A module is a repository containing `go.mod` and Go -files. Module versions are defined by 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. See [Dependency Management in Go > -Versioning](../../../development/go_guide/dependencies.md#versioning) for more -details on what constitutes a valid module or module version. +SVN, and Mercurial. A module is a repository that contains `go.mod` and Go +files. Module versions are defined by 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. + +See [Dependency Management in Go > Versioning](../../../development/go_guide/dependencies.md#versioning) +for more details about what constitutes a valid module or module version. diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index 53ba3d01b3e..83d179cbc9c 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -30,31 +30,31 @@ The Package Registry supports the following formats: You can also use the [API](../../api/packages.md) to administer the Package Registry. -The GitLab [Container Registry](container_registry/index.md) is a secure and private registry for container images. -It's built on open source software and completely integrated within GitLab. -Use GitLab CI/CD to create and publish images. Use the GitLab [API](../../api/container_registry.md) to -manage the registry across groups and projects. +## Accepting contributions -The [Dependency Proxy](dependency_proxy/index.md) is a local proxy for frequently-used upstream images and packages. - -## Suggested contributions - -Consider contributing to GitLab. This [development documentation](../../development/packages.md) will -guide you through the process. Or check out how other members of the community -are adding support for [PHP](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17417) or [Terraform](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834). +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. -| Format | Use case | +| Format | Status | | ------ | ------ | -| [Cargo](https://gitlab.com/gitlab-org/gitlab/-/issues/33060) | Cargo is the Rust package manager. Build, publish and share Rust packages | -| [Chef](https://gitlab.com/gitlab-org/gitlab/-/issues/36889) | Configuration management with Chef using all the benefits of a repository manager. | -| [CocoaPods](https://gitlab.com/gitlab-org/gitlab/-/issues/36890) | Speed up development with Xcode and CocoaPods. | -| [Conda](https://gitlab.com/gitlab-org/gitlab/-/issues/36891) | Secure and private local Conda repositories. | -| [CRAN](https://gitlab.com/gitlab-org/gitlab/-/issues/36892) | Deploy and resolve CRAN packages for the R language. | -| [Debian](https://gitlab.com/gitlab-org/gitlab/-/issues/5835) | Host and provision Debian packages. | -| [Opkg](https://gitlab.com/gitlab-org/gitlab/-/issues/36894) | Optimize your work with OpenWrt using Opkg repositories. | -| [P2](https://gitlab.com/gitlab-org/gitlab/-/issues/36895) | Host all your Eclipse plugins in your own GitLab P2 repository. | -| [Puppet](https://gitlab.com/gitlab-org/gitlab/-/issues/36897) | Configuration management meets repository management with Puppet repositories. | -| [RPM](https://gitlab.com/gitlab-org/gitlab/-/issues/5932) | Distribute RPMs directly from GitLab. | -| [RubyGems](https://gitlab.com/gitlab-org/gitlab/-/issues/803) | Use GitLab to host your own gems. | -| [SBT](https://gitlab.com/gitlab-org/gitlab/-/issues/36898) | Resolve dependencies from and deploy build output to SBT repositories when running SBT builds. | -| [Vagrant](https://gitlab.com/gitlab-org/gitlab/-/issues/36899) | Securely host your Vagrant boxes in local repositories. | +| Chef | [#36889](https://gitlab.com/gitlab-org/gitlab/-/issues/36889) | +| CocoaPods | [#36890](https://gitlab.com/gitlab-org/gitlab/-/issues/36890) | +| Conda | [#36891](https://gitlab.com/gitlab-org/gitlab/-/issues/36891) | +| CRAN | [#36892](https://gitlab.com/gitlab-org/gitlab/-/issues/36892) | +| Debian | [WIP: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44746) | +| Opkg | [#36894](https://gitlab.com/gitlab-org/gitlab/-/issues/36894) | +| P2 | [#36895](https://gitlab.com/gitlab-org/gitlab/-/issues/36895) | +| Puppet | [#36897](https://gitlab.com/gitlab-org/gitlab/-/issues/36897) | +| RPM | [#5932](https://gitlab.com/gitlab-org/gitlab/-/issues/5932) | +| RubyGems | [#803](https://gitlab.com/gitlab-org/gitlab/-/issues/803) | +| SBT | [#36898](https://gitlab.com/gitlab-org/gitlab/-/issues/36898) | +| Terraform | [WIP: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834) | +| Vagrant | [#36899](https://gitlab.com/gitlab-org/gitlab/-/issues/36899) | + +## Container Registry + +The GitLab [Container Registry](container_registry/index.md) is a secure and private registry for container images. It's built on open source software and completely integrated within GitLab. Use GitLab CI/CD to create and publish images. Use the GitLab [API](../../api/container_registry.md) to manage the registry across groups and projects. + +## Dependency Proxy + +The [Dependency Proxy](dependency_proxy/index.md) is a local proxy for frequently-used upstream images and packages. diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index d4a8ff0cdb4..5d0d64b310d 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -17,9 +17,9 @@ Then, install the packages whenever you need to use them as a dependency. This section explains how to install Maven and build a package. If you already use Maven and know how to build your own packages, go to the -[next section](#add-the-package-registry-as-a-maven-remote). +[next section](#authenticate-to-the-package-registry-with-maven). -Maven repositories work well with Gradle, too. To set up a Gradle project, see [get started with Gradle](#use-gradle-to-create-a-java-project). +Maven repositories work well with Gradle, too. To set up a Gradle project, see [get started with Gradle](#build-a-java-project-with-gradle). ### Install Maven @@ -29,14 +29,14 @@ The required minimum versions are: - Maven 3.6+ Follow the instructions at [maven.apache.org](https://maven.apache.org/install.html) -to download and install Maven for your local development environment. Once +to download and install Maven for your local development environment. After installation is complete, verify you can use Maven in your terminal by running: ```shell mvn --version ``` -You should see something similar to the below printed in the output: +The output should be similar to: ```shell Apache Maven 3.6.1 (d66c9c0b3152b2e69ee9bac180bb8fcc8e6af555; 2019-04-04T20:00:29+01:00) @@ -48,29 +48,26 @@ OS name: "mac os x", version: "10.15.2", arch: "x86_64", family: "mac" ### Create a project -Understanding how to create a full Java project is outside the scope of this -guide but you can follow the steps below to create a new project that can be +Follow these steps to create a Maven project that can be published to the GitLab Package Registry. -Start by opening your terminal and creating a directory where you would like to -store the project in your environment. From inside the directory, you can run -the following Maven command to initialize a new package: +1. Open your terminal and create a directory to store the project. +1. From the new directory, run this Maven command to initialize a new package: -```shell -mvn archetype:generate -DgroupId=com.mycompany.mydepartment -DartifactId=my-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false -``` + ```shell + mvn archetype:generate -DgroupId=com.mycompany.mydepartment -DartifactId=my-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false + ``` -The arguments are as follows: + The arguments are: -- `DgroupId`: A unique string that identifies your package. You should follow -the [Maven naming conventions](https://maven.apache.org/guides/mini/guide-naming-conventions.html). -- `DartifactId`: The name of the JAR, appended to the end of the `DgroupId`. -- `DarchetypeArtifactId`: The archetype used to create the initial structure of -the project. -- `DinteractiveMode`: Create the project using batch mode (optional). + - `DgroupId`: A unique string that identifies your package. Follow + the [Maven naming conventions](https://maven.apache.org/guides/mini/guide-naming-conventions.html). + - `DartifactId`: The name of the `JAR`, appended to the end of the `DgroupId`. + - `DarchetypeArtifactId`: The archetype used to create the initial structure of + the project. + - `DinteractiveMode`: Create the project using batch mode (optional). -After running the command, you should see the following message, indicating that -your project has been set up successfully: +This message indicates that the project was set up successfully: ```shell ... @@ -82,33 +79,33 @@ your project has been set up successfully: [INFO] ------------------------------------------------------------------------ ``` -You should see a new directory where you ran this command matching your -`DartifactId` parameter (in this case it should be `my-project`). +In the folder where you ran the command, a new directory should be displayed. +The directory name should match the `DartifactId` parameter, which in this case, +is `my-project`. -## Use Gradle to create a Java project +## Build a Java project with Gradle This section explains how to install Gradle and initialize a Java project. If you already use Gradle and know how to build your own packages, go to the -[next section](#add-the-package-registry-as-a-maven-remote). +[next section](#authenticate-to-the-package-registry-with-maven). ### Install Gradle -Installation is needed only if you want to create a new Gradle project. Follow +If you want to create a new Gradle project, you must install Gradle. Follow instructions at [gradle.org](https://gradle.org/install/) to download and install Gradle for your local development environment. -Verify you can use Gradle in your terminal by running: +In your terminal, verify you can use Gradle by running: ```shell gradle -version ``` -If you want to use an existing Gradle project, installation is not necessary. -Simply execute `gradlew` (on Linux) or `gradlew.bat` (on Windows) in the project -directory instead. +To use an existing Gradle project, in the project directory, +on Linux execute `gradlew`, or on Windows execute `gradlew.bat`. -You should see something similar to the below printed in the output: +The output should be similar to: ```plaintext ------------------------------------------------------------ @@ -127,88 +124,79 @@ OS: Windows 10 10.0 amd64 ### Create a Java project -Understanding how to create a full Java project in Gradle is outside the scope of this -guide, but you can follow the steps below to create a new project that can be +Follow these steps to create a Maven project that can be published to the GitLab Package Registry. -Start by opening your terminal and creating a directory where you would like to -store the project in your environment. From inside the directory, you can run -the following Maven command to initialize a new package: +1. Open your terminal and create a directory to store the project. +1. From this new directory, run this Maven command to initialize a new package: -```shell -gradle init -``` + ```shell + gradle init + ``` -The output should be + The output should be: -```plaintext -Select type of project to generate: - 1: basic - 2: application - 3: library - 4: Gradle plugin -Enter selection (default: basic) [1..4] -``` + ```plaintext + Select type of project to generate: + 1: basic + 2: application + 3: library + 4: Gradle plugin + Enter selection (default: basic) [1..4] + ``` -Enter `3` to create a new Library project. The output should be: +1. Enter `3` to create a new Library project. The output should be: -```plaintext -Select implementation language: - 1: C++ - 2: Groovy - 3: Java - 4: Kotlin - 5: Scala - 6: Swift -``` + ```plaintext + Select implementation language: + 1: C++ + 2: Groovy + 3: Java + 4: Kotlin + 5: Scala + 6: Swift + ``` -Enter `3` to create a new Java Library project. The output should be: +1. Enter `3` to create a new Java Library project. The output should be: -```plaintext -Select build script DSL: - 1: Groovy - 2: Kotlin -Enter selection (default: Groovy) [1..2] -``` + ```plaintext + Select build script DSL: + 1: Groovy + 2: Kotlin + Enter selection (default: Groovy) [1..2] + ``` -Choose `1` to create a new Java Library project which is described in Groovy DSL. The output should be: +1. Enter `1` to create a new Java Library project that is described in Groovy DSL. The output should be: -```plaintext -Select test framework: - 1: JUnit 4 - 2: TestNG - 3: Spock - 4: JUnit Jupiter -``` + ```plaintext + Select test framework: + 1: JUnit 4 + 2: TestNG + 3: Spock + 4: JUnit Jupiter + ``` -Choose `1` to initialize the project with JUnit 4 testing libraries. The output should be: +1. Enter `1` to initialize the project with JUnit 4 testing libraries. The output should be: -```plaintext -Project name (default: test): -``` + ```plaintext + Project name (default: test): + ``` -Enter a project name or hit enter to use the directory name as project name. +1. Enter a project name or press Enter to use the directory name as project name. -## Add the Package Registry as a Maven remote +## Authenticate to the Package Registry with Maven -The next step is to add the GitLab Package Registry as a Maven remote. If a -project is private or you want to upload Maven artifacts to GitLab, -credentials must be provided for authorization too. Support is available -for [personal access tokens](#authenticate-with-a-personal-access-token), -[CI job tokens](#authenticate-with-a-ci-job-token), and -[deploy tokens](../../project/deploy_tokens/index.md) only. Regular username/password -credentials do not work. +To authenticate to the Package Registry, you need either a personal access token or deploy token. -### Authenticate with a personal access token +- If you use a [personal access token](../../../user/profile/personal_access_tokens.md), set the scope to `api`. +- If you use a [deploy token](../../project/deploy_tokens/index.md), set the scope to `read_package_registry`, `write_package_registry`, or both. -To authenticate with a [personal access token](../../profile/personal_access_tokens.md), -set the scope to `api` when creating one, and add it to your Maven or Gradle configuration -files. +### Authenticate with a personal access token in Maven -#### Authenticate with a personal access token in Maven +To use a personal access token, add this section to your +[`settings.xml`](https://maven.apache.org/settings.html) file. -Add a corresponding section to your -[`settings.xml`](https://maven.apache.org/settings.html) file: +The `name` must be `Private-Token`. ```xml <settings> @@ -228,45 +216,40 @@ Add a corresponding section to your </settings> ``` -#### Authenticate with a personal access token in Gradle +### Authenticate with a deploy token in Maven -Create a file `~/.gradle/gradle.properties` with the following content: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) deploy token authentication in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. -```groovy -gitLabPrivateToken=REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN -``` +To use a deploy token, add this section to your +[`settings.xml`](https://maven.apache.org/settings.html) file. -Add a repositories section to your -[`build.gradle`](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html) -file: +The `name` must be `Deploy-Token`. -```groovy -repositories { - maven { - url "https://<gitlab-url>/api/v4/groups/<group>/-/packages/maven" - name "GitLab" - credentials(HttpHeaderCredentials) { - name = 'Private-Token' - value = gitLabPrivateToken - } - authentication { - header(HttpHeaderAuthentication) - } - } -} +```xml +<settings> + <servers> + <server> + <id>gitlab-maven</id> + <configuration> + <httpHeaders> + <property> + <name>Deploy-Token</name> + <value>REPLACE_WITH_YOUR_DEPLOY_TOKEN</value> + </property> + </httpHeaders> + </configuration> + </server> + </servers> +</settings> ``` -You should now be able to upload Maven artifacts to your project. - -### Authenticate with a CI job token +### Authenticate with a CI job token in Maven -If you're using GitLab CI/CD, a CI job token can be used instead -of a personal access token. +To authenticate with a CI job token, add this section to your +[`settings.xml`](https://maven.apache.org/settings.html) file. -#### Authenticate with a CI job token in Maven - -To authenticate with a CI job token, add a corresponding section to your -[`settings.xml`](https://maven.apache.org/settings.html) file: +The `name` must be `Job-Token`. ```xml <settings> @@ -286,23 +269,35 @@ To authenticate with a CI job token, add a corresponding section to your </settings> ``` -You can read more on -[how to create Maven packages using GitLab CI/CD](#creating-maven-packages-with-gitlab-cicd). +Read more about [how to create Maven packages using GitLab CI/CD](#create-maven-packages-with-gitlab-cicd). + +## Authenticate to the Package Registry with Gradle -#### Authenticate with a CI job token in Gradle +To authenticate to the Package Registry, you need either a personal access token or deploy token. -To authenticate with a CI job token, add a repositories section to your +- If you use a [personal access token](../../../user/profile/personal_access_tokens.md), set the scope to `api`. +- If you use a [deploy token](../../project/deploy_tokens/index.md), set the scope to `read_package_registry`, `write_package_registry`, or both. + +### Authenticate with a personal access token in Gradle + +Create a file `~/.gradle/gradle.properties` with the following content: + +```groovy +gitLabPrivateToken=REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN +``` + +Add a `repositories` section to your [`build.gradle`](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html) file: ```groovy repositories { maven { - url "https://<gitlab-url>/api/v4/groups/<group>/-/packages/maven" + url "https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven" name "GitLab" credentials(HttpHeaderCredentials) { - name = 'Job-Token' - value = System.getenv("CI_JOB_TOKEN") + name = 'Private-Token' + value = gitLabPrivateToken } authentication { header(HttpHeaderAuthentication) @@ -311,51 +306,42 @@ repositories { } ``` -### Authenticate with a deploy token - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. - -To authenticate with a [deploy token](./../../project/deploy_tokens/index.md), -set the scope to `api` when creating one, and add it to your Maven or Gradle configuration -files. - -#### Authenticate with a deploy token in Maven +### Authenticate with a deploy token in Gradle -Add a corresponding section to your -[`settings.xml`](https://maven.apache.org/settings.html) file: +To authenticate with a deploy token, add a `repositories` section to your +[`build.gradle`](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html) +file: -```xml -<settings> - <servers> - <server> - <id>gitlab-maven</id> - <configuration> - <httpHeaders> - <property> - <name>Deploy-Token</name> - <value>REPLACE_WITH_YOUR_DEPLOY_TOKEN</value> - </property> - </httpHeaders> - </configuration> - </server> - </servers> -</settings> +```groovy +repositories { + maven { + url "https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven" + name "GitLab" + credentials(HttpHeaderCredentials) { + name = 'Deploy-Token' + value = '<deploy-token>' + } + authentication { + header(HttpHeaderAuthentication) + } + } +} ``` -#### Authenticate with a deploy token in Gradle +### Authenticate with a CI job token in Gradle -To authenticate with a deploy token, add a repositories section to your +To authenticate with a CI job token, add a `repositories` section to your [`build.gradle`](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html) file: ```groovy repositories { maven { - url "https://<gitlab-url>/api/v4/groups/<group>/-/packages/maven" + url "https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven" name "GitLab" credentials(HttpHeaderCredentials) { - name = 'Deploy-Token' - value = '<deploy-token>' + name = 'Job-Token' + value = System.getenv("CI_JOB_TOKEN") } authentication { header(HttpHeaderAuthentication) @@ -364,177 +350,162 @@ repositories { } ``` -## Configuring your project to use the GitLab Maven repository URL - -To download and upload packages from GitLab, you need a `repository` and -`distributionManagement` section in your `pom.xml` file. If you're following the -steps from above, then you must add the following information to your -`my-project/pom.xml` file. +## Use the GitLab endpoint for Maven packages -Depending on your workflow and the amount of Maven packages you have, there are -3 ways you can configure your project to use the GitLab endpoint for Maven packages: +To use the GitLab endpoint for Maven packages, choose an option: -- **Project level**: Useful when you have few Maven packages which are not under +- **Project-level**: Use when you have few Maven packages and they are not in the same GitLab group. -- **Group level**: Useful when you have many Maven packages under the same GitLab +- **Group-level**: Use when you have many Maven packages in the same GitLab group. -- **Instance level**: Useful when you have many Maven packages under different - GitLab groups or on their own namespace. +- **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. -NOTE: **Note:** -In all cases, you need a project specific URL for uploading a package in -the `distributionManagement` section. +In all cases, to publish a package, you need: -### Project level Maven endpoint +- A project-specific URL in the `distributionManagement` section. +- A `repository` and `distributionManagement` section. -The example below shows how the relevant `repository` section of your `pom.xml` -would look like in Maven: +### Project-level Maven endpoint + +The relevant `repository` section of your `pom.xml` +in Maven should look like this: ```xml <repositories> <repository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> </repository> </repositories> <distributionManagement> <repository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> </repository> <snapshotRepository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> </snapshotRepository> </distributionManagement> ``` -The corresponding section in Gradle would look like this: +The corresponding section in Gradle would be: ```groovy repositories { maven { - url "https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven" + url "https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven" name "GitLab" } } ``` -The `id` must be the same with what you -[defined in `settings.xml`](#add-the-package-registry-as-a-maven-remote). - -Replace `PROJECT_ID` with your project ID which can be found on the home page -of your project. +- The `id` is what you [defined in `settings.xml`](#authenticate-to-the-package-registry-with-maven). +- The `PROJECT_ID` is your project ID, which you can view on your project's home page. +- Replace `gitlab.example.com` with your domain name. +- For retrieving artifacts, use either the + [URL-encoded](../../../api/README.md#namespaced-path-encoding) path of the project + (like `group%2Fproject`) or the project's ID (like `42`). However, only the + project's ID can be used for publishing. -If you have a self-managed GitLab installation, replace `gitlab.com` with your -domain name. +### Group-level Maven endpoint -NOTE: **Note:** -For retrieving artifacts, you can use either the -[URL encoded](../../../api/README.md#namespaced-path-encoding) path of the project -(such as `group%2Fproject`) or the project's ID (such as `42`). However, only the -project's ID can be used for uploading. - -### Group level Maven endpoint - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8798) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8798) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. If you rely on many packages, it might be inefficient to include the `repository` section -with a unique URL for each package. Instead, you can use the group level endpoint for -all your Maven packages stored within one GitLab group. Only packages you have access to +with a unique URL for each package. Instead, you can use the group-level endpoint for +all the Maven packages stored within one GitLab group. Only packages you have access to are available for download. -The group level endpoint works with any package names, which means the you -have the flexibility of naming compared to [instance level endpoint](#instance-level-maven-endpoint). -However, GitLab does not guarantee the uniqueness of the package names within +The group-level endpoint works with any package names, so you +have more flexibility in naming, compared to the [instance-level endpoint](#instance-level-maven-endpoint). +However, GitLab does not guarantee the uniqueness of package names within the group. You can have two projects with the same package name and package version. As a result, GitLab serves whichever one is more recent. -The example below shows how the relevant `repository` section of your `pom.xml` -would look like. You still need a project specific URL for uploading a package in +This example shows the relevant `repository` section of your `pom.xml` file. +You still need a project-specific URL for publishing a package in the `distributionManagement` section: ```xml <repositories> <repository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/groups/GROUP_ID/-/packages/maven</url> + <url>https://gitlab.example.com/api/v4/groups/GROUP_ID/-/packages/maven</url> </repository> </repositories> <distributionManagement> <repository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> </repository> <snapshotRepository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> </snapshotRepository> </distributionManagement> ``` -For Gradle, the corresponding repositories section would look like: +For Gradle, the corresponding `repositories` section would look like: ```groovy repositories { maven { - url "https://gitlab.com/api/v4/groups/GROUP_ID/-/packages/maven" + url "https://gitlab.example.com/api/v4/groups/GROUP_ID/-/packages/maven" name "GitLab" } } ``` -The `id` must be the same with what you -[defined in `settings.xml`](#add-the-package-registry-as-a-maven-remote). - -Replace `my-group` with your group name and `PROJECT_ID` with your project ID -which can be found on the home page of your project. - -If you have a self-managed GitLab installation, replace `gitlab.com` with your -domain name. +- For the `id`, use what you [defined in `settings.xml`](#authenticate-to-the-package-registry-with-maven). +- For `my-group`, use your group name. +- For `PROJECT_ID`, use your project ID, which you can view on your project's home page. +- Replace `gitlab.example.com` with your domain name. +- For retrieving artifacts, use either the + [URL-encoded](../../../api/README.md#namespaced-path-encoding) path of the group + (like `group%2Fsubgroup`) or the group's ID (like `12`). -NOTE: **Note:** -For retrieving artifacts, you can use either the -[URL encoded](../../../api/README.md#namespaced-path-encoding) path of the group -(such as `group%2Fsubgroup`) or the group's ID (such as `12`). +### Instance-level Maven endpoint -### Instance level Maven endpoint - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8274) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8274) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. If you rely on many packages, it might be inefficient to include the `repository` section -with a unique URL for each package. Instead, you can use the instance level endpoint for -all maven packages stored in GitLab and the packages you have access to are available +with a unique URL for each package. Instead, you can use the instance-level endpoint for +all Maven packages stored in GitLab. All packages you have access to are available for download. -Note that **only packages that have the same path as the project** are exposed via -the instance level endpoint. +**Only packages that have the same path as the project** are exposed by +the instance-level endpoint. -| Project | Package | Instance level endpoint available | +| Project | Package | Instance-level endpoint available | | ------- | ------- | --------------------------------- | | `foo/bar` | `foo/bar/1.0-SNAPSHOT` | Yes | | `gitlab-org/gitlab` | `foo/bar/1.0-SNAPSHOT` | No | | `gitlab-org/gitlab` | `gitlab-org/gitlab/1.0-SNAPSHOT` | Yes | -The example below shows how the relevant `repository` section of your `pom.xml` -would look like. You still need a project specific URL for uploading a package in -the `distributionManagement` section: +This example shows how relevant `repository` section of your `pom.xml`. +You still need a project-specific URL in the `distributionManagement` section. ```xml <repositories> <repository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/packages/maven</url> + <url>https://gitlab.example.com/api/v4/packages/maven</url> </repository> </repositories> <distributionManagement> <repository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> </repository> <snapshotRepository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> </snapshotRepository> </distributionManagement> ``` @@ -544,40 +515,35 @@ The corresponding repositories section in Gradle would look like: ```groovy repositories { maven { - url "https://gitlab.com/api/v4/packages/maven" + url "https://gitlab.example.com/api/v4/packages/maven" name "GitLab" } } ``` -The `id` must be the same with what you -[defined in `settings.xml`](#add-the-package-registry-as-a-maven-remote). - -Replace `PROJECT_ID` with your project ID which can be found on the home page -of your project. - -If you have a self-managed GitLab installation, replace `gitlab.com` with your -domain name. +- The `id` is what you [defined in `settings.xml`](#authenticate-to-the-package-registry-with-maven). +- The `PROJECT_ID` is your project ID, which you can view on your project's home page. +- Replace `gitlab.example.com` with your domain name. +- For retrieving artifacts, use either the + [URL-encoded](../../../api/README.md#namespaced-path-encoding) path of the project + (like `group%2Fproject`) or the project's ID (like `42`). However, only the + project's ID can be used for publishing. -NOTE: **Note:** -For retrieving artifacts, you can use either the -[URL encoded](../../../api/README.md#namespaced-path-encoding) path of the project -(such as `group%2Fproject`) or the project's ID (such as `42`). However, only the -project's ID can be used for uploading. +## Publish a package -## Uploading packages +After you have set up the [remote and authentication](#authenticate-to-the-package-registry-with-maven) +and [configured your project](#use-the-gitlab-endpoint-for-maven-packages), +publish a Maven artifact from your project. -Once you have set up the [remote and authentication](#add-the-package-registry-as-a-maven-remote) -and [configured your project](#configuring-your-project-to-use-the-gitlab-maven-repository-url), -test to upload a Maven artifact from a project of yours. +### Publish by using Maven -### Upload using Maven +To publish a package by using Maven: ```shell mvn deploy ``` -If the deploy is successful, you should see the build success message again: +If the deploy is successful, the build success message should be displayed: ```shell ... @@ -585,108 +551,112 @@ If the deploy is successful, you should see the build success message again: ... ``` -You should also see that the upload was uploaded to the correct registry: +The message should also show that the package was published to the correct location: ```shell -Uploading to gitlab-maven: https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.jar +Uploading to gitlab-maven: https://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.jar ``` -### Upload using Gradle +### Publish by using Gradle -Add the Gradle plugin [`maven-publish`](https://docs.gradle.org/current/userguide/publishing_maven.html) to the plugins section: +To publish a package by using Gradle: -```groovy -plugins { - id 'java' - id 'maven-publish' -} -``` +1. Add the Gradle plugin [`maven-publish`](https://docs.gradle.org/current/userguide/publishing_maven.html) to the plugins section: -Add a `publishing` section: + ```groovy + plugins { + id 'java' + id 'maven-publish' + } + ``` -```groovy -publishing { - publications { - library(MavenPublication) { - from components.java - } - } - repositories { - maven { - url "https://gitlab.com/api/v4/projects/<PROJECT_ID>/packages/maven" - credentials(HttpHeaderCredentials) { - name = "Private-Token" - value = gitLabPrivateToken // the variable resides in ~/.gradle/gradle.properties - } - authentication { - header(HttpHeaderAuthentication) - } - } - } -} -``` +1. Add a `publishing` section: + + ```groovy + publishing { + publications { + library(MavenPublication) { + from components.java + } + } + repositories { + maven { + url "https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/packages/maven" + credentials(HttpHeaderCredentials) { + name = "Private-Token" + value = gitLabPrivateToken // the variable resides in ~/.gradle/gradle.properties + } + authentication { + header(HttpHeaderAuthentication) + } + } + } + } + ``` -Replace `PROJECT_ID` with your project ID which can be found on the home page -of your project. +1. Replace `PROJECT_ID` with your project ID, which can be found on your project's home page. -Run the publish task: +1. Run the publish task: -```shell -gradle publish -``` + ```shell + gradle publish + ``` -You can then navigate to your project's **Packages & Registries** page and see the uploaded -artifacts or even delete them. +Now navigate to your project's **Packages & Registries** page and view the published artifacts. -## Installing a package +## Install a package -Installing a package from the GitLab Package Registry requires that you set up -the [remote and authentication](#add-the-package-registry-as-a-maven-remote) -as above. Once this is completed, there are two ways to install a package. +To install a package from the GitLab Package Registry, you must configure +the [remote and authenticate](#authenticate-to-the-package-registry-with-maven). +When this is completed, there are two ways to install a package. -### Install using Maven with `mvn install` +### Use Maven with `mvn install` -Add the dependency manually to your project `pom.xml` file. To add the example -created above, the XML would look like: +To install a package by using `mvn install`: -```xml -<dependency> - <groupId>com.mycompany.mydepartment</groupId> - <artifactId>my-project</artifactId> - <version>1.0-SNAPSHOT</version> -</dependency> -``` +1. Add the dependency manually to your project `pom.xml` file. + To add the example created earlier, the XML would be: -Then, inside your project, run the following: + ```xml + <dependency> + <groupId>com.mycompany.mydepartment</groupId> + <artifactId>my-project</artifactId> + <version>1.0-SNAPSHOT</version> + </dependency> + ``` -```shell -mvn install -``` +1. In your project, run the following: + + ```shell + mvn install + ``` -Provided everything is set up correctly, you should see the dependency -downloaded from the GitLab Package Registry: +The message should show that the package is downloading from the Package Registry: ```shell -Downloading from gitlab-maven: http://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom +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 ``` -### Install using Maven with `mvn dependency:get` +### Use Maven with `mvn dependency:get` -The second way to install packages is to use the Maven commands directly. -Inside your project directory, run: +You can install packages by using the Maven commands directly. + +1. In your project directory, run: + + ```shell + mvn dependency:get -Dartifact=com.nickkipling.app:nick-test-app:1.1-SNAPSHOT + ``` + +The message should show that the package is downloading from the Package Registry: ```shell -mvn dependency:get -Dartifact=com.nickkipling.app:nick-test-app:1.1-SNAPSHOT +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 ``` -You should see the same downloading message confirming that the project was -retrieved from the GitLab Package Registry. - TIP: **Tip:** -Both the XML block and Maven command are readily copy and pastable from the -Package details page, allowing for quick and easy installation. +In the GitLab UI, on the Package Registry page for Maven, you can view and copy these commands. -### Install using Gradle +### Use Gradle Add a [dependency](https://docs.gradle.org/current/userguide/declaring_dependencies.html) to `build.gradle` in the dependencies section: @@ -696,25 +666,25 @@ dependencies { } ``` -## Removing a package +## Remove a package -In the packages view of your project page, you can delete packages by clicking -the red trash icons or by clicking the **Delete** button on the package details -page. +For your project, go to **Packages & Registries > Package Registry**. -## Creating Maven packages with GitLab CI/CD +To remove a package, click the red trash icon or, from the package details, the **Delete** button. -Once you have your repository configured to use the GitLab Maven Repository, +## Create Maven packages with GitLab CI/CD + +After you have configured your repository to use the Package Repository for Maven, you can configure GitLab CI/CD to build new packages automatically. -### Creating Maven packages with GitLab CI/CD using Maven +### Create Maven packages with GitLab CI/CD by using Maven -The example below shows how to create a new package each time the `master` branch -is updated: +You can create a new package each time the `master` branch is updated. 1. Create a `ci_settings.xml` file that serves as Maven's `settings.xml` file. - Add the server section with the same ID you defined in your `pom.xml` file. - For example, in our case it's `gitlab-maven`: + +1. Add the `server` section with the same ID you defined in your `pom.xml` file. + For example, use `gitlab-maven` as the ID: ```xml <settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" @@ -735,30 +705,29 @@ is updated: </settings> ``` -1. Make sure your `pom.xml` file includes the following: +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. ```xml <repositories> <repository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> </repository> </repositories> <distributionManagement> <repository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> </repository> <snapshotRepository> <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> </snapshotRepository> </distributionManagement> ``` - TIP: **Tip:** - You can either let Maven utilize the CI environment variables or hardcode your project's ID. - 1. Add a `deploy` job to your `.gitlab-ci.yml` file: ```yaml @@ -773,16 +742,17 @@ is updated: 1. Push those files to your repository. The next time the `deploy` job runs, it copies `ci_settings.xml` to the -user's home location (in this case the user is `root` since it runs in a -Docker container), and Maven uses the configured CI -[environment variables](../../../ci/variables/README.md#predefined-environment-variables). +user's home location. In this example: + +- The user is `root`, because the job runs in a Docker container. +- Maven uses the configured CI [environment variables](../../../ci/variables/README.md#predefined-environment-variables). -### Creating Maven packages with GitLab CI/CD using Gradle +### Create Maven packages with GitLab CI/CD by using Gradle -The example below shows how to create a new package each time the `master` branch -is updated: +You can create a package each time the `master` branch +is updated. -1. Make sure you use the Job-Token authentication as described in ["Authenticating with a CI job token in Gradle"](#authenticate-with-a-ci-job-token-in-gradle). +1. Authenticate with [a CI job token in Gradle](#authenticate-with-a-ci-job-token-in-gradle). 1. Add a `deploy` job to your `.gitlab-ci.yml` file: @@ -795,11 +765,13 @@ is updated: - master ``` -1. Push those files to your repository. +1. Commit files to your repository. + +When the pipeline is successful, the package is created. ### Version validation -The version string is validated using the following regex. +The version string is validated by using the following regex. ```ruby \A(\.?[\w\+-]+\.?)+\z @@ -827,7 +799,7 @@ When you set these options, all network requests are logged and a large amount o ### Useful Maven command-line options There are some [Maven command-line options](https://maven.apache.org/ref/current/maven-embedder/cli.html) -that may be useful when performing tasks with GitLab CI/CD. +that you can use when performing tasks with GitLab CI/CD. - File transfer progress can make the CI logs hard to read. Option `-ntp,--no-transfer-progress` was added in @@ -835,7 +807,7 @@ that may be useful when performing tasks with GitLab CI/CD. Alternatively, look at `-B,--batch-mode` [or lower level logging changes.](https://stackoverflow.com/questions/21638697/disable-maven-download-progress-indication) -- Specify where to find the POM file (`-f,--file`): +- Specify where to find the `pom.xml` file (`-f,--file`): ```yaml package: @@ -852,11 +824,10 @@ that may be useful when performing tasks with GitLab CI/CD. - 'mvn -s settings/ci.xml package' ``` -### Verifying your Maven settings +### Verify your Maven settings -If you encounter issues within CI that relate to the `settings.xml` file, it might be useful -to add an additional script task or job to -[verify the effective settings](https://maven.apache.org/plugins/maven-help-plugin/effective-settings-mojo.html). +If you encounter issues within CI/CD that relate to the `settings.xml` file, try adding +an additional script task or job to [verify the effective settings](https://maven.apache.org/plugins/maven-help-plugin/effective-settings-mojo.html). The help plugin can also provide [system properties](https://maven.apache.org/plugins/maven-help-plugin/system-mojo.html), including environment variables: diff --git a/doc/user/packages/npm_registry/img/npm_package_view_v12_5.png b/doc/user/packages/npm_registry/img/npm_package_view_v12_5.png Binary files differdeleted file mode 100644 index a6f823011eb..00000000000 --- a/doc/user/packages/npm_registry/img/npm_package_view_v12_5.png +++ /dev/null diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index f15b31d8b67..feb797240f4 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -4,331 +4,378 @@ 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 --- -# GitLab NPM Registry +# NPM packages in the Package Registry > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. -With the GitLab NPM Registry, every -project can have its own space to store NPM packages. +Publish NPM packages in your project's Package Registry. Then install the +packages whenever you need to use them as a dependency. - - -NOTE: **Note:** Only [scoped](https://docs.npmjs.com/misc/scope) packages are supported. -## Enabling the NPM Registry - -NOTE: **Note:** -This option is available only if your GitLab administrator has -[enabled support for the NPM registry](../../../administration/packages/index.md). - -Enabling the NPM registry makes it available for all new projects -by default. To enable it for existing projects, or if you want to disable it: - -1. Navigate to your project's **Settings > General > Visibility, project features, permissions**. -1. Find the Packages feature and enable or disable it. -1. Click on **Save changes** for the changes to take effect. - -You should then be able to see the **Packages & Registries** section on the left sidebar. +## Build an NPM package -Before proceeding to authenticating with the GitLab NPM Registry, you should -get familiar with the package naming convention. +This section covers how to install NPM or Yarn and build a package for your +JavaScript project. -## Getting started +If you already use NPM and know how to build your own packages, go to +the [next section](#authenticate-to-the-package-registry). -This section covers how to install NPM (or Yarn) and build a package for your -JavaScript project. This is a quickstart if you are new to NPM packages. If you -are already using NPM and understand how to build your own packages, move on to -the [next section](#authenticating-to-the-gitlab-npm-registry). +### Install NPM -### Installing 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). -Follow the instructions at [npmjs.com](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) to download and install Node.js and -NPM to your local development environment. - -Once installation is complete, verify you can use NPM in your terminal by +When installation is complete, verify you can use NPM in your terminal by running: ```shell npm --version ``` -You should see the NPM version printed in the output: +The NPM version is shown in the output: ```plaintext 6.10.3 ``` -### Installing Yarn +### Install Yarn -You may want to install and use Yarn as an alternative to NPM. Follow the -instructions at [yarnpkg.com](https://classic.yarnpkg.com/en/docs/install) to install on -your development environment. +As an alternative to NPM, you can install Yarn in your local environment by following the +instructions at [yarnpkg.com](https://classic.yarnpkg.com/en/docs/install). -Once installed, you can verify that Yarn is available with the following command: +When installation is complete, verify you can use Yarn in your terminal by +running: ```shell yarn --version ``` -You should see the version printed like so: +The Yarn version is shown in the output: ```plaintext 1.19.1 ``` -### Creating a project +### Create a project -Understanding how to create a full JavaScript project is outside the scope of -this guide but you can initialize a new empty package by creating and navigating -to an empty directory and using the following command: +To create a project: -```shell -npm init -``` +1. Create an empty directory. +1. Go to the directory and initialize an empty package by running: -Or if you're using Yarn: + ```shell + npm init + ``` -```shell -yarn init -``` + Or if you're using Yarn: + + ```shell + yarn init + ``` + +1. Enter responses to the questions. Ensure the **package name** follows + the [naming convention](#package-naming-convention) and is scoped to the + project or group where the registry exists. + +A `package.json` file is created. + +## Use the GitLab endpoint for NPM packages + +To use the GitLab endpoint for NPM packages, choose an option: + +- **Project-level**: Use when you have few NPM packages and they are not in + the same GitLab group. +- **Instance-level**: Use when you have many NPM packages in different + GitLab groups or in their own namespace. Be sure to comply with the [package naming convention](#package-naming-convention). -This takes you through a series of questions to produce a `package.json` -file, which is required for all NPM packages. The most important question is the -package name. NPM packages must [follow the naming convention](#package-naming-convention) -and be scoped to the project or group where the registry exists. +Some features such as [publishing](#publish-an-npm-package) a package is only available on the project-level endpoint. -Once you have completed the setup, you are now ready to upload your package to -the GitLab registry. To get started, you need to set up authentication and then -configure GitLab as a remote registry. +## Authenticate to the Package Registry -## Authenticating to the GitLab NPM Registry +To authenticate to the Package Registry, you must use one of the following: -If a project is private or you want to upload an NPM package to GitLab, -you need to provide credentials for authentication. [Personal access tokens](../../profile/personal_access_tokens.md) -and [deploy tokens](../../project/deploy_tokens/index.md) -are preferred, but support is available for [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow). +- A [personal access token](../../../user/profile/personal_access_tokens.md) + (required for two-factor authentication (2FA)), with the scope set to `api`. +- A [deploy token](../../project/deploy_tokens/index.md), with the scope set to `read_package_registry`, `write_package_registry`, or both. +- It's not recommended, but you can use [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow). + Standard OAuth tokens cannot authenticate to the GitLab NPM Registry. You must use a personal access token with OAuth headers. +- A [CI job token](#authenticate-with-a-ci-job-token). -CAUTION: **Two-factor authentication (2FA) is only supported with personal access tokens:** -If you have 2FA enabled, you need to use a [personal access token](../../profile/personal_access_tokens.md) with OAuth headers with the scope set to `api` or a [deploy token](../../project/deploy_tokens/index.md) with `read_package_registry` or `write_package_registry` scopes. Standard OAuth tokens cannot authenticate to the GitLab NPM Registry. +### Authenticate with a personal access token or deploy token -### Authenticating 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 a [personal access token](../../profile/personal_access_tokens.md) or [deploy token](../../project/deploy_tokens/index.md), -set your NPM configuration: +#### Project-level NPM endpoint + +To use the [project-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, set your NPM configuration: ```shell # Set URL for your scoped packages. # For example package with name `@foo/bar` will use this URL for download -npm config set @foo:registry https://gitlab.com/api/v4/packages/npm/ +npm config set @foo:registry https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/ -# Add the token for the scoped packages URL. This will allow you to download -# `@foo/` packages from private projects. -npm config set '//gitlab.com/api/v4/packages/npm/:_authToken' "<your_token>" - -# Add token for uploading to the registry. Replace <your_project_id> -# with the project you want your package to be uploaded to. -npm config set '//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>" +# Add the token for the scoped packages URL. Replace <your_project_id> +# with the project where your package is located. +npm config set '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>" ``` -Replace `<your_project_id>` with your project ID which can be found on the home page -of your project and `<your_token>` with your personal access token or deploy token. - -If you have a self-managed GitLab installation, replace `gitlab.com` with your -domain name. +- `<your_project_id>` is your project ID, found on the project's home page. +- `<your_token>` is your personal access token or deploy token. +- Replace `gitlab.example.com` with your domain name. -You should now be able to download and upload NPM packages to your project. +You should now be able to publish and install NPM packages in your project. -NOTE: **Note:** -If you encounter an error message with [Yarn](https://classic.yarnpkg.com/en/), see the -[troubleshooting section](#troubleshooting). +If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view +[troubleshooting steps](#troubleshooting). -### Using variables to avoid hard-coding auth token values +#### Instance-level NPM endpoint -To avoid hard-coding the `authToken` value, you may use a variables in its place: +To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, set your NPM configuration: ```shell -npm config set '//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "${NPM_TOKEN}" -npm config set '//gitlab.com/api/v4/packages/npm/:_authToken' "${NPM_TOKEN}" -``` +# Set URL for your scoped packages. +# For example package with name `@foo/bar` will use this URL for download +npm config set @foo:registry https://gitlab.example.com/api/v4/packages/npm/ -Then, you could run `npm publish` either locally or via GitLab CI/CD: +# Add the token for the scoped packages URL. This will allow you to download +# `@foo/` packages from private projects. +npm config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_token>" +``` -- **Locally:** Export `NPM_TOKEN` before publishing: +- `<your_token>` is your personal access token or deploy token. +- Replace `gitlab.example.com` with your domain name. - ```shell - NPM_TOKEN=<your_token> npm publish - ``` +You should now be able to publish and install NPM packages in your project. -- **GitLab CI/CD:** Set an `NPM_TOKEN` [variable](../../../ci/variables/README.md) - under your project's **Settings > CI/CD > Variables**. +If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view +[troubleshooting steps](#troubleshooting). -### Authenticating with a CI job token +### Authenticate with a CI job token -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9104) in GitLab Premium 12.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9104) in GitLab Premium 12.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. -If you’re using NPM with GitLab CI/CD, a CI job token can be used instead of a personal access token or deploy token. +If you're using NPM with GitLab CI/CD, a CI job token can be used instead of a personal access token or deploy token. The token inherits the permissions of the user that generates the pipeline. -Add a corresponding section to your `.npmrc` file: +#### Project-level NPM endpoint + +To use the [project-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, add a corresponding section to your `.npmrc` file: ```ini -@foo:registry=https://gitlab.com/api/v4/packages/npm/ -//gitlab.com/api/v4/packages/npm/:_authToken=${CI_JOB_TOKEN} -//gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN} +@foo:registry=https://gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/ +//gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN} ``` -## Uploading packages +#### Instance-level NPM endpoint -Before you can upload a package, you need to specify the registry -for NPM. To do this, add the following section to the bottom of `package.json`: +To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, add a corresponding section to your `.npmrc` file: -```json -"publishConfig": { - "@foo:registry":"https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/" -} +```ini +@foo:registry=https://gitlab.example.com/api/v4/packages/npm/ +//gitlab.example.com/api/v4/packages/npm/:_authToken=${CI_JOB_TOKEN} ``` -Replace `<your_project_id>` with your project ID, which can be found on the home -page of your project, and replace `@foo` with your own scope. - -If you have a self-managed GitLab installation, replace `gitlab.com` with your -domain name. +#### Use variables to avoid hard-coding auth token values -Once you have enabled it and set up [authentication](#authenticating-to-the-gitlab-npm-registry), -you can upload an NPM package to your project: +To avoid hard-coding the `authToken` value, you may use a variable in its place: ```shell -npm publish +npm config set '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "${NPM_TOKEN}" +npm config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "${NPM_TOKEN}" ``` -You can then navigate to your project's **Packages & Registries** page and see the uploaded -packages or even delete them. +Then, you can run `npm publish` either locally or by using GitLab CI/CD. -Attempting to publish a package with a name that already exists within -a given scope causes a `403 Forbidden!` error. +- **Locally:** Export `NPM_TOKEN` before publishing: -## Uploading a package with the same version twice + ```shell + NPM_TOKEN=<your_token> npm publish + ``` -You cannot upload a package with the same name and version twice, unless you -delete the existing package first. This aligns with npmjs.org's behavior, with -the exception that npmjs.org does not allow users to ever publish the same version -more than once, even if it has been deleted. +- **GitLab CI/CD:** Set an `NPM_TOKEN` [variable](../../../ci/variables/README.md) + under your project's **Settings > CI/CD > Variables**. ## Package naming convention -**Packages must be scoped in the root namespace of the project**. The package -name may be anything but it is preferred that the project name be used unless -it is not possible due to a naming collision. For example: +Your NPM package name must be in the format of `@scope:package-name`. + +- The `@scope` is the root namespace of the GitLab project. It must match exactly, including the case. +- The `package-name` can be whatever you want. + +For example, if your project is `https://gitlab.example.com/my-org/engineering-group/team-amazing/analytics`, +the root namespace is `my-org`. When you publish a package, it must have `my-org` as the scope. | Project | Package | Supported | | ---------------------- | ----------------------- | --------- | -| `foo/bar` | `@foo/bar` | Yes | -| `foo/bar/baz` | `@foo/baz` | Yes | -| `foo/bar/buz` | `@foo/anything` | Yes | +| `my-org/bar` | `@my-org/bar` | Yes | +| `my-org/bar/baz` | `@my-org/baz` | Yes | +| `My-org/Bar/baz` | `@My-org/Baz` | Yes | +| `my-org/bar/buz` | `@my-org/anything` | Yes | | `gitlab-org/gitlab` | `@gitlab-org/gitlab` | Yes | | `gitlab-org/gitlab` | `@foo/bar` | No | -The regex that is used for naming is validating all package names from all package managers: +In GitLab, this regex validates all package names from all package managers: ```plaintext /\A\@?(([\w\-\.\+]*)\/)*([\w\-\.]+)@?(([\w\-\.\+]*)\/)*([\w\-\.]*)\z/ ``` -It allows for capital letters, while NPM does not, and allows for almost all of the -characters NPM allows with a few exceptions (`~` is not allowed). +This regex allows almost all of the characters that NPM allows, with a few exceptions (for example, `~` is not allowed). + +The regex also allows for capital letters, while NPM does not. Capital letters are needed because the scope must be +identical to the root namespace of the project. -NOTE: **Note:** -Capital letters are needed because the scope is required to be -identical to the top level namespace of the project. So, for example, if your -project path is `My-Group/project-foo`, your package must be named `@My-Group/any-package-name`. -`@my-group/any-package-name` will not work. +CAUTION: **Caution:** +When you update the path of a user or group, or transfer a subgroup or project, +you must remove any NPM packages first. You cannot update the root namespace +of a project with NPM packages. Make sure you update your `.npmrc` files to follow +the naming convention and run `npm publish` if necessary. -CAUTION: **When updating the path of a user/group or transferring a (sub)group/project:** -Make sure to remove any NPM packages first. You cannot update the root namespace of a project with NPM packages. Don't forget to update your `.npmrc` files to follow the above naming convention and run `npm publish` if necessary. +## Publish an NPM package -Now, you can configure your project to authenticate with the GitLab NPM -Registry. +Prerequisites: -## Installing a package +- [Authenticate](#authenticate-to-the-package-registry) to the Package Registry. +- Set a [project-level NPM endpoint](#use-the-gitlab-endpoint-for-npm-packages). -NPM packages are commonly installed using the `npm` or `yarn` commands -inside a JavaScript project. If you haven't already, set the -URL for scoped packages. You can do this with the following command: +To upload an NPM package to your project, run this command: ```shell -npm config set @foo:registry https://gitlab.com/api/v4/packages/npm/ +npm publish ``` -Replace `@foo` with your scope. +To view the package, go to your project's **Packages & Registries**. -Next, you need to ensure [authentication](#authenticating-to-the-gitlab-npm-registry) -is setup so you can successfully install the package. Once this has been -completed, you can run the following command inside your project to install a -package: +If you try to publish a package [with a name that already exists](#publishing-packages-with-the-same-name-or-version) within +a given scope, you get a `403 Forbidden!` error. -```shell -npm install @my-project-scope/my-package -``` +## Publish an NPM package by using CI/CD -Or if you're using Yarn: +Prerequisites: -```shell -yarn add @my-project-scope/my-package +- [Authenticate](#authenticate-to-the-package-registry) to the Package Registry. +- Set a [project-level NPM endpoint](#use-the-gitlab-endpoint-for-npm-packages). + +To work with NPM commands within [GitLab CI/CD](../../../ci/README.md), you can use +`CI_JOB_TOKEN` in place of the personal access token or deploy token in your commands. + +An example `.gitlab-ci.yml` file for publishing NPM packages: + +```yaml +image: node:latest + +stages: + - deploy + +deploy: + stage: deploy + script: + - echo "//gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc + - npm publish ``` -### Forwarding requests to npmjs.org +## Publishing packages with the same name or version + +You cannot publish a package if a package of the same name and version already exists. +You must delete the existing package first. + +This aligns with npmjs.org's behavior. However, npmjs.org does not ever let you publish +the same version more than once, even if it has been deleted. + +## Install a package + +NPM packages are commonly-installed by using the `npm` or `yarn` commands +in a JavaScript project. + +1. Set the URL for scoped packages by running: + + ```shell + npm config set @foo:registry https://gitlab.example.com/api/v4/packages/npm/ + ``` + + Replace `@foo` with your scope. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/55344) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9. +1. Ensure [authentication](#authenticate-to-the-package-registry) is configured. -By default, when an NPM package is not found in the GitLab NPM Registry, the request is forwarded to [npmjs.com](https://www.npmjs.com/). +1. In your project, to install a package, run: + + ```shell + npm install @my-project-scope/my-package + ``` + + Or if you're using Yarn: + + ```shell + yarn add @my-project-scope/my-package + ``` + +In [GitLab 12.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/55344), +when an NPM package is not found in the Package Registry, the request is forwarded to [npmjs.com](https://www.npmjs.com/). Administrators can disable this behavior in the [Continuous Integration settings](../../admin_area/settings/continuous_integration.md). -### Installing packages from other organizations +### Install NPM packages from other organizations You can route package requests to organizations and users outside of GitLab. -To do this, add lines to your `.npmrc` file, replacing `my-org` with the namespace or group that owns your project's repository. The name is case-sensitive and must match the name of your group or namespace exactly. +To do this, add lines to your `.npmrc` file. Replace `my-org` with the namespace or group that owns your project's repository, +and use your organization's URL. The name is case-sensitive and must match the name of your group or namespace exactly. ```shell @foo:registry=https://gitlab.example.com/api/v4/packages/npm/ -//gitlab.com/api/v4/packages/npm/:_authToken= "<your_token>" -//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken= "<your_token>" +//gitlab.example.com/api/v4/packages/npm/:_authToken= "<your_token>" +//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken= "<your_token>" @my-other-org:registry=https://gitlab.example.com/api/v4/packages/npm/ -//gitlab.com/api/v4/packages/npm/:_authToken= "<your_token>" -//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken= "<your_token>" +//gitlab.example.com/api/v4/packages/npm/:_authToken= "<your_token>" +//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken= "<your_token>" ``` -## Removing a package +### NPM dependencies metadata -In the packages view of your project page, you can delete packages by clicking -the red trash icons or by clicking the **Delete** button on the package details -page. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11867) in GitLab Premium 12.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. -## Publishing a package with CI/CD +In GitLab 12.6 and later, packages published to the Package Registry expose the following attributes to the NPM client: -To work with NPM commands within [GitLab CI/CD](./../../../ci/README.md), you can use -`CI_JOB_TOKEN` in place of the personal access token or deploy token in your commands. +- name +- version +- dist-tags +- dependencies + - dependencies + - devDependencies + - bundleDependencies + - peerDependencies + - deprecated -A simple example `.gitlab-ci.yml` file for publishing NPM packages: +## Add NPM distribution tags -```yaml -image: node:latest +> - [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. -stages: - - deploy +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. -deploy: - stage: deploy - script: - - echo "//gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc - - npm publish +When you publish a package without a tag, the `latest` tag is added by default. +When you install a package without specifying the tag or version, the `latest` tag is used. + +Examples of the supported `dist-tag` commands: + +```shell +npm publish @scope/package --tag # Publish a package with new tag +npm dist-tag add @scope/package@version my-tag # Add a tag to an existing package +npm dist-tag ls @scope/package # List all tags under the package +npm dist-tag rm @scope/package@version my-tag # Delete a tag from the package +npm install @scope/package@my-tag # Install a specific tag ``` -Learn more about [using `CI_JOB_TOKEN` to authenticate to the GitLab NPM registry](#authenticating-with-a-ci-job-token). +You cannot use your `CI_JOB_TOKEN` or deploy token with the `npm dist-tag` commands. +View [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/258835) for details. + +Due to a bug in NPM 6.9.0, deleting distribution tags fails. Make sure your NPM version is 6.9.1 or later. ## Troubleshooting @@ -344,7 +391,7 @@ info No lockfile found. warning XXX: No license field [1/4] 🔍 Resolving packages... [2/4] 🚚 Fetching packages... -error An unexpected error occurred: "https://gitlab.com/api/v4/projects/XXX/packages/npm/XXX/XXX/-/XXX/XXX-X.X.X.tgz: Request failed \"404 Not Found\"". +error An unexpected error occurred: "https://gitlab.example.com/api/v4/projects/XXX/packages/npm/XXX/XXX/-/XXX/XXX-X.X.X.tgz: Request failed \"404 Not Found\"". info If you think this is a bug, please open a bug report with the information provided in "/Users/XXX/gitlab-migration/module-util/yarn-error.log". info Visit https://classic.yarnpkg.com/en/docs/cli/install for documentation about this command ``` @@ -353,14 +400,14 @@ In this case, try adding this to your `.npmrc` file (and replace `<your_token>` with your personal access token or deploy token): ```plaintext -//gitlab.com/api/v4/projects/:_authToken=<your_token> +//gitlab.example.com/api/v4/projects/:_authToken=<your_token> ``` You can also use `yarn config` instead of `npm config` when setting your auth-token dynamically: ```shell -yarn config set '//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>" -yarn config set '//gitlab.com/api/v4/packages/npm/:_authToken' "<your_token>" +yarn config set '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>" +yarn config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_token>" ``` ### `npm publish` targets default NPM registry (`registry.npmjs.org`) @@ -375,23 +422,20 @@ should look like: "name": "@foo/my-package", "version": "1.0.0", "description": "Example package for GitLab NPM registry", - "publishConfig": { - "@foo:registry":"https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/" - } } ``` And the `.npmrc` file should look like: ```ini -//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=<your_token> -//gitlab.com/api/v4/packages/npm/:_authToken=<your_token> -@foo:registry=https://gitlab.com/api/v4/packages/npm/ +//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=<your_token> +//gitlab.example.com/api/v4/packages/npm/:_authToken=<your_token> +@foo:registry=https://gitlab.example.com/api/v4/packages/npm/ ``` ### `npm install` returns `Error: Failed to replace env in config: ${NPM_TOKEN}` -You do not need a token to run `npm install` unless your project is private (the token is only required to publish). If the `.npmrc` file was checked in with a reference to `$NPM_TOKEN`, you can remove it. If you prefer to leave the reference in, you need to set a value prior to running `npm install` or set the value using [GitLab environment variables](./../../../ci/variables/README.md): +You do not need a token to run `npm install` unless your project is private. The token is only required to publish. If the `.npmrc` file was checked in with a reference to `$NPM_TOKEN`, you can remove it. If you prefer to leave the reference in, you must set a value prior to running `npm install` or set the value by using [GitLab environment variables](../../../ci/variables/README.md): ```shell NPM_TOKEN=<your_token> npm install @@ -399,50 +443,11 @@ NPM_TOKEN=<your_token> npm install ### `npm install` returns `npm ERR! 403 Forbidden` -- Check that your token is not expired and has appropriate permissions. -- Check that [your token does not begin with `-`](https://gitlab.com/gitlab-org/gitlab/-/issues/235473). -- Check if you have attempted to publish a package with a name that already exists within a given scope. -- Ensure the scoped packages URL includes a trailing slash: - - Correct: `//gitlab.com/api/v4/packages/npm/` - - Incorrect: `//gitlab.com/api/v4/packages/npm` - -## NPM dependencies metadata - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11867) in GitLab Premium 12.6. - -Starting from GitLab 12.6, new packages published to the GitLab NPM Registry expose the following attributes to the NPM client: - -- name -- version -- dist-tags -- dependencies - - dependencies - - devDependencies - - bundleDependencies - - peerDependencies - - deprecated - -## NPM distribution tags - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9425) in GitLab Premium 12.8. - -You can add [distribution tags](https://docs.npmjs.com/cli/dist-tag) for newly published packages. -They follow NPM's convention where they are optional, and each tag can only be assigned to one -package at a time. The `latest` tag is added by default when a package is published without a tag. -The same applies to installing a package without specifying the tag or version. - -Examples of the supported `dist-tag` commands and using tags in general: - -```shell -npm publish @scope/package --tag # Publish new package with new tag -npm dist-tag add @scope/package@version my-tag # Add a tag to an existing package -npm dist-tag ls @scope/package # List all tags under the package -npm dist-tag rm @scope/package@version my-tag # Delete a tag from the package -npm install @scope/package@my-tag # Install a specific tag -``` - -NOTE: **Note:** -You cannot use your `CI_JOB_TOKEN` or deploy token with the `npm dist-tag` commands. View [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/258835) for details. +If you get this error, ensure that: -CAUTION: **Warning:** -Due to a bug in NPM 6.9.0, deleting dist tags fails. Make sure your NPM version is greater than 6.9.1. +- Your token is not expired and has appropriate permissions. +- [Your token does not begin with `-`](https://gitlab.com/gitlab-org/gitlab/-/issues/235473). +- A package with the same name doesn't already exist within the given scope. +- The scoped packages URL includes a trailing slash: + - Correct: `//gitlab.example.com/api/v4/packages/npm/` + - Incorrect: `//gitlab.example.com/api/v4/packages/npm` diff --git a/doc/user/packages/nuget_repository/img/visual_studio_nuget_source_added.png b/doc/user/packages/nuget_repository/img/visual_studio_nuget_source_added.png Binary files differindex e4f6068f28c..8c14a14e304 100644 --- a/doc/user/packages/nuget_repository/img/visual_studio_nuget_source_added.png +++ b/doc/user/packages/nuget_repository/img/visual_studio_nuget_source_added.png diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 22e1a95649d..2b61c4a6c28 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -4,34 +4,38 @@ 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 --- -# GitLab NuGet Repository +# NuGet packages in the Package Registry > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20050) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. -With the GitLab NuGet Repository, every project can have its own space to store NuGet packages. +Publish NuGet packages in your project’s Package Registry. Then, install the +packages whenever you need to use them as a dependency. -The GitLab NuGet Repository works with: +The Package Registry works with: - [NuGet CLI](https://docs.microsoft.com/en-us/nuget/reference/nuget-exe-cli-reference) - [.NET Core CLI](https://docs.microsoft.com/en-us/dotnet/core/tools/) - [Visual Studio](https://visualstudio.microsoft.com/vs/) -## Setting up your development environment +## Install NuGet -[NuGet CLI 5.1 or later](https://www.nuget.org/downloads) is required. Earlier versions have not been tested -against the GitLab NuGet Repository and might not work. If you have [Visual Studio](https://visualstudio.microsoft.com/vs/), -NuGet CLI is probably already installed. +The required minimum versions are: -Alternatively, you can use [.NET SDK 3.0 or later](https://dotnet.microsoft.com/download/dotnet-core/3.0), which installs NuGet CLI. +- [NuGet CLI 5.1 or later](https://www.nuget.org/downloads). If you have + [Visual Studio](https://visualstudio.microsoft.com/vs/), the NuGet CLI is + probably already installed. +- Alternatively, you can use [.NET SDK 3.0 or later](https://dotnet.microsoft.com/download/dotnet-core/3.0), + which installs the NuGet CLI. +- NuGet protocol version 3 or later. -You can confirm that [NuGet CLI](https://www.nuget.org/) is properly installed with: +Verify that the [NuGet CLI](https://www.nuget.org/) is installed by running: ```shell nuget help ``` -You should see something similar to: +The output should be similar to: ```plaintext NuGet Version: 5.1.0.6013 @@ -43,103 +47,98 @@ Available commands: [output truncated] ``` -NOTE: **Note:** -GitLab currently only supports NuGet's protocol version 3. Earlier versions are not supported. +### Install NuGet on macOS -### macOS support +For macOS, you can use [Mono](https://www.mono-project.com/) to run the +NuGet CLI. -For macOS, you can also use [Mono](https://www.mono-project.com/) to run -the NuGet CLI. For Homebrew users, run `brew install mono` to install -Mono. Then you should be able to download the Windows C# binary -`nuget.exe` from the [NuGet CLI page](https://www.nuget.org/downloads) -and run: +1. If you use Homebrew, to install Mono, run `brew install mono`. +1. Download the Windows C# binary `nuget.exe` from the [NuGet CLI page](https://www.nuget.org/downloads). +1. Run this command: -```shell -mono nuget.exe -``` - -## Enabling the NuGet Repository - -NOTE: **Note:** -This option is available only if your GitLab administrator has -[enabled support for the Package Registry](../../../administration/packages/index.md). - -When the NuGet Repository is enabled, it is available for all new projects -by default. To enable it for existing projects, or if you want to disable it: - -1. Navigate to your project's **Settings > General > Visibility, project features, permissions**. -1. Find the Packages feature and enable or disable it. -1. Click on **Save changes** for the changes to take effect. + ```shell + mono nuget.exe + ``` -You should then be able to see the **Packages & Registries** section on the left sidebar. +## Add the Package Registry as a source for NuGet packages -## Adding the GitLab NuGet Repository as a source to NuGet +To publish and install packages to the Package Registry, you must add the +Package Registry as a source for your packages. -You need the following: +Prerequisites: - Your GitLab username. - A personal access token or deploy token. For repository authentication: - - You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api`. - - You can generate a [deploy token](./../../project/deploy_tokens/index.md) with the scope set to `read_package_registry`, `write_package_registry`, or both. -- A suitable name for your source. -- Your project ID which can be found on the home page of your project. + - You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) + with the scope set to `api`. + - You can generate a [deploy token](../../project/deploy_tokens/index.md) + with the scope set to `read_package_registry`, `write_package_registry`, or + both. +- A name for your source. +- Your project ID, which is found on your project's home page. You can now add a new source to NuGet with: -- [NuGet CLI](#add-nuget-repository-source-with-nuget-cli) -- [Visual Studio](#add-nuget-repository-source-with-visual-studio). -- [.NET CLI](#add-nuget-repository-source-with-net-cli) +- [NuGet CLI](#add-a-source-with-the-nuget-cli) +- [Visual Studio](#add-a-source-with-visual-studio) +- [.NET CLI](#add-a-source-with-the-net-cli) -### Add NuGet Repository source with NuGet CLI +### Add a source with the NuGet CLI -To add the GitLab NuGet Repository as a source with `nuget`: +To add the Package Registry as a source with `nuget`: ```shell -nuget source Add -Name <source_name> -Source "https://gitlab-instance.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" -UserName <gitlab_username or deploy_token_username> -Password <gitlab_personal_access_token or deploy_token> +nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" -UserName <gitlab_username or deploy_token_username> -Password <gitlab_personal_access_token or deploy_token> ``` -Where: - -- `<source_name>` is your desired source name. +- `<source_name>` is the desired source name. For example: ```shell -nuget source Add -Name "GitLab" -Source "https://gitlab.example/api/v4/projects/10/packages/nuget/index.json" -UserName carol -Password 12345678asdf +nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName carol -Password 12345678asdf ``` -### Add NuGet Repository source with Visual Studio +### Add a source with Visual Studio + +To add the Package Registry as a source with Visual Studio: 1. Open [Visual Studio](https://visualstudio.microsoft.com/vs/). -1. Open the **FILE > OPTIONS** (Windows) or **Visual Studio > Preferences** (Mac OS). -1. In the **NuGet** section, open **Sources** to see a list of all your NuGet sources. -1. Click **Add**. -1. Fill the fields with: - - **Name**: Desired name for the source - - **Location**: `https://gitlab.com/api/v4/projects/<your_project_id>/packages/nuget/index.json` - - Replace `<your_project_id>` with your project ID. - - If you have a self-managed GitLab installation, replace `gitlab.com` with your domain name. - - **Username**: Your GitLab username or deploy token username - - **Password**: Your personal access token or deploy token +1. In Windows, select **File > Options**. On macOS, select **Visual Studio > Preferences**. +1. In the **NuGet** section, select **Sources** to view a list of all your NuGet sources. +1. Select **Add**. +1. Complete the following fields: + - **Name**: Name for the source. + - **Location**: `https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json`, + where `<your_project_id>` is your project ID, and `gitlab.example.com` is + your domain name. + - **Username**: Your GitLab username or deploy token username. + - **Password**: Your personal access token or deploy token.  1. Click **Save**. -  +The source is displayed in your list. -In case of any warning, please make sure that the **Location**, **Username**, and **Password** are correct. + -### Add NuGet Repository source with .NET CLI +If you get a warning, ensure that the **Location**, **Username**, and +**Password** are correct. -To add the GitLab NuGet Repository as a source for .NET, create a file named `nuget.config` in the root of your project with the following content: +### Add a source with the .NET CLI -```xml -<?xml version="1.0" encoding="utf-8"?> -<configuration> +To add the Package Registry as a source for .NET: + +1. In the root of your project, create a file named `nuget.config`. +1. Add this content: + + ```xml + <?xml version="1.0" encoding="utf-8"?> + <configuration> <packageSources> <clear /> - <add key="gitlab" value="https://gitlab-instance.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" /> + <add key="gitlab" value="https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" /> </packageSources> <packageSourceCredentials> <gitlab> @@ -147,46 +146,51 @@ To add the GitLab NuGet Repository as a source for .NET, create a file named `nu <add key="ClearTextPassword" value="<gitlab_personal_access_token or deploy_token>" /> </gitlab> </packageSourceCredentials> -</configuration> -``` + </configuration> + ``` + +## Publish a NuGet package -## Uploading packages +When publishing packages: -When uploading packages, note that: +- The Package Registry on GitLab.com can store up to 500 MB of content. + This limit is [configurable for self-managed GitLab instances](../../../administration/instance_limits.md#package-registry-limits). +- If you publish the same package with the same version multiple times, each + consecutive upload is saved as a separate file. When installing a package, + GitLab serves the most recent file. +- When publishing packages to GitLab, they aren't displayed in the packages user + interface of your project immediately. It can take up to 10 minutes to process + a package. -- The Package Registry on GitLab.com can store up to 500 MB of content. This limit is [configurable for self-managed GitLab instances](../../../administration/instance_limits.md#package-registry-limits). -- If you upload the same package with the same version multiple times, each consecutive upload - is saved as a separate file. When installing a package, GitLab serves the most recent file. -- When uploading packages to GitLab, they are not displayed in the packages UI of your project - immediately. It can take up to 10 minutes to process a package. +### Publish a package with the NuGet CLI -### Upload packages with NuGet CLI +Prerequisite: -This section assumes that your project is properly built and you already [created a NuGet package with NuGet CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package). -Upload your package using the following command: +- [A NuGet package created with NuGet CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package). + +Publish a package by running this command: ```shell nuget push <package_file> -Source <source_name> ``` -Where: - - `<package_file>` is your package filename, ending in `.nupkg`. -- `<source_name>` is the [source name used during setup](#adding-the-gitlab-nuget-repository-as-a-source-to-nuget). +- `<source_name>` is the [source name used during setup](#add-a-source-with-the-nuget-cli). + +### Publish a package with the .NET CLI + +Prerequisite: -### Upload packages with .NET CLI +[A NuGet package created with .NET CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package-dotnet-cli). -This section assumes that your project is properly built and you already [created a NuGet package with .NET CLI](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package-dotnet-cli). -Upload your package using the following command: +Publish a package by running this command: ```shell dotnet nuget push <package_file> --source <source_name> ``` -Where: - - `<package_file>` is your package filename, ending in `.nupkg`. -- `<source_name>` is the [source name used during setup](#adding-the-gitlab-nuget-repository-as-a-source-to-nuget). +- `<source_name>` is the [source name used during setup](#add-a-source-with-the-net-cli). For example: @@ -194,16 +198,47 @@ For example: dotnet nuget push MyPackage.1.0.0.nupkg --source gitlab ``` +### Publish a NuGet package by using CI/CD + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36424) in GitLab 13.3. + +If you’re using NuGet with GitLab CI/CD, a CI job token can be used instead of a +personal access token or deploy token. The token inherits the permissions of the +user that generates the pipeline. + +This example shows how to create a new package each time the `master` branch is +updated: + +1. Add a `deploy` job to your `.gitlab-ci.yml` file: + + ```yaml + image: mcr.microsoft.com/dotnet/core/sdk:3.1 + + stages: + - deploy + + deploy: + stage: deploy + script: + - dotnet pack -c Release + - dotnet nuget add source "$CI_SERVER_URL/api/v4/projects/$CI_PROJECT_ID/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text + - dotnet nuget push "bin/Release/*.nupkg" --source gitlab + only: + - master + ``` + +1. Commit the changes and push it to your GitLab repository to trigger a new CI/CD build. + ## Install packages -### Install a package with NuGet CLI +### Install a package with the NuGet CLI CAUTION: **Warning:** -By default, `nuget` checks the official source at `nuget.org` first. If you have a package in the -GitLab NuGet Repository with the same name as a package at `nuget.org`, you must specify the source -name to install the correct package. +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. -Install the latest version of a package using the following command: +Install the latest version of a package by running this command: ```shell nuget install <package_id> -OutputDirectory <output_directory> \ @@ -211,60 +246,24 @@ nuget install <package_id> -OutputDirectory <output_directory> \ -Source <source_name> ``` -Where: - - `<package_id>` is the package ID. - `<output_directory>` is the output directory, where the package is installed. -- `<package_version>` (Optional) is the package version. -- `<source_name>` (Optional) is the source name. +- `<package_version>` The package version. Optional. +- `<source_name>` The source name. Optional. -### Install a package with .NET CLI +### Install a package with the .NET CLI CAUTION: **Warning:** -If you have a package in the GitLab NuGet Repository with the same name as a package at a different source, -you should verify the order in which `dotnet` checks sources during install. This is defined in the -`nuget.config` file. +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. -Install the latest version of a package using the following command: +Install the latest version of a package by running this command: ```shell dotnet add package <package_id> \ -v <package_version> ``` -Where: - - `<package_id>` is the package ID. -- `<package_version>` (Optional) is the package version. - -## Publishing a NuGet package with CI/CD - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36424) in GitLab 13.3. - -If you’re using NuGet with GitLab CI/CD, a CI job token can be used instead of a personal access token or deploy token. -The token inherits the permissions of the user that generates the pipeline. - -This example shows how to create a new package each time the `master` branch -is updated: - -1. Add a `deploy` job to your `.gitlab-ci.yml` file: - - ```yaml - image: mcr.microsoft.com/dotnet/core/sdk:3.1 - - stages: - - deploy - - deploy: - stage: deploy - script: - - dotnet restore -p:Configuration=Release - - dotnet build -c Release - - dotnet pack -c Release - - dotnet nuget add source "$CI_SERVER_URL/api/v4/projects/$CI_PROJECT_ID/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text - - dotnet nuget push "bin/Release/*.nupkg" --source gitlab - only: - - master - ``` - -1. Commit the changes and push it to your GitLab repository to trigger a new CI build. +- `<package_version>` is the package version. Optional. diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index ae9ca5b2333..56fd4a02ba0 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -31,23 +31,30 @@ authenticate with GitLab by using the `CI_JOB_TOKEN`. CI/CD templates, which you can use to get started, are in [this repo](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). -Learn more about [using CI/CD to build Maven packages](../maven_repository/index.md#creating-maven-packages-with-gitlab-cicd), [NPM packages](../npm_registry/index.md#publishing-a-package-with-cicd), [Composer packages](../composer_repository/index.md#publish-a-composer-package-by-using-cicd), [NuGet Packages](../nuget_repository/index.md#publishing-a-nuget-package-with-cicd), [Conan Packages](../conan_repository/index.md#publish-a-conan-package-by-using-cicd), [PyPI packages](../pypi_repository/index.md#using-gitlab-ci-with-pypi-packages), and [generic packages](../generic_packages/index.md#publish-a-generic-package-by-using-cicd). +Learn more about using CI/CD to build: -If you use CI/CD to build a package, extended activity -information is displayed when you view the package details: +- [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) + +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, as well as the commit and -user who triggered it. +When using Maven and NPM, you can view which pipeline published the package, and +the commit and user who triggered it. ## Download a package To download a package: 1. Go to **Packages & Registries > Package Registry**. -1. Click the name of the package you want to download. -1. In the **Activity** section, click the name of the package you want to download. +1. Select the name of the package you want to download. +1. In the **Activity** section, select the name of the package you want to download. ## Delete a package diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 33c37ee6a6c..83b29d5f53a 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -4,89 +4,83 @@ 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 --- -# GitLab PyPI Repository +# PyPI packages in the Package Registry > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. -With the GitLab PyPI Repository, every project can have its own space to store PyPI packages. +Publish PyPI packages in your project’s Package Registry. Then install the +packages whenever you need to use them as a dependency. -The GitLab PyPI Repository works with: +The Package Registry works with: - [pip](https://pypi.org/project/pip/) - [twine](https://pypi.org/project/twine/) -## Setting up your development environment +## Build a PyPI package -You need a recent version of [pip](https://pypi.org/project/pip/) and [twine](https://pypi.org/project/twine/). +This section explains how to create a PyPI package. -## Enabling the PyPI Repository +If you already use PyPI and know how to build your own packages, go to the +[next section](#authenticate-with-the-package-registry). -NOTE: **Note:** -This option is available only if your GitLab administrator has -[enabled support for the Package Registry](../../../administration/packages/index.md). +### Install pip and twine -After the PyPI Repository is enabled, it is available for all new projects -by default. To enable it for existing projects, or if you want to disable it: +Install a recent version of [pip](https://pypi.org/project/pip/) and +[twine](https://pypi.org/project/twine/). -1. Navigate to your project's **Settings > General > Visibility, project features, permissions**. -1. Find the Packages feature and enable or disable it. -1. Click on **Save changes** for the changes to take effect. +### Create a project -You should then be able to see the **Packages & Registries** section on the left sidebar. +Create a test project. -## Getting started +1. Open your terminal. +1. Create a directory called `MyPyPiPackage`, and then go to that directory: -This section covers creating a new example PyPI package to upload. This is a -quickstart to test out the **GitLab PyPI Registry**. If you already understand how -to build and publish your own packages, move on to the [next section](#adding-the-gitlab-pypi-repository-as-a-source). + ```shell + mkdir MyPyPiPackage && cd MyPyPiPackage + ``` -### Create a project +1. Create another directory and go to it: -Understanding how to create a full Python project is outside the scope of this -guide, but you can create a small package to test out the registry. Start by -creating a new directory called `MyPyPiPackage`: + ```shell + mkdir mypypipackage && cd mypypipackage + ``` -```shell -mkdir MyPyPiPackage && cd MyPyPiPackage -``` +1. Create the required files in this directory: -After creating this, create another directory inside: + ```shell + touch __init__.py + touch greet.py + ``` -```shell -mkdir mypypipackage && cd mypypipackage -``` +1. Open the `greet.py` file, and then add: -Create two new files inside this directory to set up the basic project: + ```python + def SayHello(): + print("Hello from MyPyPiPackage") + return + ``` -```shell -touch __init__.py -touch greet.py -``` +1. Open the `__init__.py` file, and then add: -Inside `greet.py`, add the following code: + ```python + from .greet import SayHello + ``` -```python -def SayHello(): - print("Hello from MyPyPiPackage") - return -``` +1. To test the code, in your `MyPyPiPackage` directory, start the Python prompt. -Inside the `__init__.py` file, add the following: + ```shell + python + ``` -```python -from .greet import SayHello -``` +1. Run this command: -Now that the basics of our project is completed, we can test that the code runs. -Start the Python prompt inside your top `MyPyPiPackage` directory. Then run: + ```python + >>> from mypypipackage import SayHello + >>> SayHello() + ``` -```python ->>> from mypypipackage import SayHello ->>> SayHello() -``` - -You should see an output similar to the following: +A message indicates that the project was set up successfully: ```plaintext Python 3.8.2 (v3.8.2:7b3ab5921f, Feb 24 2020, 17:52:18) @@ -97,80 +91,81 @@ Type "help", "copyright", "credits" or "license" for more information. Hello from MyPyPiPackage ``` -Once we've verified that the sample project is working as above, we can next -work on creating a package. - ### Create a package -Inside your `MyPyPiPackage` directory, we need to create a `setup.py` file. Run -the following: +After you create a project, you can create a package. -```shell -touch setup.py -``` +1. In your terminal, go to the `MyPyPiPackage` directory. +1. Create a `setup.py` file: -This file contains all the information about our package. For more information -about this file, see [creating setup.py](https://packaging.python.org/tutorials/packaging-projects/#creating-setup-py). -GitLab identifies packages based on -[Python normalized names (PEP-503)](https://www.python.org/dev/peps/pep-0503/#normalized-names), -so ensure your package name meets these requirements. -See the [installation section](#install-packages) for more details. - -For this guide, we don't need to extensively fill out this file, simply add the -below to your `setup.py`: - -```python -import setuptools - -setuptools.setup( - name="mypypipackage", - version="0.0.1", - author="Example Author", - author_email="author@example.com", - description="A small example package", - packages=setuptools.find_packages(), - classifiers=[ - "Programming Language :: Python :: 3", - "License :: OSI Approved :: MIT License", - "Operating System :: OS Independent", - ], - python_requires='>=3.6', -) -``` + ```shell + touch setup.py + ``` -Save the file, then execute the setup like so: + This file contains all the information about the package. For more information + about this file, see [creating setup.py](https://packaging.python.org/tutorials/packaging-projects/#creating-setup-py). + Because GitLab identifies packages based on + [Python normalized names (PEP-503)](https://www.python.org/dev/peps/pep-0503/#normalized-names), + ensure your package name meets these requirements. See the [installation section](#authenticate-with-a-ci-job-token) + for details. -```shell -python3 setup.py sdist bdist_wheel -``` +1. Open the `setup.py` file, and then add basic information: + + ```python + import setuptools -If successful, you should be able to see the output in a newly created `dist` -folder. Run: + setuptools.setup( + name="mypypipackage", + version="0.0.1", + author="Example Author", + author_email="author@example.com", + description="A small example package", + packages=setuptools.find_packages(), + classifiers=[ + "Programming Language :: Python :: 3", + "License :: OSI Approved :: MIT License", + "Operating System :: OS Independent", + ], + python_requires='>=3.6', + ) + ``` + +1. Save the file. +1. Execute the setup: + + ```shell + python3 setup.py sdist bdist_wheel + ``` + +The output should be visible in a newly-created `dist` folder: ```shell ls dist ``` -And confirm your output matches the below: +The output should appear similar to the following: ```plaintext mypypipackage-0.0.1-py3-none-any.whl mypypipackage-0.0.1.tar.gz ``` -Our package is now all set up and ready to be uploaded to the **GitLab PyPI -Package Registry**. Before we do so, we next need to set up authentication. +The package is now ready to be published to the Package Registry. -## Adding the GitLab PyPI Repository as a source +## Authenticate with the Package Registry -### Authenticating with a personal access token +Before you can publish to the Package Registry, you must authenticate. -You need the following: +To do this, you can use: -- A personal access token. You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication. -- A suitable name for your source. -- Your project ID which can be found on the home page of your project. +- A [personal access token](../../../user/profile/personal_access_tokens.md) + with the scope set to `api`. +- A [deploy token](../../project/deploy_tokens/index.md) with the scope set to + `read_package_registry`, `write_package_registry`, or both. +- A [CI job token](#authenticate-with-a-ci-job-token). -Edit your `~/.pypirc` file and add the following: +### Authenticate with a personal access token + +To authenticate with a personal access token, edit the `~/.pypirc` file and add: ```ini [distutils] @@ -178,20 +173,17 @@ index-servers = gitlab [gitlab] -repository = https://gitlab.com/api/v4/projects/<project_id>/packages/pypi +repository = https://gitlab.example.com/api/v4/projects/<project_id>/packages/pypi username = __token__ password = <your personal access token> ``` -### Authenticating with a deploy token - -You need the following: +- `username` must be `__token__` exactly. +- Your project ID is on your project's home page. -- A deploy token. You can generate a [deploy token](./../../project/deploy_tokens/index.md) with the `read_package_registry` and/or `write_package_registry` scopes for repository authentication. -- A suitable name for your source. -- Your project ID which can be found on the home page of your project. +### Authenticate with a deploy token -Edit your `~/.pypirc` file and add the following: +To authenticate with a deploy token, edit your `~/.pypirc` file and add: ```ini [distutils] @@ -199,21 +191,58 @@ index-servers = gitlab [gitlab] -repository = https://gitlab.com/api/v4/projects/<project_id>/packages/pypi +repository = https://gitlab.example.com/api/v4/projects/<project_id>/packages/pypi username = <deploy token username> password = <deploy token> ``` -## Uploading packages +Your project ID is on your project's home page. -When uploading packages, note that: +### Authenticate with a CI job token -- The maximum allowed size is 50 Megabytes. -- You cannot upload the same version of a package multiple times. If you try, you receive the error `Validation failed: File name has already been taken`. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202012) in GitLab 13.4. + +To work with PyPI commands within [GitLab CI/CD](../../../ci/README.md), you +can use `CI_JOB_TOKEN` instead of a personal access token or deploy token. + +For example: + +```yaml +image: python:latest + +run: + script: + - pip install twine + - python setup.py sdist bdist_wheel + - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine upload --repository-url https://gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/pypi dist/* +``` + +You can also use `CI_JOB_TOKEN` in a `~/.pypirc` file that you check in to +GitLab: + +```ini +[distutils] +index-servers = + gitlab + +[gitlab] +repository = https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/pypi +username = gitlab-ci-token +password = ${env.CI_JOB_TOKEN} +``` + +## Publish a PyPI package + +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`. ### Ensure your version string is valid -If your version string (for example, `0.0.1`) is invalid, it will be rejected. GitLab uses the following regex to validate the version string. +If your version string (for example, `0.0.1`) isn't valid, it will be rejected. +GitLab uses the following regex to validate the version string. ```ruby \A(?: @@ -227,118 +256,86 @@ If your version string (for example, `0.0.1`) is invalid, it will be rejected. G )\z}xi ``` -You can play around with the regex and try your version strings on [this regular expression editor](https://rubular.com/r/FKM6d07ouoDaFV). +You can experiment with the regex and try your version strings by using this +[regular expression editor](https://rubular.com/r/FKM6d07ouoDaFV). -For more details about the regex used, please check the [documentation here](https://www.python.org/dev/peps/pep-0440/#appendix-b-parsing-version-strings-with-regular-expressions)) +For more details about the regex, review this [documentation](https://www.python.org/dev/peps/pep-0440/#appendix-b-parsing-version-strings-with-regular-expressions). -### Upload packages with Twine +### Publish a PyPI package by using twine -If you were following the guide above, then the `MyPyPiPackage` package should -be ready to be uploaded. Run the following command: +To publish a PyPI package, run a command like: ```shell python3 -m twine upload --repository gitlab dist/* ``` -If successful, you should see the following: +This message indicates that the package was published successfully: ```plaintext -Uploading distributions to https://gitlab.com/api/v4/projects/<your_project_id>/packages/pypi +Uploading distributions to https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi Uploading mypypipackage-0.0.1-py3-none-any.whl 100%|███████████████████████████████████████████████████████████████████████████████████████████| 4.58k/4.58k [00:00<00:00, 10.9kB/s] Uploading mypypipackage-0.0.1.tar.gz 100%|███████████████████████████████████████████████████████████████████████████████████████████| 4.24k/4.24k [00:00<00:00, 11.0kB/s] ``` -This indicates that the package was uploaded successfully. You can then navigate -to your project's **Packages & Registries** page and see the uploaded packages. +To view the published package, go to your project's **Packages & Registries** +page. -If you would rather not use a `.pypirc` file to define your repository source, -you can upload to the repository with the authentication inline: +If you didn't use a `.pypirc` file to define your repository source, you can +publish to the repository with the authentication inline: ```shell -TWINE_PASSWORD=<personal_access_token or deploy_token> TWINE_USERNAME=<username or deploy_token_username> python3 -m twine upload --repository-url https://gitlab.com/api/v4/projects/<project_id>/packages/pypi dist/* +TWINE_PASSWORD=<personal_access_token or deploy_token> TWINE_USERNAME=<username or deploy_token_username> python3 -m twine upload --repository-url https://gitlab.example.com/api/v4/projects/<project_id>/packages/pypi dist/* ``` -If you did not follow the guide above, then you need to ensure your package -has been properly built and you [created a PyPI package with `setuptools`](https://packaging.python.org/tutorials/packaging-projects/). +If you didn't follow the steps on this page, ensure your package was properly +built, and that you [created a PyPI package with `setuptools`](https://packaging.python.org/tutorials/packaging-projects/). -You can then upload your package using the following command: +You can then upload your package by using the following command: ```shell python -m twine upload --repository <source_name> dist/<package_file> ``` -Where: - - `<package_file>` is your package filename, ending in `.tar.gz` or `.whl`. -- `<source_name>` is the [source name used during setup](#adding-the-gitlab-pypi-repository-as-a-source). +- `<source_name>` is the [source name used during setup](#authenticate-with-the-package-registry). -## Install packages +## Install a PyPI package -Install the latest version of a package using the following command: +To install the latest version of a package, use the following command: ```shell -pip install --extra-index-url https://__token__:<personal_access_token>@gitlab.com/api/v4/projects/<project_id>/packages/pypi/simple --no-deps <package_name> +pip install --extra-index-url https://__token__:<personal_access_token>@gitlab.example.com/api/v4/projects/<project_id>/packages/pypi/simple --no-deps <package_name> ``` -Where: - - `<package_name>` is the package name. - `<personal_access_token>` is a personal access token with the `read_api` scope. - `<project_id>` is the project ID. -If you were following the guide above and want to test installing the -`MyPyPiPackage` package, you can run the following: +If you were following the guide and want to install the +`MyPyPiPackage` package, you can run: ```shell -pip install mypypipackage --no-deps --extra-index-url https://__token__:<personal_access_token>@gitlab.com/api/v4/projects/<your_project_id>/packages/pypi/simple +pip install mypypipackage --no-deps --extra-index-url https://__token__:<personal_access_token>@gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/simple ``` -This should result in the following: +This message indicates that the package was installed successfully: ```plaintext -Looking in indexes: https://__token__:****@gitlab.com/api/v4/projects/<your_project_id>/packages/pypi/simple +Looking in indexes: https://__token__:****@gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/simple Collecting mypypipackage - Downloading https://gitlab.com/api/v4/projects/<your_project_id>/packages/pypi/files/d53334205552a355fee8ca35a164512ef7334f33d309e60240d57073ee4386e6/mypypipackage-0.0.1-py3-none-any.whl (1.6 kB) + Downloading https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/files/d53334205552a355fee8ca35a164512ef7334f33d309e60240d57073ee4386e6/mypypipackage-0.0.1-py3-none-any.whl (1.6 kB) Installing collected packages: mypypipackage Successfully installed mypypipackage-0.0.1 ``` -GitLab looks for packages using -[Python normalized names (PEP-503)](https://www.python.org/dev/peps/pep-0503/#normalized-names), -so the characters `-`, `_`, and `.` are all treated the same and repeated characters are removed. -A `pip install` request for `my.package` looks for packages that match any of -the three characters, such as `my-package`, `my_package`, and `my....package`. - -## Using GitLab CI with PyPI packages +### Package names -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202012) in GitLab 13.4. - -To work with PyPI commands within [GitLab CI/CD](./../../../ci/README.md), you can use -`CI_JOB_TOKEN` in place of the personal access token or deploy token in your commands. +GitLab looks for packages that use +[Python normalized names (PEP-503)](https://www.python.org/dev/peps/pep-0503/#normalized-names). +The characters `-`, `_`, and `.` are all treated the same, and repeated +characters are removed. -For example: - -```yaml -image: python:latest - -run: - script: - - pip install twine - - python setup.py sdist bdist_wheel - - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine upload --repository-url https://gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/pypi dist/* -``` - -You can also use `CI_JOB_TOKEN` in a `~/.pypirc` file that you check into GitLab: - -```ini -[distutils] -index-servers = - gitlab - -[gitlab] -repository = https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/pypi -username = gitlab-ci-token -password = ${env.CI_JOB_TOKEN} -``` +A `pip install` request for `my.package` looks for packages that match any of +the three characters, such as `my-package`, `my_package`, and `my....package`. diff --git a/doc/user/packages/workflows/monorepo.md b/doc/user/packages/workflows/monorepo.md index f20f3427ac5..1e375dffe7e 100644 --- a/doc/user/packages/workflows/monorepo.md +++ b/doc/user/packages/workflows/monorepo.md @@ -68,7 +68,7 @@ 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) +place. See the [project registry workflow documentation](project_registry.md) for more details. ## CI workflows for automating packaging diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index 24437e6dfac..a8972f05acd 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -67,16 +67,16 @@ If you are using NPM, this involves creating an `.npmrc` file and adding the app to your project using your project ID, then adding a section to your `package.json` file with a similar URL. Follow -the instructions in the [GitLab NPM Registry documentation](../npm_registry/index.md#authenticating-to-the-gitlab-npm-registry). After +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 -[uploading packages](../npm_registry/index.md#uploading-packages) section of the docs. +[publishing packages](../npm_registry/index.md#publish-an-npm-package) section of the docs. #### Maven If you are using Maven, this involves updating your `pom.xml` file with distribution sections, including 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). -Now you can [deploy Maven packages](../maven_repository/index.md#uploading-packages) to your project. +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. #### Conan diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 2e9f36360c6..f1365ee1cab 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -163,7 +163,7 @@ The following table depicts the various user permission levels in a project. | Delete wiki pages | | | | ✓ | ✓ | | View project Audit Events | | | | ✓ | ✓ | | Manage [push rules](../push_rules/push_rules.md) | | | | ✓ | ✓ | -| Manage [project access tokens](./project/settings/project_access_tokens.md) **(CORE ONLY)** | | | | ✓ | ✓ | +| Manage [project access tokens](project/settings/project_access_tokens.md) **(CORE ONLY)** | | | | ✓ | ✓ | | Switch visibility level | | | | | ✓ | | Transfer project to another namespace | | | | | ✓ | | Rename project | | | | | ✓ | @@ -180,11 +180,11 @@ The following table depicts the various user permission levels in a project. 1. Guest users are able to perform this action on public and internal projects, but not private projects. This doesn't apply to [external users](#external-users) where explicit access must be given even if the project is internal. 1. Guest users can only view the confidential issues they created themselves. 1. If **Public pipelines** is enabled in **Project Settings > CI/CD**. -1. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [Protected Branches](./project/protected_branches.md). -1. If the [branch is protected](./project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings), this depends on the access Developers and Maintainers are given. +1. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [Protected Branches](project/protected_branches.md). +1. If the [branch is protected](project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings), this depends on the access Developers and Maintainers are given. 1. Guest users can access GitLab [**Releases**](project/releases/index.md) for downloading assets but are not allowed to download the source code nor see repository information like tags and commits. 1. Actions are limited only to records owned (referenced) by user. -1. When [Share Group Lock](./group/index.md#share-with-group-lock) is enabled the project can't be shared with other groups. It does not affect group with group sharing. +1. When [Share Group Lock](group/index.md#share-with-group-lock) is enabled the project can't be shared with other groups. It does not affect group with group sharing. 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. @@ -256,7 +256,7 @@ group. | Share (invite) groups with groups | | | | | ✓ | | Create/edit/delete group milestones | | | ✓ | ✓ | ✓ | | Create/edit/delete iterations | | | ✓ | ✓ | ✓ | -| Enable/disable a dependency proxy **(PREMIUM)** | | | ✓ | ✓ | ✓ | +| Enable/disable a dependency proxy | | | ✓ | ✓ | ✓ | | Create and edit group wiki pages **(PREMIUM)** | | | ✓ | ✓ | ✓ | | Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | | Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | @@ -314,6 +314,10 @@ External users: - Can only access public projects and projects to which they are explicitly granted access, thus hiding all other internal or private ones from them (like being logged out). +- Can only access public groups and groups to which they are explicitly granted access, + thus hiding all other internal or private ones from them (like being + logged out). +- Can only access public snippets. Access can be granted by adding the user as member to the project or group. Like usual users, they receive a role in the project or group with all @@ -391,7 +395,7 @@ with the permissions described on the documentation on [auditor users permission [Read more about Auditor users.](../administration/auditor_users.md) -## Users with minimal access **(PREMIUM ONLY)** +## Users with minimal access **(PREMIUM)** >[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40942) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. @@ -432,7 +436,7 @@ instance and project. In addition, all admins can use the admin interface under |---------------------------------------|-----------------|-------------|----------|--------| | See commits and jobs | ✓ | ✓ | ✓ | ✓ | | Retry or cancel job | | ✓ | ✓ | ✓ | -| Erase job artifacts and trace | | ✓ (*1*) | ✓ | ✓ | +| Erase job artifacts and job logs | | ✓ (*1*) | ✓ | ✓ | | Delete project | | | ✓ | ✓ | | Create project | | | ✓ | ✓ | | Change project configuration | | | ✓ | ✓ | diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index 09bfa7afc9e..cf5e4591a50 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -14,9 +14,9 @@ You can create users: ## Create users on sign in page -If you have [sign-up enabled](../../admin_area/settings/sign_up_restrictions.md), users can create their own accounts using the **Register** tab on the sign in page. +If you have [sign-up enabled](../../admin_area/settings/sign_up_restrictions.md), users can create their own accounts by selecting "Register now" on the sign-in page, or navigate to `https://gitlab.example.com/users/sign_up`. - + ## Create users in Admin Area diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index a70d11438f4..637d740ab0f 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -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: **Danger:** +DANGER: **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/img/register_tab.png b/doc/user/profile/account/img/register_tab.png Binary files differdeleted file mode 100644 index 4bbb4e62687..00000000000 --- a/doc/user/profile/account/img/register_tab.png +++ /dev/null diff --git a/doc/user/profile/account/img/register_v13_6.png b/doc/user/profile/account/img/register_v13_6.png Binary files differnew file mode 100644 index 00000000000..ce4adc0f55b --- /dev/null +++ b/doc/user/profile/account/img/register_v13_6.png diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 0e645e1b4a3..dacb6c3a5a7 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -8,12 +8,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Two-factor authentication Two-factor authentication (2FA) provides an additional level of security to your -GitLab account. Once enabled, in addition to supplying your username and -password to login, you'll be prompted for a code generated by your one time password -authenticator. For example, a password manager on one of your devices. +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 authenticator (for example, a password manager on one of your devices). -By enabling 2FA, the only way someone other than you can log into your account -is to know your username and password *and* have access to your one time password secret. +By enabling 2FA, the only way someone other than you can sign in to your account +is to know your username and password _and_ have access to your one-time +password secret. ## Overview @@ -21,30 +22,30 @@ TIP: **Tip:** 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) devices as the second factor of authentication. Once +(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 device (usually by pressing a button on it), +be prompted to activate your U2F / WebAuthn device (usually by pressing a button on it), and it will perform secure authentication on your behalf. It is highly recommended that you set up 2FA with both a -[one-time password authenticator](#enable-2fa-via-one-time-password-authenticator) -and a [U2F device](#enable-2fa-via-u2f-device), so you can still access your account -if you lose your U2F device. +[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 two ways to enable two-factor authentication: via a one time password authenticator -or a U2F device. +There are multiple ways to enable two-factor authentication: via a one time password authenticator +or a U2F / WebAuthn device. -### Enable 2FA via one time password authenticator +### One-time password To enable 2FA: 1. **In GitLab:** - 1. Log in to your GitLab account. + 1. Sign in to your GitLab account. 1. Go to your [**Profile settings**](../index.md#profile-settings). 1. Go to **Account**. - 1. Click **Enable Two-factor Authentication**. + 1. Select **Enable Two-factor Authentication**. 1. **On your device (usually your phone):** 1. Install a compatible application, like: - [Authenticator](https://mattrubin.me/authenticator/): open source app for iOS devices. @@ -59,14 +60,88 @@ To enable 2FA: 1. **In GitLab:** 1. Enter the six-digit pin number from the entry on your device into the **Pin code** field. - 1. Click **Submit**. + 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 -of [recovery codes](#recovery-codes). Make sure you download them and keep them +of [recovery codes](#recovery-codes). Be sure to download them and keep them in a safe place. -### Enable 2FA via U2F device +### One-time password via FortiAuthenticator + +> - Introduced in [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/212312) +> - It's deployed behind a feature flag, disabled by default. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-fortiauthenticator-integration). + +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 +`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). +GitLab 13.5 has been tested with FortAuthenticator version 6.2.0. + +First configure FortiAuthenticator 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_authenticator_enabled'] = true + gitlab_rails['forti_authenticator_host'] = 'forti_authenticator.example.com' + gitlab_rails['forti_authenticator_port'] = 443 + gitlab_rails['forti_authenticator_username'] = '<some_username>' + gitlab_rails['forti_authenticator_access_token'] = 's3cr3t' + ``` + + For installations from source: + + ```yaml + forti_authenticator: + enabled: true + host: forti_authenticator.example.com + port: 443 + username: <some_username> + access_token: s3cr3t + ``` + +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 FortiAuthenticator integration + +This feature comes with the `:forti_authenticator` feature flag disabled by +default. + +To enable this feature, ask a GitLab administrator with [Rails console access](../../../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags) +to run the following command: + +```ruby +Feature.enable(:forti_authenticator, User.find(<user ID>)) +``` + +### U2F device > Introduced in [GitLab 8.9](https://about.gitlab.com/blog/2016/06/22/gitlab-adds-support-for-u2f/). @@ -100,10 +175,46 @@ To set up 2FA with a U2F device: You will see a message indicating that your device was successfully set up. Click on **Register U2F Device** to complete the process. +### WebAuthn device + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22506) in GitLab 13.4. +> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-webauthn). **(CORE ONLY)** + +The WebAuthn workflow is [supported by](https://caniuse.com/#search=webauthn) the +following desktop browsers: + +- Chrome +- Edge +- Firefox +- Opera +- Safari + +and the following mobile browsers: + +- Chrome for Android +- Firefox for Android +- iOS Safari (since iOS 13.3) + +To set up 2FA with a WebAuthn compatible device: + +1. Sign in to your GitLab account. +1. Go to your [**Profile settings**](../index.md#profile-settings). +1. Go to **Account**. +1. Select **Enable Two-Factor Authentication**. +1. Plug in your WebAuthn 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. +Recovery codes are not generated for WebAuthn devices. + ## Recovery codes NOTE: **Note:** -Recovery codes are not generated for U2F devices. +Recovery codes are not generated for U2F / WebAuthn devices. CAUTION: **Caution:** Each code can be used only once to log in to your account. @@ -141,6 +252,14 @@ To log in via a U2F device: You will see a message indicating that your device responded to the authentication request and you will be 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. + ## Disabling 2FA If you ever need to disable 2FA: @@ -151,7 +270,7 @@ If you ever need to disable 2FA: 1. Click **Disable**, under **Two-Factor Authentication**. This will clear all your two-factor authentication registrations, including mobile -applications and U2F devices. +applications and U2F / WebAuthn devices. ## Personal access tokens @@ -257,7 +376,8 @@ Sign in and re-enable two-factor authentication as soon as possible. you may have cases where authorization always fails because of time differences. - The GitLab U2F implementation does _not_ work when the GitLab instance is accessed from multiple hostnames, or FQDNs. Each U2F registration is linked to the _current hostname_ at - the time of registration, and cannot be used for other hostnames/FQDNs. + the time of registration, and cannot be used for other hostnames/FQDNs. The same applies to + WebAuthn registrations. For example, if a user is trying to access a GitLab instance from `first.host.xyz` and `second.host.xyz`: @@ -268,6 +388,25 @@ Sign in and re-enable two-factor authentication as soon as possible. - To enforce 2FA at the system or group levels see [Enforce Two-factor Authentication](../../../security/two_factor_authentication.md). +## Enable or disable WebAuthn **(CORE ONLY)** + +Support for WebAuthn 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(:webauthn) +``` + +To disable it: + +```ruby +Feature.disable(:webauthn) +``` + ## Troubleshooting If you are receiving an `invalid pin code` error, this may indicate that there is a time sync issue between the authentication application and the GitLab instance itself. diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index a5b15a7880c..4630215eca6 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -1,4 +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 type: howto --- diff --git a/doc/user/profile/img/busy_status_indicator_v13_6.png b/doc/user/profile/img/busy_status_indicator_v13_6.png Binary files differnew file mode 100644 index 00000000000..291e0fab971 --- /dev/null +++ b/doc/user/profile/img/busy_status_indicator_v13_6.png diff --git a/doc/user/profile/img/unknown_sign_in_email_v13_0.png b/doc/user/profile/img/unknown_sign_in_email_v13_0.png Binary files differdeleted file mode 100644 index 51a7c29cdfa..00000000000 --- a/doc/user/profile/img/unknown_sign_in_email_v13_0.png +++ /dev/null diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 0400d9ca2e5..8ae92a42581 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -86,7 +86,7 @@ From there, you can: If you don't know your current password, select the 'I forgot my password' link. - + ## Changing your username @@ -188,17 +188,22 @@ To set your current status: 1. Set the desired emoji and/or status message. 1. Click **Set status**. Alternatively, you can click **Remove status** to remove your user status entirely. + + or 1. Click your avatar. 1. Select **Profile**. 1. Click **Edit profile** (pencil icon). 1. Enter your status message in the **Your status** text field. + 1. Alternatively, select the **Busy** checkbox ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259649) in GitLab 13.6}. 1. Click **Add status emoji** (smiley face), and select the desired emoji. 1. Click **Update profile settings**. You can also set your current status [using the API](../../api/users.md#user-status). +If you previously selected the "Busy" checkbox, remember to deselect it when you become available again. + ## Commit email > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21598) in GitLab 11.4. diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index 73a83b08a23..f3d27147557 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -7,13 +7,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Notification Emails -GitLab Notifications allow you to stay informed about what's happening in GitLab. With notifications enabled, you can receive updates about activity in issues, merge requests, and epics. Notifications are sent via email. +GitLab Notifications allow you to stay informed about what's happening in GitLab. With notifications +enabled, you can receive updates about activity in issues, merge requests, epics, and designs. +Notifications are sent via email. ## Receiving notifications You will receive notifications for one of the following reasons: -- You participate in an issue, merge request, or epic. In this context, _participate_ means comment, or edit. +- 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. @@ -209,6 +211,18 @@ If an open merge request becomes unmergeable due to conflict, its author will be If a user has also set the merge request to automatically merge once pipeline succeeds, then that user will also be notified. +## Design email notifications + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217095) in GitLab 13.6. + +Email notifications are sent to the participants when comments are made on a design. + +The participants are: + +- Authors of the design (can be multiple people if different authors have uploaded different versions of the design). +- Authors of comments on the design. +- Anyone that is `@mentioned` in a comment on the design. + ## Filtering email Notification email messages include GitLab-specific headers. You can filter the notification emails based on the content of these headers to better manage your notifications. For example, you could filter all emails for a specific project where you are being assigned either a merge request or issue. diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 61944bb9d0b..168bcb5a42e 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -1,4 +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 type: concepts, howto --- diff --git a/doc/user/profile/unknown_sign_in_notification.md b/doc/user/profile/unknown_sign_in_notification.md index 6a6820bb2d4..a97af3d6965 100644 --- a/doc/user/profile/unknown_sign_in_notification.md +++ b/doc/user/profile/unknown_sign_in_notification.md @@ -30,4 +30,4 @@ for a notification email to be sent. ## Example email - + diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index afce3869cbf..e9bb6d0e3ff 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -1,3 +1,9 @@ +--- +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 +--- + # Canary Deployments **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1659) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. @@ -61,3 +67,74 @@ Canary deployments are marked with a yellow dot in the Deploy Board so that you can easily notice them.  + +### Advanced traffic control with Canary Ingress **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215501) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. + +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 +requests between stable and canary deployments based on factors such as weight, sessions, cookies, +and others. GitLab uses this service in its [Auto Deploy architecture](../../topics/autodevops/upgrading_auto_deploy_dependencies.md#v2-chart-resource-architecture) +to let users easily and safely roll out their new deployments. + +#### How to set up a Canary Ingress in a canary deployment + +A Canary Ingress is installed by default if your Auto DevOps pipeline uses +[`v2.0.0+` of `auto-deploy-image`](../../topics/autodevops/upgrading_auto_deploy_dependencies.md#verify-dependency-versions). +A Canary Ingress becomes available when you create a new canary deployment and is destroyed when the +canary deployment is promoted to production. + +Here's an example setup flow from scratch: + +1. Prepare an [Auto DevOps-enabled](../../topics/autodevops/index.md) project. +1. Set up a [Kubernetes Cluster](../../user/project/clusters/index.md) in your project. +1. Install [Ingress](../../user/clusters/applications.md#ingress) as a GitLab Managed App. +1. Set up [the base domain](../../user/project/clusters/index.md#base-domain) based on the Ingress + Endpoint assigned above. +1. Check if [`v2.0.0+` of `auto-deploy-image` is used in your Auto DevOps pipelines](../../topics/autodevops/upgrading_auto_deploy_dependencies.md#verify-dependency-versions). + If it isn't, follow the documentation to specify the image version. +1. [Run a new Auto DevOps pipeline](../../ci/pipelines/index.md#run-a-pipeline-manually) + and make sure that the `production` job succeeds and creates a production environment. +1. Configure a [`canary` deployment job for Auto DevOps pipelines](../../topics/autodevops/customize.md#deploy-policy-for-canary-environments). +1. [Run a new Auto DevOps pipeline](../../ci/pipelines/index.md#run-a-pipeline-manually) + and make sure that the `canary` job succeeds and creates a canary deployment with Canary Ingress. + +#### 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`. + +  + + 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) +or by sending requests to the [GraphQL API](../../api/graphql/getting_started.md#command-line). + +Here's an example using [GraphiQL](../../api/graphql/getting_started.md#graphiql): + +1. Visit [GraphiQL Explorer](https://gitlab.com/-/graphql-explorer). +1. Execute the `environmentsCanaryIngressUpdate` GraphQL mutation: + + ```shell + mutation { + environmentsCanaryIngressUpdate(input:{ + id: "gid://gitlab/Environment/29", # Your Environment ID. You can get the ID from the URL of the environment page. + weight: 45 # The new traffic weight. e.g. If you set `45`, 45% of traffic goes to a canary deployment and 55% of traffic goes to a stable deployment. + }) { + errors + } + } + ``` + +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/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 65416d73f06..c3f2b96ce9f 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -139,6 +139,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: 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. 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. Click **Authenticate with AWS**. 1. Choose your cluster's settings: - **Kubernetes cluster name** - The name you wish to give the cluster. @@ -152,9 +153,6 @@ To create and add a new Kubernetes cluster to your project, group, or instance: 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) guide. - - - **Region** - The [region](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) - in which the cluster will be created. - **Key pair name** - Select the [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) that you can use to connect to your worker nodes if required. - **VPC** - Select a [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) @@ -184,9 +182,10 @@ The following errors are commonly encountered when creating a new cluster. #### Error: Request failed with status code 422 When submitting the initial authentication form, GitLab returns a status code 422 -error when it can't determine the role you've provided. Make sure you've +error when it can't determine the role or region you've provided. Make sure you've correctly configured your role with the **Account ID** and **External ID** provided by GitLab. In GitLab, make sure to enter the correct **Role ARN**. +Make sure you also have access to the chosen region. #### Could not load Security Groups for this VPC diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 094f4bcf6ba..c96e38b1dfc 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -94,7 +94,11 @@ GitLab creates the following resources for RBAC clusters. | Environment namespace | `Namespace` | Contains all environment-specific resources | Deploying to a cluster | | Environment namespace | `ServiceAccount` | Uses namespace of environment | Deploying to a cluster | | Environment namespace | `Secret` | Token for environment ServiceAccount | Deploying to a cluster | -| Environment namespace | `RoleBinding` | [`edit`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Deploying to a cluster | +| Environment namespace | `RoleBinding` | [`admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Deploying to a cluster | + +The environment namespace `RoleBinding` was +[updated](https://gitlab.com/gitlab-org/gitlab/-/issues/31113) in GitLab 13.6 +to `admin` roleRef. Previously, the `edit` roleRef was used. ### ABAC cluster resources @@ -149,6 +153,9 @@ Amazon Elastic Kubernetes Service (EKS) at the project, group, or instance level - [Amazon EKS](add_eks_clusters.md#new-eks-cluster). - [Google GKE](add_gke_clusters.md#creating-the-cluster-on-gke). +After creating a cluster, you can install runners for it as described in +[GitLab Managed Apps](../../clusters/applications.md). + ## Add existing cluster If you have an existing Kubernetes cluster, you can add it to a project, group, @@ -158,6 +165,9 @@ Kubernetes integration isn't supported for arm64 clusters. See the issue [Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab/-/issues/29838) for details. +After adding an existing cluster, you can install runners for it as described in +[GitLab Managed Apps](../../clusters/applications.md). + ### Existing Kubernetes cluster To add a Kubernetes cluster to your project, group, or instance: diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 459ba144186..9273fb7b361 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -22,6 +22,8 @@ Using the GitLab project Kubernetes integration, you can: - Use [Web terminals](#web-terminals). - Use [Deploy Boards](#deploy-boards). **(PREMIUM)** - 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). - View [Logs](#viewing-pod-logs). - Run serverless workloads on [Kubernetes with Knative](serverless/index.md). @@ -40,14 +42,15 @@ of memory and CPU usage. GitLab is committed to support at least two production-ready Kubernetes minor versions at any given time. We regularly review the versions we support, and -provide a four-month deprecation period before we remove support of a specific +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). -Currently, GitLab supports the following Kubernetes 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 @@ -241,9 +244,18 @@ A Kubernetes cluster can be the destination for a deployment job. If ### Deployment variables +Deployment variables require a valid [Deploy Token](../deploy_tokens/index.md) named +[`gitlab-deploy-token`](../deploy_tokens/index.md#gitlab-deploy-token), and the +following command in your deployment job script, for Kubernetes to access the registry: + +```plaintext +kubectl create secret docker-registry gitlab-registry --docker-server="$CI_REGISTRY" --docker-username="$CI_DEPLOY_USER" --docker-password="$CI_DEPLOY_PASSWORD" --docker-email="$GITLAB_USER_EMAIL" -o yaml --dry-run | kubectl apply -f - +``` + The Kubernetes cluster integration exposes the following [deployment variables](../../../ci/variables/README.md#deployment-environment-variables) in the -GitLab CI/CD build environment. +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 | | -------- | ----------- | diff --git a/doc/user/project/clusters/securing.md b/doc/user/project/clusters/securing.md index bed01ff4d58..2d74f67ba35 100644 --- a/doc/user/project/clusters/securing.md +++ b/doc/user/project/clusters/securing.md @@ -1,5 +1,5 @@ --- -stage: Defend +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 --- @@ -42,7 +42,7 @@ Minimum requirements (depending on the GitLab Manage Application you want to ins NOTE: **Note:** These diagrams use the term _Kubernetes_ for simplicity. In practice, Sidekiq connects to a Helm -Tiller daemon running in a pod in the cluster. +command runner pod in the cluster. You install GitLab Managed Apps from the GitLab web interface with a one-click setup process. GitLab uses Sidekiq (a background processing service) to facilitate this. diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index db91f78fc20..0de0fd38336 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -335,7 +335,7 @@ Some steps in this documentation use SAM CLI. Follow the instructions for [installing SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html) to install and configure SAM CLI. -If you use [AWS Cloud9](https://aws.amazon.com/cloud9/) as your integrated development +If you use [AWS Cloud9](https://aws.amazon.com/cloud9/) as your integrated development environment (IDE), the following are installed for you: - [AWS Command Line Interface](https://docs.aws.amazon.com/en_pv/cli/latest/userguide/cli-chap-install.html) @@ -357,7 +357,7 @@ To create a new AWS SAM application: 1. `git push` the application back to the GitLab project. This creates a SAM app named `gitlabpoc` using the default configuration, a single -Python 3.8 function invoked by an [Amazon API Gateway](https://aws.amazon.com/api-gateway/) +Python 3.8 function invoked by an [Amazon API Gateway](https://aws.amazon.com/api-gateway/) endpoint. To see additional runtimes supported by SAM and options for `sam init`, run: ```shell @@ -367,13 +367,13 @@ sam init -h ### Setting up your AWS credentials with your GitLab account In order to interact with your AWS account, the GitLab CI/CD pipelines require both -`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to be set in the project's CI/CD +`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to be set in the project's CI/CD variables. To set these: -1. Navigate to the project's **Settings > CI / CD**. -1. Expand the **Variables** section and create entries for `AWS_ACCESS_KEY_ID` and +1. Navigate to the project's **Settings > CI / CD**. +1. Expand the **Variables** section and create entries for `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. 1. Mask the credentials so they do not show in logs using the **Masked** toggle. @@ -460,7 +460,7 @@ CLI installed locally for you to test locally. First, test the function. -SAM provides a default event in `events/event.json` that includes a message body of: +SAM provides a default event in `events/event.json` that includes a message body of: ```plaintext {\"message\": \"hello world\"} @@ -491,7 +491,7 @@ sam local start-api ``` SAM again launches a Docker container, this time with a mocked Amazon API Gateway -listening on `localhost:3000`. +listening on `localhost:3000`. Call the `hello` API by running: diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index d0c5a24826a..5f96f65ea06 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -35,7 +35,9 @@ code_navigation: lsif: dump.lsif ``` -The generated LSIF file must be less than 170MiB. +The generated LSIF file size may be limited by +the [artifact application limits (`ci_max_artifact_size_lsif`)](../../administration/instance_limits.md#maximum-file-size-per-type-of-artifact), +default to 100MB (configurable by an instance administrator). After the job succeeds, code intelligence data can be viewed while browsing the code: diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 4ae3d5ec032..37ebef3a26e 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -27,7 +27,7 @@ who is responsible for each file or path. Code Owners allows for a version controlled, single source of truth file outlining the exact GitLab users or groups that own certain files or paths in a repository. Code Owners can be -utilized in the merge request approval process which can streamline +used in the merge request approval process which can streamline the process of finding the right reviewers and approvers for a given merge request. @@ -48,10 +48,14 @@ You can choose to add the `CODEOWNERS` file in three places: - Inside the `.gitlab/` directory - Inside the `docs/` directory -The `CODEOWNERS` file is scoped to a branch, which means that as -new files are introduced, the user adding the new content can -specify themselves as a code owner, all before the new changes -get merged to the target branch. +The `CODEOWNERS` file is valid for the branch where it lives. For example, if you change the code owners +in a feature branch, they won't be valid in the main branch until the feature branch is merged. + +If you introduce new files to your repository and you want to identify the code owners for that file, +you have to update `CODEOWNERS` accordingly. If you update the code owners when you are adding the files (in the same +branch), GitLab will count the owners as soon as the branch is merged. If +you don't, you can do that later, but your new files will not belong to anyone until you update your +`CODEOWNERS` file in the TARGET branch. When a file matches multiple entries in the `CODEOWNERS` file, the users from last pattern matching the file are displayed on the diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 3c6494d5f1a..2bf35b48547 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -41,9 +41,9 @@ knowledge. In particular, you should be familiar with: - [Kubernetes namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) - [Kubernetes canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments) -NOTE: **Note:** -Apps that consist of multiple deployments are shown as duplicates on the deploy board. -Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/8463) for details. +In GitLab 13.5 and earlier, apps that consist of multiple deployments are shown as +duplicates on the deploy board. This is [fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/8463) +in GitLab 13.6. ## Use cases diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 5ca421dda5b..1ac528ca4ae 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -13,57 +13,61 @@ type: howto > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI / CD** in GitLab 12.10.1. > - [Added package registry scopes](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. -Deploy tokens allow you to download (`git clone`) or push and pull packages and container registry images of a project without having a user and a password. +Deploy tokens allow you to download (`git clone`) or push and pull packages and +container registry images of a project without having a user and a password. Deploy tokens can be managed by [maintainers only](../../permissions.md). -If you have a key pair, you might want to use [deploy keys](../../../ssh/README.md#deploy-keys) instead. +If you have a key pair, you might want to use [deploy keys](../../../ssh/README.md#deploy-keys) +instead. ## Creating a Deploy Token -You can create as many deploy tokens as you like from the settings of your project. Alternatively, you can also create [group-scoped deploy tokens](#group-deploy-token). +You can create as many deploy tokens as you need from the settings of your +project. Alternatively, you can also create [group-scoped deploy tokens](#group-deploy-token). -1. Log in to your GitLab account. +1. Sign in to your GitLab account. 1. Go to the project (or group) you want to create Deploy Tokens for. 1. Go to **Settings > Repository**. 1. Click on "Expand" on **Deploy Tokens** section. 1. Choose a name, expiry date (optional), and username (optional) for the token. 1. Choose the [desired scopes](#limiting-scopes-of-a-deploy-token). -1. Click on **Create deploy token**. -1. Save the deploy token somewhere safe. Once you leave or refresh +1. Select **Create deploy token**. +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 -Deploy tokens expire on the date you define, at midnight UTC. +Deploy tokens expire at midnight UTC on the date you define. ## Revoking a deploy token -At any time, you can revoke any deploy token by just clicking the -respective **Revoke** button under the 'Active deploy tokens' area. +At any time, you can revoke any deploy token by just clicking the respective +**Revoke** button under the 'Active deploy tokens' area. ## Limiting scopes of a deploy token -Deploy tokens can be created with different scopes that allow various -actions that a given token can perform. The available scopes are depicted in -the following table along with GitLab version it was introduced in. +Deploy tokens can be created with different scopes that allow various actions +that a given token can perform. The available scopes are depicted in the +following table along with GitLab version it was introduced in: -| Scope | Description | Introduced in GitLab Version | -| ----- | ----------- | ------ | -| `read_repository` | Allows read-access to the repository through `git clone` | 10.7 | -| `read_registry` | Allows read-access to [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | 10.7 | -| `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). | 12.10 | -| `read_package_registry` | Allows read access to the package registry. | 13.0 | +| Scope | Description | Introduced in GitLab Version | +|--------------------------|-------------|------------------------------| +| `read_repository` | Allows read-access to the repository through `git clone` | 10.7 | +| `read_registry` | Allows read-access to [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | 10.7 | +| `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). | 12.10 | +| `read_package_registry` | Allows read access to the package registry. | 13.0 | | `write_package_registry` | Allows write access to the package registry. | 13.0 | ## Deploy token custom username > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29639) in GitLab 12.1. -The default username format is `gitlab+deploy-token-#{n}`. Some tools or platforms may not support this format, -in such case you can specify custom username to be used when creating the deploy token. +The default username format is `gitlab+deploy-token-#{n}`. Some tools or +platforms may not support this format; in this case you can specify a custom +username to be used when creating the deploy token. ## Usage @@ -87,13 +91,13 @@ 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. Log in to GitLab’s Container Registry using the deploy token: +1. Sign in to GitLab’s Container Registry using the deploy token: ```shell docker login -u <username> -p <deploy_token> registry.example.com ``` -Just replace `<username>` and `<deploy_token>` with the proper values. Then you can simply +Replace `<username>` and `<deploy_token>` with the proper values. You can now pull images from your Container Registry. ### Push Container Registry images @@ -104,13 +108,13 @@ 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. Log in to GitLab’s Container Registry using the deploy token: +1. Sign in to GitLab’s Container Registry using the deploy token: ```shell docker login -u <username> -p <deploy_token> registry.example.com ``` -Just replace `<username>` and `<deploy_token>` with the proper values. Then you can simply +Replace `<username>` and `<deploy_token>` with the proper values. You can now push images to your Container Registry. ### Read or pull packages @@ -121,7 +125,8 @@ To pull packages in the GitLab package registry, you'll need to: 1. Create a Deploy Token with `read_package_registry` as a scope. 1. Take note of your `username` and `token`. -1. For the [package type of your choice](./../../packages/index.md), follow the authentication instructions for deploy tokens. +1. For the [package type of your choice](../../packages/index.md), follow the + authentication instructions for deploy tokens. ### Push or upload packages @@ -131,7 +136,8 @@ To upload packages in the GitLab package registry, you'll need to: 1. Create a Deploy Token with `write_package_registry` as a scope. 1. Take note of your `username` and `token`. -1. For the [package type of your choice](./../../packages/index.md), follow the authentication instructions for deploy tokens. +1. For the [package type of your choice](../../packages/index.md), follow the + authentication instructions for deploy tokens. ### Group Deploy Token @@ -158,10 +164,10 @@ apply consistently when cloning the repository of related projects. There's a special case when it comes to Deploy Tokens. If a user creates one named `gitlab-deploy-token`, the username and token of the Deploy Token will be -automatically exposed to the CI/CD jobs as environment variables: `CI_DEPLOY_USER` and -`CI_DEPLOY_PASSWORD`, respectively. +automatically exposed to the CI/CD jobs as environment variables: `CI_DEPLOY_USER` +and `CI_DEPLOY_PASSWORD`, respectively. -After you create the token, you can login to the Container Registry using +After you create the token, you can sign in to the Container Registry by using those variables: ```shell @@ -169,4 +175,7 @@ docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY ``` 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. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/214014) for details. +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 +[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/214014). diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index e0c4097d1c5..4c14251cfa5 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -62,7 +62,7 @@ To create the `.gitlab/issue_templates` directory: 1. Click the `+` button next to `master` again and select **New directory**.This time, n 1. Name your directory `issue_templates` and commit to your default branch. -To check if this has worked correctly, [create a new issue](./issues/managing_issues.md#create-a-new-issue) +To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-a-new-issue) and see if you can choose a description template. ## Creating merge request templates diff --git a/doc/user/project/img/epics_swimlanes_drag_and_drop.png b/doc/user/project/img/epics_swimlanes_drag_and_drop.png Binary files differnew file mode 100644 index 00000000000..b2cc4105898 --- /dev/null +++ b/doc/user/project/img/epics_swimlanes_drag_and_drop.png diff --git a/doc/user/project/img/epics_swimlanes_v13.6.png b/doc/user/project/img/epics_swimlanes_v13.6.png Binary files differnew file mode 100644 index 00000000000..6f787ba8b10 --- /dev/null +++ b/doc/user/project/img/epics_swimlanes_v13.6.png diff --git a/doc/user/project/img/group_issue_board.png b/doc/user/project/img/group_issue_board.png Binary files differdeleted file mode 100644 index be360d18540..00000000000 --- a/doc/user/project/img/group_issue_board.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_add_list.png b/doc/user/project/img/issue_board_add_list.png Binary files differdeleted file mode 100644 index 91098daa1d1..00000000000 --- a/doc/user/project/img/issue_board_add_list.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_add_list_v13_6.png b/doc/user/project/img/issue_board_add_list_v13_6.png Binary files differnew file mode 100644 index 00000000000..4239ab6e7e4 --- /dev/null +++ b/doc/user/project/img/issue_board_add_list_v13_6.png diff --git a/doc/user/project/img/issue_board_assignee_lists.png b/doc/user/project/img/issue_board_assignee_lists.png Binary files differdeleted file mode 100644 index f2660cd8f80..00000000000 --- a/doc/user/project/img/issue_board_assignee_lists.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_assignee_lists_v13_6.png b/doc/user/project/img/issue_board_assignee_lists_v13_6.png Binary files differnew file mode 100644 index 00000000000..d0fbb0a2ef0 --- /dev/null +++ b/doc/user/project/img/issue_board_assignee_lists_v13_6.png diff --git a/doc/user/project/img/issue_board_creation.png b/doc/user/project/img/issue_board_creation.png Binary files differdeleted file mode 100644 index 099fe6eee21..00000000000 --- a/doc/user/project/img/issue_board_creation.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_creation_v13_6.png b/doc/user/project/img/issue_board_creation_v13_6.png Binary files differnew file mode 100644 index 00000000000..e36b53418fd --- /dev/null +++ b/doc/user/project/img/issue_board_creation_v13_6.png diff --git a/doc/user/project/img/issue_board_edit_button.png b/doc/user/project/img/issue_board_edit_button.png Binary files differdeleted file mode 100644 index a0dc6f41592..00000000000 --- a/doc/user/project/img/issue_board_edit_button.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_focus_mode.gif b/doc/user/project/img/issue_board_focus_mode.gif Binary files differdeleted file mode 100644 index 9565bdb0865..00000000000 --- a/doc/user/project/img/issue_board_focus_mode.gif +++ /dev/null diff --git a/doc/user/project/img/issue_board_milestone_lists.png b/doc/user/project/img/issue_board_milestone_lists.png Binary files differdeleted file mode 100644 index 91926f58f87..00000000000 --- a/doc/user/project/img/issue_board_milestone_lists.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_milestone_lists_v13_6.png b/doc/user/project/img/issue_board_milestone_lists_v13_6.png Binary files differnew file mode 100644 index 00000000000..a7718ffd66c --- /dev/null +++ b/doc/user/project/img/issue_board_milestone_lists_v13_6.png diff --git a/doc/user/project/img/issue_board_move_issue_card_list.png b/doc/user/project/img/issue_board_move_issue_card_list.png Binary files differdeleted file mode 100644 index 13750a63766..00000000000 --- a/doc/user/project/img/issue_board_move_issue_card_list.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_move_issue_card_list_v13_6.png b/doc/user/project/img/issue_board_move_issue_card_list_v13_6.png Binary files differnew file mode 100644 index 00000000000..2b661a63d7d --- /dev/null +++ b/doc/user/project/img/issue_board_move_issue_card_list_v13_6.png diff --git a/doc/user/project/img/issue_board_summed_weights.png b/doc/user/project/img/issue_board_summed_weights.png Binary files differdeleted file mode 100644 index 6035d7ca330..00000000000 --- a/doc/user/project/img/issue_board_summed_weights.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_summed_weights_v13_6.png b/doc/user/project/img/issue_board_summed_weights_v13_6.png Binary files differnew file mode 100644 index 00000000000..a6482e73c0a --- /dev/null +++ b/doc/user/project/img/issue_board_summed_weights_v13_6.png diff --git a/doc/user/project/img/issue_board_system_notes.png b/doc/user/project/img/issue_board_system_notes.png Binary files differdeleted file mode 100644 index c6ecb498198..00000000000 --- a/doc/user/project/img/issue_board_system_notes.png +++ /dev/null diff --git a/doc/user/project/img/issue_board_system_notes_v13_6.png b/doc/user/project/img/issue_board_system_notes_v13_6.png Binary files differnew file mode 100644 index 00000000000..4958f63541e --- /dev/null +++ b/doc/user/project/img/issue_board_system_notes_v13_6.png diff --git a/doc/user/project/img/issue_board_view_scope.png b/doc/user/project/img/issue_board_view_scope.png Binary files differdeleted file mode 100644 index d173679a0e7..00000000000 --- a/doc/user/project/img/issue_board_view_scope.png +++ /dev/null diff --git a/doc/user/project/img/issue_boards_add_issues_modal.png b/doc/user/project/img/issue_boards_add_issues_modal.png Binary files differdeleted file mode 100644 index ecddf6709d0..00000000000 --- a/doc/user/project/img/issue_boards_add_issues_modal.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 differnew file mode 100644 index 00000000000..a138efc9c1c --- /dev/null +++ b/doc/user/project/img/issue_boards_add_issues_modal_v13_6.png diff --git a/doc/user/project/img/issue_boards_blocked_icon_v12_8.png b/doc/user/project/img/issue_boards_blocked_icon_v12_8.png Binary files differdeleted file mode 100644 index 1055fb48322..00000000000 --- a/doc/user/project/img/issue_boards_blocked_icon_v12_8.png +++ /dev/null diff --git a/doc/user/project/img/issue_boards_blocked_icon_v13_6.png b/doc/user/project/img/issue_boards_blocked_icon_v13_6.png Binary files differnew file mode 100644 index 00000000000..2dac6bb2ee3 --- /dev/null +++ b/doc/user/project/img/issue_boards_blocked_icon_v13_6.png diff --git a/doc/user/project/img/issue_boards_core.png b/doc/user/project/img/issue_boards_core.png Binary files differdeleted file mode 100644 index 41ddbb24b14..00000000000 --- a/doc/user/project/img/issue_boards_core.png +++ /dev/null diff --git a/doc/user/project/img/issue_boards_core_v13_6.png b/doc/user/project/img/issue_boards_core_v13_6.png Binary files differnew file mode 100644 index 00000000000..8695b523c12 --- /dev/null +++ b/doc/user/project/img/issue_boards_core_v13_6.png diff --git a/doc/user/project/img/issue_boards_multiple.png b/doc/user/project/img/issue_boards_multiple.png Binary files differdeleted file mode 100644 index e6183360610..00000000000 --- a/doc/user/project/img/issue_boards_multiple.png +++ /dev/null diff --git a/doc/user/project/img/issue_boards_multiple_v13_6.png b/doc/user/project/img/issue_boards_multiple_v13_6.png Binary files differnew file mode 100644 index 00000000000..18ff5e2bc66 --- /dev/null +++ b/doc/user/project/img/issue_boards_multiple_v13_6.png diff --git a/doc/user/project/img/issue_boards_premium.png b/doc/user/project/img/issue_boards_premium.png Binary files differdeleted file mode 100644 index ef9f5bbea32..00000000000 --- a/doc/user/project/img/issue_boards_premium.png +++ /dev/null diff --git a/doc/user/project/img/issue_boards_premium_v13_6.png b/doc/user/project/img/issue_boards_premium_v13_6.png Binary files differnew file mode 100644 index 00000000000..8d1c1299d5c --- /dev/null +++ b/doc/user/project/img/issue_boards_premium_v13_6.png diff --git a/doc/user/project/img/issue_boards_remove_issue.png b/doc/user/project/img/issue_boards_remove_issue.png Binary files differdeleted file mode 100644 index 7050e6c3ede..00000000000 --- a/doc/user/project/img/issue_boards_remove_issue.png +++ /dev/null diff --git a/doc/user/project/img/issue_boards_remove_issue_v13_6.png b/doc/user/project/img/issue_boards_remove_issue_v13_6.png Binary files differnew file mode 100644 index 00000000000..c980759ad0c --- /dev/null +++ b/doc/user/project/img/issue_boards_remove_issue_v13_6.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 differnew file mode 100644 index 00000000000..fb59ba31615 --- /dev/null +++ b/doc/user/project/img/rollout_status_canary_ingress.png diff --git a/doc/user/project/import/img/gemnasium/connect_github.png b/doc/user/project/import/img/gemnasium/connect_github.png Binary files differindex 5933f4d5d0a..fae62e8d840 100644 --- a/doc/user/project/import/img/gemnasium/connect_github.png +++ b/doc/user/project/import/img/gemnasium/connect_github.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 differindex 6e00bf63405..8edbf711629 100644 --- a/doc/user/project/import/img/gemnasium/create_project.png +++ b/doc/user/project/import/img/gemnasium/create_project.png diff --git a/doc/user/project/import/img/gemnasium/project_connected.png b/doc/user/project/import/img/gemnasium/project_connected.png Binary files differindex 8e7216c015b..332d2230ef8 100644 --- a/doc/user/project/import/img/gemnasium/project_connected.png +++ b/doc/user/project/import/img/gemnasium/project_connected.png diff --git a/doc/user/project/import/img/jira/import_issues_from_jira_form_v12_10.png b/doc/user/project/import/img/jira/import_issues_from_jira_form_v12_10.png Binary files differdeleted file mode 100644 index 317a426394c..00000000000 --- a/doc/user/project/import/img/jira/import_issues_from_jira_form_v12_10.png +++ /dev/null diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index a1c28cfa2b7..a113758495a 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -30,6 +30,11 @@ repository is too large the import can timeout. There is also the option of [connecting your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)** +## LFS authentication + +When importing a project that contains LFS objects, if the project has an [`.lfsconfig`](https://github.com/git-lfs/git-lfs/blob/master/docs/man/git-lfs-config.5.ronn) +file with a URL host (`lfs.url`) different from the repository URL host, LFS files are not downloaded. + ## Migrating from self-managed GitLab to GitLab.com If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md). Issues and merge requests can't be imported. diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md index faa2a9b4927..cbc25552873 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -1,4 +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 type: concepts --- diff --git a/doc/user/project/index.md b/doc/user/project/index.md index a00f93bac9c..333c72a65b1 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -192,17 +192,7 @@ To delete a project, first navigate to the home page for that project. 1. Click **Delete project** 1. Confirm this action by typing in the expected text. -### Delayed deletion **(PREMIUM)** - -By default, projects in a personal namespace are deleted after a seven day delay. - -Admins can restore the project during this period of time. -This delay [may be changed by an admin](../admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). - -Admins can view all projects pending deletion. If you're an administrator, go to the top navigation bar, click **Projects > Your projects**, and then select the **Deleted projects** tab. -From this tab an admin can restore any project. - -For information on delay deletion of projects within a group, please see [Enabling delayed Project removal](../group/index.md#enabling-delayed-project-removal) +Projects in personal namespaces are deleted immediately on request. For information on delayed deletion of projects within a group, please see [Enabling delayed project removal](../group/index.md#enabling-delayed-project-removal). ## CI/CD for external repositories **(PREMIUM)** @@ -250,6 +240,14 @@ For users without permissions to view the project's code: - The wiki homepage is displayed, if any. - The list of issues within the project is displayed. +## GitLab Workflow - VS Code extension + +To avoid switching from the GitLab UI and VS Code while working in GitLab repositories, you can integrate +the [VS Code](https://code.visualstudio.com/) editor with GitLab through the +[GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow). + +To review or contribute to the extension's code, visit [its codebase in GitLab](https://gitlab.com/gitlab-org/gitlab-vscode-extension/). + ## Redirects when changing repository paths When a repository path changes, it is essential to smoothly transition from the diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 4d646ee2f79..eaef0b8d69f 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -1,3 +1,9 @@ +--- +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 +--- + # Insights **(ULTIMATE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. diff --git a/doc/user/project/integrations/ewm.md b/doc/user/project/integrations/ewm.md index be89323a246..822483a1d5b 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -1,3 +1,9 @@ +--- +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 +--- + # 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. diff --git a/doc/user/project/integrations/img/jira_create_new_group_name.png b/doc/user/project/integrations/img/jira_create_new_group_name.png Binary files differdeleted file mode 100644 index bfc0dc6b2e9..00000000000 --- a/doc/user/project/integrations/img/jira_create_new_group_name.png +++ /dev/null diff --git a/doc/user/project/integrations/img/toggle_metrics_user_starred_dashboard_v13_0.png b/doc/user/project/integrations/img/toggle_metrics_user_starred_dashboard_v13_0.png Binary files differdeleted file mode 100644 index 59dc9ccfd30..00000000000 --- a/doc/user/project/integrations/img/toggle_metrics_user_starred_dashboard_v13_0.png +++ /dev/null diff --git a/doc/user/project/integrations/img/webex_teams_configuration.png b/doc/user/project/integrations/img/webex_teams_configuration.png Binary files differdeleted file mode 100644 index 493b3ea50a0..00000000000 --- a/doc/user/project/integrations/img/webex_teams_configuration.png +++ /dev/null diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index 2c681db1692..90f91fbaa0d 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -1 +1,5 @@ +--- +redirect_to: 'overview.md' +--- + This document was moved to [Integrations](overview.md). diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 28a9afa5bb0..97be16f8dd3 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -95,6 +95,55 @@ spec: targetPort: ${CONTAINER_PORT} ``` +#### Access the UI of a Prometheus managed application in Kubernetes + +You can connect directly to Prometheus, and view the Prometheus user interface, when +using a Prometheus managed application in Kubernetes: + +1. Find the name of the Prometheus pod in the user interface of your Kubernetes + provider, such as GKE, or by running the following `kubectl` command in your + terminal: + + ```shell + kubectl get pods -n gitlab-managed-apps | grep 'prometheus-prometheus-server' + ``` + + The command should return a result like the following example, where + `prometheus-prometheus-server-55b4bd64c9-dpc6b` is the name of the Prometheus pod: + + ```plaintext + gitlab-managed-apps prometheus-prometheus-server-55b4bd64c9-dpc6b 2/2 Running 0 71d + ``` + +1. Run a `kubectl port-forward` command. In the following example, `9090` is the + Prometheus server's listening port: + + ```shell + kubectl port-forward prometheus-prometheus-server-55b4bd64c9-dpc6b 9090:9090 -n gitlab-managed-apps + ``` + + The `port-forward` command forwards all requests sent to your system's `9090` port + to the `9090` port of the Prometheus pod. If the `9090` port on your system is used + by another application, you can change the port number before the colon to your + desired port. For example, to forward port `8080` of your local system, change the + command to: + + ```shell + kubectl port-forward prometheus-prometheus-server-55b4bd64c9-dpc6b 8080:9090 -n gitlab-managed-apps + ``` + +1. Open `localhost:9090` in your browser to display the Prometheus user interface. + +#### Script access to Prometheus + +You can script the access to Prometheus, extracting the name of the pod automatically like this: + +```shell +POD_INFORMATION=$(kubectl get pods -n gitlab-managed-apps | grep 'prometheus-prometheus-server') +POD_NAME=$(echo $POD_INFORMATION | awk '{print $1;}') +kubectl port-forward $POD_NAME 9090:9090 -n gitlab-managed-apps +``` + ### Manual configuration of Prometheus #### Requirements diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 39daa14407f..7654909b735 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -10,9 +10,9 @@ 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). +1. Go to the [Incoming Webhooks app page](https://apphub.webex.com/teams/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 that will receive the notifications. +1. Enter a name for the webhook and select the space to receive the notifications. 1. Click **ADD**. 1. Copy the **Webhook URL**. @@ -27,4 +27,4 @@ Once you have a webhook URL for your Webex Teams space, you can configure GitLab 1. Paste the **Webhook** URL for the Webex Teams space. 1. Configure the remaining options and then click **Test settings and save changes**. -The Webex Teams space will begin to receive all applicable GitLab events. +The Webex Teams space now begins to receive all applicable GitLab events. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 7adea5ebcd6..6a436c5093e 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1358,6 +1358,140 @@ X-Gitlab-Event: Deployment Hook Note that `deployable_id` is the ID of the CI job. +### Feature Flag events + +Triggered when a feature flag is turned on or off. + +**Request Header**: + +```plaintext +X-Gitlab-Event: Feature Flag Hook +``` + +**Request Body**: + +```json +{ + "object_kind": "feature_flag", + "project": { + "id": 1, + "name":"Gitlab Test", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/gitlabhq/gitlab-test", + "avatar_url":null, + "git_ssh_url":"git@example.com:gitlabhq/gitlab-test.git", + "git_http_url":"http://example.com/gitlabhq/gitlab-test.git", + "namespace":"GitlabHQ", + "visibility_level":20, + "path_with_namespace":"gitlabhq/gitlab-test", + "default_branch":"master", + "ci_config_path": null, + "homepage":"http://example.com/gitlabhq/gitlab-test", + "url":"http://example.com/gitlabhq/gitlab-test.git", + "ssh_url":"git@example.com:gitlabhq/gitlab-test.git", + "http_url":"http://example.com/gitlabhq/gitlab-test.git" + }, + "user": { + "name": "Administrator", + "username": "root", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "email": "admin@example.com" + }, + "user_url": "http://example.com/root", + "object_attributes": { + "id": 6, + "name": "test-feature-flag", + "description": "test-feature-flag-description", + "active": true + } +} +``` + +### Release events + +Triggered when a release is created or updated. + +**Request Header**: + +```plaintext +X-Gitlab-Event: Release Hook +``` + +**Request Body**: + +```json +{ + "id": 1, + "created_at": "2020-11-02 12:55:12 UTC", + "description": "v1.0 has been released", + "name": "v1.1", + "released_at": "2020-11-02 12:55:12 UTC", + "tag": "v1.1", + "object_kind": "release", + "project": { + "id": 2, + "name": "release-webhook-example", + "description": "", + "web_url": "https://example.com/gitlab-org/release-webhook-example", + "avatar_url": null, + "git_ssh_url": "ssh://git@example.com/gitlab-org/release-webhook-example.git", + "git_http_url": "https://example.com/gitlab-org/release-webhook-example.git", + "namespace": "Gitlab", + "visibility_level": 0, + "path_with_namespace": "gitlab-org/release-webhook-example", + "default_branch": "master", + "ci_config_path": null, + "homepage": "https://example.com/gitlab-org/release-webhook-example", + "url": "ssh://git@example.com/gitlab-org/release-webhook-example.git", + "ssh_url": "ssh://git@example.com/gitlab-org/release-webhook-example.git", + "http_url": "https://example.com/gitlab-org/release-webhook-example.git" + }, + "url": "https://example.com/gitlab-org/release-webhook-example/-/releases/v1.1", + "action": "create", + "assets": { + "count": 5, + "links": [ + { + "id": 1, + "external": true, + "link_type": "other", + "name": "Changelog", + "url": "https://example.net/changelog" + } + ], + "sources": [ + { + "format": "zip", + "url": "https://example.com/gitlab-org/release-webhook-example/-/archive/v1.1/release-webhook-example-v1.1.zip" + }, + { + "format": "tar.gz", + "url": "https://example.com/gitlab-org/release-webhook-example/-/archive/v1.1/release-webhook-example-v1.1.tar.gz" + }, + { + "format": "tar.bz2", + "url": "https://example.com/gitlab-org/release-webhook-example/-/archive/v1.1/release-webhook-example-v1.1.tar.bz2" + }, + { + "format": "tar", + "url": "https://example.com/gitlab-org/release-webhook-example/-/archive/v1.1/release-webhook-example-v1.1.tar" + } + ] + }, + "commit": { + "id": "ee0a3fb31ac16e11b9dbb596ad16d4af654d08f8", + "message": "Release v1.1", + "title": "Release v1.1", + "timestamp": "2020-10-31T14:58:32+11:00", + "url": "https://example.com/gitlab-org/release-webhook-example/-/commit/ee0a3fb31ac16e11b9dbb596ad16d4af654d08f8", + "author": { + "name": "Example User", + "email": "user@example.com" + } + } +} +``` + ## Image URL rewriting From GitLab 11.2, simple image references are rewritten to use an absolute URL diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index bce40e9a838..dfe608df18d 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -31,7 +31,7 @@ To let your team members organize their own workflows, use [multiple issue boards](#use-cases-for-multiple-issue-boards). This allows creating multiple issue boards in the same project. - + Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: @@ -45,7 +45,7 @@ as shown in the following table: To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards) below. - + <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video presentation](https://youtu.be/vjccjHI7aGI) of @@ -69,8 +69,8 @@ For example, let's consider this simplified development workflow: 1. When frontend is complete, the new feature is deployed to a **staging** environment to be tested. 1. When successful, it's deployed to **production**. -If you have the labels "**backend**", "**frontend**", "**staging**", and -"**production**", and an issue board with a list for each, you can: +If you have the labels **Backend**, **Frontend**, **Staging**, and +**Production**, and an issue board with a list for each, you can: - Visualize the entire flow of implementations since the beginning of the development life cycle until deployed to production. @@ -78,7 +78,7 @@ If you have the labels "**backend**", "**frontend**", "**staging**", and - Move issues between lists to organize them according to the labels you've set. - Add multiple issues to lists in the board by selecting one or more existing issues. - + ### Use cases for multiple issue boards @@ -199,7 +199,7 @@ 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. @@ -229,20 +229,16 @@ An issue board can be associated with a GitLab [Milestone](milestones/index.md#m which automatically filter the board issues accordingly. This allows you to create unique boards according to your team's need. - + -You can define the scope of your board when creating it or by clicking the "Edit board" button. -Once a milestone, assignee or weight is assigned to an issue board, you can no longer +You can define the scope of your board when creating it or by clicking the **Edit board** button. +After a milestone, assignee or weight is assigned to an issue board, you can no longer filter through these in the search bar. In order to do that, you need to remove the desired scope (for example, milestone, assignee, or weight) from the issue board. - - If you don't have editing permission in a board, you're still able to see the configuration by clicking **View scope**. - - <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video presentation](https://youtu.be/m5UTNCSqaDk) of the Configurable Issue Board feature. @@ -253,12 +249,8 @@ the Configurable Issue Board feature. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28597) to the Free tier of GitLab.com in 12.10. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212331) to GitLab Core in 13.0. -Click the button at the top right to toggle focus mode on and off. In focus mode, the navigation UI -is hidden, allowing you to focus on issues in the board. - - - ---- +To enable or disable focus mode, select the **Toggle focus mode** button (**{maximize}**) at the top +right. In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board. ### Sum of issue weights **(STARTER)** @@ -266,7 +258,7 @@ The top of each list indicates the sum of issue weights for the issues that belong to that list. This is useful when using boards for capacity allocation, especially in combination with [assignee lists](#assignee-lists). - + ### Group issue boards **(PREMIUM)** @@ -279,8 +271,6 @@ group and its descendant subgroups. Similarly, you can only filter by group labe boards. When updating milestones and labels for an issue through the sidebar update mechanism, again only group-level objects are available. - - ### Assignee lists **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5784) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.0. @@ -290,15 +280,15 @@ an assignee list that shows all issues assigned to a user. You can have a board with both label lists and assignee lists. To add an assignee list: -1. Click **Add list**. +1. Select the **Add list** dropdown button. 1. Select the **Assignee list** tab. -1. Search and click the user you want to add as an assignee. +1. Search and select the user you want to add as an assignee. Now that the assignee list is added, you can assign or unassign issues to that user by [dragging issues](#drag-issues-between-lists) to and from an assignee list. To remove an assignee list, just as with a label list, click the trash icon. - + ### Milestone lists **(PREMIUM)** @@ -307,7 +297,7 @@ To remove an assignee list, just as with a label list, click the trash icon. You're also able to create lists of a milestone. These are lists that filter issues by the assigned milestone, giving you more freedom and visibility on the issue board. To add a milestone list: -1. Click **Add list**. +1. Select the **Add list** dropdown button. 1. Select the **Milestone** tab. 1. Search and click the milestone. @@ -315,7 +305,31 @@ Like the assignee lists, you're able to [drag issues](#drag-issues-between-lists to and from a milestone list to manipulate the milestone of the dragged issues. As in other list types, click the trash icon to remove a list. - + + +### Group issues in swimlanes **(PREMIUM)** + +> Grouping by epic [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3352) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. + +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. + +To group issues by epic in an issue board: + +1. Select the **Group by** dropdown button. +1. Select **Epic**. + + + +You can also [drag issues](#drag-issues-between-lists) to change their position and epic assignment: + +- To reorder an issue, drag it to the new position within a list. +- To assign an issue to another epic, drag it to the epic's horizontal lane. +- To unassign an issue from an epic, drag it to the **Issues with no epic assigned** lane. +- To move an issue to another epic _and_ another list, at the same time, drag the issue diagonally. + + ## Work In Progress limits **(STARTER)** @@ -347,7 +361,7 @@ To set a WIP limit for a list: If an issue is blocked by another issue, an icon appears next to its title to indicate its blocked status. - + ## Actions you can take on an issue board @@ -381,16 +395,16 @@ have that label. ### Create a new list -Create a new list by clicking the **Add list** button in the upper right corner of the issue board. +Create a new list by clicking the **Add list** dropdown button in the upper right corner of the issue board. - + -Then, choose the label or user to create the list from. The new list is inserted -at the end of the lists, before **Done**. Moving and reordering lists is as -easy as dragging them around. +Then, choose the label or user to base the new list on. The new list is inserted +at the end of the lists, before **Done**. To move and reorder lists, drag them around. To create a list for a label that doesn't yet exist, create the label by -choosing **Create new label**. This creates the label immediately and adds it to the dropdown. +choosing **Create project label** or **Create group label**. +This creates the label immediately and adds it to the dropdown. You can now choose it to create a list. ### Delete a list @@ -404,14 +418,14 @@ list view that's removed. You can always restore it later if you need. ### Add issues to a list You can add issues to a list by clicking the **Add issues** button -present in the upper right corner of the issue board. This opens up a modal +in the top right corner of the issue board. This opens up a modal window where you can see all the issues that do not belong to any list. Select one or more issues by clicking the cards and then click **Add issues** to add them to the selected list. You can limit the issues you want to add to the list by filtering by author, assignee, milestone, and label. - + ### Remove an issue from a list @@ -419,13 +433,13 @@ Removing an issue from a list can be done by clicking the issue card and then clicking the **Remove from board** button in the sidebar. The respective label is removed. - + ### Filter issues You should be able to use the filters on top of your issue board to show only -the results you want. It's similar to the filtering used in the issue tracker -since the metadata from the issues and labels are re-used in the issue board. +the results you want. It's similar to the filtering used in the issue tracker, +as the metadata from the issues and labels is re-used in the issue board. You can filter by author, assignee, milestone, and label. @@ -435,13 +449,13 @@ By reordering your lists, you can create workflows. As lists in issue boards are based on labels, it works out of the box with your existing issues. So if you've already labeled things with **Backend** and **Frontend**, the issue appears in -the lists as you create them. In addition, this means you can easily move -something between lists by changing a label. +the lists as you create them. In addition, this means you can move something between lists by +changing a label. A typical workflow of using an issue board would be: 1. You have [created](labels.md#label-management) and [prioritized](labels.md#label-priority) - labels so that you can easily categorize your issues. + labels to categorize your issues. 1. You have a bunch of issues (ideally labeled). 1. You visit the issue board and start [creating lists](#create-a-new-list) to create a workflow. @@ -457,15 +471,15 @@ For example, you can create a list based on the label of **Frontend** and one fo **Frontend** list. That way, everyone knows that this issue is now being worked on by the designers. -Then, once they're done, all they have to do is +Then, when they're done, all they have to do is drag it to the next list, **Backend**. Then, a backend developer can -eventually pick it up. Once they’re done, they move it to **Done**, to close the +eventually pick it up. When they’re done, they move it to **Done**, to close the issue. This process can be seen clearly when visiting an issue. With every move to another list, the label changes and a system note is recorded. - + ### Drag issues between lists @@ -473,16 +487,17 @@ When dragging issues between lists, different behavior occurs depending on the s | | To Open | To Closed | To label `B` list | To assignee `Bob` list | |----------------------------|--------------------|--------------|------------------------------|---------------------------------------| -| From Open | - | Issue closed | `B` added | `Bob` assigned | -| From Closed | Issue reopened | - | Issue reopened<br/>`B` added | Issue reopened<br/>`Bob` assigned | -| From label `A` list | `A` removed | Issue closed | `A` removed<br/>`B` added | `Bob` assigned | -| From assignee `Alice` list | `Alice` unassigned | Issue closed | `B` added | `Alice` unassigned<br/>`Bob` assigned | +| **From Open** | - | Issue closed | `B` added | `Bob` assigned | +| **From Closed** | Issue reopened | - | Issue reopened<br/>`B` added | Issue reopened<br/>`Bob` assigned | +| **From label `A` list** | `A` removed | Issue closed | `A` removed<br/>`B` added | `Bob` assigned | +| **From assignee `Alice` list** | `Alice` unassigned | Issue closed | `B` added | `Alice` unassigned<br/>`Bob` assigned | ### Multi-select issue cards > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18954) in GitLab 12.4. -You can select multiple issue cards, then drag the group to another position within the list, or to another list. This makes it faster to reorder many issues at once. +You can select multiple issue cards, then drag the group to another position within the list, or to +another list. This makes it faster to reorder many issues at once. To select and move multiple cards: diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index af01534a67f..af9a6401474 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -1,3 +1,9 @@ +--- +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 +--- + # Export Issues to CSV > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1126) in [GitLab Starter 9.0](https://about.gitlab.com/releases/2017/03/22/gitlab-9-0-released/#export-issues-ees-eep). diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index 807f4fcffdf..2cac88b1b29 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -1,3 +1,9 @@ +--- +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 +--- + # Importing issues from CSV > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23532) in GitLab 11.7. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 6f57487fccd..c19c9ca0615 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -228,7 +228,7 @@ available in the **Resolved Comment** area at the bottom of the right sidebar. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198439) in GitLab 13.4. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245074) in GitLab 13.5. -Add a to do for a design by clicking **Add a To Do** on the design sidebar: +Add a to-do item for a design by clicking **Add a to do** on the design sidebar:  diff --git a/doc/user/project/issues/img/adding_note_to_design_1.png b/doc/user/project/issues/img/adding_note_to_design_1.png Binary files differindex aa50bbb69ce..3c25fcb1241 100644 --- a/doc/user/project/issues/img/adding_note_to_design_1.png +++ b/doc/user/project/issues/img/adding_note_to_design_1.png diff --git a/doc/user/project/issues/img/adding_note_to_design_2.png b/doc/user/project/issues/img/adding_note_to_design_2.png Binary files differindex 37cefeb1a15..c418a0364c0 100644 --- a/doc/user/project/issues/img/adding_note_to_design_2.png +++ b/doc/user/project/issues/img/adding_note_to_design_2.png diff --git a/doc/user/project/issues/img/button_close_issue.png b/doc/user/project/issues/img/button_close_issue.png Binary files differdeleted file mode 100644 index 05d257ce9bf..00000000000 --- a/doc/user/project/issues/img/button_close_issue.png +++ /dev/null diff --git a/doc/user/project/issues/img/button_close_issue_v13_6.png b/doc/user/project/issues/img/button_close_issue_v13_6.png Binary files differnew file mode 100644 index 00000000000..6c7f8da496b --- /dev/null +++ b/doc/user/project/issues/img/button_close_issue_v13_6.png diff --git a/doc/user/project/issues/img/closing_and_related_issues.png b/doc/user/project/issues/img/closing_and_related_issues.png Binary files differdeleted file mode 100644 index c6543e85fdb..00000000000 --- a/doc/user/project/issues/img/closing_and_related_issues.png +++ /dev/null diff --git a/doc/user/project/issues/img/confirm_design_deletion_v12_4.png b/doc/user/project/issues/img/confirm_design_deletion_v12_4.png Binary files differindex 447d3907122..5631b6ec98e 100644 --- a/doc/user/project/issues/img/confirm_design_deletion_v12_4.png +++ b/doc/user/project/issues/img/confirm_design_deletion_v12_4.png diff --git a/doc/user/project/issues/img/delete_multiple_designs_v12_4.png b/doc/user/project/issues/img/delete_multiple_designs_v12_4.png Binary files differindex 75cbdf77c24..40d449d5b39 100644 --- a/doc/user/project/issues/img/delete_multiple_designs_v12_4.png +++ b/doc/user/project/issues/img/delete_multiple_designs_v12_4.png diff --git a/doc/user/project/issues/img/delete_single_design_v12_4.png b/doc/user/project/issues/img/delete_single_design_v12_4.png Binary files differdeleted file mode 100644 index 158b4949ce4..00000000000 --- a/doc/user/project/issues/img/delete_single_design_v12_4.png +++ /dev/null diff --git a/doc/user/project/issues/img/design_drag_and_drop_uploads_v12_9.png b/doc/user/project/issues/img/design_drag_and_drop_uploads_v12_9.png Binary files differdeleted file mode 100644 index 6680c792063..00000000000 --- a/doc/user/project/issues/img/design_drag_and_drop_uploads_v12_9.png +++ /dev/null diff --git a/doc/user/project/issues/img/design_drag_and_drop_uploads_v13_2.png b/doc/user/project/issues/img/design_drag_and_drop_uploads_v13_2.png Binary files differindex 25a02eef406..4ab5e184905 100644 --- a/doc/user/project/issues/img/design_drag_and_drop_uploads_v13_2.png +++ b/doc/user/project/issues/img/design_drag_and_drop_uploads_v13_2.png diff --git a/doc/user/project/issues/img/design_management_v12_3.png b/doc/user/project/issues/img/design_management_v12_3.png Binary files differdeleted file mode 100644 index b3647aa97c1..00000000000 --- a/doc/user/project/issues/img/design_management_v12_3.png +++ /dev/null diff --git a/doc/user/project/issues/img/design_management_v13_2.png b/doc/user/project/issues/img/design_management_v13_2.png Binary files differindex 6d7e03d6f20..3da11c92514 100644 --- a/doc/user/project/issues/img/design_management_v13_2.png +++ b/doc/user/project/issues/img/design_management_v13_2.png diff --git a/doc/user/project/issues/img/design_zooming_v12_7.png b/doc/user/project/issues/img/design_zooming_v12_7.png Binary files differindex 4acb4e10913..4966af06e41 100644 --- a/doc/user/project/issues/img/design_zooming_v12_7.png +++ b/doc/user/project/issues/img/design_zooming_v12_7.png diff --git a/doc/user/project/issues/img/epic_tree_health_status_v12_10.png b/doc/user/project/issues/img/epic_tree_health_status_v12_10.png Binary files differdeleted file mode 100644 index 1a603656fd8..00000000000 --- a/doc/user/project/issues/img/epic_tree_health_status_v12_10.png +++ /dev/null diff --git a/doc/user/project/issues/img/issue_health_status_v12_10.png b/doc/user/project/issues/img/issue_health_status_v12_10.png Binary files differdeleted file mode 100644 index dd6becbb970..00000000000 --- a/doc/user/project/issues/img/issue_health_status_v12_10.png +++ /dev/null diff --git a/doc/user/project/issues/img/issue_health_status_v12_9.png b/doc/user/project/issues/img/issue_health_status_v12_9.png Binary files differdeleted file mode 100644 index f8922a74fc1..00000000000 --- a/doc/user/project/issues/img/issue_health_status_v12_9.png +++ /dev/null diff --git a/doc/user/project/issues/img/new_issue_from_open_issue.png b/doc/user/project/issues/img/new_issue_from_open_issue.png Binary files differdeleted file mode 100644 index c6f3f0617ab..00000000000 --- a/doc/user/project/issues/img/new_issue_from_open_issue.png +++ /dev/null diff --git a/doc/user/project/issues/img/new_issue_from_open_issue_v13_6.png b/doc/user/project/issues/img/new_issue_from_open_issue_v13_6.png Binary files differnew file mode 100644 index 00000000000..902aa40614a --- /dev/null +++ b/doc/user/project/issues/img/new_issue_from_open_issue_v13_6.png diff --git a/doc/user/project/issues/img/reopen-issue.png b/doc/user/project/issues/img/reopen-issue.png Binary files differdeleted file mode 100644 index fc48742afe0..00000000000 --- a/doc/user/project/issues/img/reopen-issue.png +++ /dev/null diff --git a/doc/user/project/issues/img/report-abuse.png b/doc/user/project/issues/img/report-abuse.png Binary files differdeleted file mode 100644 index f8cef22da03..00000000000 --- a/doc/user/project/issues/img/report-abuse.png +++ /dev/null diff --git a/doc/user/project/issues/img/select_designs_v12_4.png b/doc/user/project/issues/img/select_designs_v12_4.png Binary files differindex 532a79fce65..fe1c55a4ae2 100644 --- a/doc/user/project/issues/img/select_designs_v12_4.png +++ b/doc/user/project/issues/img/select_designs_v12_4.png diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 434af3a4a49..716377f2e45 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -95,12 +95,13 @@ While you can view and manage the full details of an issue on the [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)**. -Key actions for Issues include: +Key actions for issues include: - [Creating issues](managing_issues.md#create-a-new-issue) - [Moving issues](managing_issues.md#moving-issues) - [Closing issues](managing_issues.md#closing-issues) - [Deleting issues](managing_issues.md#deleting-issues) +- [Promoting issues](managing_issues.md#promote-an-issue-to-an-epic) **(PREMIUM)** ### Issue page @@ -189,6 +190,8 @@ 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. + 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: @@ -201,7 +204,7 @@ that's progressing as planned or needs attention to keep on schedule: After an issue is closed, its health status can't be edited and the "Edit" button becomes disabled until the issue is reopened. -You can then see issue statuses on the +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 diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 003444e0ed8..a5f60fbd515 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -18,7 +18,7 @@ You can find all the information for that issue on one screen.  -- **1.** [New Issue, close issue (reopen issue, report issue)](#new-issue-close-issue-reopen-issue-report-issue) +- **1.** [Issue actions](#issue-actions) - **2.** [To Do](#to-do) - **3.** [Assignee](#assignee) - **3.1.** [Multiple Assignees **(STARTER)**](#multiple-assignees) @@ -55,22 +55,21 @@ Many of the elements of the issue screen refresh automatically, such as the titl description, when they are changed by another user. Comments and system notes also update automatically in response to various actions and content updates. -### New Issue, close issue (reopen issue, report issue) +### Issue actions -Clicking on **New issue** will open a new window to create a new issue in the same project. -Clicking on **Close issue** will close this issue, but it will not be deleted. If the -issue is already closed, you can still access it and the button will show **Reopen issue**, as shown below, -which you can click to reopen the issue. A reopened issue is no different from any -other issue. +In an open issue, you can close it by selecting the **Close issue** button. +The issue is marked as closed but is not deleted. - +To reopen a closed issue, select the **Reopen issue** button. +A reopened issue is no different from any other open issue. -If you do not have rights to modify the issue, the **close issue** button will be -replaced with **report issue**, which you can click to [submit an abuse report](../../abuse_reports.md) -about the issue. It will also appear if you have rights to modify the issue, but only -after it is closed. +To access additional actions, select the vertical ellipsis +(**{ellipsis_v}**) button: - +- To create a new issue in the same project, select **New issue** in the dropdown menu. + +- If you are not the issue author, you can [submit an abuse report](../../abuse_reports.md). + Select **Report abuse** in the dropdown menu. ### To Do diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index b033dc79dcc..62b388ec137 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -7,9 +7,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Managing issues [GitLab Issues](index.md) are the fundamental medium for collaborating on ideas and -planning work in GitLab. [Creating](#create-a-new-issue), [moving](#moving-issues), -[closing](#closing-issues), and [deleting](#deleting-issues) are key actions that -you can do with issues. +planning work in GitLab. + +Key actions for issues include: + +- [Creating issues](#create-a-new-issue) +- [Moving issues](#moving-issues) +- [Closing issues](#closing-issues) +- [Deleting issues](#deleting-issues) +- [Promoting issues](#promote-an-issue-to-an-epic) **(PREMIUM)** ## Create a new issue @@ -28,10 +34,10 @@ There are many ways to get to the New Issue form from within a project:  -- From an **opened issue** in your project, click **New Issue** to create a new - issue in the same project: +- From an **open issue** in your project, click the vertical ellipsis (**{ellipsis_v}**) button + to open a dropdown menu, and then click **New Issue** to create a new issue in the same project: -  +  - From your **Project's Dashboard**, click the plus sign (**+**) to open a dropdown menu with a few options. Select **New Issue** to create an issue in that project: @@ -178,7 +184,7 @@ end; nil When you decide that an issue is resolved, or no longer needed, you can close the issue using the close button: - + You can also close an issue from the [Issue Boards](../issue_board.md) by dragging an issue card from its list and dropping it into the **Closed** list. @@ -280,6 +286,23 @@ editing it and clicking on the delete button.  +## Promote an issue to an epic **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8. +> - Promoting issues to epics via the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233974) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. + +You can promote an issue to an epic in the immediate parent group. + +To promote an issue to an epic: + +1. In an issue, select the vertical ellipsis (**{ellipsis_v}**) button. +1. Select **Promote to epic**. + +Alternatively, you can use the `/promote` [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). + +Read more about promoting an issue to an epic on the [Manage epics page](../../group/epics/manage_epics.md#promote-an-issue-to-an-epic). + ## Add an issue to an iteration **(STARTER)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216158) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 4f0354f86af..c237f46b23a 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -95,6 +95,8 @@ If you delete a label, it is permanently deleted. All references to the label ar #### Promote a project label to a group label +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231472) in GitLab 13.6: promoting a project label keeps that label's ID and changes it into a group label. Previously, promoting a project label created a new group label with a new ID and deleted the old label. + If you previously created a project label and now want to make it available for other projects within the same group, you can promote it to a group label. @@ -105,6 +107,8 @@ also merged. All issues, merge requests, issue board lists, issue board filters, and label subscriptions 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:** Promoting a label is a permanent action, and cannot be reversed. diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index d8579c4cd8e..c66103604ed 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,3 +1,9 @@ +--- +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 +--- + # Members of a project You can manage the groups and users and their access levels in all of your diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 033d69cbbfa..395f4353f47 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -1,3 +1,9 @@ +--- +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 +--- + # Share Projects with other Groups You can share projects with other [groups](../../group/index.md). This makes it diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index e03d4e99b86..d50056c9450 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -265,6 +265,40 @@ Once the Code Quality job has completed: [downloadable artifact](../../../ci/pipelines/job_artifacts.md#downloading-artifacts) for the `code_quality` job. +### Generating an HTML report + +In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/ci-cd/codequality/-/issues/10), +it is possible to generate an HTML report file by setting the `REPORT_FORMAT` +variable to `html`. This is useful if you just want to view the report in a more +human-readable format or to publish this artifact on GitLab Pages for even +easier reviewing. + +```yaml +include: + - template: Code-Quality.gitlab-ci.yml + +code_quality: + variables: + REPORT_FORMAT: html + artifacts: + paths: [gl-code-quality-report.html] +``` + +It's also possible to generate both JSON and HTML report files by defining +another job and using `extends: code_quality`: + +```yaml +include: + - template: Code-Quality.gitlab-ci.yml + +code_quality_html: + extends: code_quality + variables: + REPORT_FORMAT: html + artifacts: + paths: [gl-code-quality-report.html] +``` + ## Extending functionality ### Using Analysis Plugins @@ -314,7 +348,7 @@ This can be due to multiple reasons: nothing will be 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. -- Large `codeclimate.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). +- Large `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: - Configure the Code Quality tool to not output those types. diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md new file mode 100644 index 00000000000..52c6f8a8d41 --- /dev/null +++ b/doc/user/project/merge_requests/csv_export.md @@ -0,0 +1,45 @@ +--- +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 +--- + +# Export Merge Requests to CSV **(CORE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3619) in GitLab 13.6. + +Exporting Merge Requests CSV enables you and your team to export all the data collected from merge requests into a comma-separated values (CSV) file, which stores tabular data in plain text. + +To export Merge Requests to CSV, navigate to your **Merge Requests** from the sidebar of a project and click **Export to CSV**. + +## CSV Output + +The following table shows what attributes will be present in the CSV. + +| Column | Description | +|--------------------|--------------------------------------------------------------| +| MR ID | MR iid | +| URL | A link to the merge request on GitLab | +| Title | Merge request title | +| State | Opened, Closed, Locked, or Merged | +| Description | Merge request description | +| Source Branch | Source branch | +| Target Branch | Target branch | +| Source Project ID | ID of the source project | +| Target Project ID | ID of the target project | +| Author | Full name of the merge request author | +| Author Username | Username of the author, with the @ symbol omitted | +| Assignees | Full names of the merge request assignees, joined with a `,` | +| Assignee Usernames | Username of the assignees, with the @ symbol omitted | +| Approvers | Full names of the approvers, joined with a `,` | +| Approver Usernames | Username of the approvers, with the @ symbol omitted | +| Merged User | Full name of the merged user | +| Merged Username | Username of the merge user, with the @ symbol omitted | +| Milestone ID | ID of the merge request milestone | +| Created At (UTC) | Formatted as YYYY-MM-DD HH:MM:SS | +| Updated At (UTC) | Formatted as YYYY-MM-DD HH:MM:SS | + +## Limitations + +- Export merge requests to CSV is not available at the Group’s merge request list. +- As the merge request CSV file is sent as an email attachment, the size is limited to 15MB to ensure successful delivery across a range of email providers. If you need to minimize the size of the file, you can narrow the search before export. For example, you can set up exports of open and closed merge requests in separate files. diff --git a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png b/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png Binary files differdeleted file mode 100644 index ed374b11fbd..00000000000 --- a/doc/user/project/merge_requests/img/merge_when_pipeline_succeeds_only_if_succeeds_settings.png +++ /dev/null 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 differindex 457716d811c..2c86a1ad839 100644 --- 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 diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 2675f509eed..3ee88275aac 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -156,7 +156,7 @@ The best approach is to capture the dynamic URL in a [`.env` file](https://docs. as a job artifact to be shared, then use a custom environment variable we've provided named `K6_DOCKER_OPTIONS` to configure the k6 Docker container to use the file. With this, k6 can then use any environment variables from the `.env` file in scripts using standard JavaScript, -such as: ``http.get(`${__ENV.ENVIRONMENT_URL`})``. +such as: ``http.get(`${__ENV.ENVIRONMENT_URL}`)``. For example: diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index bded1839f97..039f0f7d5e1 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -73,11 +73,11 @@ test: cobertura: coverage/cobertura-coverage.xml ``` -### Java examples +### Java and Kotlin examples #### Maven example -The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Java uses [Maven](https://maven.apache.org/) +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 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. @@ -101,7 +101,7 @@ coverage-jdk11: # The `visualize` stage does not exist by default. # Please define it first, or chose an existing stage like `deploy`. stage: visualize - image: haynes/jacoco2cobertura:1.0.3 + image: haynes/jacoco2cobertura:1.0.4 script: # convert report from jacoco to cobertura - 'python /opt/cover2cover.py target/site/jacoco/jacoco.xml src/main/java > target/site/cobertura.xml' @@ -117,7 +117,7 @@ coverage-jdk11: #### Gradle example -The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Java uses [Gradle](https://gradle.org/) +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 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. @@ -141,7 +141,7 @@ coverage-jdk11: # The `visualize` stage does not exist by default. # Please define it first, or chose an existing stage like `deploy`. stage: visualize - image: haynes/jacoco2cobertura:1.0.3 + image: haynes/jacoco2cobertura:1.0.4 script: # convert report from jacoco to cobertura - 'python /opt/cover2cover.py build/jacoco/jacoco.xml src/main/java > build/cobertura.xml' diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 9581c974414..0922ffb2943 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -1,4 +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 type: reference, concepts --- 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 e7abf6e5fb6..2218d38fdad 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 @@ -27,7 +27,7 @@ There are several ways to flag a merge request as a Draft: description will have the same effect. - **Deprecated** Add `[WIP]` or `WIP:` to the start of the merge request's title. **WIP** still works but was deprecated in favor of **Draft**. It will be removed in the next major version (GitLab 14.0). -- Add the `/wip` [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) +- Add the `/draft` (or `/wip`) [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) in a comment in the merge request. This is a toggle, and can be repeated to change the status back. Note that any other text in the comment will be discarded. - Add `draft:`, `Draft:`, `fixup!`, or `Fixup!` to the beginning of a commit message targeting the @@ -43,7 +43,7 @@ Similar to above, when a Merge Request is ready to be merged, you can remove the - Remove `[Draft]`, `Draft:` or `(Draft)` from the start of the merge request's title. Clicking on **Remove the Draft: prefix from the title**, under the title box, when editing the merge request's description, will have the same effect. -- Add the `/wip` [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) +- Add the `/draft` (or `/wip`) [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics) in a comment in the merge request. This is a toggle, and can be repeated to change the status back. Note that any other text in the comment will be discarded. - Click on the **Resolve Draft status** button near the bottom of the merge request description, diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index 327a52a05ab..ae03be5fa0f 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -9,18 +9,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w [Burndown](#burndown-charts) and [burnup](#burnup-charts) charts show the progress of completing a milestone. - + ## Burndown charts > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1540) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.1 for project milestones. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5354) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.8 for group milestones. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6495) to [GitLab Starter](https://about.gitlab.com/pricing/) 11.2 for group milestones. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) [fixed burndown charts](#fixed-burndown-charts) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) [fixed burndown charts](#fixed-burndown-charts) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6. Burndown charts show the number of issues over the course of a milestone. - + At a glance, you see the current state for the completion a given milestone. Without them, you would have to organize the data from the milestone and plot it @@ -81,12 +81,12 @@ cumulative value. ### Fixed burndown charts -For milestones created before GitLab 13.5, burndown charts have an additional toggle to +For milestones created before GitLab 13.6, burndown charts have an additional toggle to switch between Legacy and Fixed views. | Legacy | Fixed | | ----- | ----- | -|  |  | +|  |  | **Fixed burndown** charts track the full history of milestone activity, from its creation until the milestone expires. After the milestone due date passes, issues removed from the milestone no longer @@ -103,11 +103,18 @@ 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.5. +> - [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. Burnup charts show the assigned and completed work for a milestone. - + To view a project's burnup chart: @@ -129,6 +136,25 @@ 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 5aa5534dd37..5d9e6b67bb8 100644 --- a/doc/user/project/milestones/burndown_charts.md +++ b/doc/user/project/milestones/burndown_charts.md @@ -2,4 +2,4 @@ redirect_to: './burndown_and_burnup_charts.md' --- -This document was moved to [another location](./burndown_and_burnup_charts.md). +This document was moved to [another location](burndown_and_burnup_charts.md). diff --git a/doc/user/project/milestones/img/burndown_and_burnup_charts_v13_5.png b/doc/user/project/milestones/img/burndown_and_burnup_charts_v13_6.png Binary files differindex 8d6ba1d4fa7..8d6ba1d4fa7 100644 --- a/doc/user/project/milestones/img/burndown_and_burnup_charts_v13_5.png +++ b/doc/user/project/milestones/img/burndown_and_burnup_charts_v13_6.png diff --git a/doc/user/project/milestones/img/burndown_chart_fixed_v13_5.png b/doc/user/project/milestones/img/burndown_chart_fixed_v13_6.png Binary files differindex a532bfeeca0..a532bfeeca0 100644 --- a/doc/user/project/milestones/img/burndown_chart_fixed_v13_5.png +++ b/doc/user/project/milestones/img/burndown_chart_fixed_v13_6.png diff --git a/doc/user/project/milestones/img/burndown_chart_legacy_v13_5.png b/doc/user/project/milestones/img/burndown_chart_legacy_v13_6.png Binary files differindex 5824fc59ce5..5824fc59ce5 100644 --- a/doc/user/project/milestones/img/burndown_chart_legacy_v13_5.png +++ b/doc/user/project/milestones/img/burndown_chart_legacy_v13_6.png diff --git a/doc/user/project/milestones/img/burndown_chart_v13_5.png b/doc/user/project/milestones/img/burndown_chart_v13_6.png Binary files differindex e06b24f9907..e06b24f9907 100644 --- a/doc/user/project/milestones/img/burndown_chart_v13_5.png +++ b/doc/user/project/milestones/img/burndown_chart_v13_6.png diff --git a/doc/user/project/milestones/img/burnup_chart_v13_5.png b/doc/user/project/milestones/img/burnup_chart_v13_6.png Binary files differindex a850caba348..a850caba348 100644 --- a/doc/user/project/milestones/img/burnup_chart_v13_5.png +++ b/doc/user/project/milestones/img/burnup_chart_v13_6.png 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 differindex a517f0f7537..5bbe8e51f23 100644 --- a/doc/user/project/milestones/img/milestones_new_group_milestone.png +++ b/doc/user/project/milestones/img/milestones_new_group_milestone.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 482c73f6568..2d0bdce542d 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/img/milestones_project_milestone_page.png b/doc/user/project/milestones/img/milestones_project_milestone_page.png Binary files differindex c17bf350aeb..1faaf0b3979 100644 --- a/doc/user/project/milestones/img/milestones_project_milestone_page.png +++ b/doc/user/project/milestones/img/milestones_project_milestone_page.png diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 8cbed3de1c6..9c47f15cb8f 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -150,7 +150,7 @@ There are also tabs below these that show the following: 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. - + ### Group Burndown Charts **(STARTER)** diff --git a/doc/user/project/operations/img/alert_issue_v13_1.png b/doc/user/project/operations/img/alert_issue_v13_1.png Binary files differdeleted file mode 100644 index da79074aa2f..00000000000 --- a/doc/user/project/operations/img/alert_issue_v13_1.png +++ /dev/null diff --git a/doc/user/project/operations/img/error_details_v12_5.png b/doc/user/project/operations/img/error_details_v12_5.png Binary files differdeleted file mode 100644 index f4866141948..00000000000 --- a/doc/user/project/operations/img/error_details_v12_5.png +++ /dev/null diff --git a/doc/user/project/operations/img/error_details_v12_6.png b/doc/user/project/operations/img/error_details_v12_6.png Binary files differdeleted file mode 100644 index 3194d8284d7..00000000000 --- a/doc/user/project/operations/img/error_details_v12_6.png +++ /dev/null diff --git a/doc/user/project/operations/img/error_details_with_issue_v12_6.png b/doc/user/project/operations/img/error_details_with_issue_v12_6.png Binary files differdeleted file mode 100644 index 963b70bd1e4..00000000000 --- a/doc/user/project/operations/img/error_details_with_issue_v12_6.png +++ /dev/null diff --git a/doc/user/project/operations/img/error_details_with_issue_v12_7.png b/doc/user/project/operations/img/error_details_with_issue_v12_7.png Binary files differdeleted file mode 100644 index aa846ee7220..00000000000 --- a/doc/user/project/operations/img/error_details_with_issue_v12_7.png +++ /dev/null diff --git a/doc/user/project/operations/img/feature_flags_list_v12_7.png b/doc/user/project/operations/img/feature_flags_list_v12_7.png Binary files differdeleted file mode 100644 index a28a844b46d..00000000000 --- a/doc/user/project/operations/img/feature_flags_list_v12_7.png +++ /dev/null diff --git a/doc/user/project/operations/img/specs_list_v12_6.png b/doc/user/project/operations/img/specs_list_v12_6.png Binary files differdeleted file mode 100644 index ea429802a40..00000000000 --- a/doc/user/project/operations/img/specs_list_v12_6.png +++ /dev/null diff --git a/doc/user/project/packages/img/maven_package_view.png b/doc/user/project/packages/img/maven_package_view.png Binary files differdeleted file mode 100644 index 2eb4b6f76b4..00000000000 --- a/doc/user/project/packages/img/maven_package_view.png +++ /dev/null diff --git a/doc/user/project/packages/img/npm_package_view.png b/doc/user/project/packages/img/npm_package_view.png Binary files differdeleted file mode 100644 index e0634718c02..00000000000 --- a/doc/user/project/packages/img/npm_package_view.png +++ /dev/null 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 a7eb4c4019f..e030326ac5f 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -158,9 +158,12 @@ When it succeeds, go to **Settings > Pages** to view the URL where your site is now available. If you want to do more advanced tasks, you can update your `.gitlab-ci.yml` file -with [any of the available settings](../../../../ci/yaml/README.md). See -[Validate the `.gitlab-ci.yml`](../../../../ci/yaml/README.md#validate-the-gitlab-ciyml) -for instructions on validating your YAML file with the Lint tool included with GitLab. +with [any of the available settings](../../../../ci/yaml/README.md). You can validate +your `.gitlab-ci.yml` file with the [CI Lint](../../../../ci/lint.md) tool that's included with GitLab. + +After successful execution of this `pages` job, a special `pages:deploy` job appears in the +pipeline view. It prepares the content of the website for GitLab Pages daemon. GitLab executes it in +the background and doesn't use runner. The following topics show other examples of other options you can add to your CI/CD file. diff --git a/doc/user/project/pages/img/icons/click.png b/doc/user/project/pages/img/icons/click.png Binary files differdeleted file mode 100644 index 62a997a7591..00000000000 --- a/doc/user/project/pages/img/icons/click.png +++ /dev/null diff --git a/doc/user/project/pages/img/icons/cogs.png b/doc/user/project/pages/img/icons/cogs.png Binary files differdeleted file mode 100644 index f37f8f361d1..00000000000 --- a/doc/user/project/pages/img/icons/cogs.png +++ /dev/null diff --git a/doc/user/project/pages/img/icons/fork.png b/doc/user/project/pages/img/icons/fork.png Binary files differdeleted file mode 100644 index 1ae8fa722b7..00000000000 --- a/doc/user/project/pages/img/icons/fork.png +++ /dev/null diff --git a/doc/user/project/pages/img/icons/free.png b/doc/user/project/pages/img/icons/free.png Binary files differdeleted file mode 100644 index c74cd90fa1a..00000000000 --- a/doc/user/project/pages/img/icons/free.png +++ /dev/null diff --git a/doc/user/project/pages/img/icons/monitor.png b/doc/user/project/pages/img/icons/monitor.png Binary files differdeleted file mode 100644 index ce27b7e177e..00000000000 --- a/doc/user/project/pages/img/icons/monitor.png +++ /dev/null diff --git a/doc/user/project/pages/img/pages_workflow_v12_5.png b/doc/user/project/pages/img/pages_workflow_v12_5.png Binary files differdeleted file mode 100644 index ca5190fca79..00000000000 --- a/doc/user/project/pages/img/pages_workflow_v12_5.png +++ /dev/null diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 4f389716f08..f5cd6991869 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -29,7 +29,7 @@ directly from a repository in GitLab. </ul> </p> </div> -<div class="col-md-3"><img src="img/ssgs_pages.png" alt="Examples of SSGs supported by Pages" class="image-noshadow middle display-block"></div> +<div class="col-md-3"><img src="img/ssgs_pages.png" alt="Examples of SSGs supported by Pages" class="middle display-block"></div> </div> To publish a website with Pages, you can use any SSG, @@ -89,7 +89,7 @@ need admin access to your domain's registrar (or control panel) to set it up wit The following diagrams show the workflows you might follow to get started with Pages. -<img src="img/new_project_for_pages_v12_5.png" alt="New projects for GitLab Pages" class="image-noshadow"> +<img src="img/new_project_for_pages_v12_5.png" alt="New projects for GitLab Pages"> ## Access to your Pages site diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index b97d5328c07..6dbc12cc2ec 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -11,7 +11,7 @@ GitLab Pages offers. To familiarize yourself with GitLab Pages first: -- Read an [introduction to GitLab Pages](index.md#overview). +- Read an [introduction to GitLab Pages](index.md). - Learn [how to get started with Pages](index.md#getting-started). - Learn how to enable GitLab Pages across your GitLab instance on the [administrator documentation](../../../administration/pages/index.md). 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 02d1dd7898a..13ea57939f8 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -1,4 +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 description: "How to secure GitLab Pages websites with Let's Encrypt (manual process, deprecated)." --- diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 2f1b05f481e..46db7293711 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -40,6 +40,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/copy_metadata <#issue>` | ✓ | ✓ | | Copy labels and milestone from another issue in the project. | | `/create_merge_request <branch name>` | ✓ | | | Create a new merge request starting from the current issue. | | `/done` | ✓ | ✓ | ✓ | Mark to do as done. | +| `/draft` | | ✓ | | Toggle the draft status. | | `/due <date>` | ✓ | | | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | | `/duplicate <#issue>` | ✓ | | | Close this issue and mark as a duplicate of another issue. **(CORE)** Also, mark both as related. **(STARTER)** | | `/epic <epic>` | ✓ | | | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. **(PREMIUM)** | @@ -74,7 +75,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/tableflip <comment>` | ✓ | ✓ | ✓ | Append the comment with `(╯°□°)╯︵ ┻━┻`. | | `/target_branch <local branch name>` | | ✓ | | Set target branch. | | `/title <new title>` | ✓ | ✓ | ✓ | Change title. | -| `/todo` | ✓ | ✓ | ✓ | Add a to do. | +| `/todo` | ✓ | ✓ | ✓ | Add a to-do item. | | `/unassign @user1 @user2` | ✓ | ✓ | | Remove specific assignees. **(STARTER)** | | `/unassign` | ✓ | ✓ | | Remove all assignees. | | `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | ✓ | ✓ | ✓ | Remove specified labels. | @@ -82,7 +83,7 @@ The following quick actions are applicable to descriptions, discussions and thre | `/unlock` | ✓ | ✓ | | Unlock the discussions. | | `/unsubscribe` | ✓ | ✓ | ✓ | Unsubscribe from notifications. | | `/weight <value>` | ✓ | | | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. **(STARTER)** | -| `/wip` | | ✓ | | Toggle the Work In Progress status. | +| `/wip` | | ✓ | | Toggle the draft status. | | `/zoom <Zoom URL>` | ✓ | | | Add Zoom meeting to this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | ## Autocomplete characters diff --git a/doc/user/project/releases/img/edit_release_page_v12_10.png b/doc/user/project/releases/img/edit_release_page_v12_10.png Binary files differdeleted file mode 100644 index ebb12a549b7..00000000000 --- a/doc/user/project/releases/img/edit_release_page_v12_10.png +++ /dev/null diff --git a/doc/user/project/releases/img/edit_release_page_v12_6.png b/doc/user/project/releases/img/edit_release_page_v12_6.png Binary files differdeleted file mode 100644 index ae7641ac8a5..00000000000 --- a/doc/user/project/releases/img/edit_release_page_v12_6.png +++ /dev/null diff --git a/doc/user/project/releases/img/release_with_milestone_v12_5.png b/doc/user/project/releases/img/release_with_milestone_v12_5.png Binary files differdeleted file mode 100644 index 2a7a2ee9754..00000000000 --- a/doc/user/project/releases/img/release_with_milestone_v12_5.png +++ /dev/null diff --git a/doc/user/project/releases/img/releases.png b/doc/user/project/releases/img/releases.png Binary files differdeleted file mode 100644 index da5bcd9d913..00000000000 --- a/doc/user/project/releases/img/releases.png +++ /dev/null diff --git a/doc/user/project/releases/img/releases_count_v12_8.png b/doc/user/project/releases/img/releases_count_v12_8.png Binary files differdeleted file mode 100644 index e70f623d508..00000000000 --- a/doc/user/project/releases/img/releases_count_v12_8.png +++ /dev/null diff --git a/doc/user/project/releases/img/releases_sort_v13_6.png b/doc/user/project/releases/img/releases_sort_v13_6.png Binary files differnew file mode 100644 index 00000000000..e663e3cc7f3 --- /dev/null +++ b/doc/user/project/releases/img/releases_sort_v13_6.png diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 962d612cac1..674fe8b22b8 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -43,6 +43,13 @@ To view a list of releases: - On private projects, this number is visible to users with Reporter [permissions](../../permissions.md#project-members-permissions) or higher. +### Sort Releases + +On the top right of the **Releases** page, you can use the sorting button to order releases by +**Released date** or **Created date**. You can sort releases in ascending or descending order. + + + ## Create a release > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32812) in GitLab 12.9. Releases can be created directly in the GitLab UI. @@ -130,6 +137,8 @@ In the interface, to add release notes to an existing Git tag: You can associate a release with one or more [project milestones](../milestones/index.md#project-milestones-and-group-milestones). +[GitLab Premium](https://about.gitlab.com/pricing/) customers can specify [group milestones](../milestones/index.md#project-milestones-and-group-milestones) to associate with a release. + You can do this in the user interface, or by including a `milestones` array in your request to the [Releases API](../../../api/releases/index.md#create-a-release). @@ -446,17 +455,17 @@ In the API: - If you do not specify a `released_at` date, release evidence is collected on the date the release is created. -## GitLab Releaser +## Release Command Line -> [Introduced](https://gitlab.com/gitlab-org/gitlab-releaser/-/merge_requests/6) in GitLab 12.10. +> [Introduced](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/6) in GitLab 12.10. -GitLab Releaser is a CLI tool for managing GitLab Releases from the command line or from +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`. With it, you can create, update, modify, and delete releases right through the terminal. -Read the [GitLab Releaser documentation](https://gitlab.com/gitlab-org/gitlab-releaser/-/tree/master/docs/index.md) +Read the [Release CLI documentation](https://gitlab.com/gitlab-org/release-cli/-/blob/master/docs/index.md) for details. <!-- ## Troubleshooting diff --git a/doc/user/project/repository/branches/img/compare_branches.png b/doc/user/project/repository/branches/img/compare_branches.png Binary files differindex 52d5c518c45..e6f88da4989 100644 --- a/doc/user/project/repository/branches/img/compare_branches.png +++ b/doc/user/project/repository/branches/img/compare_branches.png diff --git a/doc/user/project/repository/img/file_ext_icons_repo_v12_10.png b/doc/user/project/repository/img/file_ext_icons_repo_v12_10.png Binary files differindex 346f0e58325..04a8f38871b 100644 --- a/doc/user/project/repository/img/file_ext_icons_repo_v12_10.png +++ b/doc/user/project/repository/img/file_ext_icons_repo_v12_10.png diff --git a/doc/user/project/repository/img/repository_mirroring_push_settings.png b/doc/user/project/repository/img/repository_mirroring_push_settings.png Binary files differindex 9fc25dd3b25..8916d21d515 100644 --- a/doc/user/project/repository/img/repository_mirroring_push_settings.png +++ b/doc/user/project/repository/img/repository_mirroring_push_settings.png diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index fe432e0d553..69a32841981 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -22,8 +22,8 @@ GitLab. ## Jupyter Hub as a GitLab Managed App -You can deploy [Jupyter Hub as a GitLab managed app](./../../../clusters/applications.md#jupyterhub). +You can deploy [Jupyter Hub as a GitLab managed app](../../../clusters/applications.md#jupyterhub). ## Jupyter Git integration -Find out how to [leverage JupyterLab’s Git extension on your Kubernetes cluster](./../../../clusters/applications.md#jupyter-git-integration). +Find out how to [leverage JupyterLab’s Git extension on your Kubernetes cluster](../../../clusters/applications.md#jupyter-git-integration). 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 ad79fd8a8f9..9f4dfe54c47 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 @@ -18,7 +18,7 @@ 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: **Danger:** +DANGER: **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). @@ -202,6 +202,12 @@ 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 diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 188699e0c77..1f9835f4f59 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -577,3 +577,7 @@ Should an error occur during a push, GitLab will display an "Error" highlight fo ### 13:Received RST_STREAM with error code 2 with GitHub If you receive an "13:Received RST_STREAM with error code 2" while mirroring to a GitHub repository, your GitHub settings might be set to block pushes that expose your email address used in commits. Either set your email address on GitHub to be public, or disable the [Block command line pushes that expose my email](https://github.com/settings/emails) setting. + +### 4:Deadline Exceeded + +When upgrading to GitLab 11.11.8 or newer, a change in how usernames are represented means that you may need to update your mirroring username and password to ensure that `%40` characters are replaced with `@`. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index af0daaaeca2..5b82cdbd9e9 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -29,6 +29,11 @@ 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). + ### Template dropdowns When starting a new project, there are some common files that the new project @@ -107,7 +112,7 @@ name or a referenced merge request or your project has an active fork relationship. If you would like to make this button appear, a possible workaround is to [remove your project's fork relationship](../settings/index.md#removing-a-fork-relationship). Once removed, the fork -relationship cannot be restored, and you will no longer be able to send merge requests to the source. +relationship cannot be restored. This project will no longer be able to receive or send merge requests to the source project or other forks.  diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 0a1b81a6359..34a075df990 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -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: **Danger:** + DANGER: **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 @@ -99,7 +99,7 @@ navigation's **Issues** menu. When a user submits a new issue using Service Desk, or when a new note is created on a Service Desk issue, an email is sent to the author. -The body of these email messages can customized by using templates. To create a new customized template, +The body of these email messages can be customized by using templates. To create a new customized template, create a new Markdown (`.md`) file inside the `.gitlab/service_desk_templates/` directory in your repository. Commit and push to your default branch. diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 478d9b3b948..3e493f02392 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Source Code +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" type: reference, howto --- @@ -32,6 +32,9 @@ To set up a project import/export: Note the following: +- Before you can import a project, you need to export the data first. + See [Exporting a project and its data](#exporting-a-project-and-its-data) + for how you can export a project through the UI. - Imports from a newer version of GitLab are not supported. The Importing GitLab version must be greater than or equal to the Exporting GitLab version. - Imports will fail unless the import and export GitLab instances are @@ -41,7 +44,7 @@ Note the following: - 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. - Project members with owner access will be imported as maintainers. -- Using an admin account to import will map users by primary email address (self-managed only). +- Imported users can be mapped by their primary email on self-managed instances, if an administrative user (not an owner) does the import. Otherwise, a supplementary comment is left to mention that the original author and the MRs, notes, or issues will be owned by the importer. - If an imported project contains merge requests originating from forks, @@ -129,6 +132,11 @@ For more details on the specific data persisted in a project export, see the ## Exporting a project and its data +Full project export functionality is limited to project maintainers and owners. +You can configure such functionality through [project settings](index.md): + +To export a project and its data, follow these steps: + 1. Go to your project's homepage. 1. Click **Settings** in the sidebar. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 8fdcf58b5aa..4b368fc20d6 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -72,6 +72,7 @@ Use the switches to enable or disable the following features: | **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) Some features depend on others: diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index b6ce21ebea6..9f8cf2ff41a 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -54,7 +54,7 @@ Furthermore, the bot user can not be added to any other project. When the project access token is [revoked](#revoking-a-project-access-token) the bot user is then deleted and all records are moved to a system-wide user with the username "Ghost User". For more information, see [Associated Records](../../profile/account/delete_account.md#associated-records). -Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#choose-the-number-of-users) and do not count as licensed seats. +Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users) and do not count as licensed seats. ## Revoking a project access token diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index 8a2f62ec7a2..e58667c275c 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -80,6 +80,7 @@ codebase. ## Edit content > - Support for modifying the default merge request title and description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216861) in GitLab 13.5. +> - Support for selecting a merge request template [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263252) in GitLab 13.6. After setting up your project, you can start editing content directly from the Static Site Editor. @@ -91,7 +92,9 @@ To edit a file: wish to edit the raw Markdown instead, you can toggle the **Markdown** mode in the bottom-right corner. 1. When you're done, click **Submit changes...**. -1. (Optional) Adjust the default title and description of the merge request that will be submitted with your changes. +1. (Optional) Adjust the default title and description of the merge request that will be submitted + with your changes. Alternatively, select a [merge request template](../../../user/project/description_templates.md#creating-merge-request-templates) + from the dropdown menu and edit it accordingly. 1. Click **Submit changes**. 1. A new merge request is automatically created and you can assign a colleague for review. @@ -104,13 +107,36 @@ The Static Site Editors supports Markdown files (`.md`, `.md.erb`) for editing t ### Images > - Support for adding images through the WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216640) in GitLab 13.1. +> - Support for uploading images via the WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218529) in GitLab 13.6. -You can add image files on the WYSIWYG mode by clicking the image icon (**{doc-image}**). -From there, link to a URL, add optional [ALT text](https://moz.com/learn/seo/alt-text), -and you're done. The link can reference images already hosted in your project, an asset hosted +#### Upload an image + +You can upload image files via the WYSIWYG editor directly to the repository to default upload directory +`source/images`. To do so: + +1. Click the image icon (**{doc-image}**). +1. Choose the **Upload file** tab. +1. Click **Choose file** to select a file from your computer. +1. Optional: add a description to the image for SEO and accessibility ([ALT text](https://moz.com/learn/seo/alt-text)). +1. Click **Insert image**. + +The selected file can be any supported image file (`.png`, `.jpg`, `.jpeg`, `.gif`). The editor renders +thumbnail previews so you can verify the correct image is included and there aren't any references to +missing images. + +#### Link to an image + +You can also link to an image if you'd like: + +1. Click the image icon (**{doc-image}**). +1. Choose the **Link to an image** tab. +1. Add the link to the image into the **Image URL** field (use the full path; relative paths are not supported yet). +1. Optional: add a description to the image for SEO and accessibility ([ALT text](https://moz.com/learn/seo/alt-text)). +1. Click **Insert image**. + +The link can reference images already hosted in your project, an asset hosted externally on a content delivery network, or any other external URL. The editor renders thumbnail previews so you can verify the correct image is included and there aren't any references to missing images. -default directory (`source/images/`). ### Videos diff --git a/doc/user/project/web_ide/img/command_palette_v13_6.png b/doc/user/project/web_ide/img/command_palette_v13_6.png Binary files differnew file mode 100644 index 00000000000..54580a79ebd --- /dev/null +++ b/doc/user/project/web_ide/img/command_palette_v13_6.png diff --git a/doc/user/project/web_ide/img/commit_changes_v12_9.png b/doc/user/project/web_ide/img/commit_changes_v12_9.png Binary files differindex d26c9cc82e1..9a8bb214b3d 100644 --- a/doc/user/project/web_ide/img/commit_changes_v12_9.png +++ b/doc/user/project/web_ide/img/commit_changes_v12_9.png diff --git a/doc/user/project/web_ide/img/dark_theme_v13_0.png b/doc/user/project/web_ide/img/dark_theme_v13_0.png Binary files differindex f1999363904..020578a9444 100644 --- a/doc/user/project/web_ide/img/dark_theme_v13_0.png +++ b/doc/user/project/web_ide/img/dark_theme_v13_0.png 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 adf6d3c6b02..b4b14f1fc7f 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 4da9b5f88ff..2b9db1c952d 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, how-to --- -# Web IDE +# Web IDE **(CORE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. > - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Core in 10.7. @@ -25,9 +25,25 @@ and from merge requests. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18323) in [GitLab Core](https://about.gitlab.com/pricing/) 10.8. The file finder allows you to quickly open files in the current branch by -searching. The file finder is launched using the keyboard shortcut `Command-p`, -`Control-p`, or `t` (when editor is not in focus). Type the filename or -file path fragments to start seeing results. +searching for fragments of the file path. The file finder is launched using the keyboard shortcut +<kbd>Cmd</kbd>+<kbd>p</kbd>, <kbd>Ctrl</kbd>+<kbd>p</kbd>, or <kbd>t</kbd> +(when editor is not in focus). Type the filename or file path fragments to +start seeing results. + +## Command palette + +You can see all available commands for manipulating editor content by pressing +the <kbd>F1</kbd> key when the editor is in focus. After that, +you'll see a complete list of available commands for +manipulating editor content. The editor supports commands for multi-cursor +editing, code block folding, commenting, searching and replacing, navigating +editor warnings and suggestions, and more. + +Some commands have a keyboard shortcut assigned to them. The command palette +displays this shortcut next to each command. You can use this shortcut to invoke +the command without having to select it in the command palette. + + ## Syntax highlighting @@ -244,6 +260,8 @@ quickly share your project with others. ### Enabling Live Preview +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/268288) in GitLab 12.9, third-party assets and libraries required for Live Preview are hosted at `https://sandbox-prod.gitlab-static.net` when it is enabled. However, some libraries are still served from other third-party services which may or may not be desirable in your environment. + The Live Preview feature needs to be enabled in the GitLab instances admin settings. Live Preview is enabled for all projects on GitLab.com diff --git a/doc/user/project/wiki/img/wiki_move_page_1.png b/doc/user/project/wiki/img/wiki_move_page_1.png Binary files differdeleted file mode 100644 index 189fcc9a845..00000000000 --- a/doc/user/project/wiki/img/wiki_move_page_1.png +++ /dev/null diff --git a/doc/user/project/wiki/img/wiki_move_page_2.png b/doc/user/project/wiki/img/wiki_move_page_2.png Binary files differdeleted file mode 100644 index 63e6ddb29c1..00000000000 --- a/doc/user/project/wiki/img/wiki_move_page_2.png +++ /dev/null diff --git a/doc/user/project/wiki/img/wiki_sidebar_v13_5.png b/doc/user/project/wiki/img/wiki_sidebar_v13_5.png Binary files differindex 0f445d61d71..f22424749a5 100644 --- a/doc/user/project/wiki/img/wiki_sidebar_v13_5.png +++ b/doc/user/project/wiki/img/wiki_sidebar_v13_5.png diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 64608b9a915..e082e091dec 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -96,12 +96,12 @@ Please note that: ## Editing a wiki page -NOTE: **Note:** -Requires Developer [permissions](../../permissions.md). +You need Developer [permissions](../../permissions.md) or higher to edit a wiki page. +To do so: -To edit a page, simply click on the **Edit** button. From there on, you can -change its content. When done, click **Save changes** for the changes to take -effect. +1. Click the edit icon (**{pencil}**). +1. Edit the content. +1. Click **Save changes**. ### Adding a table of contents @@ -110,23 +110,34 @@ For an example, see [Table of contents](../../markdown.md#table-of-contents). ## Deleting a wiki page -NOTE: **Note:** -Requires Maintainer [permissions](../../permissions.md). +You need Maintainer [permissions](../../permissions.md) or higher to delete a wiki page. +To do so: -You can find the **Delete** button only when editing a page. Click on it and -confirm you want the page to be deleted. +1. Open the page you want to delete. +1. Click the **Delete page** button. +1. Confirm the deletion. ## Moving a wiki page -You can move a wiki page from one directory to another by specifying the full -path in the wiki page title in the [edit](#editing-a-wiki-page) form. +You need Developer [permissions](../../permissions.md) or higher to move a wiki page. +To do so: + +1. Click the edit icon (**{pencil}**). +1. Add the new path to the **Title** field. +1. Click **Save changes**. + +For example, if you have a wiki page called `about` under `company` and you want to +move it to the wiki's root: - +1. Click the edit icon (**{pencil}**). +1. Change the **Title** from `about` to `/about`. +1. Click **Save changes**. - +If you want to do the opposite: -In order to move a wiki page to the root directory, the wiki page title must -be preceded by the slash (`/`) character. +1. Click the edit icon (**{pencil}**). +1. Change the **Title** from `about` to `company/about`. +1. Click **Save changes**. ## Viewing a list of all created wiki pages diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index 28dd4c142f7..ea3ca7a28d7 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -1,3 +1,9 @@ +--- +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 +--- + # Reserved project and group names Not all project & group names are allowed because they would conflict with @@ -76,6 +82,9 @@ Currently the following names are reserved as top level groups: - `s` - `search` - `sent_notifications` +- `sitemap` +- `sitemap.xml` +- `sitemap.xml.gz` - `slash-command-logo.png` - `snippets` - `unsubscribes` diff --git a/doc/user/search/advanced_search_syntax.md b/doc/user/search/advanced_search_syntax.md index ed5ecc17a8b..c1414fb9ebe 100644 --- a/doc/user/search/advanced_search_syntax.md +++ b/doc/user/search/advanced_search_syntax.md @@ -64,8 +64,8 @@ The Advanced Search Syntax also supports the use of filters. The available filte - extension: Filters by extension in the filename. Please write the extension without a leading dot. Exact match only. - blob: Filters by Git `object ID`. Exact match only. -To use them, simply add them to your query in the format `<filter_name>:<value>` without - any spaces between the colon (`:`) and the value. +To use them, add them to your keyword in the format `<filter_name>:<value>` without +any spaces between the colon (`:`) and the value. A keyword or an asterisk (`*`) is required for filter searches and has to be added in front of the filter separated by a space. Examples: diff --git a/doc/user/search/img/filtering_merge_requests_by_date_v13_6.png b/doc/user/search/img/filtering_merge_requests_by_date_v13_6.png Binary files differnew file mode 100644 index 00000000000..8f59534ef1c --- /dev/null +++ b/doc/user/search/img/filtering_merge_requests_by_date_v13_6.png diff --git a/doc/user/search/img/filtering_merge_requests_by_environment_v13_6.png b/doc/user/search/img/filtering_merge_requests_by_environment_v13_6.png Binary files differnew file mode 100644 index 00000000000..e73a0995d73 --- /dev/null +++ b/doc/user/search/img/filtering_merge_requests_by_environment_v13_6.png diff --git a/doc/user/search/img/issue_search_filter.png b/doc/user/search/img/issue_search_filter.png Binary files differdeleted file mode 100644 index d4de3ff7656..00000000000 --- a/doc/user/search/img/issue_search_filter.png +++ /dev/null diff --git a/doc/user/search/img/project_search_sha_redirect.png b/doc/user/search/img/project_search_sha_redirect.png Binary files differnew file mode 100644 index 00000000000..718a859d4af --- /dev/null +++ b/doc/user/search/img/project_search_sha_redirect.png diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 412951f8a3b..79c6cf3b07d 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -44,6 +44,7 @@ groups: - Author - Assignee - [Milestone](../project/milestones/index.md) + - [Iteration](../group/iterations/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6) - Release - [Label](../project/labels.md) - My-reaction @@ -117,6 +118,28 @@ the dropdown) **Approved-By** and select the user.  +### Filtering merge requests by environment or deployment date **(CORE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44041) in GitLab 13.6. + +To filter merge requests by deployment data, such as the environment or a date, +you can type (or select from the dropdown) the following: + +- Environment +- Deployed-before +- Deployed-after + +When filtering by an environment, a dropdown presents all environments that +you can choose from: + + + +When filtering by a deploy date, you must enter the date manually. Deploy dates +use the format `YYYY-MM-DD`, and must be quoted if you wish to specify +both a date and time (`"YYYY-MM-DD HH:MM"`): + + + ## Filters autocomplete GitLab provides many filters across many pages (issues, merge requests, epics, @@ -211,6 +234,7 @@ You can also type in this search bar to see autocomplete suggestions for: - Recently viewed issues (try and type some word from the title of a recently viewed issue) - Recently viewed merge requests (try and type some word from the title of a recently viewed merge request) - Recently viewed epics (try and type some word from the title of a recently viewed epic) +- [GitLab Flavored Markdown](../markdown.md#special-gitlab-references) (GFM) for issues within a project (try and type a GFM reference for an issue) ## Basic search @@ -248,6 +272,14 @@ the search field on the top-right of your screen while the project page is open.   +### SHA search + +You can quickly access a commit from within the project dashboard by entering the SHA +into the search field on the top right of the screen. If a single result is found, you will be +redirected to the commit result and given the option to return to the search results page. + + + ## Advanced Search **(STARTER)** Leverage Elasticsearch for faster, more advanced code search across your entire diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index c34d5be5899..6361aa856fe 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -1,4 +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 type: reference disqus_identifier: 'https://docs.gitlab.com/ee/workflow/shortcuts.html' --- diff --git a/doc/user/todos.md b/doc/user/todos.md index c48d2adfa45..061d81618a1 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -15,9 +15,9 @@ spend your time. This can include taking an action, or keeping track of things do your work, being able to get started quickly is important. Your *To-Do List* offers a chronological list of items waiting for your input -(known as *to do items*) in a single dashboard. +(known as *to-do items*) in a single dashboard. -The To-Do List supports tracking [actions](#what-triggers-a-to-do) related to +The To-Do List supports tracking [actions](#what-triggers-a-to-do-item) related to the following: - Issues @@ -27,17 +27,17 @@ the following:  You can access your To-Do List by clicking the To-Do List icon (**{task-done}**) -next to the search bar in the top navigation. If the to do item count is: +next to the search bar in the top navigation. If the to-do item count is: -- *Less than 100*, the number in blue is the number of to do items. +- *Less than 100*, the number in blue is the number of to-do items. - *100 or more*, the number displays as 99+. The exact number displays in the To-Do List.  -## What triggers a to do +## What triggers a to-do item -A to do item appears on your To-Do List when: +A to-do item appears on your To-Do List when: - An issue or merge request is assigned to you. - You're `@mentioned` in the description or comment of an issue or merge request @@ -60,19 +60,19 @@ When several trigger actions occur for the same user on the same object (for example, an issue), GitLab displays only the first action as a single to do item. -To do item triggers aren't affected by [GitLab notification email settings](profile/notifications.md). +To-do item triggers aren't affected by [GitLab notification email settings](profile/notifications.md). NOTE: **Note:** -When a user no longer has access to a resource related to a to do item (such as +When a user no longer has access to a resource related to a to-do item (such as an issue, merge request, project, or group), for security reasons GitLab -deletes any related to do items within the next hour. Deletion is delayed to +deletes any related to-do items within the next hour. Deletion is delayed to prevent data loss, in the case where a user's access is accidentally revoked. -### Directly addressing a to do +### Directly addressing a to-do item > [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 will be listed as *directly addressed*. For example, in the following comment: ```markdown @@ -87,11 +87,11 @@ listed as *directly addressed*. For example, in the following comment: @erin @frank thank you! ``` -The people receiving directly addressed to do items are `@alice`, `@erin`, and -`@frank`. Directly addressed to do items only differ from mentions in their type +The people receiving directly addressed to-do items are `@alice`, `@erin`, and +`@frank`. Directly addressed to-do items only differ from mentions in their type for filtering purposes; otherwise, they appear as normal. -### Manually creating a to do +### Manually creating a to-do item You can also add the following to your To-Do List by clicking the **Add a to do** button on an: @@ -100,14 +100,14 @@ You can also add the following to your To-Do List by clicking the **Add a to do* - [Epic](group/epics/index.md) **(ULTIMATE)** - [Design](project/issues/design_management.md) - + -## Marking a to do as done +## Marking a to-do item as done Any action to an issue or merge request (or epic **(ULTIMATE)**) will mark its -corresponding to do item as done. +corresponding to-do item as done. -Actions that dismiss to do items include: +Actions that dismiss to-do items include: - Changing the assignee - Changing the milestone @@ -115,28 +115,28 @@ Actions that dismiss to do items include: - Commenting on the issue Your To-Do List is personal, and items are only marked as done if you take -action. If you close the issue or merge request, your to do item is marked as +action. If you close the issue or merge request, your to-do item is marked as done. To prevent other users from closing issues without you being notified, if someone else closes, merges, or takes action on an issue or merge request (or -epic **(ULTIMATE)**), your to do item remains pending. +epic **(ULTIMATE)**), your to-do item remains pending. -There's just one to do item for each of these, so mentioning a user many times -in an issue only triggers one to do item. +There's just one to-do item for each of these, so mentioning a user many times +in an issue only triggers one to-do item. -If no action is needed, you can manually mark the to do item as done by +If no action is needed, you can manually mark the to-do item as done by clicking its corresponding **Done** button to have GitLab remove the item from your To-Do List.  -You can also mark a to do item as done by clicking the **Mark as done** button +You can also mark a to-do item as done by clicking the **Mark as done** button in the sidebar of an issue or merge request (or epic **(ULTIMATE)**).  -You can mark all your to do items as done at once by clicking the +You can mark all your to-do items as done at once by clicking the **Mark all as done** button. ## Filtering your To-Do List @@ -152,7 +152,7 @@ You can use the following types of filters with your To-Do List: | Action | Filter by the action that triggered the to do. | You can also filter by more than one of these at the same time. The previously -described [triggering actions](#what-triggers-a-to-do) include: +described [triggering actions](#what-triggers-a-to-do-item) include: - Any action - Assigned diff --git a/doc/user/upgrade_email_bypass.md b/doc/user/upgrade_email_bypass.md index 35fddc4a1d4..97d4b5e6a0a 100644 --- a/doc/user/upgrade_email_bypass.md +++ b/doc/user/upgrade_email_bypass.md @@ -1,3 +1,9 @@ +--- +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 +--- + # Updating to GitLab 13.2: Email confirmation issues In the [GitLab 13.0.1 security release](https://about.gitlab.com/releases/2020/05/27/security-release-13-0-1-released/), |
