diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-02-18 12:45:46 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-02-18 12:45:46 +0300 |
| commit | a7b3560714b4d9cc4ab32dffcd1f74a284b93580 (patch) | |
| tree | 7452bd5c3545c2fa67a28aa013835fb4fa071baf /doc/user | |
| parent | ee9173579ae56a3dbfe5afe9f9410c65bb327ca7 (diff) | |
Add latest changes from gitlab-org/gitlab@14-8-stable-eev14.8.0-rc42
Diffstat (limited to 'doc/user')
250 files changed, 5066 insertions, 2827 deletions
diff --git a/doc/user/admin_area/analytics/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index df34cd03d71..2ad18d5f70e 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -39,7 +39,7 @@ feature is available. ## DevOps Adoption **(ULTIMATE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247112) in GitLab 13.7 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247112) in GitLab 13.7 as a [Beta feature](../../../policy/alpha-beta-support.md#beta-features). > - The Overview tab [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330401) in GitLab 14.1. > - DAST and SAST metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328033) in GitLab 14.1. > - Fuzz Testing metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/330398) in GitLab 14.2. diff --git a/doc/user/admin_area/analytics/usage_trends.md b/doc/user/admin_area/analytics/usage_trends.md index 7901d30c3ea..a9c5adcf838 100644 --- a/doc/user/admin_area/analytics/usage_trends.md +++ b/doc/user/admin_area/analytics/usage_trends.md @@ -33,7 +33,7 @@ At the top of the page, Usage Trends shows total counts for: - Projects - Groups - Issues -- Merge Requests +- Merge requests - Pipelines These figures can be useful for understanding how much data your instance contains in total. diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index f9b5168fb08..437a72da767 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -13,9 +13,14 @@ GitLab administrators are responsible for the overall security of their instance provides a Credentials inventory to keep track of all the credentials that can be used to access their self-managed instance. -Using Credentials inventory, you can see all the personal access tokens (PAT), SSH keys, and GPG keys -that exist in your GitLab instance. In addition, you can [revoke](#revoke-a-users-personal-access-token) -and [delete](#delete-a-users-ssh-key) and see: +Use Credentials inventory to see for your GitLab instance all: + +- Personal access tokens (PAT). +- Project access tokens (GitLab 14.8 and later). +- SSH keys. +- GPG keys. + +You can also [revoke](#revoke-a-users-personal-access-token) and [delete](#delete-a-users-ssh-key) and see: - Who they belong to. - Their access scope. @@ -28,17 +33,13 @@ To access the Credentials inventory: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Credentials**. -The following is an example of the Credentials inventory page: - - - ## Revoke a user's personal access token > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214811) in GitLab 13.4. If you see a **Revoke** button, you can revoke that user's PAT. Whether you see a **Revoke** button depends on the token state, and if an expiration date has been set. For more information, see the following table: -| Token state | [Token expiration enforced?](settings/account_and_limit_settings.md#allow-expired-personal-access-tokens-to-be-used) | Show Revoke button? | Comments | +| Token state | [Token expiration enforced?](settings/account_and_limit_settings.md#allow-expired-personal-access-tokens-to-be-used-deprecated) | Show Revoke button? | Comments | |-------------|------------------------|--------------------|----------------------------------------------------------------------------| | Active | Yes | Yes | Allows administrators to revoke the PAT, such as for a compromised account | | Active | No | Yes | Allows administrators to revoke the PAT, such as for a compromised account | @@ -49,6 +50,15 @@ If you see a **Revoke** button, you can revoke that user's PAT. Whether you see When a PAT is revoked from the credentials inventory, the instance notifies the user by email. +## Revoke a user's project access token + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/243833) in GitLab 14.8. + +The **Revoke** button next to a project access token can be selected to revoke that particular project access token. This will both: + +- Revoke the token project access token. +- Enqueue a background worker to delete the project bot user. + ## Delete a user's SSH key > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225248) in GitLab 13.5. diff --git a/doc/user/admin_area/img/credentials_inventory_v13_10.png b/doc/user/admin_area/img/credentials_inventory_v13_10.png Binary files differdeleted file mode 100644 index 2790ca70fba..00000000000 --- a/doc/user/admin_area/img/credentials_inventory_v13_10.png +++ /dev/null diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index ba0802b3b7a..57a4a746ff0 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -32,7 +32,7 @@ The Admin Area is made up of the following sections: | **{slight-frown}** Abuse Reports | Manage [abuse reports](review_abuse_reports.md) submitted by your users. | | **{license}** License | Upload, display, and remove [licenses](license.md). | | **{cloud-gear}** Kubernetes | Create and manage instance-level [Kubernetes clusters](../instance/clusters/index.md). | -| **{push-rules}** Push rules | Configure pre-defined Git [push rules](../../push_rules/push_rules.md) for projects. Also, configure [merge requests approvers rules](merge_requests_approvals.md). | +| **{push-rules}** Push rules | Configure pre-defined Git [push rules](../project/repository/push_rules.md) for projects. Also, configure [merge requests approvers rules](merge_requests_approvals.md). | | **{location-dot}** Geo | Configure and maintain [Geo nodes](geo_nodes.md). | | **{key}** Deploy keys | Create instance-wide [SSH deploy keys](../project/deploy_keys/index.md). | | **{lock}** Credentials | View [credentials](credentials_inventory.md) that can be used to access your instance. | @@ -107,23 +107,6 @@ You can combine the filter options. For example, to list only public projects wi 1. Click the **Public** tab. 1. Enter `score` in the **Filter by name...** input box. -#### Projects pending deletion **(PREMIUM SELF)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37014) in GitLab 13.3. -> - [Tab renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/347468) from **Deleted projects** in GitLab 14.6. - -When delayed project deletion is [enabled for a group](../group/index.md#enable-delayed-project-deletion), -projects within that group are not deleted immediately, but only after a delay. To access a list of all projects that are pending deletion: - -1. On the top bar, select **Menu > Projects > Explore projects**. -1. Select the **Pending deletion** tab (in GitLab 14.6 and later) or the **Deleted projects** tab (GitLab 14.5 and earlier). - -Listed for each project is: - -- The time the project was marked for deletion. -- The time the project is scheduled for final deletion. -- A **Restore** link to stop the project being eventually deleted. - ### Administering Users You can administer all users in the GitLab instance from the Admin Area's Users page: diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index c3f0c94db21..22133e30aa0 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -27,9 +27,8 @@ If you have questions or need assistance upgrading from GitLab CE to EE, ## Activate GitLab EE with an activation code In GitLab Enterprise Edition 14.1 and later, you need an activation code to activate -your instance. To get an activation code, [purchase a license](https://about.gitlab.com/pricing/) -or sign up for a [free trial](https://about.gitlab.com/free-trial/). The activation -code is a 24-character alphanumeric string you receive in a confirmation email. +your instance. To get an activation code you have to [purchase a license](https://about.gitlab.com/pricing/). +The activation code is a 24-character alphanumeric string you receive in a confirmation email. You can also sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) to copy the activation code to your clipboard. @@ -60,8 +59,10 @@ Otherwise, to upload your license: 1. On the left sidebar, select **Settings**. 1. In the **License file** area, select **Upload a license**. 1. Upload a license: - - For a file, select **Upload `.gitlab-license` file**, **Choose file**, and - select the license file from your local machine. + - For a file, either: + - Select **Upload `.gitlab-license` file**, then **Choose File** and + select the license file from your local machine. + - Drag and drop the license file to the **Drag your license file here** area. - For plain text, select **Enter license key** and paste the contents in **License key**. 1. Select the **Terms of Service** checkbox. @@ -129,6 +130,8 @@ the current date range is the active license. When you upload a future-dated license, it doesn't take effect until its applicable date. You can view all active subscriptions in the **Subscription history** table. +You can also [export](../../subscriptions/self_managed/index.md) your license usage information to a CSV file. + NOTE: In GitLab 13.6 and earlier, a banner about an expiring license may continue to display when you upload a new license. This happens when the start date of the new license diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index ee38664fa66..e8db319df77 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -208,7 +208,13 @@ Users can also be activated using the [GitLab API](../../api/users.md#activate-u ## Ban and unban users -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327353) in GitLab 14.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327353) in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ban_user_feature_flag`. Disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/330667) in GitLab 14.8. + +FLAG: +On self-managed GitLab, by default this feature is available. +To hide the feature, ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `ban_user_feature_flag`. +On GitLab.com, this feature is available to GitLab.com administrators only. GitLab administrators can ban and unban users. Banned users are blocked, and their issues are hidden. The banned user's comments are still displayed. Hiding a banned user's comments is [tracked in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/327356). diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 75905d60c4e..213bddec325 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/admin_area/reporting/spamcheck.md b/doc/user/admin_area/reporting/spamcheck.md new file mode 100644 index 00000000000..02d7cd01139 --- /dev/null +++ b/doc/user/admin_area/reporting/spamcheck.md @@ -0,0 +1,65 @@ +--- +stage: Enablement +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Spamcheck anti-spam service **(PREMIUM SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6259) in GitLab 14.8. + +[Spamcheck](https://gitlab.com/gitlab-org/spamcheck) is an anti-spam engine +developed by GitLab originally to combat rising amount of spam in GitLab.com, +and later made public to be used in self-managed GitLab instances. + +## Enable Spamcheck + +Spamcheck is only available for package-based installations: + +1. Edit `/etc/gitlab/gitlab.rb` and enable Spamcheck: + + ```ruby + spamcheck['enable'] = true + ``` + +1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Verify that the new services `spamcheck` and `spam-classifier` are + up and running: + + ```shell + sudo gitlab-ctl status + ``` + +## Configure GitLab to use Spamcheck + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Reporting**. +1. Expand **Spam and Anti-bot Protection**. +1. Update the Spam Check settings: + 1. Check the "Enable Spam Check via external API endpoint" checkbox. + 1. For **URL of the external Spam Check endpoint** use `grpc://localhost:8001`. + 1. Leave **Spam Check API key** blank. +1. Select **Save changes**. + +NOTE: +In single-node instances, Spamcehck runs over `localhost`, and hence is running +in an unauthenticated mode. If on multi-node instances where GitLab runs on one +server and Spamcheck runs on another server listening over a public endpoint, it +is recommended to enforce some sort of authentication using a reverse proxy in +front of the Spamcheck service that can be used along with an API key. One +example would be to use `JWT` authentication for this and specifying a bearer +token as the API key. +[Native authentication for Spamcheck is in the works](https://gitlab.com/gitlab-com/gl-security/engineering-and-research/automation-team/spam/spamcheck/-/issues/171). + +## Running Spamcheck over TLS + +Spamcheck service on its own can not communicate directly over TLS with GitLab. +However, Spamcheck can be deployed behind a reverse proxy which performs TLS +termination. In such a scenario, GitLab can be made to communicate with +Spamcheck over TLS by specifying `tls://` scheme for the external Spamcheck URL +instead of `grpc://` in the Admin settings. diff --git a/doc/user/admin_area/review_abuse_reports.md b/doc/user/admin_area/review_abuse_reports.md index 4c5a241ab18..ec8e6f2dda4 100644 --- a/doc/user/admin_area/review_abuse_reports.md +++ b/doc/user/admin_area/review_abuse_reports.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, 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 f748f575419..1d982196228 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -234,10 +234,14 @@ Once a lifetime for SSH keys is set, GitLab: NOTE: When a user's SSH key becomes invalid they can delete and re-add the same key again. -## Allow expired SSH keys to be used **(ULTIMATE SELF)** +## Allow expired SSH keys to be used (DEPRECATED) **(ULTIMATE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250480) in GitLab 13.9. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/320970) in GitLab 14.0. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/351963) in GitLab 14.8. + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/351963) in GitLab 14.8. By default, expired SSH keys **are not usable**. @@ -283,10 +287,14 @@ Once a lifetime for personal access tokens is set, GitLab: allowed lifetime. Three hours is given to allow administrators to change the allowed lifetime, or remove it, before revocation takes place. -## Allow expired Personal Access Tokens to be used **(ULTIMATE SELF)** +## Allow expired Personal Access Tokens to be used (DEPRECATED) **(ULTIMATE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214723) in GitLab 13.1. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/296881) in GitLab 13.9. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/351962) in GitLab 14.8. + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/351962) in GitLab 14.8. By default, expired personal access tokens (PATs) **are not usable**. diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index e18808ffb41..18379471bcf 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -197,6 +197,12 @@ To enable or disable the banner: ## Required pipeline configuration **(PREMIUM SELF)** +WARNING: +Required pipeline configurations is in its end-of-life process for Premium users. It's +[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/352316) for use in GitLab 14.8, +and planned to be unavailable for Premium users in GitLab 15.0. This feature is planned to continue +to be available for Ultimate users. Ultimate users are not impacted by this deprecation and removal. + NOTE: An alternative [compliance solution](../../project/settings/index.md#compliance-pipeline-configuration) is available. We recommend this alternative solution because it provides greater flexibility, diff --git a/doc/user/admin_area/settings/deprecated_api_rate_limits.md b/doc/user/admin_area/settings/deprecated_api_rate_limits.md index 9be703f3b82..d651e445a95 100644 --- a/doc/user/admin_area/settings/deprecated_api_rate_limits.md +++ b/doc/user/admin_area/settings/deprecated_api_rate_limits.md @@ -30,7 +30,7 @@ for deprecated API endpoints. No other new features are provided by this overrid Prerequisites: -- You must have the Administrator role for your instance. +- You must have administrator access for your instance. To override the general user and IP rate limits for requests to deprecated API endpoints: diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index 6bc9e97629c..e4fc3b6e6d4 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -56,7 +56,7 @@ To change the hostname used in private commit emails: NOTE: After the hostname is configured, every private commit email using the previous hostname is not -recognized by GitLab. This can directly conflict with certain [Push rules](../../../push_rules/push_rules.md) such as +recognized by GitLab. This can directly conflict with certain [Push rules](../../project/repository/push_rules.md) such as `Check whether author is a GitLab user` and `Check whether committer is the current authenticated user`. ## Custom additional text **(PREMIUM SELF)** diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 4fd7c59ef24..ef980981fec 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -105,7 +105,7 @@ label defined in the [global settings](#configuration) is used. The label is shown on all project pages in the upper right corner. - + <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/files_api_rate_limits.md b/doc/user/admin_area/settings/files_api_rate_limits.md index 675561ce9cf..7305e49b0d2 100644 --- a/doc/user/admin_area/settings/files_api_rate_limits.md +++ b/doc/user/admin_area/settings/files_api_rate_limits.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Files API rate limits **(FREE SELF)** +# Rate limits on Repository files API **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68561) in GitLab 14.3. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75918) in GitLab 14.6. [Feature flag files_api_throttling](https://gitlab.com/gitlab-org/gitlab/-/issues/338903) removed. @@ -26,7 +26,7 @@ for the Files API. No other new features are provided by this override. Prerequisite: -- You must have the Administrator role for your instance. +- You must have administrator access for your instance. To override the general user and IP rate limits for requests to the Repository files API: diff --git a/doc/user/admin_area/settings/git_lfs_rate_limits.md b/doc/user/admin_area/settings/git_lfs_rate_limits.md index adc6cc2b11b..c10300baeef 100644 --- a/doc/user/admin_area/settings/git_lfs_rate_limits.md +++ b/doc/user/admin_area/settings/git_lfs_rate_limits.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Git LFS Rate Limits **(FREE SELF)** +# Rate limits on Git LFS **(FREE SELF)** [Git LFS (Large File Storage)](../../../topics/git/lfs/index.md) is a Git extension for handling large files. If you use Git LFS in your repository, common Git operations diff --git a/doc/user/admin_area/settings/img/classification_label_on_project_page.png b/doc/user/admin_area/settings/img/classification_label_on_project_page.png Binary files differdeleted file mode 100644 index 4aedb332cec..00000000000 --- a/doc/user/admin_area/settings/img/classification_label_on_project_page.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/classification_label_on_project_page_v14_8.png b/doc/user/admin_area/settings/img/classification_label_on_project_page_v14_8.png Binary files differnew file mode 100644 index 00000000000..4bd2e7d389b --- /dev/null +++ b/doc/user/admin_area/settings/img/classification_label_on_project_page_v14_8.png diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 2820f3ae9df..a581fd4aebc 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -137,6 +137,7 @@ The **Network** settings contain: - [Incident Management Limits](../../../operations/incident_management/index.md) - Limit the number of inbound alerts that can be sent to a project. - [Notes creation limit](rate_limit_on_notes_creation.md) - Set a rate limit on the note creation requests. +- [Get single user limit](rate_limit_on_users_api.md) - Set a rate limit on users API endpoint to get a user by ID. ### Preferences @@ -160,7 +161,7 @@ The **Preferences** settings contain: The **Reporting** settings contain: - [Spam and Anti-bot Protection](../../../integration/recaptcha.md) - - Enable anti-spam services, like reCAPTCHA or Akismet, and set IP limits. + Enable anti-spam services, like reCAPTCHA, Akismet or [Spamcheck](../reporting/spamcheck.md), and set IP limits. - [Abuse reports](../review_abuse_reports.md) - Set notification email for abuse reports. ### Repository diff --git a/doc/user/admin_area/settings/rate_limit_on_users_api.md b/doc/user/admin_area/settings/rate_limit_on_users_api.md new file mode 100644 index 00000000000..7954055f38b --- /dev/null +++ b/doc/user/admin_area/settings/rate_limit_on_users_api.md @@ -0,0 +1,33 @@ +--- +type: reference +stage: Manage +group: Authentication & Authorization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Rate limits on Users API **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78364) in GitLab 14.8. + +You can configure the per user rate limit for requests to [Users API](../../../api/users.md). + +To change the rate limit: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**. +1. Expand **Users API rate limit**. +1. In the **Maximum requests per 10 minutes** text box, enter the new value. +1. Optional. In the **Users to exclude from the rate limit** box, list users allowed to exceed the limit. +1. Select **Save changes**. + +This limit is: + +- Applied independently per user. +- Not applied per IP address. + +The default value is `300`. + +Requests over the rate limit are logged into the `auth.log` file. + +For example, if you set a limit of 300, requests to the `GET /users/:id` API endpoint +exceeding a rate of 300 per 10 minutes are blocked. Access to the endpoint is allowed after ten minutes have elapsed. diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 52b20d5b437..c63cd88eeb4 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -38,7 +38,7 @@ they do not have access to all projects, groups, or the **Admin Area** menu. To access potentially dangerous resources, an administrator can activate Admin Mode by: - Selecting the *Enable Admin Mode* button -- Trying to access any part of the UI that requires an administrator role, specifically those which call `/admin` endpoints. +- Trying to access any part of the UI that requires administrator access, specifically those which call `/admin` endpoints. The main use case allows administrators to perform their regular tasks as a regular user, based on their memberships, without having to set up a second account for 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 d713ef4b4e0..88be73c3215 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 @@ -22,6 +22,11 @@ NOTE: By default, all Git operations are first tried unauthenticated. Because of this, HTTP Git operations may trigger the rate limits configured for unauthenticated requests. +NOTE: +[In GitLab 14.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/344807), +the rate limits for API requests don't affect requests made by the frontend, as these are always +counted as web traffic. + ## Enable unauthenticated API request rate limit To enable the unauthenticated request rate limit: 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 82e0d3d27d4..c38b2455a8d 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -7,12 +7,12 @@ type: reference # Control access and visibility **(FREE SELF)** -GitLab enables users with the [Administrator role](../../permissions.md) to enforce +GitLab enables users with administrator access to enforce specific controls on branches, projects, snippets, groups, and more. To access the visibility and access control options: -1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. Sign in to GitLab as a user with Administrator access level. 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. @@ -29,7 +29,7 @@ or configure [branch protection for groups](../../group/index.md#change-the-defa To change the default branch protection for the entire instance: -1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. Sign in to GitLab as a user with Administrator access level. 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. @@ -55,7 +55,7 @@ can be overridden on a per-group basis by the group's owner. In [GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can disable this privilege for group owners, enforcing the instance-level protection rule: -1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. Sign in to GitLab as a user with Administrator access level. 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. @@ -71,7 +71,7 @@ Instance-level protections for project creation define which roles can [add projects to a group](../../group/index.md#specify-who-can-add-projects-to-a-group) on the instance. To alter which roles have permission to create projects: -1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. Sign in to GitLab as a user with Administrator access level. 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. @@ -84,9 +84,9 @@ on the instance. To alter which roles have permission to create projects: ## Restrict project deletion to Administrators **(PREMIUM SELF)** Anyone with the **Owner** role, either at the project or group level, can -delete a project. To allow only users with the Administrator role to delete projects: +delete a project. To allow only users with administrator access to delete projects: -1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. Sign in to GitLab as a user with Administrator access level. 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. @@ -137,7 +137,7 @@ Alternatively, projects that are marked for removal can be deleted immediately. To set the default [visibility levels for new projects](../../../public_access/public_access.md): -1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. Sign in to GitLab as a user with Administrator access level. 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. @@ -152,7 +152,7 @@ To set the default [visibility levels for new projects](../../../public_access/p To set the default visibility levels for new [snippets](../../snippets.md): -1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. Sign in to GitLab as a user with Administrator access level. 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. @@ -166,7 +166,7 @@ For more details on snippet visibility, read To set the default visibility levels for new groups: -1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. Sign in to GitLab as a user with Administrator access level. 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. @@ -183,7 +183,7 @@ For more details on group visibility, see To restrict visibility levels for projects, snippets, and selected pages: -1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. Sign in to GitLab as a user with Administrator access level. 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. @@ -200,7 +200,7 @@ For more details on project visibility, see You can specify from which hosting sites users can [import their projects](../../project/import/index.md): -1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. Sign in to GitLab as a user with Administrator access level. 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. @@ -212,7 +212,7 @@ You can specify from which hosting sites users can [import their projects](../.. To enable the export of [projects and their data](../../../user/project/settings/import_export.md#export-a-project-and-its-data): -1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. Sign in to GitLab as a user with Administrator access level. 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. @@ -228,7 +228,7 @@ The GitLab restrictions apply at the application level. To specify the enabled Git access protocols: -1. Sign in to GitLab as a user with [Administrator role](../../permissions.md). +1. Sign in to GitLab as a user with Administrator access level. 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. @@ -280,7 +280,7 @@ NOTE: SSH clone URLs can be customized in `gitlab.rb` by setting `gitlab_rails['gitlab_ssh_host']` and other related settings. -## Configure defaults for RSA, DSA, ECDSA, ED25519 SSH keys +## Configure defaults for RSA, DSA, ECDSA, ED25519, ECDSA_SK, ED25519_SK SSH keys These options specify the permitted types and lengths for SSH keys. diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index 066b45aeb39..18a6ca20bc7 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -17,7 +17,7 @@ requests, and: - Take action on individual merge requests. - Reduce overall cycle time. -Code Review Analytics is available to users with at least the Reporter [role](../permissions.md), and displays a table of open merge requests that have at least one non-author comment. The review time is measured from the time the first non-author comment was submitted. +Code Review Analytics is available to users with at least the Reporter role, and displays a table of open merge requests that have at least one non-author comment. The review time is measured from the time the first non-author comment was submitted. NOTE: Initially, no data appears. Data is populated as users comment on open merge requests. diff --git a/doc/user/analytics/img/issues_created_per_month_v13_11.png b/doc/user/analytics/img/issues_created_per_month_v13_11.png Binary files differdeleted file mode 100644 index da3340bfdc2..00000000000 --- a/doc/user/analytics/img/issues_created_per_month_v13_11.png +++ /dev/null diff --git a/doc/user/analytics/img/issues_created_per_month_v14_8.png b/doc/user/analytics/img/issues_created_per_month_v14_8.png Binary files differnew file mode 100644 index 00000000000..7dcfa73ea19 --- /dev/null +++ b/doc/user/analytics/img/issues_created_per_month_v14_8.png diff --git a/doc/user/analytics/img/mr_mean_time_to_merge_metric_v13_9.png b/doc/user/analytics/img/mr_mean_time_to_merge_metric_v13_9.png Binary files differdeleted file mode 100644 index ad108dabf73..00000000000 --- a/doc/user/analytics/img/mr_mean_time_to_merge_metric_v13_9.png +++ /dev/null diff --git a/doc/user/analytics/img/mr_throughput_table_v13_3.png b/doc/user/analytics/img/mr_throughput_table_v13_3.png Binary files differdeleted file mode 100644 index bb63770dc3f..00000000000 --- a/doc/user/analytics/img/mr_throughput_table_v13_3.png +++ /dev/null diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md index 6aa2f594532..62fff443073 100644 --- a/doc/user/analytics/issue_analytics.md +++ b/doc/user/analytics/issue_analytics.md @@ -34,7 +34,7 @@ You can change the total number of months displayed by setting a URL parameter. For example, `https://gitlab.com/groups/gitlab-org/-/issues_analytics?months_back=15` shows a total of 15 months for the chart in the GitLab.org group. - + ## Drill into the information diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index bb110ab495f..f9ca06c0ef9 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -1,119 +1,66 @@ --- -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. +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: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Merge Request Analytics **(PREMIUM)** +# Merge request analytics **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229045) in GitLab 13.3. > - Moved to GitLab Premium in 13.9. -Merge Request Analytics helps you understand the efficiency of your code review process, and the productivity of your team. +Use merge request analytics to view: -## Overview +- The number of merge requests your organization merged per month. +- The average time between merge request creation and merge. +- Information about each merged merge request. -Merge Request Analytics displays information that will help you evaluate the efficiency and productivity of your merge request process. +You can use merge request analytics to identify: -The Throughput chart shows the number of merge requests merged, by month. Merge request throughput is -a common measure of productivity in software engineering. Although imperfect, the average throughput can -be a meaningful benchmark of your team's overall productivity. +- Low or high productivity months. +- Efficiency and productivity of your merge request process. +- Efficiency of your code review process. -To access Merge Request Analytics: +## View merge request analytics + +You must have at least the Reporter role to view merge request analytics. + +To view merge request analytics: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Merge request**. -## Use cases +## View merge requests merged per month -This feature is designed for [development team leaders](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#delaney-development-team-lead) -and others who want to understand broad patterns in code review and productivity. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232651) in GitLab 13.3. +> - Filtering [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229266) in GitLab 13.4 -You can use Merge Request Analytics to expose when your team is most and least productive, and -identify improvements that might substantially accelerate your development cycle. +To view the number of merge requests merged per month: -Merge Request Analytics could be used when: - -- You want to know if you were more productive this month than last month, or 12 months ago. -- You want to drill into low- or high-productivity months to understand the work that took place. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Merge request**. +1. Optional. Filter results: + 1. Select the filter bar. + 1. Select a parameter. + 1. Select a value or enter text to refine the results. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. -## Visualizations and data +The **Throughput** chart shows the number of merge requests merged per month. -The following visualizations and data are available, representing all merge requests that were merged in the given date range. +The table shows up to 20 merge requests per page, and includes +information about each merge request. -### Mean time to merge +## View average time between merge request creation and merge > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229389) in GitLab 13.9. -The mean time to merge (MTTM) metric shows the average time between when a merge request is created, -and when it is merged. To view how the MTTM changes over time, compare MTTM across different date ranges. - - - -### Throughput chart - -The throughput chart shows the number of merge requests merged per month. - - - -### Throughput table - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232651) in GitLab 13.3. - -The Throughput table displays the most recent merge requests merged in the date range. The -table displays up to 20 merge requests at a time. If there are more than 20 merge requests, -you can paginate to them. For each merge request, you can review the following data: - -- Title (as a link to the merge request itself) -- ID -- Pipeline status -- Label count -- Comment count -- Approval count (if approved) -- Date merged -- Time to merge -- Milestone -- Commit count -- Pipeline count -- Line change counts -- Assignees - - +Use the number in **Mean time to merge** to view the average time between when a merge request is +created and when it's merged. -## Filter the data +To view **Mean time to merge**: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229266) in GitLab 13.4 - -You can filter the data that is presented on the page based on the following parameters: - -- Author -- Assignee -- Label -- Milestone -- Source branch -- Target branch - -To filter results: - -1. Select the filter bar. -1. Select a parameter to filter by. -1. Select a value from the autocompleted results, or enter search text to refine the results. -1. Press Enter. - -## Date range - -The date range is set to the past 12 months by default. You can modify the date range by changing the "From" and/or "To" values that appear alongside the filter bar. After changing either value, the data displayed on the page will update automatically. - -## Tip: Bookmark preferred settings - -You can bookmark preferred filters and date ranges. After you have applied a change to the -filter bar or the date range, you'll see that information in the URL. You can create a -bookmark for those preferred settings in your browser. - -## Permissions - -The **Merge Request Analytics** feature can be accessed only: - -- On [GitLab Premium](https://about.gitlab.com/pricing/) and above. -- By users with at least the Reporter [role](../permissions.md). +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Merge request**. diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md index e1ba2f5565e..be710f8cbd7 100644 --- a/doc/user/analytics/productivity_analytics.md +++ b/doc/user/analytics/productivity_analytics.md @@ -65,7 +65,7 @@ request is merged. Select the dropdown to view: The right-side histogram shows the size or complexity of a merge request. Select the dropdown to view: - + - Number of commits per merge request. - Number of lines of code (LOC) per commit. - Number of files touched. @@ -103,4 +103,4 @@ You can filter analytics based on a date range. To filter results: The **Productivity Analytics** dashboard can be accessed only: - On [GitLab Premium](https://about.gitlab.com/pricing/) and above. -- By users with at least the Reporter [role](../permissions.md). +- By users with at least the Reporter role. diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index be6b06a0797..4eb721f8832 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -114,6 +114,7 @@ To generate an API Fuzzing configuration snippet: > - Support for OpenAPI Specification v3.0 was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228652) in GitLab 13.9. > - Support for OpenAPI Specification using YAML format was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330583) in GitLab 14.0. > - Support for OpenAPI Specification v3.1 was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327268) in GitLab 14.2. +> - Support to generate media type `application/xml` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327268) in GitLab 14.8. The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an API description format for REST APIs. This section shows you how to configure API fuzzing using an OpenAPI Specification to provide information about the target API to test. @@ -125,6 +126,7 @@ the body generation is limited to these body types: - `application/x-www-form-urlencoded` - `multipart/form-data` - `application/json` +- `application/xml` #### Configure Web API fuzzing with an OpenAPI Specification @@ -459,7 +461,7 @@ Follow these steps to provide the bearer token with `FUZZAPI_OVERRIDES_ENV`: ``` 1. To validate that authentication is working, run an API fuzzing test and review the fuzzing logs - and the test API's application logs. + and the test API's application logs. See the [overrides section](#overrides) for more information about override commands. ##### Token generated at test runtime @@ -493,7 +495,7 @@ variables: FUZZAPI_PROFILE: Quick FUZZAPI_OPENAPI: test-api-specification.json FUZZAPI_TARGET_URL: http://test-deployment/ - FUZZAPI_OVERRIDES_FILE: output/api-fuzzing-overrides.json + FUZZAPI_OVERRIDES_FILE: api-fuzzing-overrides.json ``` To validate that authentication is working, run an API fuzzing test and review the fuzzing logs and @@ -535,7 +537,7 @@ variables: FUZZAPI_PROFILE: Quick-10 FUZZAPI_OPENAPI: test-api-specification.json FUZZAPI_TARGET_URL: http://test-deployment/ - FUZZAPI_OVERRIDES_FILE: output/api-fuzzing-overrides.json + FUZZAPI_OVERRIDES_FILE: api-fuzzing-overrides.json FUZZAPI_OVERRIDES_CMD: renew_token.py FUZZAPI_OVERRIDES_INTERVAL: 300 ``` @@ -575,6 +577,9 @@ profile increases as the number of tests increases. |[`FUZZAPI_OVERRIDES_FILE`](#overrides) | Path to a JSON file containing overrides. | |[`FUZZAPI_OVERRIDES_ENV`](#overrides) | JSON string containing headers to override. | |[`FUZZAPI_OVERRIDES_CMD`](#overrides) | Overrides command. | +|[`FUZZAPI_OVERRIDES_CMD_VERBOSE`](#overrides) | When set to any value. It shows overrides command output as part of the job output. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334578) in GitLab 14.8. | +|`FUZZAPI_PRE_SCRIPT` | Run user command or script before scan session starts. | +|`FUZZAPI_POST_SCRIPT` | Run user command or script after scan session has finished. | |[`FUZZAPI_OVERRIDES_INTERVAL`](#overrides) | How often to run overrides command in seconds. Defaults to `0` (once). | |[`FUZZAPI_HTTP_USERNAME`](#http-basic-authentication) | Username for HTTP authentication. | |[`FUZZAPI_HTTP_PASSWORD`](#http-basic-authentication) | Password for HTTP authentication. | @@ -754,7 +759,7 @@ variables: FUZZAPI_PROFILE: Quick FUZZAPI_OPENAPI: test-api-specification.json FUZZAPI_TARGET_URL: http://test-deployment/ - FUZZAPI_OVERRIDES_FILE: output/api-fuzzing-overrides.json + FUZZAPI_OVERRIDES_FILE: api-fuzzing-overrides.json ``` #### Using a CI/CD variable @@ -799,16 +804,181 @@ variables: If the value must be generated or regenerated on expiration, you can provide a program or script for the API fuzzer to execute on a specified interval. The provided script runs in an Alpine Linux -container that has Python 3 and Bash installed. If the Python script requires additional packages, -it must detect this and install the packages at runtime. The script creates the overrides JSON file -as defined above. +container that has Python 3 and Bash installed. + +You have to set the environment variable `FUZZAPI_OVERRIDES_CMD` to the program or script you would like +to execute. The provided command creates the overrides JSON file as defined previously. + +You might want to install other scripting runtimes like NodeJS or Ruby, or maybe you need to install a dependency for +your overrides command. In this case, we recommend setting the `FUZZAPI_PRE_SCRIPT` to the file path of a script which +provides those prerequisites. The script provided by `FUZZAPI_PRE_SCRIPT` is executed once, before the analyzer starts. + +See the [Alpine Linux package management](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management) +page for information about installing Alpine Linux packages. You must provide three CI/CD variables, each set for correct operation: - `FUZZAPI_OVERRIDES_FILE`: File generated by the provided command. -- `FUZZAPI_OVERRIDES_CMD`: Command to generate JSON file. +- `FUZZAPI_OVERRIDES_CMD`: Overrides command in charge of generating the overrides JSON file periodically. - `FUZZAPI_OVERRIDES_INTERVAL`: Interval in seconds to run command. +Optionally: + +- `FUZZAPI_PRE_SCRIPT`: Script to install runtimes or dependencies before the analyzer starts. + +```yaml +stages: + - fuzz + +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OVERRIDES_FILE: api-fuzzing-overrides.json + FUZZAPI_OVERRIDES_CMD: renew_token.py + FUZZAPI_OVERRIDES_INTERVAL: 300 +``` + +#### Debugging overrides + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334578) in GitLab 14.8. + +By default the output of the overrides command is hidden. If the overrides command returns a non zero exit code, the command is displayed as part of your job output. Optionally, you can set the variable `FUZZAPI_OVERRIDES_CMD_VERBOSE` to any value in order to display overrides command output as it is generated. This is useful when testing your overrides script, but should be disabled afterwards as it slows down testing. + +It is also possible to write messages from your script to a log file that is collected when the job completes or fails. The log file must be created in a specific location and follow a naming convention. + +Adding some basic logging to your overrides script is useful in case the script fails unexpectedly during normal running of the job. The log file is automatically included as an artifact of the job, allowing you to download it after the job has finished. + +Following our example, we provided `renew_token.py` in the environmental variable `FUZZAPI_OVERRIDES_CMD`. Please notice two things in the script: + +- Log file is saved in the location indicated by the environment variable `CI_PROJECT_DIR`. +- Log file name should match `gl-*.log`. + +```python +#!/usr/bin/env python + +# Example of an overrides command + +# Override commands can update the overrides json file +# with new values to be used. This is a great way to +# update an authentication token that will expire +# during testing. + +import logging +import json +import os +import requests +import backoff + +# [1] Store log file in directory indicated by env var CI_PROJECT_DIR +working_directory = os.environ['CI_PROJECT_DIR'] + +# [2] File name should match the pattern: gl-*.log +log_file_path = os.path.join(working_directory, 'gl-user-overrides.log') + +# Set up logger +logging.basicConfig(filename=log_file_path, level=logging.DEBUG) + +# Use `backoff` decorator to retry in case of transient errors. +@backoff.on_exception(backoff.expo, + (requests.exceptions.Timeout, + requests.exceptions.ConnectionError), + max_time=30) +def get_auth_response(): + return requests.get('https://authorization.service/api/get_api_token', auth=(os.environ['AUTH_USER'], os.environ['AUTH_PWD'])) + + +# In our example, access token is retrieved from a given endpoint +try: + + # Performs a http request, response sample: + # { "Token" : "b5638ae7-6e77-4585-b035-7d9de2e3f6b3" } + response = get_auth_response() + + # Check that the request is successful. may raise `requests.exceptions.HTTPError` + response.raise_for_status() + + # Gets JSON data + response_body = response.json() + +# If needed specific exceptions can be caught +# requests.ConnectionError : A network connection error problem occurred +# requests.HTTPError : HTTP request returned an unsuccessful status code. [Response.raise_for_status()] +# requests.ConnectTimeout : The request timed out while trying to connect to the remote server +# requests.ReadTimeout : The server did not send any data in the allotted amount of time. +# requests.TooManyRedirects : The request exceeds the configured number of maximum redirections +# requests.exceptions.RequestException : All exceptions that related to Requests +except requests.exceptions.RequestException as requests_error: + # logs exceptions related to `Requests` + logging.error(f'Error, failed while performing HTTP request. Error message: {requests_error}') + raise +except requests.exceptions.JSONDecodeError as json_decode_error: + # logs errors related decoding JSON response + logging.error(f'Error, failed while decoding JSON response. Error message: {json_decode_error}') + raise +except Exception as e: + # logs any other error + logging.error(f'Error, unknown error while retrieving access token. Error message: {e}') + raise + +# computes object that holds overrides file content. +# It uses data fetched from request +overrides_data = { + "headers": { + "Authorization": f"Token {response_body['Token']}" + } +} + +# log entry informing about the file override computation +overrides_file_path = os.path.join( + working_directory, "api-fuzzing-overrides.json") +logging.info("Creating overrides file: %s" % overrides_file_path) + +# attempts to overwrite the file +try: + if os.path.exists(overrides_file_path): + os.unlink(overrides_file_path) + + # overwrites the file with our updated dictionary + with open(overrides_file_path, "wb+") as fd: + fd.write(json.dumps(overrides_data).encode('utf-8')) +except Exception as e: + # logs any other error + logging.error(f'Error, unkown error when overwritng file {overrides_file_path}. Error message: {e}') + raise + +# logs informing override has finished successfully +logging.info("Override file has been updated") + +# end +``` + +In the overrides command example, the Python script depends on the `backoff` library. To make sure the library is installed before executing the Python script, the `FUZZAPI_PRE_SCRIPT` is set to a script that will install the dependencies of your overrides command. +As for example, the following script `user-pre-scan-set-up.sh`: + +```shell +#!/bin/bash + +# user-pre-scan-set-up.sh +# Ensures python dependencies are installed + +echo "**** install python dependencies ****" + +python3 -m ensurepip +pip3 install --no-cache --upgrade \ + pip \ + backoff + +echo "**** python dependencies installed ****" + +# end +``` + +You have to update your configuration to set the `FUZZAPI_PRE_SCRIPT` to our new `user-pre-scan-set-up.sh` script. For example: + ```yaml stages: - fuzz @@ -820,11 +990,14 @@ variables: FUZZAPI_PROFILE: Quick FUZZAPI_OPENAPI: test-api-specification.json FUZZAPI_TARGET_URL: http://test-deployment/ - FUZZAPI_OVERRIDES_FILE: output/api-fuzzing-overrides.json + FUZZAPI_PRE_SCRIPT: user-pre-scan-set-up.sh + FUZZAPI_OVERRIDES_FILE: api-fuzzing-overrides.json FUZZAPI_OVERRIDES_CMD: renew_token.py FUZZAPI_OVERRIDES_INTERVAL: 300 ``` +In the previous sample, you could use the script `user-pre-scan-set-up.sh` to also install new runtimes or applications that later on you could use in your overrides command. + ### Exclude Paths > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211892) in GitLab 14.0. diff --git a/doc/user/application_security/cluster_image_scanning/index.md b/doc/user/application_security/cluster_image_scanning/index.md index 5f2dd626526..0db9af7a0d3 100644 --- a/doc/user/application_security/cluster_image_scanning/index.md +++ b/doc/user/application_security/cluster_image_scanning/index.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/) in GitLab 14.1. WARNING: -This analyzer is in [Alpha](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) +This analyzer is in [Alpha](../../../policy/alpha-beta-support.md#alpha-features) and is unstable. The JSON report and CI/CD configuration may be subject to change or breakage across GitLab releases. @@ -301,7 +301,9 @@ the security vulnerabilities in your groups, projects, and pipelines. ## Interacting with the vulnerabilities -After a vulnerability is found, you can [address it](../vulnerabilities/index.md). +After you find a vulnerability, you can address it in the [vulnerability report](../vulnerabilities/index.md) +or the [GitLab Agent's](../../clusters/agent/install/index.md#view-vulnerabilities-in-cluster-images) +details section. ## Troubleshooting diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index cdcd334dba6..430f8e1a2a2 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -58,11 +58,11 @@ You can configure the following security controls: - [API Fuzzing](../api_fuzzing/index.md) - Select **Enable API Fuzzing** to use API Fuzzing for the current project. For more details, read [API Fuzzing](../../../user/application_security/api_fuzzing/index.md#enable-web-api-fuzzing). - [Coverage Fuzzing](../coverage_fuzzing/index.md) - - Can be configured with `.gitlab-ci.yml`. For more details, read [Coverage Fuzzing](../../../user/application_security/coverage_fuzzing/index.md#configuration). + - Can be configured with `.gitlab-ci.yml`. For more details, read [Coverage Fuzzing](../../../user/application_security/coverage_fuzzing/index.md#enable-coverage-guided-fuzz-testing). ## Compliance **(ULTIMATE)** You can configure the following security controls: - [License Compliance](../../../user/compliance/license_compliance/index.md) - - Can be configured with `.gitlab-ci.yml`. For more details, read [License Compliance](../../../user/compliance/license_compliance/index.md#configuration). + - Can be configured with `.gitlab-ci.yml`. For more details, read [License Compliance](../../../user/compliance/license_compliance/index.md#enable-license-compliance). diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 5a2dd5eb54f..08a8c46cc72 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -222,6 +222,7 @@ You can [configure](#customizing-the-container-scanning-settings) analyzers by u | `CS_DISABLE_DEPENDENCY_LIST` | `"false"` | Disable Dependency Scanning for packages installed in the scanned image. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. | All | | `CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` | `"true"` | Disable scanning for language-specific packages installed in the scanned image. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. | All | | `CS_DOCKER_INSECURE` | `"false"` | Allow access to secure Docker registries using HTTPS without validating the certificates. | All | +| `CS_IGNORE_UNFIXED` | `"false"` | Ignore vulnerabilities that are not fixed. | All | | `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. Works with all scanners, but the registry must listen on port `80/tcp` for Trivy to work. | All | | `CS_SEVERITY_THRESHOLD` | `UNKNOWN` | Severity level threshold. The scanner outputs vulnerabilities with severity level higher than or equal to this threshold. Supported levels are Unknown, Low, Medium, High, and Critical. | Trivy | | `DOCKER_IMAGE` | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | The Docker image to be scanned. If set, this variable overrides the `$CI_APPLICATION_REPOSITORY` and `$CI_APPLICATION_TAG` variables. | All | @@ -513,7 +514,7 @@ registry.gitlab.com/security-products/container-scanning/trivy:4 The process for importing Docker images into a local offline Docker registry depends on **your network security policy**. Please consult your IT staff to find an accepted and approved process by which you can import or temporarily access external resources. These scanners -are [periodically updated](../vulnerabilities/index.md#vulnerability-scanner-maintenance), +are [periodically updated](../index.md#vulnerability-scanner-maintenance), and you may be able to make occasional updates on your own. For more information, see [the specific steps on how to update an image with a pipeline](#automating-container-scanning-vulnerability-database-updates-with-a-pipeline). @@ -728,8 +729,16 @@ the security vulnerabilities in your groups, projects and pipelines. ## Vulnerabilities database update -If you use container scanning and want more information about the vulnerabilities database update, -see the [maintenance table](../vulnerabilities/index.md#vulnerability-scanner-maintenance). +All analyzer images are [updated daily](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/-/blob/master/README.md#image-updates). + +The images include the latest advisory database available for their respective scanner. Each +scanner includes data from multiple sources: + +- [Grype](https://github.com/anchore/grype#grypes-database). +- [Trivy](https://aquasecurity.github.io/trivy/latest/vulnerability/detection/data-source/). + +Database update information for other analyzers is available in the +[maintenance table](../index.md#vulnerability-scanner-maintenance). ## Interacting with the vulnerabilities diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 89b4cdcc34d..290d4a06dcc 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -2,7 +2,6 @@ stage: Secure group: Dynamic Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, howto --- # Coverage-guided fuzz testing **(ULTIMATE)** @@ -23,8 +22,14 @@ The fuzz testing process: 1. Compiles the target application. 1. Runs the instrumented application, using the `gitlab-cov-fuzz` tool. 1. Parses and analyzes the exception information output by the fuzzer. -1. Downloads the [corpus](../terminology/index.md#corpus) and crash events from previous pipelines. +1. Downloads the [corpus](../terminology/index.md#corpus) from either: + - The previous pipelines. + - If `COVFUZZ_USE_REGISTRY` is set to `true`, the [corpus registry](#corpus-registry). +1. Downloads crash events from previous pipeline. 1. Outputs the parsed crash events and data to the `gl-coverage-fuzzing-report.json` file. +1. Updates the corpus, either: + - In the job's pipeline. + - If `COVFUZZ_USE_REGISTRY` is set to `true`, in the corpus registry. The results of the coverage-guided fuzz testing are available in the CI/CD pipeline. @@ -44,9 +49,20 @@ You can use the following fuzzing engines to test the specified languages. | Python | [`pythonfuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/pythonfuzz) | [pythonfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/pythonfuzz-fuzzing-example) | | AFL (any language that works on top of AFL) | [AFL](https://lcamtuf.coredump.cx/afl/) | [afl-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/afl-fuzzing-example) | -## Configuration +## Confirm status of coverage-guided fuzz testing -To enable coverage-guided fuzz testing, edit the `.gitlab-ci.yml` file: +To confirm the status of coverage-guided fuzz testing: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. +1. In the **Coverage Fuzzing** section the status is: + - **Not configured** + - **Enabled** + - A prompt to upgrade to GitLab Ultimate. + +## Enable coverage-guided fuzz testing + +To enable coverage-guided fuzz testing, edit `.gitlab-ci.yml`: 1. Add the `fuzz` stage to the list of stages. @@ -99,10 +115,13 @@ Use the following variables to configure coverage-guided fuzz testing in your CI | CI/CD variable | Description | |---------------------------|---------------------------------------------------------------------------------| -| `COVFUZZ_ADDITIONAL_ARGS` | Arguments passed to `gitlab-cov-fuzz`. Used to customize the behavior of the underlying fuzzing engine. Read the fuzzing engine's documentation for a complete list of arguments. | +| `COVFUZZ_ADDITIONAL_ARGS` | Arguments passed to `gitlab-cov-fuzz`. Used to customize the behavior of the underlying fuzzing engine. Read the fuzzing engine's documentation for a complete list of arguments. | | `COVFUZZ_BRANCH` | The branch on which long-running fuzzing jobs are to be run. On all other branches, only fuzzing regression tests are run. Default: Repository's default branch. | | `COVFUZZ_SEED_CORPUS` | Path to a seed corpus directory. Default: empty. | | `COVFUZZ_URL_PREFIX` | Path to the `gitlab-cov-fuzz` repository cloned for use with an offline environment. You should only change this value when using an offline environment. Default: `https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz/-/raw`. | +| `COVFUZZ_USE_REGISTRY` | Set to `true` to have the corpus stored in the GitLab corpus registry. The variables `COVFUZZ_CORPUS_NAME` and `COVFUZZ_GITLAB_TOKEN` are required if this variable is set to `true`. Default: `false`. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5017) in GitLab 14.8. | +| `COVFUZZ_CORPUS_NAME` | Name of the corpus to be used in the job. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5017) in GitLab 14.8. | +| `COVFUZZ_GITLAB_TOKEN` | Environment variable configured with [Personal Access Token](../../../user/profile/personal_access_tokens.md#create-a-personal-access-token) with API read/write access. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5017) in GitLab 14.8. | #### Seed corpus @@ -123,9 +142,93 @@ Each fuzzing step outputs these artifacts: You can download the JSON report file from the CI/CD pipelines page. For more information, see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). -### Coverage-guided fuzz testing report +## Corpus registry + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5017) in GitLab 14.8. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, ask an +administrator to [disable the feature flags](../../../administration/feature_flags.md) named +`corpus_management` and `corpus_management_ui`. On GitLab.com, this feature is available. + +The corpus registry is a library of corpuses. Corpuses in a project's registry are available to +all jobs in that project. A project-wide registry is a more efficient way to manage corpuses than +the default option of one corpus per job. + +The corpus registry uses the package registry to store the project's corpuses. Corpuses stored in +the registry are hidden to ensure data integrity. + +In the GitLab UI, with corpus management you can: + +- View details of the corpus registry. +- Download a corpus. +- Delete a corpus. +- Create a new corpus. + +When you download a corpus, the file is named `artifacts.zip`, regardless of the filename used when +the corpus was initially uploaded. This file contains only the corpus, which is different to the +artifacts files you can download from the CI/CD pipeline. + +### View details of the corpus registry + +To view details of the corpus registry: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. +1. In the **Coverage Fuzzing** section, select **Manage corpus**. + +### Create a corpus in the corpus registry + +To create a corpus in the corpus registry, either: + +- Create a corpus in a pipeline +- Upload an existing corpus file + +#### Create a corpus in a pipeline + +To create a corpus in a pipeline: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220062) in GitLab 13.3 as an [Alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). +1. In the `.gitlab-ci.yml` file, edit the `my_fuzz_target` job. +1. Set the following variables: + - Set `COVFUZZ_USE_REGISTRY` to `true`. + - Set `COVFUZZ_CORPUS_NAME` to name the corpus. + - Set `COVFUZZ_GITLAB_TOKEN` to the value of the personal access token. + +After the `my_fuzz_target` job runs, the corpus is stored in the corpus registry, with the name +provided by the `COVFUZZ_CORPUS_NAME` variable. The corpus is updated on every pipeline run. + +#### Upload a corpus file + +To upload an existing corpus file: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. +1. In the **Coverage Fuzzing** section, select **Manage corpus**. +1. Select **New corpus**. +1. Complete the fields. +1. Select **Upload file**. +1. Select **Add**. + +You can now reference the corpus in the `.gitlab-ci.yml` file. Ensure the value used in the +`COVFUZZ_CORPUS_NAME` variable matches exactly the name given to the uploaded corpus file. + +### Use a corpus stored in the corpus registry + +To use a corpus stored in the corpus registry, you must reference it by its name. To confirm the +name of the relevant corpus, view details of the corpus registry. + +Prerequisites: + +- [Enable coverage-guide fuzz testing](#enable-coverage-guided-fuzz-testing) in the project. + +1. Set the following variables in the `.gitlab-ci.yml` file: + - Set `COVFUZZ_USE_REGISTRY` to `true`. + - Set `COVFUZZ_CORPUS_NAME` to the name of the corpus. + - Set `COVFUZZ_GITLAB_TOKEN` to the value of the personal access token. + +## Coverage-guided fuzz testing report + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220062) in GitLab 13.3 as an [Alpha feature](../../../policy/alpha-beta-support.md#alpha-features). For detailed information about the `gl-coverage-fuzzing-report.json` file's format, read the [schema](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/coverage-fuzzing-report-format.json). @@ -161,9 +264,9 @@ Example coverage-guided fuzzing report: ## Duration of coverage-guided fuzz testing -The available durations for coverage-guided fuzz testing are: 10 minutes (default) and 60 minutes. +The available durations for coverage-guided fuzz testing are: -- 10-minute duration: Recommended for the default branch. +- 10-minute duration (default): Recommended for the default branch. - 60-minute duration: Recommended for the development branch and merge requests. The longer duration provides greater coverage. In the `COVFUZZ_ADDITIONAL_ARGS` variable set the value `--regression=true`. @@ -256,3 +359,16 @@ vulnerability: engines listed in [Supported fuzzing engines and languages](#supported-fuzzing-engines-and-languages). <!-- vale gitlab.Acronyms = YES --> + +## Troubleshooting + +### Error "Unable to extract corpus folder from artifacts zip file" + +If you see this error message, and `COVFUZZ_USE_REGISTRY` is set to `true`, ensure that the uploaded +corpus file extracts into a folder named `corpus`. + +### Error "400 Bad request - Duplicate package is not allowed" + +If you see this error message when running the fuzzing job with `COVFUZZ_USE_REGISTRY` set to `true`, +ensure that duplicates are allowed. For more details, see +[duplicate Generic packages](../../packages/generic_packages/#do-not-allow-duplicate-generic-packages). diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index 5d1e57553f4..4cde1847419 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -10,7 +10,7 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323423) in GitLab 13.12. WARNING: -This product is in an early-access stage and is considered a [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) feature. +This product is in an early-access stage and is considered a [beta](../../../policy/alpha-beta-support.md#beta-features) feature. GitLab DAST's new browser-based crawler is a crawl engine built by GitLab to test Single Page Applications (SPAs) and traditional web applications. Due to the reliance of modern web applications on JavaScript, handling SPAs or applications that are dependent on JavaScript is paramount to ensuring proper coverage of an application for Dynamic Application Security Testing (DAST). diff --git a/doc/user/application_security/dast/checks/1004.1.md b/doc/user/application_security/dast/checks/1004.1.md index dfbc600b05b..9626973eb36 100644 --- a/doc/user/application_security/dast/checks/1004.1.md +++ b/doc/user/application_security/dast/checks/1004.1.md @@ -4,7 +4,7 @@ group: Dynamic Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Sensitive cookie without `HttpOnly` attribute +# Sensitive cookie without HttpOnly attribute ## Description diff --git a/doc/user/application_security/dast/checks/16.2.md b/doc/user/application_security/dast/checks/16.2.md index 95461e8677d..484460b6642 100644 --- a/doc/user/application_security/dast/checks/16.2.md +++ b/doc/user/application_security/dast/checks/16.2.md @@ -38,7 +38,7 @@ the `Server` header. ## Links -- [cwe](https://cwe.mitre.org/data/definitions/16.html) +- [CWE](https://cwe.mitre.org/data/definitions/16.html) - [Apache ServerTokens](https://blog.mozilla.org/security/2016/08/26/mitigating-mime-confusion-attacks-in-firefox/) - [NGINX server_tokens](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_tokens) - [IIS 10 Remove Server Header](https://docs.microsoft.com/en-us/iis/configuration/system.webserver/security/requestfiltering/#attributes) diff --git a/doc/user/application_security/dast/checks/16.3.md b/doc/user/application_security/dast/checks/16.3.md index 6f80a2a32c6..e4fc2468dae 100644 --- a/doc/user/application_security/dast/checks/16.3.md +++ b/doc/user/application_security/dast/checks/16.3.md @@ -32,4 +32,4 @@ information from the `X-Powered-By` header. ## Links - [CWE](https://cwe.mitre.org/data/definitions/16.html) -- [PHP `expose_php`](https://www.php.net/manual/en/ini.core.php#ini.expose-php) +- [PHP expose_php](https://www.php.net/manual/en/ini.core.php#ini.expose-php) diff --git a/doc/user/application_security/dast/checks/200.1.md b/doc/user/application_security/dast/checks/200.1.md new file mode 100644 index 00000000000..98a482b4a0f --- /dev/null +++ b/doc/user/application_security/dast/checks/200.1.md @@ -0,0 +1,29 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Exposure of sensitive information to an unauthorized actor (private IP address) + +## Description + +A private RFC 1918 was identified in the target application. Public facing websites should not be issuing +requests to private IP Addresses. Attackers attempting to execute subsequent attacks, such as Server-Side +Request Forgery (SSRF), may be able to use this information to identify additional internal targets. + +## Remediation + +Identify the resource that is incorrectly specifying an internal IP address and replace it with it's public +facing version, or remove the reference from the target application. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 200.1 | true | 200 | Passive | Low | + +## Links + +- [CWE](https://cwe.mitre.org/data/definitions/200.html) +- [RFC](https://datatracker.ietf.org/doc/html/rfc1918) diff --git a/doc/user/application_security/dast/checks/548.1.md b/doc/user/application_security/dast/checks/548.1.md new file mode 100644 index 00000000000..94f747739c5 --- /dev/null +++ b/doc/user/application_security/dast/checks/548.1.md @@ -0,0 +1,45 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Exposure of information through directory listing + +## Description + +The target web server is configured to list the contents of directories that do not contain an index file +such as `index.html`. This could lead to accidental exposure of sensitive information, or give an attacker +details on how filenames and directories are structured and stored. + +## Remediation + +Directory indexing should be disabled. + +Apache: +For Apache based web sites, ensure all `<Directory>` definitions have `Options -Indexes` configured in the +`apache2.conf` or `httpd.conf` configuration file. + +NGINX: +For NGINX based websites, ensure all `location` definitions have the `autoindex off` directive set in the +`nginx.conf` file. + +IIS: +For IIS based websites version 7.0 and above you can use the `<directoryBrowse enabled="false" />` element +in the `applicationHost.config` or `Web.config` files. + +For all other server types, please consult your product's documentation on how to disable directory +indexing. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 548.1 | false | 548 | Passive | Low | + +## Links + +- [CWE](https://cwe.mitre.org/data/definitions/598.html) +- [Apache Options](https://httpd.apache.org/docs/2.4/mod/core.html#options) +- [NGINX autoindex](https://nginx.org/en/docs/http/ngx_http_autoindex_module.html) +- [IIS directoryBrowse element](https://docs.microsoft.com/en-us/iis/configuration/system.webserver/directorybrowse) diff --git a/doc/user/application_security/dast/checks/614.1.md b/doc/user/application_security/dast/checks/614.1.md index 46f7f61b0c7..ec68ce33529 100644 --- a/doc/user/application_security/dast/checks/614.1.md +++ b/doc/user/application_security/dast/checks/614.1.md @@ -4,7 +4,7 @@ group: Dynamic Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Sensitive cookie without `Secure` attribute +# Sensitive cookie without Secure attribute ## Description @@ -35,6 +35,6 @@ Set-Cookie: {cookie_name}=<random secure value>; Secure ## Links -- [owasp](https://owasp.org/www-community/controls/SecureCookieAttribute) +- [OWASP](https://owasp.org/www-community/controls/SecureCookieAttribute) - [CWE](https://cwe.mitre.org/data/definitions/614.html) - [Mozilla MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies) diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md index a3b89e09751..97224554723 100644 --- a/doc/user/application_security/dast/checks/index.md +++ b/doc/user/application_security/dast/checks/index.md @@ -10,12 +10,14 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | ID | Check | Severity | Type | |:---|:------|:---------|:-----| -| [1004.1](1004.1.md) | Sensitive cookie without `HttpOnly` attribute | Low | Passive | +| [1004.1](1004.1.md) | Sensitive cookie without HttpOnly attribute | Low | Passive | | [16.1](16.1.md) | Missing Content-Type header | Low | Passive | | [16.2](16.2.md) | Server header exposes version information | Low | Passive | | [16.3](16.3.md) | X-Powered-By header exposes version information | Low | Passive | | [16.4](16.4.md) | X-Backend-Server header exposes server information | Info | Passive | | [16.5](16.5.md) | AspNet header exposes version information | Low | Passive | | [16.6](16.6.md) | AspNetMvc header exposes version information | Low | Passive | -| [614.1](614.1.md) | Sensitive cookie without `Secure` attribute | Low | Passive | +| [200.1](200.1.md) | Exposure of sensitive information to an unauthorized actor (private IP address) | Low | Passive | +| [548.1](548.1.md) | Exposure of information through directory listing | Low | Passive | +| [614.1](614.1.md) | Sensitive cookie without Secure attribute | Low | Passive | | [693.1](693.1.md) | Missing X-Content-Type-Options: nosniff | Low | Passive | diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index aeaa93f4a85..0865cc10691 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -53,7 +53,7 @@ results. On failure, the analyzer outputs an - [GitLab Runner](../../../ci/runners/index.md) available, with the [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). - Target application deployed. For more details, read [Deployment options](#deployment-options). -- DAST runs in the `test` stage, which is available by default. If you redefine the stages in the `.gitlab-ci.yml` file, the `test` stage is required. +- DAST runs in the `dast` stage, which must be added manually to your `.gitlab-ci.yml`. ### Deployment options @@ -588,6 +588,28 @@ Using the [`DAST_MASK_HTTP_HEADERS` CI/CD variable](#available-cicd-variables), headers whose values you want masked. For details on how to mask headers, see [Customizing the DAST settings](#customize-dast-settings). +#### Use Mutual TLS + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299596) in GitLab 14.8. + +Mutual TLS allows a target application server to verify that requests are from a known source. Browser-based scans do not support Mutual TLS. + +**Requirements** + +- Base64-encoded PKCS12 certificate +- Password of the base64-encoded PKCS12 certificate + +To enable Mutual TLS: + +1. If the PKCS12 certificate is not already base64-encoded, convert it to base64 encoding. For security reasons, we recommend encoding the certificate locally, **not** using a web-hosted conversion service. For example, to encode the certificate on either macOS or Linux: + + ```shell + base64 <path-to-pkcs12-certificate-file> + ``` + +1. Create a [masked variable](../../../ci/variables/index.md) named `DAST_PKCS12_CERTIFICATE_BASE64` and store the base64-encoded PKCS12 certificate's value in that variable. +1. Create a masked variable `DAST_PKCS12_PASSWORD` and store the PKCS12 certificate's password in that variable. + #### Available CI/CD variables These CI/CD variables are specific to DAST. They can be used to customize the behavior of DAST to your requirements. @@ -623,6 +645,8 @@ These CI/CD variables are specific to DAST. They can be used to customize the be | `DAST_PASSWORD_FIELD` <sup>1,2</sup> | string | The selector of password field at the sign-in HTML form. Example: `id:password` | | `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | | `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | +| `DAST_PKCS12_CERTIFICATE_BASE64` | string | The PKCS12 certificate used for sites that require Mutual TLS. Must be encoded as base64 text. | +| `DAST_PKCS12_PASSWORD` | string | The password of the certificate used in `DAST_PKCS12_CERTIFICATE_BASE64`. | | `DAST_REQUEST_HEADERS` <sup>1</sup> | 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_SKIP_TARGET_CHECK` | boolean | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229067) in GitLab 13.8. | | `DAST_SPIDER_MINS` <sup>1</sup> | 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. | @@ -1172,7 +1196,7 @@ To edit an existing site profile: 1. Edit the fields then select **Save profile**. If a site profile is linked to a security policy, a user cannot edit the profile from this page. See -[Scan Execution Policies](../policies/index.md#scan-execution-policy-editor) +[Scan execution policies](../policies/scan-execution-policies.md) for more information. #### Delete a site profile @@ -1186,7 +1210,7 @@ To delete an existing site profile: 1. Select **Delete** to confirm the deletion. If a site profile is linked to a security policy, a user cannot delete the profile from this page. -See [Scan Execution Policies](../policies/index.md#scan-execution-policy-editor) +See [Scan execution policies](../policies/scan-execution-policies.md) for more information. #### Validate a site profile @@ -1329,7 +1353,7 @@ To edit a scanner profile: 1. Select **Save profile**. If a scanner profile is linked to a security policy, a user cannot edit the profile from this page. -See [Scan Execution Policies](../policies/index.md#scan-execution-policy-editor) +See [Scan execution policies](../policies/scan-execution-policies.md) for more information. #### Delete a scanner profile @@ -1343,7 +1367,7 @@ To delete a scanner profile: 1. Select **Delete**. If a scanner profile is linked to a security policy, a user cannot delete the profile from this -page. See [Scan Execution Policies](../policies/index.md#scan-execution-policy-editor) +page. See [Scan execution policies](../policies/scan-execution-policies.md) for more information. ## Auditing @@ -1365,7 +1389,7 @@ The JSON report artifacts are not a public API of DAST and their format is expec The DAST tool always emits a JSON report file called `gl-dast-report.json` and sample reports can be found in the -[DAST repository](https://gitlab.com/gitlab-org/security-products/dast/-/tree/master/test/end-to-end/expect). +[DAST repository](https://gitlab.com/gitlab-org/security-products/dast/-/tree/main/test/end-to-end/expect). ## Optimizing DAST diff --git a/doc/user/application_security/dast/run_dast_offline.md b/doc/user/application_security/dast/run_dast_offline.md index 86621d73524..63163167a6c 100644 --- a/doc/user/application_security/dast/run_dast_offline.md +++ b/doc/user/application_security/dast/run_dast_offline.md @@ -36,7 +36,7 @@ For DAST, import the following default DAST analyzer image from `registry.gitlab The process for importing Docker images into a local offline Docker registry depends on **your network security policy**. Please consult your IT staff to find an accepted and approved process by which external resources can be imported or temporarily accessed. -These scanners are [periodically updated](../vulnerabilities/index.md#vulnerability-scanner-maintenance) +These scanners are [periodically updated](../index.md#vulnerability-scanner-maintenance) with new definitions, and you may be able to make occasional updates on your own. For details on saving and transporting Docker images as a file, see Docker's documentation on diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index f1eba505589..cc20b49764f 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -69,8 +69,8 @@ starting in GitLab 14.0, GitLab will not check your repository's root for config ### OpenAPI Specification -> Support for OpenAPI Specification using YAML format was -> [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330583) in GitLab 14.0. +> - Support for OpenAPI Specification using YAML format was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330583) in GitLab 14.0. +> - Support to generate media type `application/xml` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327268) in GitLab 14.8. The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an API description format for REST APIs. This section shows you how to configure API fuzzing using an OpenAPI Specification to provide information about the target API to test. @@ -82,6 +82,7 @@ the body generation is limited to these body types: - `application/x-www-form-urlencoded` - `multipart/form-data` - `application/json` +- `application/xml` Follow these steps to configure DAST API in GitLab with an OpenAPI specification: @@ -478,6 +479,9 @@ Follow these steps to provide the bearer token with `DAST_API_OVERRIDES_ENV`: `{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}` (substitute your token). You can create CI/CD variables from the GitLab projects page at **Settings > CI/CD**, in the **Variables** section. + Due to the format of `TEST_API_BEARERAUTH` it's not possible to mask the variable. + To mask the token's value, you can create a second variable with the token value's, and define + `TEST_API_BEARERAUTH` with the value `{"headers":{"Authorization":"Bearer $MASKED_VARIABLE"}}`. 1. In your `.gitlab-ci.yml` file, set `DAST_API_OVERRIDES_ENV` to the variable you just created: @@ -529,7 +533,7 @@ variables: DAST_API_PROFILE: Quick DAST_API_OPENAPI: test-api-specification.json DAST_API_TARGET_URL: http://test-deployment/ - DAST_API_OVERRIDES_FILE: output/dast-api-overrides.json + DAST_API_OVERRIDES_FILE: dast-api-overrides.json ``` To validate that authentication is working, run an DAST API test and review the job logs and @@ -571,13 +575,12 @@ variables: DAST_API_PROFILE: Quick DAST_API_OPENAPI: test-api-specification.json DAST_API_TARGET_URL: http://test-deployment/ - DAST_API_OVERRIDES_FILE: output/dast-api-overrides.json + DAST_API_OVERRIDES_FILE: dast-api-overrides.json DAST_API_OVERRIDES_CMD: renew_token.py DAST_API_OVERRIDES_INTERVAL: 300 ``` -To validate that authentication is working, run an DAST API test and review the job logs and -the test API's application logs. +To validate that authentication is working, run an DAST API test and review the job logs and the test API's application logs. See the [overrides section](#overrides) for more information about override commands. ### Configuration files @@ -644,6 +647,9 @@ can be added, removed, and modified by creating a custom configuration. |[`DAST_API_OVERRIDES_FILE`](#overrides) | Path to a JSON file containing overrides. | |[`DAST_API_OVERRIDES_ENV`](#overrides) | JSON string containing headers to override. | |[`DAST_API_OVERRIDES_CMD`](#overrides) | Overrides command. | +|[`DAST_API_OVERRIDES_CMD_VERBOSE`](#overrides) | When set to any value. It shows overrides command output as part of the job output. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334578) in GitLab 14.6. | +|`DAST_API_PRE_SCRIPT` | Run user command or script before scan session starts. | +|`DAST_API_POST_SCRIPT` | Run user command or script after scan session has finished. | |[`DAST_API_OVERRIDES_INTERVAL`](#overrides) | How often to run overrides command in seconds. Defaults to `0` (once). | |[`DAST_API_HTTP_USERNAME`](#http-basic-authentication) | Username for HTTP authentication. | |[`DAST_API_HTTP_PASSWORD`](#http-basic-authentication) | Password for HTTP authentication. | @@ -825,7 +831,7 @@ variables: DAST_API_PROFILE: Quick DAST_API_OPENAPI: test-api-specification.json DAST_API_TARGET_URL: http://test-deployment/ - DAST_API_OVERRIDES_FILE: output/dast-api-overrides.json + DAST_API_OVERRIDES_FILE: dast-api-overrides.json ``` #### Using a CI/CD variable @@ -869,17 +875,29 @@ variables: #### Using a command If the value must be generated or regenerated on expiration, you can provide a program or script for -the DAST API scanner to execute on a specified interval. The provided script runs in an Alpine Linux -container that has Python 3 and Bash installed. If the Python script requires additional packages, -it must detect this and install the packages at runtime. The script creates the overrides JSON file -as defined above. +the DAST API scanner to execute on a specified interval. The provided command runs in an Alpine Linux +container that has Python 3 and Bash installed. + +You have to set the environment variable `DAST_API_OVERRIDES_CMD` to the program or script you would like +to execute. The provided command creates the overrides JSON file as defined previously. + +You might want to install other scripting runtimes like NodeJS or Ruby, or maybe you need to install a dependency for +your overrides command. In this case, we recommend setting the `DAST_API_PRE_SCRIPT` to the file path of a script which +provides those prerequisites. The script provided by `DAST_API_PRE_SCRIPT` is executed once, before the analyzer starts. + +See the [Alpine Linux package management](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management) +page for information about installing Alpine Linux packages. You must provide three CI/CD variables, each set for correct operation: - `DAST_API_OVERRIDES_FILE`: File generated by the provided command. -- `DAST_API_OVERRIDES_CMD`: Command to generate JSON file. +- `DAST_API_OVERRIDES_CMD`: Overrides command in charge of generating the overrides JSON file periodically. - `DAST_API_OVERRIDES_INTERVAL`: Interval in seconds to run command. +Optionally: + +- `DAST_API_PRE_SCRIPT`: Script to install runtimes or dependencies before the scan starts. + ```yaml stages: - dast @@ -891,11 +909,167 @@ variables: DAST_API_PROFILE: Quick DAST_API_OPENAPI: test-api-specification.json DAST_API_TARGET_URL: http://test-deployment/ - DAST_API_OVERRIDES_FILE: output/dast-api-overrides.json + DAST_API_OVERRIDES_FILE: dast-api-overrides.json DAST_API_OVERRIDES_CMD: renew_token.py DAST_API_OVERRIDES_INTERVAL: 300 ``` +#### Debugging overrides + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334578) in GitLab 14.8. + +By default the output of the overrides command is hidden. If the overrides command returns a non zero exit code, the command is displayed as part of your job output. Optionally, you can set the variable `DAST_API_OVERRIDES_CMD_VERBOSE` to any value in order to display overrides command output as it is generated. This is useful when testing your overrides script, but should be disabled afterwards as it slows down testing. + +It is also possible to write messages from your script to a log file that is collected when the job completes or fails. The log file must be created in a specific location and following a naming convention. + +Adding some basic logging to your overrides script is useful in case the script fails unexpectedly during normal running of the job. The log file is automatically included as an artifact of the job, allowing you to download it after the job has finished. + +Following our example, we provided `renew_token.py` in the environment variable `DAST_API_OVERRIDES_CMD`. Please notice two things in the script: + +- Log file is saved in the location indicated by the environmental variable `CI_PROJECT_DIR`. +- Log file name should match `gl-*.log`. + +```python +#!/usr/bin/env python + +# Example of an overrides command + +# Override commands can update the overrides json file +# with new values to be used. This is a great way to +# update an authentication token that will expire +# during testing. + +import logging +import json +import os +import requests +import backoff + +# [1] Store log file in directory indicated by env var CI_PROJECT_DIR +working_directory = os.environ['CI_PROJECT_DIR'] + +# [2] File name should match the pattern: gl-*.log +log_file_path = os.path.join(working_directory, 'gl-user-overrides.log') + +# Set up logger +logging.basicConfig(filename=log_file_path, level=logging.DEBUG) + +# Use `backoff` decorator to retry in case of transient errors. +@backoff.on_exception(backoff.expo, + (requests.exceptions.Timeout, + requests.exceptions.ConnectionError), + max_time=30) +def get_auth_response(): + return requests.get('https://authorization.service/api/get_api_token', auth=(os.environ['AUTH_USER'], os.environ['AUTH_PWD'])) + +# In our example, access token is retrieved from a given endpoint +try: + + # Performs a http request, response sample: + # { "Token" : "b5638ae7-6e77-4585-b035-7d9de2e3f6b3" } + response = get_auth_response() + + # Check that the request is successful. may raise `requests.exceptions.HTTPError` + response.raise_for_status() + + # Gets JSON data + response_body = response.json() + +# If needed specific exceptions can be caught +# requests.ConnectionError : A network connection error problem occurred +# requests.HTTPError : HTTP request returned an unsuccessful status code. [Response.raise_for_status()] +# requests.ConnectTimeout : The request timed out while trying to connect to the remote server +# requests.ReadTimeout : The server did not send any data in the allotted amount of time. +# requests.TooManyRedirects : The request exceeds the configured number of maximum redirections +# requests.exceptions.RequestException : All exceptions that related to Requests +except requests.exceptions.RequestException as requests_error: + # logs exceptions related to `Requests` + logging.error(f'Error, failed while performing HTTP request. Error message: {requests_error}') + raise +except requests.exceptions.JSONDecodeError as json_decode_error: + # logs errors related decoding JSON response + logging.error(f'Error, failed while decoding JSON response. Error message: {json_decode_error}') + raise +except Exception as e: + # logs any other error + logging.error(f'Error, unknown error while retrieving access token. Error message: {e}') + raise + +# computes object that holds overrides file content. +# It uses data fetched from request +overrides_data = { + "headers": { + "Authorization": f"Token {response_body['Token']}" + } +} + +# log entry informing about the file override computation +# the location of the overrides json file is also CI_PROJECT_DIR +overrides_file_path = os.path.join( + working_directory, "dast-api-overrides.json") +logging.info("Creating overrides file: %s" % overrides_file_path) + +# attempts to overwrite the file +try: + if os.path.exists(overrides_file_path): + os.unlink(overrides_file_path) + + # overwrites the file with our updated dictionary + with open(overrides_file_path, "wb+") as fd: + fd.write(json.dumps(overrides_data).encode('utf-8')) +except Exception as e: + # logs any other error + logging.error(f'Error, unkown error when overwritng file {overrides_file_path}. Error message: {e}') + raise + +# logs informing override has finished successfully +logging.info("Override file has been updated") + +# end +``` + +In the overrides command example, the Python script depends on the `backoff` library. To make sure the library is installed before executing the Python script, the `DAST_API_PRE_SCRIPT` is set to a script that will install the dependencies of your overrides command. +As for example, the following script `user-pre-scan-set-up.sh` + +```shell +#!/bin/bash + +# user-pre-scan-set-up.sh +# Ensures python dependencies are installed + +echo "**** install python dependencies ****" + +python3 -m ensurepip +pip3 install --no-cache --upgrade \ + pip \ + backoff + +echo "**** python dependencies installed ****" + +# end +``` + +You have to update your configuration to set the `DAST_API_PRE_SCRIPT` to our new `user-pre-scan-set-up.sh` script. For example: + +```yaml +stages: + - dast + +include: + - template: DAST-API.gitlab-ci.yml + +variables: + DAST_API_PROFILE: Quick + DAST_API_OPENAPI: test-api-specification.json + DAST_API_TARGET_URL: http://test-deployment/ + DAST_API_PRE_SCRIPT: user-pre-scan-set-up.sh + DAST_API_OVERRIDES_FILE: dast-api-overrides.json + DAST_API_OVERRIDES_CMD: renew_token.py + DAST_API_OVERRIDES_INTERVAL: 300 +``` + +In the previous sample, you could use the script `user-pre-scan-set-up.sh` to also install new runtimes or applications that later on you could use in our overrides command. + ### Exclude Paths > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211892) in GitLab 14.0. diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index 1b502b306bb..551488c0dc0 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -29,11 +29,16 @@ Dependency Scanning supports the following official analyzers: The analyzers are published as Docker images, which Dependency Scanning uses to launch dedicated containers for each analysis. +The Dependency Scanning analyzers' current major version number is 2. + Dependency Scanning is pre-configured with a set of **default images** that are maintained by GitLab, but users can also integrate their own **custom images**. WARNING: -The `bundler-audit` analyzer is deprecated and will be removed in GitLab 15.0 since it duplicates the functionality of the `gemnasium` analyzer. For more information, read the [deprecation announcement](../../../update/deprecations.md#deprecation-of-bundler-audit-dependency-scanning-tool). +The `bundler-audit` analyzer is deprecated and will be removed in GitLab 15.0 since it duplicates the functionality of the `gemnasium` analyzer. For more information, read the [deprecation announcement](../../../update/deprecations.md#bundler-audit-dependency-scanning-tool). + +WARNING: +The `retire.js` analyzer is deprecated and will be removed in GitLab 15.0 since it duplicates the functionality of the `gemnasium` analyzer. For more information, read the [deprecation announcement](../../../update/deprecations.md#retire-js-dependency-scanning-tool). ## Official default analyzers diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index a8cc33d5545..a169b78a193 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -338,12 +338,12 @@ To support the following package managers, the GitLab analyzers proceed in two s | Package Manager | Preinstalled Versions | Tested Versions | | ------ | ------ | ------ | | Bundler | [2.1.4](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit/-/blob/v2.11.3/Dockerfile#L15)<sup><b><a href="#exported-dependency-information-notes-1">1</a></b></sup> | [1.17.3](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/master/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | -| sbt | [1.3.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L4) | [1.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L263), [1.1.4](https://gitlab.com/gitlab-org/security-products/tests/scala-sbt-multiproject/-/blob/main/project/build.properties#L1), [1.1.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L272), [1.2.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L281), [1.3.12](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L290), [1.4.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/master/.gitlab-ci.yml#L299) | +| sbt | [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/config/.tool-versions#L4) | [1.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L330), [1.1.4](https://gitlab.com/gitlab-org/security-products/tests/scala-sbt-multiproject/-/blob/main/project/build.properties#L1), [1.1.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L339), [1.2.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L348), [1.3.12](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L357), [1.4.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L366), [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L384) | | Maven | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L3) | [3.6.3](https://gitlab.com/gitlab-org/security-products/tests/java-maven/-/blob/master/pom.xml#L3) | -| Gradle | [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L5) | [5.6.4](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/master/gradle/wrapper/gradle-wrapper.properties#L3), [6.5](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14/gradle/wrapper/gradle-wrapper.properties#L3), [6.7-rc-1](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-15/gradle/wrapper/gradle-wrapper.properties#L3), [6.9](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14-gradle-6-9/gradle/wrapper/gradle-wrapper.properties#L3), [7.0-rc-2](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-16/gradle/wrapper/gradle-wrapper.properties#L3) | -| setuptools | [50.3.2](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L27) | [57.5.0](https://gitlab.com/gitlab-org/security-products/tests/python-setuptools/-/blob/main/setup.py) | +| Gradle | [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L5) | [5.6.4](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/master/gradle/wrapper/gradle-wrapper.properties#L3), [6.5](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14/gradle/wrapper/gradle-wrapper.properties#L3), [6.7-rc-1](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-15/gradle/wrapper/gradle-wrapper.properties#L3), [6.9](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14-gradle-6-9/gradle/wrapper/gradle-wrapper.properties#L3), [7.0-rc-2](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-16/gradle/wrapper/gradle-wrapper.properties#L3) | +| setuptools | [50.3.2](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L27) | [57.5.0](https://gitlab.com/gitlab-org/security-products/tests/python-setuptools/-/blob/main/setup.py) | | pip | [20.2.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L26) | [20.x](https://gitlab.com/gitlab-org/security-products/tests/python-pip/-/blob/master/requirements.txt) | -| Pipenv | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.18.4/requirements.txt#L13) | [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/pipfile-lock-FREEZE/Pipfile.lock#L6)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/master/Pipfile) | +| Pipenv | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.18.4/requirements.txt#L13) | [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/pipfile-lock-FREEZE/Pipfile.lock#L6)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/master/Pipfile) | <!-- markdownlint-disable MD044 --> <ol> @@ -389,7 +389,8 @@ The following analyzers are executed, each of which have different behavior when Does not support multiple lockfiles. When multiple lockfiles exist, `bundler-audit` analyzes the first lockfile discovered while traversing the directory tree in alphabetical order. -We execute both analyzers because they use different sources of vulnerability data. The result is more comprehensive analysis than if only one was executed. +WARNING: +The `bundler-audit` analyzer is deprecated and will be removed in GitLab 15.0 since it duplicates the functionality of the `gemnasium` analyzer. For more information, read the [deprecation announcement](../../../update/deprecations.md#bundler-audit-dependency-scanning-tool). #### Python @@ -418,6 +419,11 @@ The following analyzers are executed, each of which have different behavior when Does not support multiple lockfiles. When multiple lockfiles exist, `Retire.js` analyzes the first lockfile discovered while traversing the directory tree in alphabetical order. +From GitLab 14.8 the `Gemnasium` analyzer scans supported JavaScript projects for vendored libraries +(that is, those checked into the project but not managed by the package manager). + +WARNING: +The `retire.js` analyzer is deprecated and will be removed in GitLab 15.0 since it duplicates the functionality of the `gemnasium` analyzer. For more information, read the [deprecation announcement](../../../update/deprecations.md#retire-js-dependency-scanning-tool). We execute both analyzers because they use different sources of vulnerability data. The result is more comprehensive analysis than if only one was executed. #### PHP, Go, C, C++, .NET, C# @@ -547,7 +553,7 @@ The following variables allow configuration of global dependency scanning settin The following variables are used for configuring specific analyzers (used for a specific language/framework). | CI/CD variable | Analyzer | Default | Description | -| ------------------------------------ | ------------------ | ---------------------------- |------------ | +|--------------------------------------| ------------------ | ---------------------------- |------------ | | `BUNDLER_AUDIT_UPDATE_DISABLED` | `bundler-audit` | `"false"` | Disable automatic updates for the `bundler-audit` analyzer. Use if you're running dependency scanning in an offline, air-gapped environment.| | `BUNDLER_AUDIT_ADVISORY_DB_URL` | `bundler-audit` | `https://github.com/rubysec/ruby-advisory-db` | URL of the advisory database used by bundler-audit. | | `BUNDLER_AUDIT_ADVISORY_DB_REF_NAME` | `bundler-audit` | `master` | Git ref for the advisory database specified by `BUNDLER_AUDIT_ADVISORY_DB_URL`. | @@ -556,6 +562,7 @@ The following variables are used for configuring specific analyzers (used for a | `GEMNASIUM_DB_REMOTE_URL` | `gemnasium` | `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` | Repository URL for fetching the Gemnasium database. | | `GEMNASIUM_DB_REF_NAME` | `gemnasium` | `master` | Branch name for remote repository database. `GEMNASIUM_DB_REMOTE_URL` is required. | | `DS_REMEDIATE` | `gemnasium` | `"true"` | Enable automatic remediation of vulnerable dependencies. | +| `GEMNASIUM_LIBRARY_SCAN_ENABLED` | `gemnasium` | `"true"` | Enable detecting vulnerabilities in vendored JavaScript libraries. For now, `gemnasium` leverages [`Retire.js`](https://github.com/RetireJS/retire.js) to do this job. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350512) in GitLab 14.8. | | `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`, `15`, `16`. | | `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that are passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repositories). | | `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that are passed to `gradle` by the analyzer. | @@ -565,11 +572,36 @@ The following variables are used for configuring specific analyzers (used for a | `PIP_REQUIREMENTS_FILE` | `gemnasium-python` | | Pip requirements file to be scanned. | | `DS_PIP_VERSION` | `gemnasium-python` | | Force the install of a specific pip version (example: `"19.3"`), otherwise the pip installed in the Docker image is used. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12811) in GitLab 12.7) | | `DS_PIP_DEPENDENCY_PATH` | `gemnasium-python` | | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12412) in GitLab 12.2) | -| `DS_PYTHON_VERSION` | `retire.js` | | Version of Python. If set to 2, dependencies are installed using Python 2.7 instead of Python 3.6. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12296) in GitLab 12.1, [removed](https://www.python.org/doc/sunset-python-2/) in GitLab 13.7). | | `RETIREJS_JS_ADVISORY_DB` | `retire.js` | `https://raw.githubusercontent.com/RetireJS/retire.js/master/repository/jsrepository.json` | Path or URL to `retire.js` JS vulnerability data file. Note that if the URL hosting the data file uses a custom SSL certificate, for example in an offline installation, you can pass the certificate in the `ADDITIONAL_CA_CERT_BUNDLE` variable. | | `RETIREJS_NODE_ADVISORY_DB` | `retire.js` | `https://raw.githubusercontent.com/RetireJS/retire.js/master/repository/npmrepository.json` | Path or URL to `retire.js` node vulnerability data file. Note that if the URL hosting the data file uses a custom SSL certificate, for example in an offline installation, you can pass the certificate in the `ADDITIONAL_CA_CERT_BUNDLE` variable. | | `RETIREJS_ADVISORY_DB_INSECURE` | `retire.js` | `false` | Enable fetching remote JS and Node vulnerability data files (defined by the `RETIREJS_JS_ADVISORY_DB` and `RETIREJS_NODE_ADVISORY_DB` variables) from hosts using an insecure or self-signed SSL (TLS) certificate. | +#### Other variables + +The previous tables are not an exhaustive list of all variables that can be used. They contain all specific GitLab and analyzer variables we support and test. There are many variables, such as environment variables, that you can pass in and they will work. This is a large list, many of which we may be unaware of, and as such is not documented. + +For example, to pass the non-GitLab environment variable `HTTPS_PROXY` to all Dependency Scanning jobs, +set it as a [custom CI/CD variable in your `.gitlab-ci.yml`](../../../ci/variables/#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file) +file like this: + +```yaml +variables: + HTTPS_PROXY: "https://squid-proxy:3128" +``` + +Alternatively we may use it in specific jobs, like Dependency Scanning: + +```yaml +dependency_scanning: + variables: + HTTPS_PROXY: $HTTPS_PROXY +``` + +As we have not tested all variables you may find some will work and others will not. +If one does not work and you need it we suggest +[submitting a feature request](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal%20-%20detailed&issue[title]=Docs%20feedback%20-%20feature%20proposal:%20Write%20your%20title) +or [contributing to the code](../../../development/index.md) to enable it to be used. + ### Using a custom SSL CA certificate authority You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following: @@ -613,7 +645,7 @@ vulnerabilities in your groups, projects and pipelines. Read more about the ## Vulnerabilities database update For more information about the vulnerabilities database update, see the -[maintenance table](../vulnerabilities/index.md#vulnerability-scanner-maintenance). +[maintenance table](../index.md#vulnerability-scanner-maintenance). ## Dependency List @@ -735,6 +767,87 @@ Here's an example dependency scanning report: } ``` +### CycloneDX reports + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350509) in GitLab 14.8 in [Beta](../../../policy/alpha-beta-support.md#beta-features). + +In addition to the [JSON report file](#reports-json-format), the [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) +Dependency Scanning tool outputs a [CycloneDX](https://cyclonedx.org/) report for +each supported lock or build file it detects. These CycloneDX reports are named +`cyclonedx-<package-type>-<package-manager>.json`, and are saved in the same directory +as the detected lock or build files. + +For example, if your project has the following structure: + +```plaintext +. +├── ruby-project/ +│ └── Gemfile.lock +├── ruby-project-2/ +│ └── Gemfile.lock +├── php-project/ +│ └── composer.lock +└── go-project/ + └── go.sum +``` + +Then the Gemnasium scanner generates the following CycloneDX reports: + +```plaintext +. +├── ruby-project/ +│ ├── Gemfile.lock +│ └── cyclonedx-gem-bundler.json +├── ruby-project-2/ +│ ├── Gemfile.lock +│ └── cyclonedx-gem-bundler.json +├── php-project/ +│ ├── composer.lock +│ └── cyclonedx-packagist-composer.json +└── go-project/ + ├── go.sum + └── cyclonedx-go-go.json +``` + +The CycloneDX reports can be downloaded [the same way as other job artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). + +### Merging multiple CycloneDX Reports + +You can use a CI/CD job to merge multiple CycloneDX Reports into a single report. +For example: + +```yaml +stages: + - test + - merge-cyclonedx-reports + +include: + - template: Security/Dependency-Scanning.gitlab-ci.yml + +merge cyclonedx reports: + stage: merge-cyclonedx-reports + image: alpine:latest + script: + - wget https://github.com/CycloneDX/cyclonedx-cli/releases/download/v0.22.0/cyclonedx-linux-musl-x64 -O /usr/local/bin/cyclonedx-cli + - chmod 755 /usr/local/bin/cyclonedx-cli + - apk --update add --no-cache icu-dev libstdc++ + - find * -name "cyclonedx-*.json" -exec cyclonedx-cli merge --input-files {} --output-file cyclonedx-all.json + + artifacts: + paths: + - cyclonedx-all.json +``` + +GitLab uses [CycloneDX Properties](https://cyclonedx.org/use-cases/#properties--name-value-store) +to store implementation-specific details in the metadata of each CycloneDX report, +such as the location of build and lock files. If multiple CycloneDX reports are merged together, +this information is removed from the resulting merged file. + +NOTE: +CycloneDX reports are a [Beta](../../../policy/alpha-beta-support.md#beta-features) feature, +and the reports are subject to change during the beta period. Do not build integrations +that rely on the format of these reports staying consistent, as the format might change +before the feature is made generally available. + ## Versioning and release process Please check the [Release Process documentation](https://gitlab.com/gitlab-org/security-products/release/blob/master/docs/release_process.md). @@ -789,7 +902,7 @@ registry.gitlab.com/gitlab-org/security-products/analyzers/bundler-audit:2 The process for importing Docker images into a local offline Docker registry depends on **your network security policy**. Please consult your IT staff to find an accepted and approved process by which external resources can be imported or temporarily accessed. -These scanners are [periodically updated](../vulnerabilities/index.md#vulnerability-scanner-maintenance) +These scanners are [periodically updated](../index.md#vulnerability-scanner-maintenance) with new definitions, and you may be able to make occasional updates on your own. For details on saving and transporting Docker images as a file, see Docker's documentation on diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index 4d5c1da3c47..89d3531bccd 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -36,9 +36,15 @@ GitLab IaC scanning supports a variety of IaC configuration files. Our IaC secur |------------------------------------------|----------------------------------|-------------------------------| | Ansible | [KICS](https://kics.io/) | 14.5 | | AWS CloudFormation | [KICS](https://kics.io/) | 14.5 | +| Azure Resource Manager <sup>1</sup> | [KICS](https://kics.io/) | 14.5 | +| Dockerfile | [KICS](https://kics.io/) | 14.5 | +| Google Deployment Manager | [KICS](https://kics.io/) | 14.5 | | Kubernetes | [KICS](https://kics.io/) | 14.5 | +| OpenAPI | [KICS](https://kics.io/) | 14.5 | | Terraform | [KICS](https://kics.io/) | 14.5 | +1. IaC scanning can analyze Azure Resource Manager templates in JSON format. If you write templates in the [Bicep](https://docs.microsoft.com/en-us/azure/azure-resource-manager/bicep/overview) language, you must use [the bicep CLI](https://docs.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-cli) to convert your Bicep files into JSON before GitLab IaC scanning can analyze them. + ### Making IaC analyzers available to all GitLab tiers All open source (OSS) analyzers are available with the GitLab Free tier. Future proprietary analyzers may be restricted to higher tiers. diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index f5c727a1418..6a0b81335fd 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -2,7 +2,6 @@ stage: Secure group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, howto --- # Secure your application **(ULTIMATE)** @@ -46,6 +45,25 @@ GitLab uses the following tools to scan and report known vulnerabilities found i | [Coverage fuzzing](coverage_fuzzing/index.md) | Find unknown bugs and vulnerabilities with coverage-guided fuzzing. | | [Cluster Image Scanning](cluster_image_scanning/index.md) | Scan Kubernetes clusters for known vulnerabilities. | +## Vulnerability scanner maintenance + +The following vulnerability scanners and their databases are regularly updated: + +| Secure scanning tool | Vulnerabilities database updates | +|:----------------------------------------------------------------|:---------------------------------| +| [Container Scanning](container_scanning/index.md) | A job runs on a daily basis to build new images with the latest vulnerability database updates from the upstream scanner. For more details, see [Vulnerabilities database update](container_scanning/index.md#vulnerabilities-database-update). | +| [Dependency Scanning](dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for npm packages), and `gemnasium` (the GitLab tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated on a daily basis using [data from NVD, the `ruby-advisory-db` and the GitHub Security Advisory Database as data sources](https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/blob/master/SOURCES.md). 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/main/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. | + +In versions of GitLab that use the same major version of the analyzer, you do not have to update +GitLab to benefit from the latest vulnerabilities definitions. The security tools are released as +Docker images. The vendored job definitions that enable them use major release tags according to +[semantic versioning](https://semver.org/). Each new release of the tools overrides these tags. +Although in a major analyzer version you automatically get the latest versions of the scanning +tools, there are some [known issues](https://gitlab.com/gitlab-org/gitlab/-/issues/9725) with this +approach. + ## Security scanning with Auto DevOps To enable all GitLab Security scanning tools, with default settings, enable @@ -98,10 +116,10 @@ base address for Docker images. You can override this globally by setting the CI the container-scanning analyzer which uses `registry.gitlab.com/security-products/container-scanning` as its registry. -### Use security scanning tools with Pipelines for Merge Requests +### Use security scanning tools with merge request pipelines By default, the application security jobs are configured to run for branch pipelines only. -To use them with [pipelines for merge requests](../../ci/pipelines/merge_request_pipelines.md), +To use them with [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md), you may need to override the default `rules:` configuration to add: ```yaml @@ -149,8 +167,8 @@ The artifact generated by the secure analyzer contains all findings it discovers ### All tiers Merge requests which have run security scans let you know that the generated -reports are available to download. To download a report, click on the -**Download results** dropdown, and select the desired report. +reports are available to download. To download a report, select +**Download results**, and select the desired report.  @@ -200,12 +218,17 @@ security issues: ### Vulnerability-Check rule +WARNING: +This feature is in its end-of-life process. It is [deprecated](../../update/deprecations.md#vulnerability-check) +for use in GitLab 14.8, and is planned for removal in GitLab 15.0. Users should migrate to the new +[Security Approval Policies](policies/#scan-result-policy-editor). + To prevent a merge request introducing a security vulnerability in a project, enable the Vulnerability-Check rule. While this rule is enabled, additional merge request approval by [eligible approvers](../project/merge_requests/approvals/rules.md#eligible-approvers) is required when the latest security report in a merge request: -- Contains vulnerabilities with states (for example, `previously detected`, `dismissed`) matching the rule's vulnerability states. Only `newly detected` will be considered if the target branch differs from the project default branch. +- Contains vulnerabilities with states (for example, `previously detected`, `dismissed`) matching the rule's vulnerability states. Only `newly detected` are considered if the target branch differs from the project default branch. - Contains vulnerabilities with severity levels (for example, `high`, `critical`, or `unknown`) matching the rule's severity levels. - Contains a vulnerability count higher than the rule allows. @@ -218,7 +241,7 @@ An approval is optional when the security report: the rule's severity levels. - Contains a vulnerability count equal to or less than what the rule allows. -Project members assigned [at least the Maintainer role](../permissions.md#project-members-permissions) can enable or edit +Project members with at least the Maintainer role can enable or edit the Vulnerability-Check rule. #### Enable the Vulnerability-Check rule @@ -451,28 +474,24 @@ GitLab provides two methods of accomplishing this, each with advantages and disa - [Compliance framework pipelines](../project/settings/#compliance-pipeline-configuration) are recommended when: - - Scan execution enforcement is required for SAST IaC, Container Scanning, Dependency Scanning, + - Scan execution enforcement is required for SAST IaC, Dependency Scanning, License Compliance, API Fuzzing, or Coverage-guided Fuzzing. - - Scan execution enforcement of SAST or Secret Detection when customization of the default scan - variables is required. - Scan execution enforcement is required for scanners external to GitLab. - Enforced execution is required for custom jobs other than security scans. -- [Scan execution policies](policies/#scan-execution-policies) +- [Scan execution policies](policies/scan-execution-policies.md) are recommended when: - - Scan execution enforcement is required for DAST. - - Scan execution enforcement is required for SAST or Secret Detection with the default scan - variables. + - Scan execution enforcement is required for DAST, SAST, Secret Detection, or Container Scanning. - Scans are required to run on a regular, scheduled cadence. Additional details about the differences between the two solutions are outlined below: | | Compliance Framework Pipelines | Scan Execution Policies | | ------ | ------ | ------ | -| **Flexibility** | Supports anything that can be done in a CI file. | Limited to only the items for which GitLab has explicitly added support. DAST, SAST, and Secret Detection scans are supported. | +| **Flexibility** | Supports anything that can be done in a CI file. | Limited to only the items for which GitLab has explicitly added support. DAST, SAST, Secret Detection, and Container Scanning scans are supported. | | **Usability** | Requires knowledge of CI YAML. | Follows a `rules` and `actions`-based YAML structure. | -| **Inclusion in CI pipeline** | The compliance pipeline is executed instead of the project's `gitlab-ci.yml` file. To include the project's `gitlab-ci.yml` file, use an `include` statement. Defined variables aren't allowed to be overwritten by the included project's YAML file. | Forced inclusion of a new job into the CI pipeline. DAST jobs that must be customized on a per-project basis can have project-level Site Profiles and Scan Profiles defined. To ensure separation of duties, these profiles are immutable when referenced in a scan execution policy. | +| **Inclusion in CI pipeline** | The compliance pipeline is executed instead of the project's `gitlab-ci.yml` file. To include the project's `gitlab-ci.yml` file, use an `include` statement. Defined variables aren't allowed to be overwritten by the included project's YAML file. | Forced inclusion of a new job into the CI pipeline. DAST jobs that must be customized on a per-project basis can have project-level Site Profiles and Scan Profiles defined. To ensure separation of duties, these profiles are immutable when referenced in a scan execution policy. All jobs can be customized as part of the security policy itself with the same variables that are normally available to the CI job. | | **Schedulable** | Can be scheduled through a scheduled pipeline on the group. | Can be scheduled natively through the policy configuration itself. | | **Separation of Duties** | Only group owners can create compliance framework labels. Only project owners can apply compliance framework labels to projects. The ability to make or approve changes to the compliance pipeline definition is limited to individuals who are explicitly given access to the project that contains the compliance pipeline. | Only project owners can define a linked security policy project. The ability to make or approve changes to security policies is limited to individuals who are explicitly given access to the security policy project. | | **Ability to apply one standard to multiple projects** | The same compliance framework label can be applied to multiple projects inside a group. | The same security policy project can be used for multiple projects across GitLab with no requirement of being located in the same group. | diff --git a/doc/user/application_security/policies/img/scan_result_policy_yaml_mode_v14_6.png b/doc/user/application_security/policies/img/scan_result_policy_yaml_mode_v14_6.png Binary files differnew file mode 100644 index 00000000000..57649c58d8b --- /dev/null +++ b/doc/user/application_security/policies/img/scan_result_policy_yaml_mode_v14_6.png diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 11f2b91177a..803f3983b96 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -17,8 +17,9 @@ can access these by navigating to your project's **Security & Compliance > Polic GitLab supports the following security policies: -- [Container Network Policy](#container-network-policy) -- [Scan Execution Policy](#scan-execution-policy-schema) +- [Scan Execution Policy](scan-execution-policies.md) +- [Scan Result Policy](scan-result-policies.md) +- [Container Network Policy](#container-network-policy) (DEPRECATED) ## Policy management @@ -77,9 +78,62 @@ by the Rule mode, Rule mode is automatically disabled. If the YAML is incorrect, you must use YAML mode to fix your policy before Rule mode is available again. +## Security Policies project + +NOTE: +We recommend using the [Security Policies project](#security-policies-project) +exclusively for managing policies for the project. Do not add your application's source code to such +projects. + +The Security Policies feature is a repository to store policies. All security policies are stored in +the `.gitlab/security-policies/policy.yml` YAML file. The format for this YAML is specific to the type of policy that is being stored there. Examples and schema information are available for the following policy types: + +- [Scan execution policy](scan-execution-policies.md#example-security-policies-project) +- [Scan result policy](scan-result-policies.md#example-security-scan-result-policies-project) + +Policies created in this project are applied through a background job that runs once every 10 +minutes. Allow up to 10 minutes for any policy changes committed to this project to take effect. + +## Security Policy project selection + +NOTE: +Only project Owners have the [permissions](../../permissions.md#project-members-permissions) +to select Security Policy Project. + +When the Security Policy project is created and policies are created within that repository, you +must create an association between that project and the project you want to apply policies to: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Policies**. +1. Select **Edit Policy Project**, and search for and select the + project you would like to link from the dropdown menu. +1. Select **Save**. + +  + +### Unlink Security Policy projects + +Project owners can unlink Security Policy projects from development projects. To do this, follow +the steps described in [Security Policy project selection](#security-policy-project-selection), +but select the trash can icon in the modal. + +## Scan execution policies + +See [Scan execution policies](scan-execution-policies.md). + +## Scan result policy editor + +See [Scan result policies](scan-result-policies.md). + ## Container Network Policy -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in GitLab 12.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in GitLab 12.9. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. + +WARNING: +Container Network Policy is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) +for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 15.0. The **Container Network Policy** section provides packet flow metrics for your application's Kubernetes namespace. This section has the following @@ -159,7 +213,7 @@ at the bottom of the editor. You can use policy alerts to track your policy's impact. Alerts are only available if you've [installed](../../clusters/agent/repository.md) -and [configured](../../clusters/agent/install/index.md#register-an-agent-with-gitlab) +and [configured](../../clusters/agent/install/index.md#register-the-agent-with-gitlab) an agent for this project. There are two ways to create policy alerts: @@ -176,276 +230,7 @@ There are two ways to create policy alerts: Once added, the UI updates and displays a warning about the dangers of too many alerts. -## Security Policies project - -NOTE: -We recommend using the [Security Policies project](#security-policies-project) -exclusively for managing policies for the project. Do not add your application's source code to such -projects. - -The Security Policies feature is a repository to store policies. All security policies are stored as -the `.gitlab/security-policies/policy.yml` YAML file with this format: - -```yaml ---- -scan_execution_policy: -- name: Enforce DAST in every pipeline - description: This policy enforces pipeline configuration to have a job with DAST scan - enabled: true - rules: - - type: pipeline - branches: - - master - actions: - - scan: dast - scanner_profile: Scanner Profile A - site_profile: Site Profile B -- name: Enforce DAST in every pipeline in main branch - description: This policy enforces pipeline configuration to have a job with DAST scan for main branch - enabled: true - rules: - - type: pipeline - branches: - - main - actions: - - scan: dast - scanner_profile: Scanner Profile C - site_profile: Site Profile D -``` - -## Security Policy project selection - -NOTE: -Only project Owners have the [permissions](../../permissions.md#project-members-permissions) -to select Security Policy Project. - -When the Security Policy project is created and policies are created within that repository, you -must create an association between that project and the project you want to apply policies to: - -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Security & Compliance > Policies**. -1. Select **Edit Policy Project**, and search for and select the - project you would like to link from the dropdown menu. -1. Select **Save**. - -  - -### Unlink Security Policy projects - -Project owners can unlink Security Policy projects from development projects. To do this, follow -the steps described in [Security Policy project selection](#security-policy-project-selection), -but select the trash can icon in the modal. - -## Scan execution policies - -Project owners can use scan execution policies to require that security scans run on a specified -schedule or with the project pipeline. Required scans are injected into the CI pipeline as new jobs -with a long, random job name. In the unlikely event of a job name collision, the security policy job -overwrites any pre-existing job in the pipeline. - -This feature has some overlap with [compliance framework pipelines](../../project/settings/#compliance-pipeline-configuration), -as we have not [unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). -For details on the similarities and differences between these features, see -[Enforce scan execution](../#enforce-scan-execution). - -### Scan Execution Policy editor - -NOTE: -Only project Owners have the [permissions](../../permissions.md#project-members-permissions) -to select Security Policy Project. - -Once your policy is complete, save it by selecting **Create via merge request** -at the bottom of the editor. You are redirected to the merge request on the project's -configured security policy project. If one does not link to your project, a security -policy project is automatically created. Existing policies can also be -removed from the editor interface by selecting **Delete policy** -at the bottom of the editor. - - - -The policy editor currently only supports the YAML mode. The Rule mode is tracked in the [Allow Users to Edit Rule-mode Scan Execution Policies in the Policy UI](https://gitlab.com/groups/gitlab-org/-/epics/5363) epic. - -### Scan Execution Policies Schema - -The YAML file with Scan Execution Policies consists of an array of objects matching Scan Execution Policy Schema nested under the `scan_execution_policy` key. You can configure a maximum of 5 policies under the `scan_execution_policy` key. - -When you save a new policy, GitLab validates its contents against [this JSON schema](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/validators/json_schemas/security_orchestration_policy.json). -If you're not familiar with how to read [JSON schemas](https://json-schema.org/), -the following sections and tables provide an alternative. - -| Field | Type | Possible values | Description | -|-------|------|-----------------|-------------| -| `scan_execution_policy` | `array` of Scan Execution Policy | | List of scan execution policies (maximum 5) | - -### Scan Execution Policy Schema - -| Field | Type | Possible values | Description | -|-------|------|-----------------|-------------| -| `name` | `string` | | Name of the policy. | -| `description` (optional) | `string` | | Description of the policy. | -| `enabled` | `boolean` | `true`, `false` | Flag to enable (`true`) or disable (`false`) the policy. | -| `rules` | `array` of rules | | List of rules that the policy applies. | -| `actions` | `array` of actions | | List of actions that the policy enforces. | - -### `pipeline` rule type - -This rule enforces the defined actions whenever the pipeline runs for a selected branch. - -| Field | Type | Possible values | Description | -|-------|------|-----------------|-------------| -| `type` | `string` | `pipeline` | The rule's type. | -| `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | - -### `schedule` rule type - -This rule enforces the defined actions and schedules a scan on the provided date/time. - -| Field | Type | Possible values | Description | -|------------|------|-----------------|-------------| -| `type` | `string` | `schedule` | The rule's type. | -| `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | -| `cadence` | `string` | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. | -| `clusters` | `object` | | The cluster where the given policy enforces running selected scans (only for `container_scanning`/`cluster_image_scanning` scans). The key of the object is the name of the Kubernetes cluster configured for your project in GitLab. In the optionally provided value of the object, you can precisely select Kubernetes resources that are scanned. | - -#### `cluster` schema - -Use this schema to define `clusters` objects in the [`schedule` rule type](#schedule-rule-type). - -| Field | Type | Possible values | Description | -|--------------|---------------------|--------------------------|-------------| -| `containers` | `array` of `string` | | The container name that is scanned (only the first value is currently supported). | -| `resources` | `array` of `string` | | The resource name that is scanned (only the first value is currently supported). | -| `namespaces` | `array` of `string` | | The namespace that is scanned (only the first value is currently supported). | -| `kinds` | `array` of `string` | `deployment`/`daemonset` | The resource kind that should be scanned (only the first value is currently supported). | - -### `scan` action type - -This action executes the selected `scan` with additional parameters when conditions for at least one -rule in the defined policy are met. - -| Field | Type | Possible values | Description | -|-------|------|-----------------|-------------| -| `scan` | `string` | `dast`, `secret_detection`, `sast`, `container_scanning`, `cluster_image_scanning` | The action's type. | -| `site_profile` | `string` | Name of the selected [DAST site profile](../dast/index.md#site-profile). | The DAST site profile to execute the DAST scan. This field should only be set if `scan` type is `dast`. | -| `scanner_profile` | `string` or `null` | Name of the selected [DAST scanner profile](../dast/index.md#scanner-profile). | The DAST scanner profile to execute the DAST scan. This field should only be set if `scan` type is `dast`.| -| `variables` | `object` | | Set of variables applied and enforced for the selected scan. The object's key is the variable name with a value provided as a string. | - -Note the following: - -- You must create the [site profile](../dast/index.md#site-profile) and [scanner profile](../dast/index.md#scanner-profile) - with selected names for each project that is assigned to the selected Security Policy Project. - Otherwise, the policy is not applied and a job with an error message is created instead. -- Once you associate the site profile and scanner profile by name in the policy, it is not possible - to modify or delete them. If you want to modify them, you must first disable the policy by setting - the `active` flag to `false`. -- When configuring policies with a scheduled DAST scan, the author of the commit in the security - policy project's repository must have access to the scanner and site profiles. Otherwise, the scan - is not scheduled successfully. -- For a secret detection scan, only rules with the default ruleset are supported. [Custom rulesets](../secret_detection/index.md#custom-rulesets) - are not supported. -- A secret detection scan runs in `normal` mode when executed as part of a pipeline, and in - [`historic`](../secret_detection/index.md#full-history-secret-detection) - mode when executed as part of a scheduled scan. -- A container scanning and cluster image scanning scans configured for the `pipeline` rule type ignores the cluster defined in the `clusters` object. - They use predefined CI/CD variables defined for your project. Cluster selection with the `clusters` object is supported for the `schedule` rule type. - Cluster with name provided in `clusters` object must be created and configured for the project. To be able to successfully perform the `container_scanning`/`cluster_image_scanning` scans for the cluster you must follow instructions for the [Cluster Image Scanning feature](../cluster_image_scanning/index.md#prerequisites). -- The SAST scan uses the default template and runs in a [child pipeline](../../../ci/pipelines/parent_child_pipelines.md). - -### Example security policies project - -You can use this example in a `.gitlab/security-policies/policy.yml`, as described in -[Security policies project](#security-policies-project). - -```yaml ---- -scan_execution_policy: -- name: Enforce DAST in every release pipeline - description: This policy enforces pipeline configuration to have a job with DAST scan for release branches - enabled: true - rules: - - type: pipeline - branches: - - release/* - actions: - - scan: dast - scanner_profile: Scanner Profile A - site_profile: Site Profile B -- name: Enforce DAST and secret detection scans every 10 minutes - description: This policy enforces DAST and secret detection scans to run every 10 minutes - enabled: true - rules: - - type: schedule - branches: - - main - cadence: "*/10 * * * *" - actions: - - scan: dast - scanner_profile: Scanner Profile C - site_profile: Site Profile D - - scan: secret_detection -- name: Enforce Secret Detection and Container Scanning in every default branch pipeline - description: This policy enforces pipeline configuration to have a job with Secret Detection and Container Scanning scans for the default branch - enabled: true - rules: - - type: pipeline - branches: - - main - actions: - - scan: secret_detection - - scan: sast - variables: - SAST_EXCLUDED_ANALYZERS: brakeman - - scan: container_scanning -- name: Enforce Cluster Image Scanning on production-cluster every 24h - description: This policy enforces Cluster Image Scanning scan to run every 24 hours - enabled: true - rules: - - type: schedule - cadence: "15 3 * * *" - clusters: - production-cluster: - containers: - - database - resources: - - production-application - namespaces: - - production-namespace - kinds: - - deployment - actions: - - scan: cluster_image_scanning -``` - -In this example: - -- For every pipeline executed on branches that match the `release/*` wildcard (for example, branch - `release/v1.2.1`), DAST scans run with `Scanner Profile A` and `Site Profile B`. -- DAST and secret detection scans run every 10 minutes. The DAST scan runs with `Scanner Profile C` - and `Site Profile D`. -- Secret detection, container scanning, and SAST scans run for every pipeline executed on the `main` - branch. The SAST scan runs with the `SAST_EXCLUDED_ANALYZER` variable set to `"brakeman"`. -- Cluster Image Scanning scan runs every 24h. The scan runs on the `production-cluster` cluster and fetches vulnerabilities - from the container with the name `database` configured for deployment with the name `production-application` in the `production-namespace` namespace. - -### Example for scan execution policy editor - -You can use this example in the YAML mode of the [Scan Execution Policy editor](#scan-execution-policy-editor). -It corresponds to a single object from the previous example. - -```yaml -name: Enforce Secret Detection and Container Scanning in every default branch pipeline -description: This policy enforces pipeline configuration to have a job with Secret Detection and Container Scanning scans for the default branch -enabled: true -rules: - - type: pipeline - branches: - - main -actions: - - scan: secret_detection - - scan: container_scanning -``` - ## Roadmap -See the [Category Direction page](https://about.gitlab.com/direction/protect/container_network_security/) -for more information on the product direction of Container Network Security. +See the [Category Direction page](https://about.gitlab.com/direction/protect/security_orchestration/) +for more information on the product direction of security policies within GitLab. diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md new file mode 100644 index 00000000000..4e44162d5c5 --- /dev/null +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -0,0 +1,219 @@ +--- +stage: Protect +group: Container Security +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Scan execution policies **(ULTIMATE)** + +Project owners can use scan execution policies to require that security scans run on a specified +schedule or with the project pipeline. Required scans are injected into the CI pipeline as new jobs +with a long, random job name. In the unlikely event of a job name collision, the security policy job +overwrites any pre-existing job in the pipeline. + +This feature has some overlap with [compliance framework pipelines](../../project/settings/#compliance-pipeline-configuration), +as we have not [unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). +For details on the similarities and differences between these features, see +[Enforce scan execution](../#enforce-scan-execution). + +## Scan execution policy editor + +NOTE: +Only project Owners have the [permissions](../../permissions.md#project-members-permissions) +to select Security Policy Project. + +Once your policy is complete, save it by selecting **Create via merge request** +at the bottom of the editor. You are redirected to the merge request on the project's +configured security policy project. If one does not link to your project, a security +policy project is automatically created. Existing policies can also be +removed from the editor interface by selecting **Delete policy** +at the bottom of the editor. + +All scan execution policy changes are applied through a background job that runs once every 10 +minutes. Allow up to 10 minutes for any policy changes committed to this project to take effect. + + + +The policy editor currently only supports the YAML mode. The Rule mode is tracked in the [Allow Users to Edit Rule-mode Scan Execution Policies in the Policy UI](https://gitlab.com/groups/gitlab-org/-/epics/5363) epic. + +## Scan execution policies schema + +The YAML file with scan execution policies consists of an array of objects matching scan execution +policy schema nested under the `scan_execution_policy` key. You can configure a maximum of 5 +policies under the `scan_execution_policy` key. + +When you save a new policy, GitLab validates its contents against [this JSON schema](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/validators/json_schemas/security_orchestration_policy.json). +If you're not familiar with how to read [JSON schemas](https://json-schema.org/), +the following sections and tables provide an alternative. + +| Field | Type | Possible values | Description | +|-------|------|-----------------|-------------| +| `scan_execution_policy` | `array` of scan execution policy | | List of scan execution policies (maximum 5) | + +## Scan execution policy schema + +| Field | Type | Possible values | Description | +|-------|------|-----------------|-------------| +| `name` | `string` | | Name of the policy. | +| `description` (optional) | `string` | | Description of the policy. | +| `enabled` | `boolean` | `true`, `false` | Flag to enable (`true`) or disable (`false`) the policy. | +| `rules` | `array` of rules | | List of rules that the policy applies. | +| `actions` | `array` of actions | | List of actions that the policy enforces. | + +## `pipeline` rule type + +This rule enforces the defined actions whenever the pipeline runs for a selected branch. + +| Field | Type | Possible values | Description | +|-------|------|-----------------|-------------| +| `type` | `string` | `pipeline` | The rule's type. | +| `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | + +## `schedule` rule type + +This rule enforces the defined actions and schedules a scan on the provided date/time. + +| Field | Type | Possible values | Description | +|------------|------|-----------------|-------------| +| `type` | `string` | `schedule` | The rule's type. | +| `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | +| `cadence` | `string` | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. | +| `clusters` | `object` | | The cluster where the given policy enforces running selected scans (only for `container_scanning`/`cluster_image_scanning` scans). The key of the object is the name of the Kubernetes cluster configured for your project in GitLab. In the optionally provided value of the object, you can precisely select Kubernetes resources that are scanned. | + +### `cluster` schema + +Use this schema to define `clusters` objects in the [`schedule` rule type](#schedule-rule-type). + +| Field | Type | Possible values | Description | +|--------------|---------------------|--------------------------|-------------| +| `containers` | `array` of `string` | | The container name that is scanned (only the first value is currently supported). | +| `resources` | `array` of `string` | | The resource name that is scanned (only the first value is currently supported). | +| `namespaces` | `array` of `string` | | The namespace that is scanned (only the first value is currently supported). | +| `kinds` | `array` of `string` | `deployment`/`daemonset` | The resource kind that should be scanned (only the first value is currently supported). | + +## `scan` action type + +This action executes the selected `scan` with additional parameters when conditions for at least one +rule in the defined policy are met. + +| Field | Type | Possible values | Description | +|-------|------|-----------------|-------------| +| `scan` | `string` | `dast`, `secret_detection`, `sast`, `container_scanning`, `cluster_image_scanning` | The action's type. | +| `site_profile` | `string` | Name of the selected [DAST site profile](../dast/index.md#site-profile). | The DAST site profile to execute the DAST scan. This field should only be set if `scan` type is `dast`. | +| `scanner_profile` | `string` or `null` | Name of the selected [DAST scanner profile](../dast/index.md#scanner-profile). | The DAST scanner profile to execute the DAST scan. This field should only be set if `scan` type is `dast`.| +| `variables` | `object` | | A set of CI variables, supplied as an array of `key: value` pairs, to apply and enforce for the selected scan. The `key` is the variable name, with its `value` provided as a string. This parameter supports any variable that the GitLab CI job supports for the specified scan. | + +Note the following: + +- You must create the [site profile](../dast/index.md#site-profile) and [scanner profile](../dast/index.md#scanner-profile) + with selected names for each project that is assigned to the selected Security Policy Project. + Otherwise, the policy is not applied and a job with an error message is created instead. +- Once you associate the site profile and scanner profile by name in the policy, it is not possible + to modify or delete them. If you want to modify them, you must first disable the policy by setting + the `active` flag to `false`. +- When configuring policies with a scheduled DAST scan, the author of the commit in the security + policy project's repository must have access to the scanner and site profiles. Otherwise, the scan + is not scheduled successfully. +- For a secret detection scan, only rules with the default ruleset are supported. [Custom rulesets](../secret_detection/index.md#custom-rulesets) + are not supported. +- A secret detection scan runs in `normal` mode when executed as part of a pipeline, and in + [`historic`](../secret_detection/index.md#full-history-secret-detection) + mode when executed as part of a scheduled scan. +- A container scanning and cluster image scanning scans configured for the `pipeline` rule type ignores the cluster defined in the `clusters` object. + They use predefined CI/CD variables defined for your project. Cluster selection with the `clusters` object is supported for the `schedule` rule type. + Cluster with name provided in `clusters` object must be created and configured for the project. To be able to successfully perform the `container_scanning`/`cluster_image_scanning` scans for the cluster you must follow instructions for the [Cluster Image Scanning feature](../cluster_image_scanning/index.md#prerequisites). +- The SAST scan uses the default template and runs in a [child pipeline](../../../ci/pipelines/parent_child_pipelines.md). + +## Example security policies project + +You can use this example in a `.gitlab/security-policies/policy.yml`, as described in +[Security policies project](index.md#security-policies-project). + +```yaml +--- +scan_execution_policy: +- name: Enforce DAST in every release pipeline + description: This policy enforces pipeline configuration to have a job with DAST scan for release branches + enabled: true + rules: + - type: pipeline + branches: + - release/* + actions: + - scan: dast + scanner_profile: Scanner Profile A + site_profile: Site Profile B +- name: Enforce DAST and secret detection scans every 10 minutes + description: This policy enforces DAST and secret detection scans to run every 10 minutes + enabled: true + rules: + - type: schedule + branches: + - main + cadence: "*/10 * * * *" + actions: + - scan: dast + scanner_profile: Scanner Profile C + site_profile: Site Profile D + - scan: secret_detection +- name: Enforce Secret Detection and Container Scanning in every default branch pipeline + description: This policy enforces pipeline configuration to have a job with Secret Detection and Container Scanning scans for the default branch + enabled: true + rules: + - type: pipeline + branches: + - main + actions: + - scan: secret_detection + - scan: sast + variables: + SAST_EXCLUDED_ANALYZERS: brakeman + - scan: container_scanning +- name: Enforce Cluster Image Scanning on production-cluster every 24h + description: This policy enforces Cluster Image Scanning scan to run every 24 hours + enabled: true + rules: + - type: schedule + cadence: "15 3 * * *" + clusters: + production-cluster: + containers: + - database + resources: + - production-application + namespaces: + - production-namespace + kinds: + - deployment + actions: + - scan: cluster_image_scanning +``` + +In this example: + +- For every pipeline executed on branches that match the `release/*` wildcard (for example, branch + `release/v1.2.1`), DAST scans run with `Scanner Profile A` and `Site Profile B`. +- DAST and secret detection scans run every 10 minutes. The DAST scan runs with `Scanner Profile C` + and `Site Profile D`. +- Secret detection, container scanning, and SAST scans run for every pipeline executed on the `main` + branch. The SAST scan runs with the `SAST_EXCLUDED_ANALYZER` variable set to `"brakeman"`. +- Cluster Image Scanning scan runs every 24h. The scan runs on the `production-cluster` cluster and fetches vulnerabilities + from the container with the name `database` configured for deployment with the name `production-application` in the `production-namespace` namespace. + +## Example for scan execution policy editor + +You can use this example in the YAML mode of the [scan execution policy editor](#scan-execution-policy-editor). +It corresponds to a single object from the previous example. + +```yaml +name: Enforce Secret Detection and Container Scanning in every default branch pipeline +description: This policy enforces pipeline configuration to have a job with Secret Detection and Container Scanning scans for the default branch +enabled: true +rules: + - type: pipeline + branches: + - main +actions: + - scan: secret_detection + - scan: container_scanning +``` diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md new file mode 100644 index 00000000000..7857de8c780 --- /dev/null +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -0,0 +1,175 @@ +--- +stage: Protect +group: Container Security +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Scan result policies **(ULTIMATE)** + +You can use scan result policies to take action based on scan results. For example, one type of scan +result policy is a security approval policy that allows approval to be required based on the +findings of one or more security scan jobs. Scan result policies are evaluated after a CI scanning +job is fully executed. + +## Scan result policy editor + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77814) in GitLab 14.8 with a flag named `scan_result_policy`. Disabled by default. + +NOTE: +Only project Owners have the [permissions](../../permissions.md#project-members-permissions) +to select Security Policy Project. + +Once your policy is complete, save it by selecting **Create merge request** at the bottom of the +editor. This redirects you to the merge request on the project's configured security policy project. +If a security policy project doesn't link to your project, GitLab creates such a project for you. +Existing policies can also be removed from the editor interface by selecting **Delete policy** at +the bottom of the editor. + +All scan result policy changes are applied through a background job that runs once every 10 minutes. +Allow up to 10 minutes for any policy changes committed to this project to take effect. + +The policy editor only supports YAML mode. To follow work on Rule mode, see the epic +[Allow Users to Edit Rule-mode scan result policies in the Policy UI](https://gitlab.com/groups/gitlab-org/-/epics/5363). + + + +## Scan result policies schema + +The YAML file with scan result policies consists of an array of objects matching the scan result +policy schema nested under the `scan_result_policy` key. You can configure a maximum of five +policies under the `scan_result_policy` key. + +When you save a new policy, GitLab validates its contents against [this JSON schema](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/validators/json_schemas/security_orchestration_policy.json). +If you're not familiar with how to read [JSON schemas](https://json-schema.org/), +the following sections and tables provide an alternative. + +| Field | Type | Possible values | Description | +|-------|------|-----------------|-------------| +| `scan_result_policy` | `array` of Scan Result Policy | | List of scan result policies (maximum 5). | + +## Scan result policy schema + +| Field | Type | Possible values | Description | +|-------|------|-----------------|-------------| +| `name` | `string` | | Name of the policy. | +| `description` (optional) | `string` | | Description of the policy. | +| `enabled` | `boolean` | `true`, `false` | Flag to enable (`true`) or disable (`false`) the policy. | +| `rules` | `array` of rules | | List of rules that the policy applies. | +| `actions` | `array` of actions | | List of actions that the policy enforces. | + +## `scan_finding` rule type + +This rule enforces the defined actions based on the information provided. + +| Field | Type | Possible values | Description | +|------------|------|-----------------|-------------| +| `type` | `string` | `scan_finding` | The rule's type. | +| `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | +| `scanners` | `array` of `string` | `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing` | The security scanners for this rule to consider. | +| `vulnerabilities_allowed` | `integer` | Greater than or equal to zero | Number of vulnerabilities allowed before this rule is considered. | +| `severity_levels` | `array` of `string` | `info`, `unknown`, `low`, `medium`, `high`, `critical`| The severity levels for this rule to consider. | +| `vulnerability_states` | `array` of `string` | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed` | The vulnerability states for this rule to consider when the target branch is set to the default branch. | + +## `require_approval` action type + +This action sets an approval rule to be required when conditions are met for at least one rule in +the defined policy. + +| Field | Type | Possible values | Description | +|-------|------|-----------------|-------------| +| `type` | `string` | `require_approval` | The action's type. | +| `approvals_required` | `integer` | Greater than or equal to zero | The number of MR approvals required. | +| `user_approvers` | `array` of `string` | Username of one of more users | The users to consider as approvers. | +| `user_approvers_ids` | `array` of `integer` | ID of one of more users | The IDs of users to consider as approvers. | +| `group_approvers` | `array` of `string` | Path of one of more groups | The groups to consider as approvers. | +| `group_approvers_ids` | `array` of `integer` | ID of one of more groups | The IDs of groups to consider as approvers. | + +Requirements and limitations: + +- You must add the respective [security scanning tools](../index.md#security-scanning-tools). + Otherwise, scan result policies won't have any effect. +- The maximum number of policies is five. +- Each policy can have a maximum of five rules. + +## Example security scan result policies project + +You can use this example in a `.gitlab/security-policies/policy.yml`, as described in +[Security policies project](index.md#security-policies-project): + +```yaml +--- +scan_result_policy: +- name: critical vulnerability CS approvals + description: critical severity level only for container scanning + enabled: true + rules: + - type: scan_finding + branches: + - main + scanners: + - container_scanning + vulnerabilities_allowed: 0 + severity_levels: + - critical + vulnerability_states: + - newly_detected + actions: + - type: require_approval + approvals_required: 1 + user_approvers: + - adalberto.dare +- name: secondary CS approvals + description: secondary only for container scanning + enabled: true + rules: + - type: scan_finding + branches: + - main + scanners: + - container_scanning + vulnerabilities_allowed: 1 + severity_levels: + - low + - unknown + vulnerability_states: + - newly_detected + actions: + - type: require_approval + approvals_required: 1 + user_approvers: + - sam.white +``` + +In this example: + +- Every MR that contains new `critical` vulnerabilities identified by container scanning requires + one approval from `alberto.dare`. +- Every MR that contains more than one new `low` or `unknown` vulnerability identified by container + scanning requires one approval from `sam.white`. + +## Example for Scan Result Policy editor + +You can use this example in the YAML mode of the [Scan Result Policy editor](#scan-result-policy-editor). +It corresponds to a single object from the previous example: + +```yaml +- name: critical vulnerability CS approvals + description: critical severity level only for container scanning + enabled: true + rules: + - type: scan_finding + branches: + - main + scanners: + - container_scanning + vulnerabilities_allowed: 1 + severity_levels: + - critical + vulnerability_states: + - newly_detected + actions: + - type: require_approval + approvals_required: 1 + user_approvers: + - adalberto.dare +``` diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index de2f9af82c7..3c0a2caf114 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -288,12 +288,14 @@ brakeman-sast: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235382) in GitLab 13.5. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for > passthrough chains. Expanded to include additional passthrough types of `file`, `git`, and `url` in GitLab 14.6. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in GitLab 14.8. You can customize the default scanning rules provided by our SAST analyzers. -Ruleset customization supports two capabilities that can be used +Ruleset customization supports the following that can be used simultaneously: - [Disabling predefined rules](index.md#disable-predefined-analyzer-rules). Available for all analyzers. +- [Overriding predefined rules](index.md#override-predefined-analyzer-rules). Available for all analyzers. - Modifying the default behavior of a given analyzer by [synthesizing and passing a custom configuration](index.md#synthesize-a-custom-configuration). Available for only `nodejs-scan`, `gosec`, and `semgrep`. To customize the default scanning rules, create a file containing custom rules. These rules @@ -343,6 +345,50 @@ and `sobelow` by matching the `type` and `value` of identifiers: value = "sql_injection" ``` +#### Override predefined analyzer rules + +To override analyzer rules: + +1. In one or more `ruleset.identifier` subsections, list the rules that you want to override. Every `ruleset.identifier` section has: + + - a `type` field, to name the predefined rule identifier that the targeted analyzer uses. + - a `value` field, to name the rule to be overridden. + +1. In the `ruleset.override` context of a `ruleset` section, + provide the keys to override. Any combination of keys can be + overridden. Valid keys are: + + - description + - message + - name + - severity (valid options are: Critical, High, Medium, Low, Unknown, Info) + +##### Example: Override predefined rules of SAST analyzers + +In the following example, rules from `eslint` +and `gosec` are matched by the `type` and `value` of identifiers and +then overridden: + +```toml +[eslint] + [[eslint.ruleset]] + [eslint.ruleset.identifier] + type = "eslint_rule_id" + value = "security/detect-object-injection" + [eslint.ruleset.override] + description = "OVERRIDDEN description" + message = "OVERRIDDEN message" + name = "OVERRIDDEN name" + severity = "Critical" +[gosec] + [[gosec.ruleset]] + [gosec.ruleset.identifier] + type = "CWE" + value = "CWE-79" + [gosec.ruleset.override] + severity = "Critical" +``` + #### Synthesize a custom configuration To create a custom configuration, you can use passthrough chains. @@ -639,15 +685,33 @@ variables: ### 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 -earlier stage in the pipeline. This is the current strategy when requiring -a `before_script` execution to prepare your scan job. +Most GitLab SAST analyzers directly scan your source code without compiling it first. +However, for technical reasons, some analyzers can only scan compiled code. + +By default, these analyzers automatically attempt to fetch dependencies and compile your code so it can be scanned. +Automatic compilation can fail if: + +- your project requires custom build configurations. +- you use language versions that aren't built into the analyzer. + +To resolve these issues, you can skip the analyzer's compilation step and directly provide artifacts from an earlier stage in your pipeline instead. +This strategy is called _pre-compilation_. + +Pre-compilation is available for the analyzers that support the `COMPILE` CI/CD variable. +See [Analyzer settings](#analyzer-settings) for the current list. + +To use pre-compilation: + +1. Output your project's dependencies to a directory in the project's working directory, then save that directory as an artifact by [setting the `artifacts: paths` configuration](../../../ci/yaml/index.md#artifactspaths). +1. Provide the `COMPILE: "false"` CI/CD variable to the analyzer to disable automatic compilation. +1. Add your compilation stage as a dependency for the analyzer job. + +To allow the analyzer to recognize the compiled artifacts, you must explicitly specify the path to +the vendored directory. +This configuration can vary per analyzer. For Maven projects, you can use `MAVEN_REPO_PATH`. +See [Analyzer settings](#analyzer-settings) for the complete list of available options. -To pass your project's dependencies as artifacts, the dependencies must be included -in the project's working directory and specified using the `artifacts:path` configuration. -If all dependencies are present, the `COMPILE=false` CI/CD variable can be provided to the -analyzer and compilation is skipped: +The following example pre-compiles a Maven project and provides it to the SpotBugs SAST analyzer: ```yaml stages: @@ -678,11 +742,6 @@ spotbugs-sast: sast: gl-sast-report.json ``` -To allow the analyzer to recognize the compiled artifacts, you must explicitly specify the path to -the vendored directory. This configuration can vary per analyzer but in the case of Java above, you -can use `MAVEN_REPO_PATH`. See -[Analyzer settings](#analyzer-settings) for the complete list of available options. - ### Available CI/CD variables SAST can be configured using the [`variables`](../../../ci/yaml/index.md#variables) parameter in @@ -779,7 +838,7 @@ Some analyzers can be customized with CI/CD variables. | `SAST_GOSEC_CONFIG` | Gosec | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/328301)** in GitLab 14.0 - use custom rulesets instead. Path to configuration for Gosec (optional). | | `PHPCS_SECURITY_AUDIT_PHP_EXTENSIONS` | phpcs-security-audit | Comma separated list of additional PHP Extensions. | | `SAST_DISABLE_BABEL` | NodeJsScan | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64025)** in GitLab 13.5 | -| `SAST_SEMGREP_METRICS` | Semgrep | Set to `"false"` to disable sending anonymized scan metrics to [r2c](https://r2c.dev/). Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330565) in GitLab 14.0. | +| `SAST_SEMGREP_METRICS` | Semgrep | Set to `"false"` to disable sending anonymized scan metrics to [r2c](https://r2c.dev/). Default: `true`. Introduced in GitLab 14.0 from the [confidential issue](../../project/issues/confidential_issues.md) `https://gitlab.com/gitlab-org/gitlab/-/issues/330565`. | #### Custom CI/CD variables @@ -819,86 +878,18 @@ variables: ## Reports JSON format -The SAST tool emits a JSON report file. For more information, see the -[schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/sast-report-format.json). - -The JSON report file can be downloaded from the CI pipelines page, or the -pipelines tab on merge requests by [setting `artifacts: paths`](../../../ci/yaml/index.md#artifactspaths) to `gl-sast-report.json`. For more information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md). - -Here's an example SAST report: - -```json-doc -{ - "version": "2.0", - "vulnerabilities": [ - { - "id": "9e96e0ab-23da-4d7d-a09e-0acbaa5e83ca", - "category": "sast", - "name": "Predictable pseudorandom number generator", - "message": "Predictable pseudorandom number generator", - "description": "The use of java.util.Random is predictable", - "severity": "Medium", - "confidence": "Medium", - "scanner": { - "id": "find_sec_bugs", - "name": "Find Security Bugs" - }, - "location": { - "file": "groovy/src/main/groovy/com/gitlab/security_products/tests/App.groovy", - "start_line": 47, - "end_line": 47, - "class": "com.gitlab.security_products.tests.App", - "method": "generateSecretToken2", - "dependency": { - "package": {} - } - }, - "identifiers": [ - { - "type": "find_sec_bugs_type", - "name": "Find Security Bugs-PREDICTABLE_RANDOM", - "value": "PREDICTABLE_RANDOM", - "url": "https://find-sec-bugs.github.io/bugs.htm#PREDICTABLE_RANDOM" - }, - { - "type": "cwe", - "name": "CWE-330", - "value": "330", - "url": "https://cwe.mitre.org/data/definitions/330.html" - } - ] - }, - { - "id": "e6dbf91f-4c07-46f7-a365-0169489c27d1", - "category": "sast", - "message": "Probable insecure usage of temp file/directory.", - "severity": "Medium", - "confidence": "Medium", - "scanner": { - "id": "bandit", - "name": "Bandit" - }, - "location": { - "file": "python/hardcoded/hardcoded-tmp.py", - "start_line": 10, - "end_line": 10, - "dependency": { - "package": {} - } - }, - "identifiers": [ - { - "type": "bandit_test_id", - "name": "Bandit Test ID B108", - "value": "B108", - "url": "https://docs.openstack.org/bandit/latest/plugins/b108_hardcoded_tmp_directory.html" - } - ] - }, - ], - "remediations": [] -} -``` +SAST outputs a report file in JSON format. The report file contains details of all found vulnerabilities. +To download the report file, you can either: + +- Download the file from the CI/CD pipelines page. +- In the pipelines tab on merge requests, set [`artifacts: paths`](../../../ci/yaml/index.md#artifactspaths) to `gl-sast-report.json`. + +For information, see [Download job artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). + +For details of the report file's schema, see +[SAST report file schema](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/sast-report-format.json). + +For an example SAST report file, see [`gl-secret-detection-report.json`](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/qa/expect/secrets/gl-secret-detection-report.json) example. ## Running SAST in an offline environment @@ -945,7 +936,7 @@ registry.gitlab.com/security-products/sast/spotbugs:2 The process for importing Docker images into a local offline Docker registry depends on **your network security policy**. Please consult your IT staff to find an accepted and approved -process by which external resources can be imported or temporarily accessed. These scanners are [periodically updated](../vulnerabilities/index.md#vulnerability-scanner-maintenance) +process by which external resources can be imported or temporarily accessed. These scanners are [periodically updated](../index.md#vulnerability-scanner-maintenance) with new definitions, and you may be able to make occasional updates on your own. For details on saving and transporting Docker images as a file, see Docker's documentation on diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index c5761a5743f..2ce2d59898f 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -63,7 +63,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 | **{dotted-circle}** | **{check-circle}** | +| Presentation of JSON Report in merge request | **{dotted-circle}** | **{check-circle}** | | View identified secrets in the pipelines' **Security** tab | **{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}** | @@ -182,14 +182,89 @@ Secret Detection can be customized by defining available CI/CD variables: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211387) in GitLab 13.5. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for > passthrough chains. Expanded to include additional passthrough types of `file`, `git`, and `url` in GitLab 14.6. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in GitLab 14.8. You can customize the default secret detection rules provided with GitLab. +Ruleset customization supports the following capabilities that can be used +simultaneously: + +- [Disabling predefined rules](index.md#disable-predefined-analyzer-rules). +- [Overriding predefined rules](index.md#override-predefined-analyzer-rules). +- Modifying the default behavior of the Secret Detection analyzer by [synthesizing and passing a custom configuration](index.md#synthesize-a-custom-configuration). Available for only `nodejs-scan`, `gosec`, and `semgrep`. + Customization allows replacing the default secret detection rules with rules that you define. To create a custom ruleset: 1. Create a `.gitlab` directory at the root of your project, if one doesn't already exist. 1. Create a custom ruleset file named `secret-detection-ruleset.toml` in the `.gitlab` directory. + +#### Disable predefined analyzer rules + +To disable analyzer rules: + +1. Set the `disabled` flag to `true` in the context of a `ruleset` section. + +1. In one or more `ruleset.identifier` subsections, list the rules that you want disabled. Every `ruleset.identifier` section has: + + - a `type` field, to name the predefined rule identifier. + - a `value` field, to name the rule to be disabled. + +##### Example: Disable predefined rules of Secret Detection analyzer + +In the following example, the disabled rules is assigned to `secrets` +by matching the `type` and `value` of identifiers: + +```toml +[secrets] + [[secrets.ruleset]] + disable = true + [secrets.ruleset.identifier] + type = "gitleaks_rule_id" + value = "RSA private key" +``` + +#### Override predefined analyzer rules + +To override rules: + +1. In one or more `ruleset.identifier` subsections, list the rules that you want to override. Every `ruleset.identifier` section has: + + - a `type` field, to name the predefined rule identifier that the Secret Detection analyzer uses. + - a `value` field, to name the rule to be overridden. + +1. In the `ruleset.override` context of a `ruleset` section, + provide the keys to override. Any combination of keys can be + overridden. Valid keys are: + + - description + - message + - name + - severity (valid options are: Critical, High, Medium, Low, Unknown, Info) + +##### Example: Override predefined rules of Secret Detection analyzer + +In the following example, rules +are matched by the `type` and `value` of identifiers and +then overridden: + +```toml +[secrets] + [[secrets.ruleset]] + [secrets.ruleset.identifier] + type = "gitleaks_rule_id" + value = "RSA private key" + [secrets.ruleset.override] + description = "OVERRIDDEN description" + message = "OVERRIDDEN message" + name = "OVERRIDDEN name" + severity = "Info" +``` + +#### Synthesize a custom configuration + +To create a custom configuration, you can use passthrough chains. + 1. In the `secret-detection-ruleset.toml` file, do one of the following: - Define a custom ruleset: @@ -239,31 +314,8 @@ From highest to lowest severity, the logging levels are: ## Post-processing and revocation -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4639) in GitLab 13.6. - -Upon detection of a secret, GitLab supports post-processing hooks. These can be used to take actions like notifying the cloud service who issued the secret. The cloud provider can confirm the credentials and take remediation actions like revoking or reissuing a new secret and notifying the creator of the secret. Post-processing workflows vary by supported cloud providers. - -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). - -NOTE: -Post-processing is currently limited to a project's default branch, see the above epic for future efforts to support additional branches. - -```mermaid -sequenceDiagram - autonumber - Rails->>+Sidekiq: gl-secret-detection-report.json - Sidekiq-->+Sidekiq: Ci::BuildFinishedWorker - Sidekiq-->+RevocationAPI: GET revocable keys types - RevocationAPI-->>-Sidekiq: OK - Sidekiq->>+RevocationAPI: POST revoke revocable keys - RevocationAPI-->>-Sidekiq: ACCEPTED - RevocationAPI-->>+Cloud Vendor: revoke revocable keys - Cloud Vendor-->>+RevocationAPI: ACCEPTED -``` +Upon detection of a secret, GitLab SaaS supports post-processing hooks. +For more information, see [Post-processing and revocation](post_processing.md). ## Full History Secret Detection @@ -316,7 +368,7 @@ registry.gitlab.com/security-products/secret-detection:3 The process for importing Docker images into a local offline Docker registry depends on **your network security policy**. Please consult your IT staff to find an accepted and approved -process by which external resources can be imported or temporarily accessed. These scanners are [periodically updated](../vulnerabilities/index.md#vulnerability-scanner-maintenance) +process by which external resources can be imported or temporarily accessed. These scanners are [periodically updated](../index.md#vulnerability-scanner-maintenance) with new definitions, and you may be able to make occasional updates on your own. For details on saving and transporting Docker images as a file, see Docker's documentation on @@ -370,7 +422,7 @@ For information on this, see the [general Application Security troubleshooting s ### Error: `Couldn't run the gitleaks command: exit status 2` -If a pipeline is triggered from a Merge Request containing 60 commits while the `GIT_DEPTH` variable's +If a pipeline is triggered from a merge request containing 60 commits while the `GIT_DEPTH` variable's value is less than that, the Secret Detection job fails as the clone is not deep enough to contain all of the relevant commits. For information on the current default value, see the [pipeline configuration documentation](../../../ci/pipelines/settings.md#limit-the-number-of-changes-fetched-during-clone). @@ -395,3 +447,12 @@ secret_detection: variables: GIT_DEPTH: 100 ``` + +### `secret-detection` job fails with `ERR fatal: ambiguous argument` message + +Your `secret-detection` job can fail with `ERR fatal: ambiguous argument` error if your +repository's default branch is unrelated to the branch the job was triggered for. +See issue [!352014](https://gitlab.com/gitlab-org/gitlab/-/issues/352014) for more details. + +To resolve the issue, make sure to correctly [set your default branch](../../project/repository/branches/default.md#change-the-default-branch-name-for-a-project) on your repository. You should set it to a branch +that has related history with the branch you run the `secret-detection` job on. diff --git a/doc/user/application_security/secret_detection/post_processing.md b/doc/user/application_security/secret_detection/post_processing.md new file mode 100644 index 00000000000..972558c3b95 --- /dev/null +++ b/doc/user/application_security/secret_detection/post_processing.md @@ -0,0 +1,179 @@ +--- +stage: Secure +group: Static Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Secret Detection post-processing and revocation **(FREE SAAS)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4639) in GitLab 13.6. + +GitLab supports running post-processing hooks after detecting a secret. These +hooks can perform actions, like notifying the cloud service that issued the secret. +The cloud provider can then confirm the credentials and take remediation actions, like: + +- Revoking a secret. +- Reissuing a secret. +- Notifying the creator of the secret. + +GitLab SaaS supports post-processing for Amazon Web Services (AWS). +Post-processing workflows vary by supported cloud providers. + +Post-processing is limited to a project's default branch. The epic +[Post-processing of leaked secrets](https://gitlab.com/groups/gitlab-org/-/epics/4639). +contains: + +- Technical details of post-processing secrets. +- Discussions of efforts to support additional branches. + +NOTE: +Post-processing is currently limited to a project's default branch + +## High-level architecture + +This diagram describes how a post-processing hook revokes a secret within the GitLab application: + +```mermaid +sequenceDiagram + autonumber + GitLab Rails->>+Sidekiq: gl-secret-detection-report.json + Sidekiq-->+Sidekiq: StoreSecurityReportsWorker + Sidekiq-->+RevocationAPI: GET revocable keys types + RevocationAPI-->>-Sidekiq: OK + Sidekiq->>+RevocationAPI: POST revoke revocable keys + RevocationAPI-->>-Sidekiq: ACCEPTED + RevocationAPI-->>+Cloud Vendor: revoke revocable keys + Cloud Vendor-->>+RevocationAPI: ACCEPTED +``` + +## Integrate your cloud provider service with GitLab Saas + +Third party cloud and SaaS providers can [express integration interest by filling out this form](https://forms.gle/wWpvrtLRK21Q2WJL9). + +### Implement a vendor revocation receiver service + +A vendor revocation receiver service integrates with a GitLab instance to receive +a web notification and respond to leaked token requests. + +To implement a receiver service to revoke leaked tokens: + +1. Create a publicly accessible HTTP service matching the corresponding API contract + below. Your service should be idempotent and rate-limited. +1. When a pipeline corresponding to its revocable token type (in the example, `my_api_token`) + completes, GitLab sends a request to your receiver service. +1. The included URL should be publicly accessible, and contain the commit where the + leaked token can be found. For example: + + ```plaintext + POST / HTTP/2 + Accept: */* + Content-Type: application/json + X-Gitlab-Token: MYSECRETTOKEN + + [ + {"type": "my_api_token", "token":"XXXXXXXXXXXXXXXX","url": "https://example.com/some-repo/blob/abcdefghijklmnop/compromisedfile1.java"} + ] + ``` + +## Implement a revocation service for self-managed + +Self-managed instances interested in using the revocation capabilities must: + +- Deploy the [RevocationAPI](#high-level-architecture). +- Configure the GitLab instance to use the RevocationAPI. + +A RevocationAPI must: + +- Match a minimal API specification. +- Provide two endpoints: + - Fetching revocable token types. + - Revoking leaked tokens. +- Be rate-limited and idempotent. + +Requests to the documented endpoints are authenticated via API tokens passed in +the `Authorization` header. Request and response bodies, if present, are +expected to have the content type `application/json`. + +All endpoints may return these responses: + +- `401 Unauthorized` +- `405 Method Not Allowed` +- `500 Internal Server Error` + +### `GET /v1/revocable_token_types` + +Returns the valid `type` values for use in the `revoke_tokens` endpoint. + +NOTE: +These values match the concatenation of [the `secrets` analyzer's](index.md) +[primary identifier](../../../development/integrations/secure.md#identifiers) by means +of concatenating the `primary_identifier.type` and `primary_identifier.value`. +In the case below, a finding identifier matches: + +```json +{"type": "gitleaks_rule_id", "name": "Gitleaks rule ID GitLab Personal Access Token", "value": "GitLab Personal Access Token"} +``` + +| Status Code | Description | +| ----- | --- | +| `200` | The response body contains the valid token `type` values. | + +Example response body: + +```json +{ + "types": ["gitleaks_rule_id_gitlab_personal_access_token"] +} +``` + +### `POST /v1/revoke_tokens` + +Accepts a list of tokens to be revoked by the appropriate provider. + +| Status Code | Description | +| ----- | --- | +| `204` | All submitted tokens have been accepted for eventual revocation. | +| `400` | The request body is invalid or one of the submitted token types is not supported. The request should not be retried. | +| `429` | The provider has received too many requests. The request should be retried later. | + +Example request body: + +```json +[{ + "type": "gitleaks_rule_id_gitlab_personal_access_token", + "token": "glpat--8GMtG8Mf4EnMJzmAWDU", + "location": "https://example.com/some-repo/blob/abcdefghijklmnop/compromisedfile1.java" +}, +{ + "type": "gitleaks_rule_id_gitlab_personal_access_token", + "token": "glpat--tG84EGK33nMLLDE70zU", + "location": "https://example.com/some-repo/blob/abcdefghijklmnop/compromisedfile2.java" +}] +``` + +### Configure GitLab to interface with RevocationAPI + +You must configure the following database settings in the GitLab instance: + +- `secret_detection_token_revocation_enabled` +- `secret_detection_token_revocation_url` +- `secret_detection_token_revocation_token` +- `secret_detection_revocation_token_types_url` + +For example, to configure these values in the +[Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): + +```ruby +::Gitlab::CurrentSettings.update!(secret_detection_token_revocation_token: 'MYSECRETTOKEN') +::Gitlab::CurrentSettings.update!(secret_detection_token_revocation_url: 'https://example.gitlab.com/revocation_service/v1/revoke_tokens') +::Gitlab::CurrentSettings.update!(secret_detection_revocation_token_types_url: 'https://example.gitlab.com/revocation_service/v1/revocable_token_types') +::Gitlab::CurrentSettings.update!(secret_detection_token_revocation_enabled: true) +``` + +After you configure these values, completing a pipeline performs these actions: + +1. The revocation service is triggered once. +1. A request is made to `secret_detection_revocation_token_types_url` to fetch a + list of revocable tokens. +1. Any Secret Detection findings matching the results of the `token_types` request + are included in the subsequent revocation request. diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 937ca33c3a1..a0cfd6d9d77 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -75,7 +75,7 @@ To view the total number of vulnerabilities per scan: Depending on the type of security scanner, you can download: -- A JSON artifact that contains the security scanner [report]('https://docs.gitlab.com/ee/development/integrations/secure.html#report'). +- A JSON artifact that contains the security scanner [report](../../../development/integrations/secure.md#report). - A CSV file that contains URLs and endpoints scanned by the security scanner. To download a security scan output: diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index ae5f6ba0fe1..390882d4326 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -7,7 +7,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Threat Monitoring **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14707) in GitLab 12.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14707) in GitLab 12.9. +> - [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. + +WARNING: +Threat Monitoring is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) +for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 15.0. The **Threat Monitoring** page provides alerts and metrics for the GitLab application runtime security features. You can access diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 9aa8a0cd3cd..7b39002bac3 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -1,5 +1,4 @@ --- -type: reference, howto stage: Secure group: Threat Insights info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments @@ -160,23 +159,3 @@ To manually apply the patch that GitLab generated for a vulnerability: 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. - -## Vulnerability scanner maintenance - -The following vulnerability scanners and their databases are regularly updated: - -| Secure scanning tool | Vulnerabilities database updates | -|:----------------------------------------------------------------|----------------------------------| -| [Container Scanning](../container_scanning/index.md) | A job runs on a daily basis to build new images with the latest vulnerability database updates from the upstream scanner. | -| [Dependency Scanning](../dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for npm packages), and `gemnasium` (the GitLab tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated on a daily basis using [data from NVD, the `ruby-advisory-db` and the GitHub Security Advisory Database as data sources](https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/blob/master/SOURCES.md). 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/main/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. | - -You do not have to update GitLab to benefit from the latest vulnerabilities definitions. -The security tools are released as Docker images. The vendored job definitions that enable them use -major release tags according to [semantic versioning](https://semver.org/). Each new release of the -tools overrides these tags. -The Docker images are updated to match the previous GitLab releases. Although -you automatically get the latest versions of the scanning tools, -there are some [known issues](https://gitlab.com/gitlab-org/gitlab/-/issues/9725) -with this approach. diff --git a/doc/user/application_security/vulnerabilities/severities.md b/doc/user/application_security/vulnerabilities/severities.md index f3e8e98bce3..89464064ea3 100644 --- a/doc/user/application_security/vulnerabilities/severities.md +++ b/doc/user/application_security/vulnerabilities/severities.md @@ -35,10 +35,10 @@ the following tables: ## SAST -| GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example | -|--------------------------------------------------------------------------------------------------------|--------------------------|----------------------------|------------------------------------| -| [`security-code-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) | **{dotted-circle}** No | N/A | N/A | -| [`brakeman`](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) | **{dotted-circle}** No | N/A | N/A | +| GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example | +|----------------------------------------------------------------------------------------------------------|--------------------------|----------------------------|------------------------------------| +| [`security-code-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) | **{check-circle}** Yes | String | `CRITICAL`, `HIGH`, `MEDIUM` in [analyzer version 3.2.0 and later](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan/-/blob/master/CHANGELOG.md#v320). In earlier versions, hardcoded to `Unknown`. | +| [`brakeman`](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) | **{check-circle}** Yes | String | `HIGH`, `MEDIUM`, `LOW` | | [`sobelow`](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) | **{check-circle}** Yes | N/A | Hardcodes all severity levels to `Unknown` | | [`nodejs-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan) | **{check-circle}** Yes | String | `INFO`, `WARNING`, `ERROR` | | [`flawfinder`](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder) | **{check-circle}** Yes | Integer | `0`, `1`, `2`, `3`, `4`, `5` | diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index 05ff5c511f9..ba1455ab70a 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -7,7 +7,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Vulnerability Report **(ULTIMATE)** -The Vulnerability Report provides information about vulnerabilities from scans of the default branch. It is available for projects, groups, and the Security Center. +The Vulnerability Report provides information about vulnerabilities from scans of the default branch. It contains cumulative results of all successful jobs, regardless of whether the pipeline was successful. + +The scan results from a pipeline are only ingested after all the jobs in the pipeline complete. Partial results for a pipeline with jobs in progress can be seen in the pipeline security tab. + +The report is available for projects, groups, and the Security Center. At all levels, the Vulnerability Report contains: diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index da75c008ed1..80c85358fcb 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -232,6 +232,11 @@ v1.0, 2019-01-01 #### Includes +NOTE: +[Wiki pages](project/wiki/index.md#create-a-new-wiki-page) created with the AsciiDoc +format are saved with the file extension `.asciidoc`. When working with AsciiDoc wiki +pages, change the file name from `.adoc` to `.asciidoc`. + ```plaintext include::basics.adoc[] diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md index f1c49b87383..5fe772d9686 100644 --- a/doc/user/clusters/agent/ci_cd_tunnel.md +++ b/doc/user/clusters/agent/ci_cd_tunnel.md @@ -12,53 +12,52 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) to GitLab Free in 14.5. > - Support for Omnibus installations was [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5686) in GitLab 14.5. -The CI/CD Tunnel enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network -connectivity between GitLab Runner and a cluster. GitLab Runner does not have to be running in the same cluster. +To use GitLab CI/CD to safely deploy your application to a cluster, you can use the CI/CD Tunnel. -Only CI/CD jobs set in the configuration project can access one of the configured agents. +You can authorize multiple projects to access the same cluster, so you +can keep your application's codebase in one repository and configure +your cluster in another. This method is scalable and can save you resources. -## Prerequisites - -- An existing Kubernetes cluster. -- An agent [installed on your cluster](install/index.md#install-the-agent-into-the-cluster). +To ensure access to your cluster is safe, only the projects you +authorize can access your Agent through the CI/CD Tunnel. -## Use the CI/CD Tunnel to run Kubernetes commands from GitLab CI/CD - -If your project has access to one or more Agent records available, its CI/CD -jobs provide a `KUBECONFIG` variable compatible with `kubectl`. +## Prerequisites -Also, each Agent has a separate context (`kubecontext`). By default, -there isn't any context selected. -Contexts are named in the following format: `<agent-configuration-project-path>:<agent-name>`. -To get the list of available contexts, run `kubectl config get-contexts`. +To use the CI/CD Tunnel, you need an existing Kubernetes cluster connected to GitLab through the +[GitLab Agent](install/index.md#install-the-agent-onto-the-cluster). -## Share the CI/CD Tunnel provided by an Agent with other projects and groups +To run your CI/CD jobs using the CI/CD Tunnel, you do not need to have a runner in the same cluster. -The Agent can be configured to enable access to the CI/CD Tunnel to other projects or all the projects under a given group. This way you can have a single agent serving all the requests for several projects saving on resources and maintenance. +## How the CI/CD Tunnel works -You can read more on how to [authorize access in the Agent configuration reference](repository.md#authorize-projects-and-groups-to-use-an-agent). +When you authorize a project to use an Agent, the Tunnel automatically +injects a `KUBECONFIG` variable into its CI/CD jobs. This way, you can +run `kubectl` commands from GitLab CI/CD scripts that belong to the +authorized project. -## Restrict access of authorized projects and groups **(PREMIUM)** +When you authorize a group, all the projects that belong to that group +become authorized to access the selected Agent. -You can [configure various impersonations](repository.md#use-impersonation-to-restrict-project-and-group-access) to restrict the permissions of a shared CI/CD Tunnel. +An Agent can only authorize projects or groups in the same group +hierarchy as the Agent's configuration project. You can authorize +up to 100 projects and 100 groups per Agent. -## Example for a `kubectl` command using the CI/CD Tunnel +Also, each Agent has a separate context (`kubecontext`). +The Tunnel uses this information to safely allow access to the cluster from +jobs running in the projects you authorized. -The following example shows a CI/CD job that runs a `kubectl` command using the CI/CD Tunnel. -You can run any Kubernetes-specific commands similarly, such as `kubectl`, `helm`, -`kpt`, and so on. To do so: +### `~/.kube/cache` permissions + +`kubectl` and other tools based on the same libraries (such as Helm, `kpt`, and `kustomize`) cache information about +the cluster in `~/.kube/cache`. If this directory is not writable, the tool fetches information on each invocation, +making interactions slower and creating unnecessary load on the cluster. Make sure that this directory in the container image +you use is writable for the best experience. -1. Set your Agent's context in the first command with the format `<agent-configuration-project-path>:<agent-name>`. -1. Run Kubernetes commands. +## Configure the CI/CD Tunnel -For example: +The CI/CD Tunnel is configured directly through the +Agent's configuration file ([`config.yaml`](repository.md)) to: -```yaml - deploy: - image: - name: bitnami/kubectl:latest - entrypoint: [""] - script: - - kubectl config use-context path/to/agent-configuration-project:your-agent-name - - kubectl get pods -``` +- Authorize [projects](repository.md#authorize-projects-to-use-an-agent) and [groups](repository.md#authorize-groups-to-use-an-agent) to use the same Agent. +- [Run `kubectl` commands using the CI/CD Tunnel](repository.md#run-kubectl-commands-using-the-cicd-tunnel). +- [Restrict access of authorized projects and groups through impersonation strategies](repository.md#use-impersonation-to-restrict-project-and-group-access). diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index a235c0ef6f8..3fb141e402f 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -4,60 +4,71 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Agent for Kubernetes **(FREE)** +# Connecting a Kubernetes cluster with GitLab > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in GitLab 13.4. > - Support for `grpcs` [introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) in GitLab 13.6. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300960) in GitLab 13.10, KAS became available on GitLab.com under `wss://kas.gitlab.com` through an Early Adopter Program. -> - Introduced in GitLab 13.11, the GitLab Agent became available to every project on GitLab.com. +> - Agent Server [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300960) on GitLab.com under `wss://kas.gitlab.com` through an Early Adopter Program in GitLab 13.10. +> - The agent became available to every project on GitLab.com in GitLab 13.11. > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5. -> - [Renamed](https://gitlab.com/groups/gitlab-org/-/epics/7167) from "GitLab Kubernetes Agent" to "GitLab Agent for Kubernetes" in GitLab 14.6. +> - [Renamed](https://gitlab.com/groups/gitlab-org/-/epics/7167) from "GitLab Kubernetes Agent" to "GitLab agent for Kubernetes" in GitLab 14.6. -The [GitLab Agent for Kubernetes](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) ("Agent", for short) -is an active in-cluster component for connecting Kubernetes clusters to GitLab safely to support cloud-native deployment, management, and monitoring. +You can connect your Kubernetes cluster with GitLab to deploy, manage, +and monitor your cloud-native solutions. You can choose from two primary workflows. -The Agent is installed into the cluster through code, providing you with a fast, safe, stable, and scalable solution. +In a **GitOps workflow**, you keep your Kubernetes manifests in GitLab. You install a GitLab agent in your cluster, and +any time you update your manifests, the agent updates the cluster. This workflow is fully driven with Git and is considered pull-based, +because the cluster is pulling updates from your GitLab repository. + +In a **CI/CD** workflow, you use GitLab CI/CD to query and update your cluster by using the Kubernetes API. +This workflow is considered push-based, because GitLab is pushing requests from GitLab CI/CD to your cluster. + +Both of these workflows require you to [install an agent in your cluster](install/index.md). + +## Supported cluster versions + +GitLab supports the following Kubernetes versions. You can upgrade your +Kubernetes version to a supported version at any time: + +- 1.20 (support ends on July 22, 2022) +- 1.19 (support ends on February 22, 2022) +- 1.18 (support ends on November 22, 2021) +- 1.17 (support ends on September 22, 2021) + +GitLab supports at least two production-ready Kubernetes minor +versions at any given time. GitLab regularly reviews the supported versions and +provides a three-month deprecation period before removing support for a specific +version. The list of supported versions is based on: + +- The versions supported by major managed Kubernetes providers. +- The versions [supported by the Kubernetes community](https://kubernetes.io/releases/version-skew-policy/#supported-versions). + +[This epic](https://gitlab.com/groups/gitlab-org/-/epics/4827) tracks support for other Kubernetes versions. + +Some GitLab features might work on versions not listed here. + +## Using Kubernetes with GitOps **(PREMIUM)** With GitOps, you can manage containerized clusters and applications from a Git repository that: - Is the single source of truth of your system. - Is the single place where you operate your system. -- Is a single resource to monitor your system. -By combining GitLab, Kubernetes, and GitOps, it results in a robust infrastructure: +By combining GitLab, Kubernetes, and GitOps, you can have: - GitLab as the GitOps operator. - Kubernetes as the automation and convergence system. -- GitLab CI/CD as the Continuous Integration and Continuous Deployment engine. +- GitLab CI/CD for Continuous Integration and the agent for Continuous Deployment. Beyond that, you can use all the features offered by GitLab as the all-in-one DevOps platform for your product and your team. -## Agent's features +### GitOps workflow **(PREMIUM)** -By using the Agent, you can: - -- Connect GitLab with a Kubernetes cluster behind a firewall or a -Network Address Translation (NAT). -- Have real-time access to API endpoints in your cluster from GitLab CI/CD. -- Use GitOps to configure your cluster through the [Agent's repository](repository.md). -- Perform pull-based or push-based GitOps deployments. -- Configure [Network Security Alerts](#kubernetes-network-security-alerts) -based on [Container Network Policies](../../application_security/policies/index.md#container-network-policy). -- Track objects applied to your cluster through [inventory objects](../../infrastructure/clusters/deploy/inventory_object.md). -- Use the [CI/CD Tunnel](ci_cd_tunnel.md) to access Kubernetes clusters -from GitLab CI/CD jobs while keeping the cluster's APIs safe and unexposed -to the internet. -- [Deploy the GitLab Runner in a Kubernetes cluster](https://docs.gitlab.com/runner/install/kubernetes-agent.html). - -See the [Agent roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329) to track its development. - -To contribute to the Agent, see the [Agent's development documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/doc). - -## Agent's GitOps workflow **(PREMIUM)** - -The Agent uses multiple GitLab projects to provide a flexible workflow +The agent uses multiple GitLab projects to provide a flexible workflow that can suit various needs. This diagram shows these repositories and the main +The agent uses multiple GitLab projects to provide a flexible workflow. +This diagram shows these repositories and the main actors involved in a deployment: ```mermaid @@ -65,7 +76,7 @@ sequenceDiagram participant D as Developer participant A as Application code repository participant M as Manifest repository - participant K as GitLab Agent + participant K as GitLab agent participant C as Agent configuration repository loop Regularly K-->>C: Grab the configuration @@ -78,61 +89,28 @@ sequenceDiagram end ``` -For more details, refer to our [architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture) in the Agent project. - -## Install the Agent in your cluster - -See how to [install the Agent in your cluster](install/index.md). - -## GitOps deployments **(PREMIUM)** - -To perform GitOps deployments with the Agent, you need: +For details, view the [architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture). -- A properly-configured Kubernetes cluster where the Agent is running. -- A [configuration repository](repository.md) that contains a -`config.yaml` file, which tells the Agent the repositories to synchronize -with the cluster. -- A manifest repository that contains manifest files. Any changes to manifest files are applied to the cluster. +To perform GitOps deployments, you need: -You can use a single GitLab project or different projects for the Agent -configuration and manifest files, as follows: +- A properly-configured Kubernetes cluster where the GitLab agent is running. +- A project that contains the agent's configuration file (`config.yaml`) in the repository. + This file tells the agent which repositories to synchronize with the cluster. +- A project that contains Kubernetes manifests. Any changes to manifests are applied to the cluster. -- Single GitLab project (recommended): When you use a single repository to hold - both the manifest and the configuration files, these projects can be either - private or public. -- Two GitLab projects: When you use two different GitLab projects (one for - manifest files and another for configuration files), the manifests project must - be public, while the configuration project can be either private or public. +You can keep the agent's configuration file and Kubernetes manifests in one project, or you can use multiple. -Support for separated private manifest and configuration repositories is tracked in this [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/220912). +- One GitLab project (recommended): When you use one project for both the Kubernetes manifests + and the agent's configuration file, the projects can be either private or public. +- Two GitLab projects: When you use two different GitLab projects (one for Kubernetes + manifests and another for the agent's configuration file), the project with Kubernetes manifests must + be public. The project with the agent's configuration file can be either private or public. -## Kubernetes Network Security Alerts **(ULTIMATE)** - -The GitLab Agent also provides an integration with Cilium. This integration provides a simple way to -generate network policy-related alerts and to surface those alerts in GitLab. - -There are several components that work in concert for the Agent to generate the alerts: - -- A working Kubernetes cluster. -- Cilium integration through either of these options: - - Installation through [cluster management template](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium). - - Enablement of [hubble-relay](https://docs.cilium.io/en/v1.8/concepts/overview/#hubble) on an - existing installation. -- One or more network policies through any of these options: - - Use the [Container Network Policy editor](../../application_security/policies/index.md#container-network-policy-editor) to create and manage policies. - - Use an [AutoDevOps](../../application_security/policies/index.md#container-network-policy) configuration. - - Add the required labels and annotations to existing network policies. -- A configuration repository with [Cilium configured in `config.yaml`](repository.md#surface-network-security-alerts-from-cluster-to-gitlab) - -The setup process follows the same [Agent's installation steps](install/index.md), -with the following differences: - -- When you define a configuration repository, you must do so with [Cilium settings](repository.md#surface-network-security-alerts-from-cluster-to-gitlab). -- You do not need to specify the `gitops` configuration section. +Support for separate private projects is tracked in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/283885). ## Remove an agent -You can remove an agent using the [GitLab UI](#remove-an-agent-through-the-gitlab-ui) or through the [GraphQL API](#remove-an-agent-with-the-gitlab-graphql-api). +You can remove an agent by using the [GitLab UI](#remove-an-agent-through-the-gitlab-ui) or the [GraphQL API](#remove-an-agent-with-the-gitlab-graphql-api). ### Remove an agent through the GitLab UI @@ -140,16 +118,16 @@ You can remove an agent using the [GitLab UI](#remove-an-agent-through-the-gitla To remove an agent from the UI: -1. Go to your agent's configuration repository. -1. From your project's sidebar, select **Infrastructure > Kubernetes clusters**. -1. Select your agent from the table, and then in the **Options** column, click the vertical ellipsis -(**{ellipsis_v}**) button and select **Delete agent**. +1. On the top bar, select **Menu > Projects** and find the project that contains the agent's configuration file. +1. From the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. In the table, in the row for your agent, in the **Options** column, select the vertical ellipsis (**{ellipsis_v}**). +1. Select **Delete agent**. ### Remove an agent with the GitLab GraphQL API 1. Get the `<cluster-agent-token-id>` from a query in the interactive GraphQL explorer. -For GitLab.com, go to <https://gitlab.com/-/graphql-explorer> to open GraphQL Explorer. -For self-managed GitLab instances, go to `https://gitlab.example.com/-/graphql-explorer`, replacing `gitlab.example.com` with your own instance's URL. + - For GitLab.com, go to <https://gitlab.com/-/graphql-explorer> to open GraphQL Explorer. + - For self-managed GitLab, go to `https://gitlab.example.com/-/graphql-explorer`, replacing `gitlab.example.com` with your instance's URL. ```graphql query{ @@ -195,185 +173,48 @@ For self-managed GitLab instances, go to `https://gitlab.example.com/-/graphql-e } ``` -1. Delete the Agent in your cluster: +1. Delete the agent in your cluster: ```shell kubectl delete -n gitlab-kubernetes-agent -f ./resources.yml ``` -## Migrating to the GitLab Agent from the legacy certificate-based integration - -Find out how to [migrate to the GitLab Agent for Kubernetes](../../infrastructure/clusters/migrate_to_gitlab_agent.md) from the certificate-based integration depending on the features you use. - -## Troubleshooting - -If you face any issues while using the Agent, read the -service logs with the following command: - -```shell -kubectl logs -f -l=app=gitlab-kubernetes-agent -n gitlab-kubernetes-agent -``` - -GitLab administrators can additionally view the [GitLab Agent Server logs](../../../administration/clusters/kas.md#troubleshooting). - -### Agent logs - -#### Transport: Error while dialing failed to WebSocket dial +## Migrating to the agent from the legacy certificate-based integration -```json -{ - "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. - -```json -{ - "level": "error", - "time": "2021-06-25T21:15:45.335Z", - "msg": "Reverse tunnel", - "mod_name": "reverse_tunnel", - "error": "Connect(): rpc error: code = Unavailable desc = connection error: desc= \"transport: Error while dialing failed to WebSocket dial: expected handshake response status code 101 but got 301\"" -} -``` - -This error occurs if the `kas-address` doesn't include a trailing slash. To fix it, make sure that the -`wss` or `ws` URL ends with a trailing slash, such as `wss://GitLab.host.tld:443/-/kubernetes-agent/` -or `ws://GitLab.host.tld:80/-/kubernetes-agent/`. - -#### ValidationError(Deployment.metadata) - -```json -{ - "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]" -} -``` +Find out how to [migrate to the agent for Kubernetes](../../infrastructure/clusters/migrate_to_gitlab_agent.md) from the certificate-based integration. -This error is shown if a manifest file is malformed, and Kubernetes can't -create specified objects. Make sure that your manifest files are valid. You -may try using them to create objects in Kubernetes directly for more troubleshooting. +## Kubernetes network security alerts **(ULTIMATE)** -#### Error while dialing failed to WebSocket dial: failed to send handshake request - -```json -{ - "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>:8150`. - -#### Decompressor is not installed for grpc-encoding - -```json -{ - "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\"" -} -``` +> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. -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. +WARNING: +Cilium integration is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) +for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 15.0. -#### Certificate signed by unknown authority +The agent for Kubernetes also provides an integration with Cilium. This integration provides a simple way to +generate network policy-related alerts and to surface those alerts in GitLab. -```json -{ - "level": "error", - "time": "2021-02-25T07:22:37.158Z", - "msg": "Reverse tunnel", - "mod_name": "reverse_tunnel", - "error": "Connect(): 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/\\\": x509: certificate signed by unknown authority\"" -} -``` +Several components work in concert for the agent to generate the alerts: -This error is shown if your GitLab instance is using a certificate signed by an internal CA that -is unknown to the agent. One approach to fixing it is to present the CA certificate file to the agent -via a Kubernetes `configmap` and mount the file in the agent `/etc/ssl/certs` directory from where it -will be picked up automatically. +- A working Kubernetes cluster. +- Cilium integration through either of these options: + - Installation through [cluster management template](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium). + - Enablement of [hubble-relay](https://docs.cilium.io/en/v1.8/concepts/overview/#hubble) on an + existing installation. +- One or more network policies through any of these options: + - Use the [Container Network Policy editor](../../application_security/policies/index.md#container-network-policy-editor) to create and manage policies. + - Use an [AutoDevOps](../../application_security/policies/index.md#container-network-policy) configuration. + - Add the required labels and annotations to existing network policies. +- A configuration repository with [Cilium configured in `config.yaml`](repository.md#surface-network-security-alerts-from-cluster-to-gitlab) -For example, if your internal CA certificate is `myCA.pem`: +The setup process follows the same [agent's installation steps](install/index.md), +with the following differences: -```plaintext -kubectl -n gitlab-kubernetes-agent create configmap ca-pemstore --from-file=myCA.pem -``` +- When you define a configuration repository, you must do so with [Cilium settings](repository.md#surface-network-security-alerts-from-cluster-to-gitlab). +- You do not need to specify the `gitops` configuration section. -Then in `resources.yml`: - -```yaml - spec: - serviceAccountName: gitlab-kubernetes-agent - containers: - - name: agent - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>" - args: - - --token-file=/config/token - - --kas-address - - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com. - # - wss://gitlab.host.tld:443/-/kubernetes-agent/ - # - wss://kas.gitlab.com # for GitLab.com users, use this KAS. - # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker. - volumeMounts: - - name: token-volume - mountPath: /config - - name: ca-pemstore-volume - mountPath: /etc/ssl/certs/myCA.pem - subPath: myCA.pem - volumes: - - name: token-volume - secret: - secretName: gitlab-kubernetes-agent-token - - name: ca-pemstore-volume - configMap: - name: ca-pemstore - items: - - key: myCA.pem - path: myCA.pem -``` +## Related topics -Alternatively, you can mount the certificate file at a different location and include it using the -`--ca-cert-file` agent parameter: - -```yaml - containers: - - name: agent - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>" - args: - - --ca-cert-file=/tmp/myCA.pem - - --token-file=/config/token - - --kas-address - - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com. - # - wss://gitlab.host.tld:443/-/kubernetes-agent/ - # - wss://kas.gitlab.com # for GitLab.com users, use this KAS. - # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker. - volumeMounts: - - name: token-volume - mountPath: /config - - name: ca-pemstore-volume - mountPath: /tmp/myCA.pem - subPath: myCA.pem -``` +- [Troubleshooting](troubleshooting.md) +- [Contribute to the GitLab agent's development](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/doc) diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index b2372789284..4d196e57f8f 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -6,112 +6,140 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Install the GitLab Agent **(FREE)** -> [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5. +> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5. +> - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/594) multi-arch images in GitLab 14.8. The first multi-arch release is `v14.8.1`. It supports AMD64 and ARM64 architectures. -To get started with the Agent, install it in your cluster. +To connect a cluster to GitLab, you need to install the GitLab Agent +onto your cluster. -## Prerequisites **(SELF)** +## Prerequisites -- An existing Kubernetes cluster. +- An existing Kubernetes cluster. If you don't have a cluster yet, you can create a new cluster on cloud providers, such as: + - [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine/docs/quickstart) + - [Amazon Elastic Kubernetes Service (EKS)](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html) + - [Digital Ocean](https://docs.digitalocean.com/products/kubernetes/quickstart/) - On self-managed GitLab instances, a GitLab administrator needs to set up the [GitLab Agent Server (KAS)](../../../../administration/clusters/kas.md). ## Installation steps -To install the [Agent](../index.md) in your cluster: +To install the GitLab Agent on your cluster: 1. [Define a configuration repository](#define-a-configuration-repository). -1. [Register an agent with GitLab](#register-an-agent-with-gitlab). -1. [Install the agent into the cluster](#install-the-agent-into-the-cluster). +1. [Register the Agent with GitLab](#register-the-agent-with-gitlab). +1. [Install the Agent onto the cluster](#install-the-agent-onto-the-cluster). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a GitLab 14.2 [walking-through video](https://www.youtube.com/watch?v=XuBpKtsgGkE) with this process. +When you complete the installation process, you can +[view your Agent's status and activity information](#view-your-agents). +You can also [configure](#configure-the-agent) it to your needs. + ### Define a configuration repository > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the Agent manifest configuration can be added to multiple directories (or subdirectories) of its repository. > - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. -To create an agent, you need a GitLab repository to hold the configuration file. +To create an Agent, you need a GitLab repository to hold its +configuration file. If you already have a repository holding your +cluster's manifest files, you can use it to store your +Agent's configuration file and sync them with no further steps. -After installed, when you update the configuration file, GitLab transmits the -information to the cluster automatically without downtime. +#### Create the Agent's configuration file -In your repository, add the Agent configuration file under: +To create an Agent, go to the repository where you want to store +it and add the Agent's configuration file under: ```plaintext .gitlab/agents/<agent-name>/config.yaml ``` -Make sure that `<agent-name>` conforms to the [Agent's naming format](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md#agent-identity-and-name). - -WARNING: -The agent is only recognized if you use `.yaml` extension for the `config.yaml` file. The extension `.yml` is **not** recognized. - -You **don't have to add any content** to this file when you create it. The fact that the file exists -tells GitLab that this is an agent configuration file and enables the [CI/CD tunnel](../ci_cd_tunnel.md#example-for-a-kubectl-command-using-the-cicd-tunnel). Later on, you can use this -file to [configure the agent](../repository.md) by setting up parameters such as: +You **don't have to add any content** to this file at the moment you +create it. The fact that the file exists tells GitLab that this is +an Agent. You can edit it later to [configure the Agent](#configure-the-agent). -- Groups and projects that can access the agent via the [CI/CD Tunnel](../ci_cd_tunnel.md). -- [Manifest projects to synchronize](../repository.md#synchronize-manifest-projects). -- The address of the `hubble-relay` for the [Network Security policy integrations](../../../project/clusters/protect/index.md). +When creating this file, pay special attention to: -To see all the settings available, read the [Agent configuration repository documentation](../repository.md). +- The [Agent's naming format](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md#agent-identity-and-name). +- The file extension: use the `.yaml` extension (`config.yaml`). The `.yml` extension is **not** recognized. -### Register an agent with GitLab +### Register the Agent with GitLab > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5786) in GitLab 14.1, you can create a new Agent record directly from the GitLab UI. -Next, create a GitLab Rails Agent record to associate it with -the configuration repository project. Creating this record also creates a Secret needed to configure -the Agent in subsequent steps. +Now that you've created your Agent's configuration file, register it +with GitLab. +When you register the Agent, GitLab generates a token that you need for +installing the Agent onto your cluster. -In GitLab: +In GitLab, go to the project where you added your Agent's configuration +file and: 1. Ensure that [GitLab CI/CD is enabled in your project](../../../../ci/enable_or_disable_ci.md#enable-cicd-in-a-project). 1. From your project's sidebar, select **Infrastructure > Kubernetes clusters**. 1. Select **Actions**. -1. From the **Select an agent** dropdown, select the agent you want to connect and select **Register an agent** to access the installation form. -1. The form reveals your registration token. Securely store this secret token as you cannot view it again. -1. Copy the command under **Recommended installation method**. +1. From the **Select an Agent** dropdown list, select the Agent you want to register and select **Register an Agent**. +1. GitLab generates a registration token for this Agent. Securely store this secret token, as you need it to install the Agent onto your cluster and to [update the Agent](#update-the-agent-version) to another version. +1. Copy the command under **Recommended installation method**. You need it to install the Agent onto your cluster through the one-liner installation method. + +### Install the Agent onto the cluster -### Install the agent into the cluster +To connect your cluster to GitLab, install the registered Agent +onto your cluster. To install it, you can use either: -In your computer: +- [The one-liner installation method](#one-liner-installation). +- [The advanced installation method](#advanced-installation). -1. Open your local terminal and connect to your cluster. +You can use the one-liner installation for trying to use the Agent for the first time, to do internal setups with +high trust, and to quickly get started. For long-term production usage, you may want to use the advanced installation +method to benefit from more configuration options. + +#### One-liner installation + +The one-liner installation is the simplest process, but you need +Docker installed locally. If you don't have it, you can either install +it or opt to the [advanced installation method](#advanced-installation). + +To install the Agent on your cluster using the one-liner installation: + +1. In your computer, open the terminal and connect to your cluster. 1. Run the command you copied when registering your cluster in the previous step. -See the following sections to learn about customizing the installation. +Optionally, you can [customize the one-liner installation command](#customize-the-one-liner-installation). -## Simple installation method +##### Customize the one-liner installation -The command provided by GitLab does the following things: +The one-liner command generated by GitLab: - Creates a namespace for the deployment (`gitlab-kubernetes-agent`). -- Sets up a service account with `cluster-admin` rights. Read more on [how you can restrict this service account](#customize-the-permissions-for-the-agentk-service-account). -- Creates a `Secret` resource for the agent registration token. +- Sets up a service account with `cluster-admin` rights (see [how to restrict this service account](#customize-the-permissions-for-the-agentk-service-account)). +- Creates a `Secret` resource for the Agent's registration token. - Creates a `Deployment` resource for the `agentk` pod. -The one-liner installer can be customized at the command line. To find out the various options the above Docker container supports, run: +You can edit these parameters according to your needs to customize the +one-liner installation command at the command line. To find all available +options, run in your terminal: ```shell docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help ``` WARNING: -`--agent-version stable` can be used to refer to the latest stable release at the time when the command runs. It's fine for -testing purposes but for production please make sure to specify a matching version explicitly. - -## Advanced installation method +`--agent-version stable` can be used to refer to the latest stable +release at the time when the command runs. It's fine for testing +purposes but for production please make sure to specify a matching +version explicitly. -For more advanced configurations, we recommend to use [the `kpt` based installation method](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent). +#### Advanced installation -Otherwise, follow the manual installation steps described below. +For advanced installation options, use [the `kpt` installation method](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent). -### Customize the permissions for the `agentk` service account +##### Customize the permissions for the `agentk` service account -The GitLab Agent for Kubernetes allows you to fully own your cluster and requires only the permissions you give. Still, for easy getting started, by default the generated manifests provide `cluster-admin` rights to the agent. +The GitLab Agent allows you to fully own your cluster and grant GitLab +the permissions you want. Still, to facilitate the process, by default the +generated manifests provide `cluster-admin` rights to the Agent. -As part of the advanced installation method, you can restrict the agent access rights using Kustomize overlays. [An example is commented out](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/build/deployment/gitlab-agent/cluster/kustomization.yaml) in the `kpt` package you retrieved as part of the installation. +You can restrict the Agent's access rights using Kustomize overlays. [An example is commented out](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/build/deployment/gitlab-agent/cluster/kustomization.yaml) in the `kpt` package you retrieved as part of the installation. To create restricted permissions: @@ -121,50 +149,115 @@ To create restricted permissions: The above setup allows you to regularly update from the upstream package using `kpt pkg update gitlab-agent --strategy resource-merge` and maintain your customizations at the same time. -## Example projects +## Configure the Agent -The following example projects can help you get started with the Agent. +When successfully installed, you can [configure the Agent](../repository.md) +by editing its configuration file. +When you update the configuration file, GitLab transmits the +information to the cluster automatically without downtime. -- [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent) -- This basic GitOps example deploys NGINX: [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) +## View your Agents -## View installed Agents +> The version of installed `agentk` shown on the Agent tab [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340882) in GitLab 14.8. +If you have at least the Developer role, you can access the Agent's +configuration repository and view the Agent's list: -Users with at least the [Developer](../../../permissions.md) can access the user interface -for the Agent at **Infrastructure > Kubernetes clusters**, under the -**Agent** tab. This page lists all registered agents for the current project, -and the configuration directory for each agent: +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. Select **Agent** tab to view clusters connected to GitLab through the Agent. - +On this page, you can view: -Additional management interfaces are planned for the GitLab Agent. -[Provide more feedback in the related epic](https://gitlab.com/groups/gitlab-org/-/epics/4739). +- All the registered Agents for the current project. +- The connection status. +- The version of `agentk` installed on your cluster. +- The path to each Agent's configuration file. -## View Agent activity information +Furthermore, if you select one of the Agents on your list, you can view its +[activity information](#view-the-agents-activity-information). + +### View the Agent's activity information > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/277323) in GitLab 14.6. -Users with at least the [Developer](../../../permissions.md) can view the Agent's activity events. -The activity logs help you to identify problems and get the information you need for troubleshooting. -You can see events from a week before the current date. -To access an agent's activity: +The activity logs help you to identify problems and get the information +you need for troubleshooting. You can see events from a week before the +current date. To access an Agent's activity: + +1. In your Agent's repository, go to the Agents list as described [above](#view-your-agents). +1. Select the Agent you want to see the activity. + +The activity list includes: + +- Agent registration events: when a new token is **created**. +- Connection events: when an Agent is successfully **connected** to a cluster. + +Note that the connection status is logged when you connect an Agent for +the first time or after more than an hour of inactivity. -1. Go to your agent's configuration repository. -1. From the sidebar, select **Infrastructure > Kubernetes clusters**. +To check what else is planned for the Agent's UI and provide feedback, +see the [related epic](https://gitlab.com/groups/gitlab-org/-/epics/4739). + +### View vulnerabilities in cluster images **(ULTIMATE)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6346) in GitLab 14.8 [with a flag](../../../../administration/feature_flags.md) named `cluster_vulnerabilities`. Enabled by default. + +Users with at least the [Developer role](../../../permissions.md) +can view cluster vulnerabilities. You can access them through the [vulnerability report](../../../application_security/vulnerabilities/index.md) +or in your cluster's image through the following process: + +1. Configure [cluster image scanning](../../../application_security/cluster_image_scanning/index.md) + to your build process. +1. Go to your Agent's configuration repository. +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. 1. Select the **Agent** tab. -1. Select the agent you want to see the activity. +1. Select the Agent you want to see the vulnerabilities for. + + + +## Create multiple Agents + +You can create and install multiple Agents using the same process +documented above. Give each Agent's configuration file a unique name +and you're good to go. You can create multiple Agents, for example: + +- To reach your cluster from different projects. +- To connect multiple clusters to GitLab. + +## Update the Agent version + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340882) in GitLab 14.8, GitLab warns you on the Agent's list page to update the Agent version installed on your cluster. + +To update the Agent's version on your cluster, you need to re-run the [installation command](#install-the-agent-onto-the-cluster) +with a newer `--agent-version`. Make sure to specify the other required parameters: `--kas-address`, `--namespace`, and `--agent-token`. +You can find the available `agentk` versions in [the container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/1223205?sort=desc). -You can see the following events on the activity list: +If you don't have access to your Agent's token, you can retrieve it from your cluster: -- Agent registration: - - When a new token is **created**. -- Connection events: - - When an agent is successfully **connected** to a cluster. +1. On your computer, open the terminal and connect to your cluster. +1. To retrieve the namespace, run: -Note that the connection status is logged when you connect an agent for the first time -or after more than an hour of inactivity. + ```shell + kubectl get namespaces + ``` - +1. To retrieve the secret, run: + + ```shell + kubectl -n <namespace> get secrets + ``` + +1. To retrieve the token, run: + + ```shell + kubectl -n <namespace> get secret <secret-name> --template={{.data.token}} | base64 --decode + ``` + +## Example projects + +The following example projects can help you get started with the Agent. + +- [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent) +- This basic GitOps example deploys NGINX: [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) ## Upgrades and version compatibility @@ -178,7 +271,8 @@ A feature introduced in a given GitLab minor version might work with other `agen To make sure that it works, use at least the same `agentk` and `kas` minor version. For example, if your GitLab version is 14.2, use at least `agentk` 14.2 and `kas` 14.2. -We recommend upgrading your `kas` installations together with GitLab instances' upgrades, and to upgrade the `agentk` installations after upgrading GitLab. +We recommend upgrading your `kas` installations together with GitLab instances' upgrades, and to +[upgrade the `agentk` installations](#update-the-agent-version) after upgrading GitLab. The available `agentk` and `kas` versions can be found in [the container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/). diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index 22964fde395..a9d9fd1c13d 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -40,6 +40,9 @@ with Kubernetes resource definitions in YAML or JSON format. The Agent monitors each project you declare, and when the project changes, GitLab deploys the changes using the Agent. +WARNING: +When using separate GitLab projects for manifest files and configuration repository, the manifests project must be public. + To use multiple YAML files, specify a `paths` attribute in the `gitops.manifest_projects` section. ```yaml @@ -150,26 +153,19 @@ gitops: ## Authorize projects and groups to use an Agent -> - Group authorization [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. -> - Project authorization [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327850) in GitLab 14.4. - -If you use the same cluster across multiple projects, you can set up the [CI/CD Tunnel](ci_cd_tunnel.md) -to grant access to an Agent from one or more projects or groups. This way, all the authorized -projects can access the same Agent, which facilitates you to save resources and have a scalable setup. +With the [CI/CD Tunnel](ci_cd_tunnel.md), you can authorize [projects](#authorize-projects-to-use-an-agent) +and [groups](#authorize-groups-to-use-an-agent) to use an Agent. -When you authorize a project to use an agent through the [CI/CD Tunnel](ci_cd_tunnel.md), -the selected Kubernetes context is automatically injected into CI/CD jobs, allowing you to -run Kubernetes commands from your authorized projects' scripts. When you authorize a group, -all the projects that belong to that group can access the selected agent. - -An Agent can only authorize projects or groups in the same group hierarchy as the Agent's configuration -project. You can authorize up to 100 projects and 100 groups per Agent. +Then, you can reach your cluster from authorized projects and [run Kubernetes commands from GitLab CI/CD scripts](#run-kubectl-commands-using-the-cicd-tunnel) +in these projects. ### Authorize projects to use an Agent -To grant projects access to the Agent through the [CI/CD Tunnel](ci_cd_tunnel.md): +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327850) in GitLab 14.4. + +To grant projects access to the Agent through the CI/CD Tunnel: -1. Go to your Agent's configuration project. +1. Go to your Agent's configuration repository. 1. Edit the Agent's configuration file (`config.yaml`). 1. Add the `projects` attribute into `ci_access`. 1. Identify the project through its path: @@ -182,9 +178,11 @@ To grant projects access to the Agent through the [CI/CD Tunnel](ci_cd_tunnel.md ### Authorize groups to use an Agent +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. + To grant access to all projects within a group: -1. Go to your Agent's configuration project. +1. Go to your Agent's configuration repository. 1. Edit the Agent's configuration file (`config.yaml`). 1. Add the `groups` attribute into `ci_access`. 1. Identify the group or subgroup through its path: @@ -195,7 +193,64 @@ To grant access to all projects within a group: - id: path/to/group/subgroup ``` -### Use impersonation to restrict project and group access **(PREMIUM)** +## Run `kubectl` commands using the CI/CD Tunnel + +After you authorize your project or group to use the Agent, you need to +configure the project's `.gitlab-ci.yaml` file to access the Agent. +This makes it possible to deploy applications to your cluster and run +any Kubernetes-specific commands from the authorized project. + +First, configure your Agent: + +1. Go to your Agent's configuration repository. +1. Edit your Agent's `config.yaml` file authorizing the [project](#authorize-projects-to-use-an-agent) or [group](#authorize-groups-to-use-an-agent) you want to run Kubernetes commands from. + +Then, configure the other project: + +1. Go to the project where you want to run Kubernetes commands from. +1. Edit your project's `.gitlab-ci.yml` file. +1. Set your Agent's context in the first command of the script with the format `path/to/agent/repository:agent-name`. +1. Run Kubernetes commands. + +For example: + +```yaml + deploy: + image: + name: bitnami/kubectl:latest + entrypoint: [""] + script: + - kubectl config use-context path/to/agent/repository:agent-name + - kubectl get pods +``` + +When you use the Agent, KubeContexts are named as `path/to/agent/repository:agent-name`. + +To get the list of available contexts: + +1. Open your terminal and connect to your cluster. +1. Run `kubectl config get-contexts`. + +### `kubectl` commands not supported + +The commands `kubectl exec`, `kubectl cp`, and `kubectl attach` are not supported by the CI/CD tunnel. +Anything else that uses the same API endpoints does not work either as they use the deprecated +SPDY protocol. +We [plan to add support for these features](https://gitlab.com/gitlab-org/gitlab/-/issues/346248) +in a future version of GitLab. + +### `kubectl` requires TLS + +`kubectl` would never send credentials over an unencrypted connection. Self-managed users should ensure that their +GitLab instance is configured with TLS for the CI/CD tunnel feature to work. Trying to use it without TLS +would produce errors: + +```shell +$ kubectl get pods +error: You must be logged in to the server (the server has asked for the client to provide credentials) +``` + +## Use impersonation to restrict project and group access **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345014) in GitLab 14.5. @@ -211,11 +266,11 @@ You can impersonate: - The CI job that accesses the cluster. - A specific user or system account defined within the cluster. -#### Impersonate the Agent +### Impersonate the Agent The Agent is impersonated by default. You don't need to do anything to impersonate it. -#### Impersonate the CI job that accesses the cluster +### Impersonate the CI job that accesses the cluster To impersonate the CI job that accesses the cluster, add the `ci_job: {}` key-value under the `access_as` key. @@ -261,7 +316,7 @@ ci_access: ci_job: {} ``` -#### Impersonate a static identity +### Impersonate a static identity For the given CI/CD Tunnel connection, you can use a static identity for the impersonation. @@ -278,6 +333,13 @@ See the [official Kubernetes documentation for more details](https://kubernetes. ## Surface network security alerts from cluster to GitLab **(ULTIMATE)** +> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. + +WARNING: +Cilium integration is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) +for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 15.0. + The GitLab Agent provides an [integration with Cilium](index.md#kubernetes-network-security-alerts). To integrate, add a top-level `cilium` section to your `config.yml` file. Currently, the only configuration option is the Hubble relay address: diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md new file mode 100644 index 00000000000..2c9f98b7c45 --- /dev/null +++ b/doc/user/clusters/agent/troubleshooting.md @@ -0,0 +1,193 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Troubleshooting the GitLab Agent for Kubernetes + +When you are using the GitLab Agent for Kubernetes, you might experience issues you need to troubleshoot. + +You can start by viewing the service logs: + +```shell +kubectl logs -f -l=app=gitlab-agent -n gitlab-kubernetes-agent +``` + +If you are a GitLab administrator, you can also view the [GitLab Agent Server logs](../../../administration/clusters/kas.md#troubleshooting). + +## Transport: Error while dialing failed to WebSocket dial + +```json +{ + "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. + +```json +{ + "level": "error", + "time": "2021-06-25T21:15:45.335Z", + "msg": "Reverse tunnel", + "mod_name": "reverse_tunnel", + "error": "Connect(): rpc error: code = Unavailable desc = connection error: desc= \"transport: Error while dialing failed to WebSocket dial: expected handshake response status code 101 but got 301\"" +} +``` + +This error occurs if the `kas-address` doesn't include a trailing slash. To fix it, make sure that the +`wss` or `ws` URL ends with a trailing slash, such as `wss://GitLab.host.tld:443/-/kubernetes-agent/` +or `ws://GitLab.host.tld:80/-/kubernetes-agent/`. + +## ValidationError(Deployment.metadata) + +```json +{ + "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 a manifest file is malformed, and Kubernetes can't +create specified objects. Make sure that your manifest files are valid. You +may try using them to create objects in Kubernetes directly for more troubleshooting. + +## Error while dialing failed to WebSocket dial: failed to send handshake request + +```json +{ + "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>:8150`. + +## Decompressor is not installed for grpc-encoding + +```json +{ + "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. + +## Certificate signed by unknown authority + +```json +{ + "level": "error", + "time": "2021-02-25T07:22:37.158Z", + "msg": "Reverse tunnel", + "mod_name": "reverse_tunnel", + "error": "Connect(): 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/\\\": x509: certificate signed by unknown authority\"" +} +``` + +This error is shown if your GitLab instance is using a certificate signed by an internal CA that +is unknown to the agent. One approach to fixing it is to present the CA certificate file to the agent +via a Kubernetes `configmap` and mount the file in the agent `/etc/ssl/certs` directory from where it +will be picked up automatically. + +For example, if your internal CA certificate is `myCA.pem`: + +```plaintext +kubectl -n gitlab-kubernetes-agent create configmap ca-pemstore --from-file=myCA.pem +``` + +Then in `resources.yml`: + +```yaml + spec: + serviceAccountName: gitlab-kubernetes-agent + containers: + - name: agent + image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>" + args: + - --token-file=/config/token + - --kas-address + - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com. + # - wss://gitlab.host.tld:443/-/kubernetes-agent/ + # - wss://kas.gitlab.com # for GitLab.com users, use this KAS. + # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker. + volumeMounts: + - name: token-volume + mountPath: /config + - name: ca-pemstore-volume + mountPath: /etc/ssl/certs/myCA.pem + subPath: myCA.pem + volumes: + - name: token-volume + secret: + secretName: gitlab-kubernetes-agent-token + - name: ca-pemstore-volume + configMap: + name: ca-pemstore + items: + - key: myCA.pem + path: myCA.pem +``` + +Alternatively, you can mount the certificate file at a different location and include it using the +`--ca-cert-file` agent parameter: + +```yaml + containers: + - name: agent + image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>" + args: + - --ca-cert-file=/tmp/myCA.pem + - --token-file=/config/token + - --kas-address + - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com. + # - wss://gitlab.host.tld:443/-/kubernetes-agent/ + # - wss://kas.gitlab.com # for GitLab.com users, use this KAS. + # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker. + volumeMounts: + - name: token-volume + mountPath: /config + - name: ca-pemstore-volume + mountPath: /tmp/myCA.pem + subPath: myCA.pem +``` + +## Project not found + +```json +{ + "level ":"error ", + "time ":"2022-01-05T15:18:11.331Z", + "msg ":"GetObjectsToSynchronize.Recv failed ", + "mod_name ":"gitops ", + "error ":"rpc error: code = NotFound desc = project not found ", +} +``` + +This error is shown if the manifest project is not public. To fix it, +[make sure your manifest project is public](repository.md#synchronize-manifest-projects) or your manifest files +are stored in the Agent's configuration repository. diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md index 14850ca85b3..c99eef385ce 100644 --- a/doc/user/clusters/cost_management.md +++ b/doc/user/clusters/cost_management.md @@ -22,7 +22,7 @@ insights within GitLab: ## Configure cluster cost management -To get started with cluster cost management, you need the [Maintainer role](../permissions.md) in a project or group. +To get started with cluster cost management, you need the Maintainer role for a project or group. 1. Clone the [`kubecost-cost-model`](https://gitlab.com/gitlab-examples/kubecost-cost-model/) example repository, which contains minor modifications to the upstream Kubecost diff --git a/doc/user/clusters/img/cluster_agent_security_tab_v14_8.png b/doc/user/clusters/img/cluster_agent_security_tab_v14_8.png Binary files differnew file mode 100644 index 00000000000..91d7e40429e --- /dev/null +++ b/doc/user/clusters/img/cluster_agent_security_tab_v14_8.png diff --git a/doc/user/clusters/img/gitlab_agent_activity_events_v14_6.png b/doc/user/clusters/img/gitlab_agent_activity_events_v14_6.png Binary files differdeleted file mode 100644 index 90b41ee849c..00000000000 --- a/doc/user/clusters/img/gitlab_agent_activity_events_v14_6.png +++ /dev/null diff --git a/doc/user/clusters/img/kubernetes-agent-ui-list_v14_5.png b/doc/user/clusters/img/kubernetes-agent-ui-list_v14_5.png Binary files differdeleted file mode 100644 index 3463eeb5d93..00000000000 --- a/doc/user/clusters/img/kubernetes-agent-ui-list_v14_5.png +++ /dev/null diff --git a/doc/user/clusters/img/kubernetes-agent-ui-list_v14_8.png b/doc/user/clusters/img/kubernetes-agent-ui-list_v14_8.png Binary files differnew file mode 100644 index 00000000000..5b5ba3a9804 --- /dev/null +++ b/doc/user/clusters/img/kubernetes-agent-ui-list_v14_8.png diff --git a/doc/user/clusters/migrating_from_gma_to_project_template.md b/doc/user/clusters/migrating_from_gma_to_project_template.md index 20c4408d57e..b2ba1bef338 100644 --- a/doc/user/clusters/migrating_from_gma_to_project_template.md +++ b/doc/user/clusters/migrating_from_gma_to_project_template.md @@ -23,16 +23,16 @@ See also [video walk-throughs](#video-walk-throughs) with examples. 1. Create a new project based on the [Cluster Management Project template](management_project_template.md#create-a-new-project-based-on-the-cluster-management-template). 1. [Associate your new Cluster Management Project with your cluster](management_project.md#associate-the-cluster-management-project-with-the-cluster). 1. Detect apps deployed through Helm v2 releases by using the pre-configured [`.gitlab-ci.yml`](management_project_template.md#the-gitlab-ciyml-file) file: - - In case you had overwritten the default GitLab Managed Apps namespace, edit `.gitlab-ci.yml`, - and make sure the script is receiving the correct namespace as an argument: + - In case you had overwritten the default GitLab Managed Apps namespace, edit `.gitlab-ci.yml`, + and make sure the script is receiving the correct namespace as an argument: - ```yaml - script: - - gl-fail-if-helm2-releases-exist <your_custom_namespace> - ``` + ```yaml + script: + - gl-fail-if-helm2-releases-exist <your_custom_namespace> + ``` - - If you kept the default name (`gitlab-managed-apps`), then the script is already - set up. + - If you kept the default name (`gitlab-managed-apps`), then the script is already + set up. Either way, [run a pipeline manually](../../ci/pipelines/index.md#run-a-pipeline-manually) and read the logs of the `detect-helm2-releases` job to know if you have any Helm v2 releases and which are they. @@ -53,7 +53,7 @@ See also [video walk-throughs](#video-walk-throughs) with examples. ```shell helm ls -n gitlab-managed-apps - + NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION runner gitlab-managed-apps 1 2021-06-09 19:36:55.739141644 +0000 UTC deployed gitlab-runner-0.28.0 13.11.0 ``` @@ -67,39 +67,42 @@ See also [video walk-throughs](#video-walk-throughs) with examples. 1. Edit the `applications/{app}/values.yaml` associated with your app to match the currently deployed values. For example, for GitLab Runner: - 1. Copy the output of the following command (it might be big): + 1. Copy the output of the following command (it might be big): - ```shell - helm get values runner -n gitlab-managed-apps -a --output yaml - ``` + ```shell + helm get values runner -n gitlab-managed-apps -a --output yaml + ``` - 1. Overwrite `applications/gitlab-runner/values.yaml` with the output of the previous command. + 1. Overwrite `applications/gitlab-runner/values.yaml` with the output of the previous command. This safe step will guarantee that no unexpected default values overwrite your currently deployed values. For instance, your GitLab Runner could have its `gitlabUrl` or `runnerRegistrationToken` overwritten by mistake. 1. Some apps require special attention: - - Ingress: Due to an existing [chart issue](https://github.com/helm/charts/pull/13646), you might see - `spec.clusterIP: Invalid value` when trying to run the [`./gl-helmfile`](management_project_template.md#the-gitlab-ciyml-file) - command. To work around this, after overwriting the release values in `applications/ingress/values.yaml`, - you might need to overwrite all the occurrences of `omitClusterIP: false`, setting it to `omitClusterIP: true`. - Another approach,could be to collect these IPs by running `kubectl get services -n gitlab-managed-apps` - and then overwriting each `ClusterIP` that it complains about with the value you got from that command. - - - Vault: This application introduces a breaking change from the chart we used in Helm v2 to the chart - used in Helm v3. So, the only way to integrate it with this Cluster Management Project is to actually uninstall this app and accept the - chart version proposed in `applications/vault/values.yaml`. - - - Cert-manager: - - For users on Kubernetes version 1.20 or above, the deprecated cert-manager v0.10 is no longer valid and - and the upgrade includes a breaking change. So we suggest that you [backup and uninstall cert-manager v0.10](#backup-and-uninstall-cert-manager-v010) - , and install cert-manager v1.4 instead. To install this version, uncomment the `applications/cert-manager-1-4/helmfile.yaml` - from the [`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file). - This triggers a pipeline to install the new version. - - For users on Kubernetes versions lower than 1.20, you can stick to v0.10 by uncommenting - `applications/cert-manager/helmfile.yaml` - in your project's main Helmfile ([`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file)). + - Ingress: Due to an existing [chart issue](https://github.com/helm/charts/pull/13646), you might see + `spec.clusterIP: Invalid value` when trying to run the [`./gl-helmfile`](management_project_template.md#the-gitlab-ciyml-file) + command. To work around this, after overwriting the release values in `applications/ingress/values.yaml`, + you might need to overwrite all the occurrences of `omitClusterIP: false`, setting it to `omitClusterIP: true`. + Another approach,could be to collect these IPs by running `kubectl get services -n gitlab-managed-apps` + and then overwriting each `ClusterIP` that it complains about with the value you got from that command. + + - Vault: This application introduces a breaking change from the chart we used in Helm v2 to the chart + used in Helm v3. So, the only way to integrate it with this Cluster Management Project is to actually uninstall this app and accept the + chart version proposed in `applications/vault/values.yaml`. + + - Cert-manager: + - For users on Kubernetes version 1.20 or above, the deprecated cert-manager v0.10 is no longer valid + and the upgrade includes a breaking change. So we suggest that you [backup and uninstall cert-manager v0.10](#backup-and-uninstall-cert-manager-v010), + and install the latest cert-manager instead. To install this version, uncomment `applications/cert-manager/helmfile.yaml` + from [`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file). + This triggers a pipeline to install the new version. + - For users on Kubernetes versions lower than 1.20, you can stick to v0.10 by uncommenting + `applications/cert-manager-legacy/helmfile.yaml` + in your project's main Helmfile ([`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file)). + + WARNING: + Cert-manager v0.10 breaks when Kubernetes is upgraded to version 1.20 or later. 1. After following all the previous steps, [run a pipeline manually](../../ci/pipelines/index.md#run-a-pipeline-manually) and watch the `apply` job logs to see if any of your applications were successfully detected, installed, and whether they got any @@ -118,7 +121,7 @@ you want to manage with the Cluster Management Project. ## Backup and uninstall cert-manager v0.10 1. Follow the [official docs](https://docs.cert-manager.io/en/release-0.10/tasks/backup-restore-crds.html) on how to - backup your cert-manager v0.10 data. + backup your cert-manager v0.10 data. 1. Uninstall cert-manager by editing the setting all the occurrences of `installed: true` to `installed: false` in the `applications/cert-manager/helmfile.yaml` file. 1. Search for any left-over resources by executing the following command `kubectl get Issuers,ClusterIssuers,Certificates,CertificateRequests,Orders,Challenges,Secrets,ConfigMaps -n gitlab-managed-apps | grep certmanager`. diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 04d3cc0595e..18de33ea03b 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -14,15 +14,9 @@ project's dependencies for their licenses. You can then decide whether to allow each license. For example, if your application uses an external (open source) library whose license is incompatible with yours, then you can deny the use of that license. -You can take advantage of License Compliance by either: +To detect the licenses in use, License Compliance uses the [License Finder](https://github.com/pivotal/LicenseFinder) scan tool that runs as part of the CI/CD pipeline. The License Compliance job is not dependent on any other job in +a pipeline. -- [Including the job](#configuration) - in your existing `.gitlab-ci.yml` file. -- Implicitly using - [Auto License Compliance](../../../topics/autodevops/stages.md#auto-license-compliance), - provided by [Auto DevOps](../../../topics/autodevops/index.md). - -To detect the licenses in use, License Compliance uses the [License Finder](https://github.com/pivotal/LicenseFinder) scan tool that runs as part of the CI/CD pipeline. For the job to activate, License Finder needs to find a compatible package definition in the project directory. For details, see the [Activation on License Finder documentation](https://github.com/pivotal/LicenseFinder#activation). GitLab checks the License Compliance report, compares the licenses between the source and target branches, and shows the information right on the merge @@ -39,6 +33,14 @@ is displayed in the merge request area. That is the case when you add the Consecutive merge requests have something to compare to and the license compliance report is shown properly. +The results are saved as a +[License Compliance report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportslicense_scanning) +that you can later download and analyze. Due to implementation limitations, we +always take the latest License Compliance artifact available. + +WARNING: +License Compliance Scanning does not support run-time installation of compilers and interpreters. +  You can select a license to see more information. @@ -91,27 +93,26 @@ The reported licenses might be incomplete or inaccurate. | Rust | [Cargo](https://crates.io) | | PHP | [Composer](https://getcomposer.org/) | -## Requirements +## Enable License Compliance -WARNING: -License Compliance Scanning does not support run-time installation of compilers and interpreters. +To enable License Compliance in your project's pipeline, either: -To run a License Compliance scanning job, you need GitLab Runner with the -[`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). +- Enable [Auto License Compliance](../../../topics/autodevops/stages.md#auto-license-compliance) + (provided by [Auto DevOps](../../../topics/autodevops/index.md)). +- Include the [`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/License-Scanning.gitlab-ci.yml) in your `.gitlab-ci.yml` file. -## Configuration +### Include the License Scanning template -For GitLab 12.8 and later, to enable License Compliance, you must -[include](../../../ci/yaml/index.md#includetemplate) the -[`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/License-Scanning.gitlab-ci.yml) -that's provided as a part of your GitLab installation. -For older versions of GitLab from 11.9 to 12.7, you must -[include](../../../ci/yaml/index.md#includetemplate) the -[`License-Management.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/d2cc841c55d65bc8134bfb3a467e66c36ac32b0a/lib/gitlab/ci/templates/Security/License-Management.gitlab-ci.yml). -For GitLab versions earlier than 11.9, you can copy and use the job as defined -that template. +Prerequisites: -Add the following to your `.gitlab-ci.yml` file: +- [GitLab Runner](../../../ci/runners/index.md) available, with the + [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). If you're using the + shared runners on GitLab.com, this is enabled by default. +- License Scanning runs in the `test` stage, which is available by default. If you redefine the stages in the + `.gitlab-ci.yml` file, the `test` stage is required. + +To [include](../../../ci/yaml/index.md#includetemplate) the +[`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/License-Scanning.gitlab-ci.yml), add it to your `.gitlab-ci.yml` file: ```yaml include: @@ -121,26 +122,6 @@ include: The included template creates a `license_scanning` job in your CI/CD pipeline and scans your dependencies to find their licenses. -NOTE: -Before GitLab 12.8, the `license_scanning` job was named `license_management`. GitLab 13.0 removes -the `license_management` job, so you must migrate to the `license_scanning` job and use the new -`License-Scanning.gitlab-ci.yml` template. - -The results are saved as a -[License Compliance report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportslicense_scanning) -that you can later download and analyze. Due to implementation limitations, we -always take the latest License Compliance artifact available. Behind the scenes, the -[GitLab License Compliance Docker image](https://gitlab.com/gitlab-org/security-products/analyzers/license-finder) -is used to detect the languages/frameworks and in turn analyzes the licenses. - -The License Compliance settings can be changed through [CI/CD variables](#available-cicd-variables) by using the -[`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`. - -### When License Compliance runs - -When using the GitLab `License-Scanning.gitlab-ci.yml` template, the License Compliance job doesn't -wait for other stages to complete. - ### Available CI/CD variables License Compliance can be configured using CI/CD variables. @@ -651,7 +632,7 @@ successfully run. For more information, see [Offline environments](../../applica To use License Compliance in an offline environment, you need: -- GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). +- To meet the standard [License Compliance prerequisites](#include-the-license-scanning-template). - Docker Container Registry with locally available copies of License Compliance [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. NOTE: @@ -674,7 +655,7 @@ registry.gitlab.com/gitlab-org/security-products/analyzers/license-finder:latest The process for importing Docker images into a local offline Docker registry depends on **your network security policy**. Please consult your IT staff to find an accepted and approved -process by which external resources can be imported or temporarily accessed. Note that these scanners are [updated periodically](../../application_security/vulnerabilities/index.md#vulnerability-scanner-maintenance) +process by which external resources can be imported or temporarily accessed. Note that these scanners are [updated periodically](../../application_security/index.md#vulnerability-scanner-maintenance) with new definitions, so consider if you are able to make periodic updates yourself. For details on saving and transporting Docker images as a file, see Docker's documentation on @@ -729,7 +710,7 @@ details about them. For the licenses to appear under the license list, the following requirements must be met: -1. The License Compliance CI job must be [configured](#configuration) for your project. +1. The License Compliance CI/CD job must be [enabled](#enable-license-compliance) for your project. 1. Your project must use at least one of the [supported languages and package managers](#supported-languages-and-package-managers). @@ -772,7 +753,7 @@ Developers of the project can view the policies configured in a project. Prerequisites: -- Maintainer or Owner [role](../../permissions.md#project-members-permissions). +- Maintainer or Owner role. `License-Check` is a [merge request approval](../../project/merge_requests/approvals/index.md) rule you can enable to allow an individual or group to approve a merge request that contains a `denied` diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md index f0f9a907a73..305cca33dd5 100644 --- a/doc/user/crm/index.md +++ b/doc/user/crm/index.md @@ -6,7 +6,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Customer relations management (CRM) **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2256) in GitLab 14.6 [with a flag](../../administration/feature_flags.md) named `customer_relations`. Disabled by default. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2256) in GitLab 14.6 [with a flag](../../administration/feature_flags.md) named `customer_relations`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `customer_relations`. +On GitLab.com, this feature is not available. With customer relations management (CRM) you can create a record of contacts (individuals) and organizations (companies) and relate them to issues. @@ -133,7 +137,7 @@ API. ### Add contacts to an issue -To add contacts to an issue use the `/add_contacts` +To add contacts to an issue use the `/add_contacts [contact:address@example.com]` [quick action](../project/quick_actions.md). You can also add, remove, or replace issue contacts using the @@ -142,9 +146,25 @@ API. ### Remove contacts from an issue -To remove contacts from an issue use the `/remove_contacts` +To remove contacts from an issue use the `/remove_contacts [contact:address@example.com]` [quick action](../project/quick_actions.md). You can also add, remove, or replace issue contacts using the [GraphQL](../../api/graphql/reference/index.md#mutationissuesetcrmcontacts) API. + +## Autocomplete contacts **(FREE SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2256) in GitLab 14.8 [with a flag](../../administration/feature_flags.md) named `contacts_autocomplete`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `contacts_autocomplete`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +When you use the `/add_contacts` or `/remove_contacts` quick actions, follow them with `[contact:` and an autocomplete list appears: + +```plaintext +/add_contacts [contact: +/remove_contacts [contact: +``` diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 7831fdff249..37047e9f8d0 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -115,8 +115,7 @@ You can use [Markdown](../markdown.md) and [quick actions](../project/quick_acti You can edit your own comment at any time. -Anyone with the [Maintainer role](../permissions.md) or -higher can also edit a comment made by someone else. +Anyone with at least the Maintainer role can also edit a comment made by someone else. ## Prevent comments by locking an issue @@ -209,7 +208,7 @@ When you reply to a standard comment, you create a thread. Prerequisites: -- You must have at least the [Guest role](../permissions.md#project-members-permissions). +- You must have at least the Guest role. - You must be in an issue, merge request, or epic. Threads in commits and snippets are not supported. To create a thread by replying to a comment: @@ -231,7 +230,7 @@ You can create a thread without replying to a standard comment. Prerequisites: -- You must have at least the [Guest role](../permissions.md#project-members-permissions). +- You must have at least the Guest role. - You must be in an issue, merge request, commit, or snippet. To create a thread: @@ -253,7 +252,7 @@ In a merge request, you can resolve a thread when you want to finish a conversat Prerequisites: -- You must have at least the [Developer role](../permissions.md#project-members-permissions) +- You must have at least the Developer role or be the author of the change being reviewed. - Resolvable threads can be added only to merge requests. It doesn't work for comments in issues, commits, or snippets. diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index f02073b477b..80ee8d23a35 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -122,6 +122,8 @@ Below are the settings for [GitLab Pages](https://about.gitlab.com/stages-devops The maximum size of your Pages site is regulated by the artifacts maximum size, which is part of [GitLab CI/CD](#gitlab-cicd). +There are also [rate limits set for GitLab Pages](#gitlabcom-specific-rate-limits). + ## GitLab CI/CD Below are the current settings regarding [GitLab CI/CD](../../ci/index.md). @@ -310,17 +312,19 @@ limiting responses](#rate-limiting-responses). The following table describes the rate limits for GitLab.com, both before and after the limits change in January, 2021: -| Rate limit | Before 2021-01-18 | From 2021-01-18 | From 2021-02-12 | -|:--------------------------------------------------------------------------|:----------------------------|:------------------------------|:------------------------------| -| **Protected paths** (for a given **IP address**) | **10** requests per minute | **10** requests per minute | **10** requests per minute | -| **Raw endpoint** traffic (for a given **project, commit, and file path**) | **300** requests per minute | **300** requests per minute | **300** requests per minute | -| **Unauthenticated** traffic (from a given **IP address**) | No specific limit | **500** requests per minute | **500** requests per minute | -| **Authenticated** API traffic (for a given **user**) | No specific limit | **2,000** requests per minute | **2,000** requests per minute | -| **Authenticated** non-API HTTP traffic (for a given **user**) | No specific limit | **1,000** requests per minute | **1,000** requests per minute | -| **All** traffic (from a given **IP address**) | **600** requests per minute | **2,000** requests per minute | **2,000** requests per minute | -| **Issue creation** | | **300** requests per minute | **300** requests per minute | -| **Note creation** (on issues and merge requests) | | **300** requests per minute | **60** requests per minute | -| **Advanced, project, and group search** API (for a given **IP address**) | | | **10** requests per minute | +| Rate limit | Before 2021-02-12 | From 2021-02-12 | From 2022-02-03 | +|:--------------------------------------------------------------------------|:------------------------------|:------------------------------|:----------------------------------------| +| **Protected paths** (for a given **IP address**) | **10** requests per minute | **10** requests per minute | **10** requests per minute | +| **Raw endpoint** traffic (for a given **project, commit, and file path**) | **300** requests per minute | **300** requests per minute | **300** requests per minute | +| **Unauthenticated** traffic (from a given **IP address**) | **500** requests per minute | **500** requests per minute | **500** requests per minute | +| **Authenticated** API traffic (for a given **user**) | **2,000** requests per minute | **2,000** requests per minute | **2,000** requests per minute | +| **Authenticated** non-API HTTP traffic (for a given **user**) | **1,000** requests per minute | **1,000** requests per minute | **1,000** requests per minute | +| **All** traffic (from a given **IP address**) | **2,000** requests per minute | **2,000** requests per minute | **2,000** requests per minute | +| **Issue creation** | **300** requests per minute | **300** requests per minute | **300** requests per minute | +| **Note creation** (on issues and merge requests) | **300** requests per minute | **60** requests per minute | **60** requests per minute | +| **Advanced, project, and group search** API (for a given **IP address**) | | **10** requests per minute | **10** requests per minute | +| **GitLab Pages** requests (for a given **IP address**) | | | **1000** requests per **50 seconds** | +| **GitLab Pages** requests (for a given **GitLab Pages domain**) | | | **5000** requests per **10 seconds** | More details are available on the rate limits for [protected paths](#protected-paths-throttle) and [raw diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index 76a8eb77e72..3b866c4a1b0 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -11,8 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w With Contribution Analytics, you can get an overview of the [contribution events](../../index.md#user-contribution-events) in your group. -- Analyze your team's contributions over a period of time, and offer a bonus for the top - contributors. +- Analyze your team's contributions over a period of time. - Identify opportunities for improvement with group members who may benefit from additional support. diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index 2214a18475a..00e6bc671c1 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -24,7 +24,7 @@ You can also configure [custom templates for the instance](../admin_area/custom_ Prerequisite: -- You must have the [Owner role for the group](../permissions.md#group-members-permissions). +- You must have the Owner role for the group. To set up custom project templates in a group, add the subgroup that contains the project templates to the group settings: diff --git a/doc/user/group/devops_adoption/index.md b/doc/user/group/devops_adoption/index.md index 4151745189d..333bef84dcc 100644 --- a/doc/user/group/devops_adoption/index.md +++ b/doc/user/group/devops_adoption/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Group DevOps Adoption **(ULTIMATE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321083) in GitLab 13.11 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321083) in GitLab 13.11 as a [Beta feature](../../../policy/alpha-beta-support.md#beta-features). > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/333556) in GitLab 14.1. > - The Overview tab [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330401) in GitLab 14.1. > - DAST and SAST metrics [added](https://gitlab.com/gitlab-org/gitlab/-/issues/328033) in GitLab 14.1. @@ -32,7 +32,7 @@ how to use those features. Prerequisite: -- You must have at least the [Reporter role](../../permissions.md) for the group. +- You must have at least the Reporter role for the group. To view DevOps Adoption: diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md index d184030718a..f03a56d8a00 100644 --- a/doc/user/group/epics/epic_boards.md +++ b/doc/user/group/epics/epic_boards.md @@ -24,7 +24,7 @@ To view an epic board: Prerequisites: -- You must have at least the [Reporter role](../../permissions.md#group-members-permissions) for a group. +- You must have at least the Reporter role for a group. To create a new epic board: @@ -49,7 +49,7 @@ To change these options later, [edit the board](#edit-the-scope-of-an-epic-board Prerequisites: -- You must have at least the [Reporter role](../../permissions.md#group-members-permissions) for a group. +- You must have at least the Reporter role for a group. - A minimum of two boards present in a group. To delete the active epic board: @@ -73,7 +73,7 @@ To delete the active epic board: Prerequisites: -- You must have at least the [Reporter role](../../permissions.md#group-members-permissions) for a group. +- You must have at least the Reporter role for a group. To create a new list: @@ -91,7 +91,7 @@ list view that's removed. You can always create it again later if you need. Prerequisites: -- You must have at least the [Reporter role](../../permissions.md#group-members-permissions) for a group. +- You must have at least the Reporter role for a group. To remove a list from an epic board: @@ -106,7 +106,7 @@ To remove a list from an epic board: Prerequisites: -- You must have at least the [Reporter role](../../permissions.md#group-members-permissions) for a group. +- You must have at least the Reporter role for a group. - You must have [created a list](#create-a-new-list) first. To create an epic from a list in epic board: @@ -147,7 +147,7 @@ You can move epics and lists by dragging them. Prerequisites: -- You must have at least the [Reporter role](../../permissions.md#group-members-permissions) for a group. +- You must have at least the Reporter role for a group. To move an epic, select the epic card and drag it to another position in its current list or into another list. Learn about possible effects in [Dragging epics between lists](#dragging-epics-between-lists). @@ -170,7 +170,7 @@ and the target list. Prerequisites: -- You must have at least the [Reporter role](../../permissions.md#group-members-permissions) for a group. +- You must have at least the Reporter role for a group. To edit the scope of an epic board: diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index caca10a05a2..3350b0f1169 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -83,7 +83,7 @@ To edit an epic's start date, due date, or labels: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7250) in GitLab 12.2. -Users with at least the [Reporter role](../../permissions.md) can manage epics. +Users with at least the Reporter role can manage epics. When bulk editing epics in a group, you can edit their labels. @@ -98,8 +98,7 @@ To update multiple epics at the same time: ## Delete an epic NOTE: -To delete an epic, you must be an [Owner](../../permissions.md#group-members-permissions) of a group -or subgroup. +To delete an epic, you must be an Owner of a group or subgroup. To delete the epic: @@ -165,6 +164,7 @@ than 1000. The cached value is rounded to thousands or millions and updated ever > - Sorting by epic titles [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.1. > - Searching by milestone and confidentiality [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/268372) in GitLab 14.2 [with a flag](../../../administration/feature_flags.md) named `vue_epics_list`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/276189) in GitLab 14.7. +> - [Feature flag `vue_epics_list`](https://gitlab.com/gitlab-org/gitlab/-/issues/327320) removed in GitLab 14.8. You can search for an epic from the list of epics using filtered search bar based on following parameters: diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index 70406cfe8e8..cdc3fe02a53 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -10,20 +10,81 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/249160) in GitLab 13.7 [with a flag](../../feature_flags.md) named `bulk_import`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/338985) in GitLab 14.3. +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `bulk_import`. On GitLab.com, this feature is available. + +You can migrate your existing top-level groups to any of the following: + +- Another GitLab instance, including GitLab.com. +- Another top-level group. +- The subgroup of any existing top-level group. + +Migrating groups is not the same as [group import/export](../settings/import_export.md). + +- Group import/export requires you to export a group to a file and then import that file in + another GitLab instance. +- Group migration automates this process. + +## Import your groups into GitLab + +When you migrate a group, you connect to your GitLab instance and then choose +groups to import. Not all the data is migrated. View the +[Migrated resources](#migrated-resources) list for details. + +Leave feedback about group migration in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/284495). + NOTE: -The importer migrates **only** the group data listed on this page. To leave feedback on this -feature, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/284495). +You might need to reconfigure your firewall to prevent blocking the connection on the self-managed +instance. + +### Connect to the remote GitLab instance -Using GitLab Group Migration, you can migrate existing top-level groups from GitLab.com or a self-managed instance. Groups can be migrated to a target instance, as a top-level group, or as a subgroup of any existing top-level group. +Before you begin, ensure that the target GitLab instance can communicate with the source over HTTPS +(HTTP is not supported). You might need to reconfigure your firewall to prevent blocking the connection on the self-managed +instance. -The following resources are migrated to the target instance: +Then create the group you want to import into, and connect: + +1. Create a new group or subgroup: + + - On the top bar, select `+` and then **New group**. + - Or, on an existing group's page, in the top right, select **New subgroup**. + +1. Select **Import group**. +1. Enter the source URL of your GitLab instance. +1. Generate or copy a [personal access token](../../../user/profile/personal_access_tokens.md) + with the `api` and `read_repository` scopes on your remote GitLab instance. +1. Enter the [personal access token](../../../user/profile/personal_access_tokens.md) for your remote GitLab instance. +1. Select **Connect instance**. + +### Select the groups to import + +After you have authorized access to the GitLab instance, you are redirected to the GitLab Group +Migration importer page. The remote groups you have the Owner role for are listed. + +1. By default, the proposed group namespaces match the names as they exist in remote instance, but based on your permissions, you can choose to edit these names before you proceed to import any of them. +1. Next to the groups you want to import, select **Import**. +1. The **Status** column shows the import status of each group. If you leave the page open, it updates in real-time. +1. After a group has been imported, select its GitLab path to open its GitLab URL. + + + +## Automate group and project import **(PREMIUM)** + +For information on automating user, group, and project import API calls, see +[Automate group and project import](../../project/import/index.md#automate-group-and-project-import). + +## Migrated resources + +Only the following resources are migrated to the target instance. Any other items are **not** +migrated: - Groups ([Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4374) in 13.7) - description - attributes - subgroups - avatar ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322904) in 14.0) -- Group Labels ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292429) in 13.9) +- Group labels ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292429) in 13.9) - title - description - color @@ -71,67 +132,3 @@ The following resources are migrated to the target instance: - image URL - Boards - Board Lists - -Any other items are **not** migrated. - -## Enable or disable GitLab Group Migration - -GitLab Migration is deployed behind the `bulk_import` feature flag, which is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can disable it. - -To disable it: - -```ruby -Feature.disable(:bulk_import) -``` - -To enable it: - -```ruby -Feature.enable(:bulk_import) -``` - -## Import your groups into GitLab - -Before you begin, ensure that the target instance of GitLab can communicate with the source -over HTTPS (HTTP is not supported). - -NOTE: -This might involve reconfiguring your firewall to prevent blocking connection on the side of self-managed instance. - -### Connect to the remote GitLab instance - -1. Go to the New Group page: - - - On the top bar, select `+` and then **New group**. - - Or, on an existing group's page, in the top right, select **New subgroup**. - -  - -1. On the New Group page, select **Import group**. - -  - -1. Enter the source URL of your GitLab instance. -1. Generate or copy a [personal access token](../../../user/profile/personal_access_tokens.md) - with the `api` and `read_repository` scopes on your remote GitLab instance. -1. Enter the [personal access token](../../../user/profile/personal_access_tokens.md) for your remote GitLab instance. -1. Select **Connect instance**. - -### Selecting which groups to import - -After you have authorized access to the GitLab instance, you are redirected to the GitLab Group -Migration importer page. The remote groups you have the Owner role for are listed. - -1. By default, the proposed group namespaces match the names as they exist in remote instance, but based on your permissions, you can choose to edit these names before you proceed to import any of them. -1. Next to the groups you want to import, select **Import**. -1. The **Status** column shows the import status of each group. If you leave the page open, it updates in real-time. -1. After a group has been imported, select its GitLab path to open its GitLab URL. - - - -## Automate group and project import **(PREMIUM)** - -For information on automating user, group, and project import API calls, see -[Automate group and project import](../../project/import/index.md#automate-group-and-project-import). diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 8aa9b8e799d..ec76dc52516 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -68,19 +68,9 @@ To create a group: - Select **Menu > Groups**, and on the right, select **Create group**. - To the left of the search box, select the plus sign and then **New group**. 1. Select **Create group**. -1. For the **Group name**, use only: - - Alphanumeric characters - - Emojis - - Underscores - - Dashes, dots, spaces, and parentheses (however, it cannot start with any of these characters) - - For a list of words that cannot be used as group names, see [reserved names](../reserved_names.md). - -1. For the **Group URL**, which is used for the [namespace](#namespaces), - use only: - - Alphanumeric characters - - Underscores - - Dashes and dots (it cannot start with dashes or end in a dot) +1. Enter a name for the group in **Group name**. For a list of words that cannot be used as group names, see + [reserved names](../reserved_names.md). +1. Enter a path for the group in **Group URL**, which is used for the [namespace](#namespaces). 1. Choose the [visibility level](../../public_access/public_access.md). 1. Personalize your GitLab experience by answering the following questions: - What is your role? @@ -138,7 +128,7 @@ your group. ## Change the owner of a group You can change the owner of a group. Each group must always have at least one -member with the [Owner role](../permissions.md#group-members-permissions). +member with the Owner role. - As an administrator: 1. Go to the group and from the left menu, select **Group information > Members**. @@ -153,7 +143,7 @@ member with the [Owner role](../permissions.md#group-members-permissions). Prerequisites: -- You must have the [Owner role](../permissions.md#group-members-permissions). +- You must have the Owner role. - The member must have direct membership in the group. If membership is inherited from a parent group, then the member can be removed from the parent group only. @@ -250,7 +240,7 @@ There are two different ways to add a new project to a group: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2534) in GitLab 10.5. > - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25975) from GitLab Premium to GitLab Free in 11.10. -By default, [Developers and Maintainers](../permissions.md#group-members-permissions) can create projects under a group. +By default, users with at least the Developer role can create projects under a group. To change this setting for a specific group: @@ -290,10 +280,15 @@ To view the activity feed in Atom format, select the ## Share a group with another group -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18328) in GitLab 12.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18328) in GitLab 12.7. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal window [with a flag](../feature_flags.md). Disabled by default. +> - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 14.8. -NOTE: -In GitLab 13.11, you can [replace this form with a modal window](#share-a-group-modal-window). +FLAG: +On self-managed GitLab, by default the modal window feature is available. +To hide the feature, ask an administrator to [disable the feature flag](../../administration/feature_flags.md) +named `invite_members_group_modal`. +On GitLab.com, this feature is available. Similar to how you [share a project with a group](../project/members/share_project_with_groups.md), you can share a group with another group. Members get direct access @@ -303,35 +298,14 @@ To share a given group, for example, `Frontend` with another group, for example, `Engineering`: 1. Go to the `Frontend` group. -1. From the left menu, select **Group information > Members**. -1. Select the **Invite group** tab. +1. On the left sidebar, select **Group information > Members**. +1. Select **Invite a group**. 1. In the **Select a group to invite** list, select `Engineering`. -1. For the **Max role**, select a [role](../permissions.md). +1. Select a [role](../permissions.md). 1. Select **Invite**. All the members of the `Engineering` group are added to the `Frontend` group. -### Share a group modal window - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11. -> - [Deployed behind a feature flag](../feature_flags.md), disabled by default. -> - Enabled on GitLab.com. -> - Recommended for production use. -> - Replaces the existing form with buttons to open a modal window. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](../project/members/index.md#enable-or-disable-modal-window). - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -In GitLab 13.11, you can optionally replace the sharing form with a modal window. -To share a group after enabling this feature: - -1. Go to your group's page. -1. On the left sidebar, go to **Group information > Members**, and then select **Invite a group**. -1. Select a group, and select a **Max role**. -1. Optional. Select an **Access expiration date**. -1. Select **Invite**. - ## Manage group memberships via LDAP **(PREMIUM SELF)** Group syncing allows LDAP groups to be mapped to GitLab groups. This provides more control over per-group user management. To configure group syncing, edit the `group_base` **DN** (`'OU=Global Groups,OU=GitLab INT,DC=GitLab,DC=org'`). This **OU** contains all groups that will be associated with GitLab groups. @@ -432,10 +406,22 @@ for the group's projects to meet your group's needs. To remove a group and its contents: -1. Go to your group's **Settings > General** page. -1. Expand the **Path, transfer, remove** section. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand the **Advanced** section. +1. In the **Remove group** section, select **Remove group**. +1. Type the group name. +1. Select **Confirm**. + +A group can also be removed from the groups dashboard: + +1. On the top bar, select **Menu > Groups**. +1. Select **Your Groups**. +1. Select (**{ellipsis_v}**) for the group you want to delete. +1. Select **Delete**. 1. In the Remove group section, select **Remove group**. -1. Confirm the action. +1. Type the group name. +1. Select **Confirm**. This action removes the group. It also adds a background job to delete all projects in the group. @@ -534,7 +520,7 @@ disabled for the group and its subgroups. Prerequisite: -- You must be assigned the [Owner role](../permissions.md#group-members-permissions) for the group. +- You must be assigned the Owner role) for the group. To specify a user cap: @@ -556,7 +542,7 @@ You can remove the user cap, so there is no limit on the number of members you c Prerequisite: -- You must be assigned the [Owner role](../permissions.md#group-members-permissions) for the group. +- You must be assigned the Owner role) for the group. To remove the user cap: @@ -575,7 +561,7 @@ and must be approved. Prerequisite: -- You must be assigned the [Owner role](../permissions.md#group-members-permissions) for the group. +- You must be assigned the Owner role) for the group. To approve members that are pending because they've exceeded the user cap: @@ -651,7 +637,7 @@ To restrict group access by IP address: 1. Go to the group's **Settings > General** page. 1. Expand the **Permissions and group features** section. -1. In the **Allow access to the following IP addresses** field, enter IP address ranges in CIDR notation. +1. In the **Allow access to the following IP addresses** field, enter IPv4 or IPv6 address ranges in CIDR notation. 1. Select **Save changes**.  @@ -803,7 +789,7 @@ Existing forks are not removed. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/224129) in GitLab 13.4. Group push rules allow group maintainers to set -[push rules](../../push_rules/push_rules.md) for newly created projects in the specific group. +[push rules](../project/repository/push_rules.md) for newly created projects in the specific group. To configure push rules for a group: diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 8a79effba15..c0bd6f1a672 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -52,7 +52,7 @@ With iteration cadences enabled, you must first Prerequisites: -- You must have at least the [Developer role](../../permissions.md) for a group. +- You must have at least the Developer role for a group. To create an iteration cadence: @@ -65,7 +65,7 @@ To create an iteration cadence: Prerequisites: -- You must have at least the [Developer role](../../permissions.md) for a group. +- You must have at least the Developer role for a group. Deleting an iteration cadence also deletes all iterations within that cadence. @@ -86,7 +86,7 @@ From there you can create a new iteration or select an iteration to get a more d Prerequisites: -- You must have at least the [Developer role](../../permissions.md) for a group. +- You must have at least the Developer role for a group. For manually scheduled iteration cadences, you create and add iterations yourself. @@ -104,7 +104,7 @@ To create an iteration: Prerequisites: -- You must have at least the [Developer role](../../permissions.md) for a group. +- You must have at least the Developer role for a group. To edit an iteration, select the three-dot menu (**{ellipsis_v}**) > **Edit**. @@ -114,7 +114,7 @@ To edit an iteration, select the three-dot menu (**{ellipsis_v}**) > **Edit**. Prerequisites: -- You must have at least the [Developer role](../../permissions.md) for a group. +- You must have at least the Developer role for a group. To delete an iteration, select the three-dot menu (**{ellipsis_v}**) > **Delete**. diff --git a/doc/user/group/planning_hierarchy/img/view-project-work-item-hierarchy_v14_8.png b/doc/user/group/planning_hierarchy/img/view-project-work-item-hierarchy_v14_8.png Binary files differnew file mode 100644 index 00000000000..2ddd551ee46 --- /dev/null +++ b/doc/user/group/planning_hierarchy/img/view-project-work-item-hierarchy_v14_8.png diff --git a/doc/user/group/planning_hierarchy/index.md b/doc/user/group/planning_hierarchy/index.md index 5887328abe4..934421e8a9a 100644 --- a/doc/user/group/planning_hierarchy/index.md +++ b/doc/user/group/planning_hierarchy/index.md @@ -5,7 +5,7 @@ group: Product Planning info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Planning hierarchies **(PREMIUM)** +# Planning hierarchies **(FREE)** Planning hierarchies are an integral part of breaking down your work in GitLab. To understand how you can use epics and issues together in hierarchies, remember the following: @@ -20,7 +20,21 @@ To learn about hierarchies in general, common frameworks, and using GitLab for portfolio management, see [How to use GitLab for Agile portfolio planning and project management](https://about.gitlab.com/blog/2020/11/11/gitlab-for-agile-portfolio-planning-project-management/). -## Hierarchies with epics +## View planning hierarchies + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340844/) in GitLab 14.8. + +To view the planning hierarchy in a project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Planning hierarchy**. + +Under **Current structure**, you can see a hierarchy diagram that matches your current planning hierarchy. +The work items outside your subscription plan show up below **Unavailable structure**. + + + +## Hierarchies with epics **(PREMIUM)** With epics, you can achieve the following hierarchy: @@ -54,14 +68,14 @@ Epic "1"*-- "0..*" Issue  -## View ancestry of an epic - -In an epic, you can view the ancestors as parents in the right sidebar under **Ancestors**. - - - ## View ancestry of an issue In an issue, you can view the parented epic above the issue in the right sidebar under **Epic**.  + +## View ancestry of an epic **(PREMIUM)** + +In an epic, you can view the ancestors as parents in the right sidebar under **Ancestors**. + + diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index 2487ab188e8..6e3ea7d6c0f 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -1,7 +1,6 @@ --- -type: reference stage: Verify -group: Testing +group: Pipeline Insights info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index 7d489bc5b2d..f10dc3bc22a 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -72,6 +72,26 @@ You can also filter epics in the Roadmap view by the epics': Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap-in-epics). +### Roadmap settings + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345158) in GitLab 14.8 [with a flag](../../../administration/feature_flags.md) named `roadmap_settings`. Enabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `roadmap_settings`. +On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. + +When you enable the roadmap settings sidebar, you can use it to refine epics shown in the roadmap. + +You can configure the following: + +- Select date range. +- Turn milestones on or off and select whether to show all, group, sub-group, or project milestones. +- Show all, open, or closed epics. +- Turn progress tracking for child issues on or off and select whether + to use issue weights or counts. + + The progress tracking setting is not saved in user preferences but is saved or shared using URL parameters. + ## Timeline duration > - Introduced in GitLab 11.0. diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md index 06e666f4d24..aeb7db923a9 100644 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ b/doc/user/group/saml_sso/group_managed_accounts.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 20ff4a201f5..14c4447c5c6 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -21,7 +21,7 @@ SAML SSO is only configurable at the top-level group. If required, you can find [a glossary of common terms](../../../integration/saml.md#glossary-of-common-terms). -## Configuring your identity provider +## Configure your identity provider 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Settings > SAML SSO**. @@ -32,7 +32,7 @@ If required, you can find [a glossary of common terms](../../../integration/saml 1. Configure the required [user attributes](#user-attributes), ensuring you include the user's email address. 1. While the default is enabled for most SAML providers, please ensure the app is set to have service provider initiated calls in order to link existing GitLab accounts. -1. Once the identity provider is set up, move on to [configuring GitLab](#configuring-gitlab). +1. Once the identity provider is set up, move on to [configuring GitLab](#configure-gitlab).  @@ -82,7 +82,7 @@ GitLab provides metadata XML that can be used to configure your identity provide 1. Copy the provided **GitLab metadata URL**. 1. Follow your identity provider's documentation and paste the metadata URL when it's requested. -## Configuring GitLab +## Configure GitLab After you set up your identity provider to work with GitLab, you must configure GitLab to use it for authentication: @@ -108,7 +108,9 @@ The certificate [fingerprint algorithm](../../../integration/saml.md#notes-on-co > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9152) in GitLab 13.11 with enforcing open SSO session to use Git if this setting is switched on. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/339888) in GitLab 14.7 to not enforce SSO checks for Git activity originating from CI/CD jobs. -With this option enabled, users (except users with the Owner role) must access GitLab using your group GitLab single sign-on URL to access group resources. Users added manually as members can't access group resources. +With this option enabled, users must access GitLab using your group GitLab single sign-on URL to access group resources. +Users can't be added as new members manually. +Users with the Owner role can use the standard sign in process to make necessary changes to top-level group settings. SSO enforcement does not affect sign in or access to any resources outside of the group. Users can view which groups and projects they are a member of without SSO sign in. @@ -116,7 +118,7 @@ However, users are not prompted to sign in through SSO on each visit. GitLab che has authenticated through SSO. If it's been more than 1 day since the last sign-in, GitLab prompts the user to sign in again through SSO. -We intend to add a similar SSO requirement for [API activity](https://gitlab.com/gitlab-org/gitlab/-/issues/297389). +An [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/297389) to add a similar SSO requirement for API activity. SSO has the following effects when enabled: @@ -127,7 +129,6 @@ SSO has the following effects when enabled: - Git activity originating from CI/CD jobs do not have the SSO check enforced. - Credentials that are not tied to regular users (for example, access tokens and deploy keys) do not have the SSO check enforced. - Users must be signed-in through SSO before they can pull images using the [Dependency Proxy](../../packages/dependency_proxy/index.md). -<!-- Add bullet for API activity when https://gitlab.com/gitlab-org/gitlab/-/issues/9152 is complete --> When SSO is enforced, users are not immediately revoked. If the user: @@ -139,7 +140,7 @@ When SSO is enforced, users are not immediately revoked. If the user: The SAML standard means that you can use a wide range of identity providers with GitLab. Your identity provider might have relevant documentation. It can be generic SAML documentation or specifically targeted for GitLab. -When [configuring your identity provider](#configuring-your-identity-provider), please consider the notes below for specific providers to help avoid common issues and as a guide for terminology used. +When [configuring your identity provider](#configure-your-identity-provider), please consider the notes below for specific providers to help avoid common issues and as a guide for terminology used. For providers not listed below, you can refer to the [instance SAML notes on configuring an identity provider](../../../integration/saml.md#notes-on-configuring-your-identity-provider) for additional guidance on information your identity provider may require. @@ -293,12 +294,16 @@ convert the information to XML. An example SAML response is shown here. ### Role -Starting from [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/214523), group owners can set a 'Default membership role' other than 'Guest'. To do so, [configure the SAML SSO for the group](#configuring-gitlab). That role becomes the starting access level of all users added to the group. +Starting from [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/214523), group owners can set a +"Default membership role" other than Guest. To do so, [configure the SAML SSO for the group](#configure-gitlab). +That role becomes the starting access level of all users added to the group. Existing members with appropriate privileges can promote or demote users, as needed. If a user is already a member of the group, linking the SAML identity does not change their role. +Users given a "minimal access" role have [specific restrictions](../../permissions.md#users-with-minimal-access). + ### Blocking access To rescind a user's access to the group when only SAML SSO is configured, either: @@ -336,6 +341,13 @@ For example, to unlink the `MyOrg` account: ## Group Sync +WARNING: +Changing Group Sync configuration can remove users from the relevant GitLab group. +Removal happens if there is any mismatch between the group names and the list of `groups` in the SAML response. +If changes must be made, ensure either the SAML response includes the `groups` attribute +and the `AttributeValue` value matches the **SAML Group Name** in GitLab, +or that all groups are removed from GitLab to disable Group Sync. + <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a demo of Group Sync using Azure, see [Demo: SAML Group Sync](https://youtu.be/Iqvo2tJfXjg). @@ -353,10 +365,6 @@ Ensure your SAML identity provider sends an attribute statement named `Groups` o </saml:AttributeStatement> ``` -WARNING: -Setting up Group Sync can disconnect users from SAML IDP if there is any mismatch in the configuration. Ensure the -`Groups` attribute is included in the SAML response, and the **SAML Group Name** matches the `AttributeValue` attribute. - Other attribute names such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` are not accepted as a source of groups. See the [SAML troubleshooting page](../../../administration/troubleshooting/group_saml_scim.md) @@ -533,7 +541,7 @@ This can then be compared to the [NameID](#nameid) being sent by the identity pr If you receive a `404` during setup when using "verify configuration", make sure you have used the correct [SHA-1 generated fingerprint](../../../integration/saml.md#notes-on-configuring-your-identity-provider). -If a user is trying to sign in for the first time and the GitLab single sign-on URL has not [been configured](#configuring-your-identity-provider), they may see a 404. +If a user is trying to sign in for the first time and the GitLab single sign-on URL has not [been configured](#configure-your-identity-provider), they may see a 404. As outlined in the [user access section](#linking-saml-to-your-existing-gitlabcom-account), a group Owner needs to provide the URL to users. ### Message: "SAML authentication failed: Extern UID has already been taken" diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index d7d663f4115..d1e9ba29378 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -1,7 +1,7 @@ --- type: howto, reference stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -49,22 +49,21 @@ Once [Group Single Sign-On](index.md) has been configured, we can: ### Azure configuration steps -The SAML application that was created during [Single sign-on](index.md) setup for [Azure](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal) now needs to be set up for SCIM. +The SAML application that was created during [Single sign-on](index.md) setup for [Azure](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal) now needs to be set up for SCIM. You can refer to [Azure SCIM setup documentation](https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/use-scim-to-provision-users-and-groups#getting-started). -1. Enable automatic provisioning and administrative credentials by following the - [Azure's SCIM setup documentation](https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/use-scim-to-provision-users-and-groups#provisioning-users-and-groups-to-applications-that-support-scim). +1. In your app, go to the Provisioning tab, and set the **Provisioning Mode** to **Automatic**. + Then fill in the **Admin Credentials**, and save. The **Tenant URL** and **secret token** are the items + retrieved in the [previous step](#gitlab-configuration). -During this configuration, note the following: +1. After saving, two more tabs appear: -- The `Tenant URL` and `secret token` are the items retrieved in the - [previous step](#gitlab-configuration). -- We recommend setting a notification email and selecting the **Send an email notification when a failure occurs** checkbox. -- For mappings, we only leave `Synchronize Azure Active Directory Users to AppName` enabled. - `Synchronize Azure Active Directory Groups to AppName` is usually disabled. However, this - does not mean Azure AD users cannot be provisioned in groups. Leaving it enabled does not break - the SCIM user provisioning, but causes errors in Azure AD that may be confusing and misleading. + - **Settings**: We recommend setting a notification email and selecting the **Send an email notification when a failure occurs** checkbox. + You also control what is actually synced by selecting the **Scope**. For example, **Sync only assigned users and groups** only syncs the users and groups assigned to the application. Otherwise, it syncs the whole Active Directory. -You can then test the connection by clicking on **Test Connection**. If the connection is successful, be sure to save your configuration before moving on. See below for [troubleshooting](#troubleshooting). + - **Mappings**: We recommend keeping **Provision Azure Active Directory Users** enabled, and disable **Provision Azure Active Directory Groups**. + Leaving **Provision Azure Active Directory Groups** enabled does not break the SCIM user provisioning, but it causes errors in Azure AD that may be confusing and misleading. + +1. You can then test the connection by selecting **Test Connection**. If the connection is successful, save your configuration before moving on. See below for [troubleshooting](#troubleshooting). #### Configure attribute mapping @@ -93,11 +92,6 @@ For guidance, you can view [an example configuration in the troubleshooting refe 1. Save all changes. 1. In the **Provisioning** step, set the `Provisioning Status` to `On`. - NOTE: - You can control what is actually synced by selecting the `Scope`. For example, - `Sync only assigned users and groups` only syncs the users assigned to - the application (`Users and groups`), otherwise, it syncs the whole Active Directory. - Once enabled, the synchronization details and any errors appears on the bottom of the **Provisioning** screen, together with a link to the audit events. diff --git a/doc/user/group/settings/group_access_tokens.md b/doc/user/group/settings/group_access_tokens.md index 816edb629f5..769943cd5d8 100644 --- a/doc/user/group/settings/group_access_tokens.md +++ b/doc/user/group/settings/group_access_tokens.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -140,8 +140,11 @@ To enable or disable group access token creation for all sub-groups in a top-lev Even when creation is disabled, you can still use and revoke existing group access tokens. -## Bot users +## Bot users for groups Each time you create a group access token, a bot user is created and added to the group. -These bot users are similar to [project bot users](../../project/settings/project_access_tokens.md#project-bot-users), but are added to groups instead of projects. For more information, see -[Project bot users](../../project/settings/project_access_tokens.md#project-bot-users). +These bot users are similar to [bot users for projects](../../project/settings/project_access_tokens.md#bot-users-for-projects), +except they are added to groups instead of projects. +These bot users do not count as licensed seats. + +For more information, see [Bot users for projects](../../project/settings/project_access_tokens.md#bot-users-for-projects). diff --git a/doc/user/group/settings/import_export.md b/doc/user/group/settings/import_export.md index 5745c499c5c..7b63466656d 100644 --- a/doc/user/group/settings/import_export.md +++ b/doc/user/group/settings/import_export.md @@ -16,7 +16,7 @@ You can also [export projects](../../project/settings/import_export.md). Prerequisite: -- You must have the [Owner role](../../permissions.md) for the group. +- You must have the Owner role for the group. To enable import and export for a group: @@ -69,7 +69,7 @@ in GitLab 14.6 and replaced by [GitLab Migration](../import/). Prerequisites: -- You must have the [Owner role](../../permissions.md) for the group. +- You must have the Owner role for the group. To export the contents of a group: diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index ef984a76a7d..46dea81ae9f 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto, concepts --- @@ -158,7 +158,7 @@ added to), add the user to the new subgroup again with a higher set of permissio For example, if User 1 was first added to group `one/two` with Developer permissions, then they inherit those permissions in every other subgroup -of `one/two`. To give them the [Maintainer role](../../permissions.md) for group `one/two/three/four`, +of `one/two`. To give them the Maintainer role for group `one/two/three/four`, you would add them again in that group as Maintainer. Removing them from that group, the permissions fall back to those of the ancestor group. diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index 4663cfc8bfd..ccf77f79fd9 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -117,16 +117,15 @@ production environment for all merge requests deployed in the given time period. The "Recent Activity" metrics near the top of the page are measured as follows: - **New Issues:** the number of issues created in the date range. -- **Deploys:** the number of deployments <sup>1</sup> to production <sup>2</sup> in the date range. -- **Deployment Frequency:** the average number of deployments <sup>1</sup> to production <sup>2</sup> +- **Deploys:** the number of deployments to production in the date range. +- **Deployment Frequency:** the average number of deployments to production per day in the date range. -1. To give a more accurate representation of deployments that actually completed successfully, - the calculation for these two metrics changed in GitLab 13.9 from using the time a deployment was - created to the time a deployment finished. If you were referencing this metric prior to 13.9, please - keep this slight change in mind. -1. To see deployment metrics, you must have a - [production environment configured](../../../ci/environments/index.md#deployment-tier-of-environments). +To see deployment metrics, you must have a [production environment configured](../../../ci/environments/index.md#deployment-tier-of-environments). + +NOTE: +In GitLab 13.9 and later, deployment metrics are calculated based on when the deployment was finished. +In GitLab 13.8 and earlier, deployment metrics are calculated based on when the deployment was created. You can learn more about these metrics in our [analytics definitions](../../analytics/index.md). diff --git a/doc/user/index.md b/doc/user/index.md index a3b7cfc4b3c..f4a7cd6a5d9 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -44,7 +44,7 @@ GitLab is a Git-based platform that integrates a great number of essential tools - Tracking proposals for new implementations, bug reports, and feedback with a fully featured [Issue tracker](project/issues/index.md). - Organizing and prioritizing with [issue boards](project/issue_board.md). -- Reviewing code in [Merge Requests](project/merge_requests/index.md) with live-preview changes per +- Reviewing code in [merge requests](project/merge_requests/index.md) with live-preview changes per branch with [Review Apps](../ci/review_apps/index.md). - Building, testing, and deploying with built-in [Continuous Integration](../ci/index.md). - Deploying personal and professional static websites with [GitLab Pages](project/pages/index.md). @@ -56,7 +56,7 @@ GitLab is a Git-based platform that integrates a great number of essential tools With GitLab Enterprise Edition, you can also: - Improve collaboration with: - - [Merge Request Approvals](project/merge_requests/approvals/index.md). + - [Merge request approvals](project/merge_requests/approvals/index.md). - [Multiple Assignees for Issues](project/issues/multiple_assignees_for_issues.md). - [Multiple issue boards](project/issue_board.md#multiple-issue-boards). - Create formal relationships between issues with [linked issues](project/issues/related_issues.md). @@ -152,8 +152,8 @@ it all at once, from one single project. - [Repositories](project/repository/index.md): Host your codebase in repositories with version control and as part of a fully integrated platform. - [Issues](project/issues/index.md): Explore the best of GitLab Issues' features. -- [Merge Requests](project/merge_requests/index.md): Collaborate on code, - reviews, live preview changes per branch, and request approvals with Merge Requests. +- [Merge requests](project/merge_requests/index.md): Collaborate on code, + reviews, live preview changes per branch, and request approvals with merge requests. - [Milestones](project/milestones/index.md): Work on multiple issues and merge requests towards the same target date with Milestones. diff --git a/doc/user/infrastructure/clusters/connect/index.md b/doc/user/infrastructure/clusters/connect/index.md index 9e57622875d..06d1307984d 100644 --- a/doc/user/infrastructure/clusters/connect/index.md +++ b/doc/user/infrastructure/clusters/connect/index.md @@ -15,28 +15,6 @@ If you don't have a cluster yet, create one and connect it to GitLab through the You can also create a new cluster from GitLab using [Infrastructure as Code](../../iac/index.md#create-a-new-cluster-through-iac). --> -## Supported cluster versions - -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 three-month deprecation period before we remove support of a specific -version. The range of supported versions is based on the evaluation of: - -- The versions supported by major managed Kubernetes providers. -- The versions [supported by the Kubernetes community](https://kubernetes.io/releases/version-skew-policy/#supported-versions). - -GitLab supports the following Kubernetes versions, and you can upgrade your -Kubernetes version to any supported version at any time: - -- 1.20 (support ends on July 22, 2022) -- 1.19 (support ends on February 22, 2022) -- 1.18 (support ends on November 22, 2021) -- 1.17 (support ends on September 22, 2021) - -[Adding support to other versions of Kubernetes is managed under this epic](https://gitlab.com/groups/gitlab-org/-/epics/4827). - -Some GitLab features may support versions outside the range provided here. - ## Cluster levels (DEPRECATED) > [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md index 12f99af8d8d..58de5f5e368 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/certmanager.md @@ -8,48 +8,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. > - Support for cert-manager v1.4 was [introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/69405) in GitLab 14.3. +> - [Upgraded](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/23) to cert-manager 1.7 in GitLab 14.8. Assuming you already have a [Cluster management project](../../../../../user/clusters/management_project.md) created from a [management project template](../../../../../user/clusters/management_project_template.md), to install cert-manager you should uncomment this line from your `helmfile.yaml`: ```yaml - - path: applications/cert-manager-1-4/helmfile.yaml + - path: applications/cert-manager/helmfile.yaml ``` NOTE: -We kept the `- path: applications/cert-manager/helmfile.yaml` with cert-manager v0.10 to facilitate -the [migration from GitLab Managed Apps to a cluster management project](../../../../clusters/migrating_from_gma_to_project_template.md). +If your Kubernetes version is earlier than 1.20 and you are [migrating from GitLab +Managed Apps to a cluster management +project](../../../../clusters/migrating_from_gma_to_project_template.md), then +you can instead use `- path: applications/cert-manager-legacy/helmfile.yaml` to +take over an existing release of cert-manager v0.10. cert-manager: - Is installed by default into the `gitlab-managed-apps` namespace of your cluster. -- Can be installed with or without a default - [Let's Encrypt `ClusterIssuer`](https://cert-manager.io/docs/configuration/acme/), which requires an - email address to be specified. The email address is used by Let's Encrypt to +- Includes a + [Let's Encrypt + `ClusterIssuer`](https://cert-manager.io/docs/configuration/acme/) enabled by + default. In the `certmanager-issuer` release, the issuer requires a valid email address + for `letsEncryptClusterIssuer.email`. Let's Encrypt uses this email address to contact you about expiring certificates and issues related to your account. - -To install cert-manager in your cluster, configure your `applications/cert-manager-1-4/helmfile.yaml` to: - -```yaml -certManager: - installed: true - letsEncryptClusterIssuer: - installed: true - email: "user@example.com" -``` - -Or without the default `ClusterIssuer`: - -```yaml -certManager: - installed: true - letsEncryptClusterIssuer: - installed: false -``` - -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://github.com/jetstack/cert-manager) for the -available configuration options. +- Can be customized in `applications/cert-manager/helmfile.yaml` by passing custom + `values` to the `certmanager` release. Refer to the + [chart](https://github.com/jetstack/cert-manager) for the available + configuration options. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md b/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md index 3bd675b7439..f9d0948a2bb 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/elasticstack.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md b/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md index fd2eed25997..f76c7363a83 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md b/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md index 9e5d7860a67..b968e63d632 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index ceb6101688b..6fef1aa7879 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -6,36 +6,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Infrastructure as Code with Terraform and GitLab **(FREE)** -## Motivation +With Terraform in GitLab, you can use GitLab authentication and authorization with +your GitOps and Infrastructure-as-Code (IaC) workflows. +Use these features if you want to collaborate on Terraform code within GitLab or would like to use GitLab as a Terraform state storage that incorporates best practices out of the box. -The Terraform integration features in GitLab enable your GitOps / Infrastructure-as-Code (IaC) -workflows to tie into GitLab authentication and authorization. These features focus on -lowering the barrier to entry for teams to adopt Terraform, collaborate effectively in -GitLab, and support Terraform best practices. - -## Quick Start +## Integrate your project with Terraform > SAST test was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6655) in GitLab 14.6. -Use the following `.gitlab-ci.yml` to set up a basic Terraform project integration -for GitLab versions 14.0 and later: +In GitLab 14.0 and later, to integrate your project with Terraform, add the following +to your `.gitlab-ci.yml` file: ```yaml include: - template: Terraform.latest.gitlab-ci.yml variables: - # If not using GitLab's HTTP backend, remove this line and specify TF_HTTP_* variables + # If you do not use the GitLab HTTP backend, remove this line and specify TF_HTTP_* variables TF_STATE_NAME: default TF_CACHE_KEY: default # If your terraform files are in a subdirectory, set TF_ROOT accordingly # TF_ROOT: terraform/production ``` -This template includes the following parameters that you can override: +The `Terraform.latest.gitlab-ci.yml` template: - Uses the latest [GitLab Terraform image](https://gitlab.com/gitlab-org/terraform-images). -- Uses the [GitLab-managed Terraform State](#gitlab-managed-terraform-state) as +- Uses the [GitLab-managed Terraform state](#gitlab-managed-terraform-state) as the Terraform state storage backend. - Creates [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml): `test`, `validate`, `build`, and `deploy`. These stages @@ -44,10 +41,12 @@ This template includes the following parameters that you can override: - Runs the [Terraform SAST scanner](../../application_security/iac_scanning/index.md#configure-iac-scanning-manually), that you can disable by creating a `SAST_DISABLED` environment variable and setting it to `1`. -The latest template described above might contain breaking changes between major GitLab releases. For users requiring more stable setups, we -recommend using the stable templates: +You can override the values in the default template by updating your `.gitlab-ci.yml` file. + +The latest template might contain breaking changes between major GitLab releases. +For a more stable template, we recommend: -- [A ready to use version](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) +- [A ready-to-use version](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) - [A base template for customized setups](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml) This video from January 2021 walks you through all the GitLab Terraform integration features: @@ -59,7 +58,7 @@ This video from January 2021 walks you through all the GitLab Terraform integrat <iframe src="https://www.youtube.com/embed/iGXjUrkkzDI" frameborder="0" allowfullscreen="true"> </iframe> </figure> -## GitLab Managed Terraform state +## GitLab-managed Terraform state [Terraform remote backends](https://www.terraform.io/docs/language/settings/backends/index.html) enable you to store the state file in a remote, shared store. GitLab uses the @@ -67,7 +66,7 @@ enable you to store the state file in a remote, shared store. GitLab uses the 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 +The GitLab-managed Terraform state backend can store your Terraform state easily and securely. It spares you from setting up additional remote resources like Amazon S3 or Google Cloud Storage. Its features include: @@ -75,7 +74,7 @@ Amazon S3 or Google Cloud Storage. Its features include: - Locking and unlocking state. - Remote Terraform plan and apply execution. -Read more on setting up and [using GitLab Managed Terraform states](terraform_state.md). +Read more about setting up and [using GitLab-managed Terraform states](terraform_state.md). ## Terraform module registry @@ -83,12 +82,12 @@ GitLab can be used as a [Terraform module registry](../../packages/terraform_mod to create and publish Terraform modules to a private registry specific to your top-level namespace. -## Terraform integration in Merge Requests +## 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 +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. Read more on setting up and [using the merge request integrations](mr_integration.md). @@ -104,7 +103,7 @@ to manage various aspects of GitLab using Terraform. The provider is an open sou owned by GitLab, where everyone can contribute. The [documentation of the provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs) -is available as part of the official Terraform provider documentations. +is available as part of the official Terraform provider documentation. ## Create a new cluster through IaC (DEPRECATED) @@ -114,66 +113,9 @@ NOTE: The linked tutorial connects the cluster to GitLab through cluster certificates, and this method was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. You can still create a cluster through IaC and then connect it to GitLab -through the [Agent](../../clusters/agent/index.md), the default and fully supported +through the [agent](../../clusters/agent/index.md), the default and fully supported method to connect clusters to GitLab. ## Troubleshooting -### `gitlab_group_share_group` resources not detected when subgroup state is refreshed - -The GitLab Terraform provider can fail to detect existing `gitlab_group_share_group` resources -due to the issue ["User with permissions cannot retrieve `share_with_groups` from the API"](https://gitlab.com/gitlab-org/gitlab/-/issues/328428). -This results in an error when running `terraform apply` because Terraform attempts to recreate an -existing resource. - -For example, consider the following group/subgroup configuration: - -```plaintext -parent-group -├── subgroup-A -└── subgroup-B -``` - -Where: - -- User `user-1` creates `parent-group`, `subgroup-A`, and `subgroup-B`. -- `subgroup-A` is shared with `subgroup-B`. -- User `terraform-user` is member of `parent-group` with inherited `owner` access to both subgroups. - -When the Terraform state is refreshed, the API query `GET /groups/:subgroup-A_id` issued by the provider does not return the -details of `subgroup-B` in the `shared_with_groups` array. This leads to the error. - -To workaround this issue, make sure to apply one of the following conditions: - -1. The `terraform-user` creates all subgroup resources. -1. Grant Maintainer or Owner role to the `terraform-user` user on `subgroup-B`. -1. The `terraform-user` inherited access to `subgroup-B` and `subgroup-B` contains at least one project. - -### Invalid CI/CD syntax error when using the "latest" base template - -On GitLab 14.2 and later, you might get a CI/CD syntax error when using the -`latest` Base Terraform template: - -```yaml -include: - - template: Terraform/Base.latest.gitlab-ci.yml - -my-Terraform-job: - extends: .init -``` - -The base template's [jobs were renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67719/) -with better Terraform-specific names. To resolve the syntax error, you can: - -- Use the stable `Terraform/Base.gitlab-ci.yml` template, which has not changed. -- Update your pipeline configuration to use the new job names in - `https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Terraform/Base.latest.gitlab-ci.yml`. - For example: - - ```yaml - include: - - template: Terraform/Base.latest.gitlab-ci.yml - - my-Terraform-job: - extends: .terraform:init # The updated name. - ``` +See the [troubleshooting](troubleshooting.md) documentation. diff --git a/doc/user/infrastructure/iac/mr_integration.md b/doc/user/infrastructure/iac/mr_integration.md index ab59f8ad64b..8c135f18bc1 100644 --- a/doc/user/infrastructure/iac/mr_integration.md +++ b/doc/user/infrastructure/iac/mr_integration.md @@ -4,9 +4,9 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Terraform integration in Merge Requests **(FREE)** +# Terraform integration in merge requests **(FREE)** -Collaborating around Infrastructure as Code (IaC) changes requires both code changes and expected infrastructure changes to be checked and approved. GitLab provides a solution to help collaboration around Terraform code changes and their expected effects using the Merge Request pages. This way users don't have to build custom tools or rely on 3rd party solutions to streamline their IaC workflows. +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 @@ -16,14 +16,14 @@ enabling you to see statistics about the resources that Terraform creates, modifies, or destroys. WARNING: -Like any other job artifact, Terraform Plan data is viewable by anyone with the Guest [role](../../permissions.md) on the repository. +Like any other job artifact, Terraform Plan data is viewable by anyone with the Guest role for 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, we strongly recommend encrypting plan output or modifying the project visibility settings. ## Configure Terraform report artifacts -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. +GitLab ships with a [pre-built CI template](index.md#integrate-your-project-with-terraform) 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: @@ -83,7 +83,7 @@ To manually configure a GitLab Terraform Report artifact: 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: @@ -151,8 +151,8 @@ apply: ### 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. +Starting with GitLab version 13.2, you can display multiple reports on a merge request. +The reports also display the `artifacts: name:`. See example below for a suggested setup. ```yaml default: diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index a45ef02622f..8fd38215b04 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab managed Terraform State **(FREE)** +# GitLab-managed Terraform state **(FREE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. @@ -19,7 +19,7 @@ Using local storage (the default) on clustered deployments of GitLab will result a split state across nodes, making subsequent executions of Terraform inconsistent. You are highly advised to use a remote storage resource in that case. -The GitLab managed Terraform state backend can store your Terraform state easily and +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: @@ -33,11 +33,13 @@ before using this feature. ## Permissions for using Terraform -In GitLab version 13.1, the [Maintainer role](../../permissions.md) was required to use a -GitLab managed Terraform state backend. In GitLab versions 13.2 and greater, the -[Maintainer role](../../permissions.md) is required to lock, unlock, and write to the state -(using `terraform apply`), while the [Developer role](../../permissions.md) is required to read -the state (using `terraform plan -lock=false`). +In GitLab version 13.1, at least the Maintainer role was required to use a +GitLab managed Terraform state backend. + +In GitLab versions 13.2 and later, at least: + +- The Maintainer role is required to lock, unlock, and write to the state (using `terraform apply`). +- The Developer role is required to read the state (using `terraform plan -lock=false`). ## Set up GitLab-managed Terraform state @@ -72,9 +74,8 @@ local machine, this is a simple way to get started: 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 in 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`: + Terraform state, and stores that state in your GitLab project. This example + uses `gitlab.com`: ```shell terraform init \ @@ -88,6 +89,10 @@ local machine, this is a simple way to get started: -backend-config="retry_wait_min=5" ``` + WARNING: + The name of your state can contain only uppercase and lowercase letters, decimal digits, + hyphens, and underscores. + If you already have a GitLab-managed Terraform state, you can use the `terraform init` command with the pre-populated parameters values: @@ -205,7 +210,7 @@ and the CI YAML file: The output from the above `terraform` commands should be viewable in the job logs. WARNING: -Like any other job artifact, Terraform plan data is viewable by anyone with the Guest [role](../../permissions.md) on the repository. +Like any other job artifact, Terraform plan data is viewable by anyone with the Guest role on 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. @@ -214,7 +219,7 @@ recommends encrypting plan output or modifying the project visibility settings. See [this reference project](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-aws) using GitLab and Terraform to deploy a basic AWS EC2 in a custom VPC. -## Using a GitLab managed Terraform state backend as a remote data source +## 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/language/state/remote-state-data.html). @@ -255,16 +260,16 @@ An example setup is shown below: Outputs from the data source can now be referenced in your Terraform resources using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`. -You need at least the [Developer role](../../permissions.md) in the target project +You need at least the Developer role in the target project to read the Terraform state. -## Migrating to GitLab Managed 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. +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. +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 @@ -313,6 +318,7 @@ the old state is, you can tell it about the new location: TF_ADDRESS="https://gitlab.com/api/v4/projects/${PROJECT_ID}/terraform/state/new-state-name" terraform init \ + -migrate-state \ -backend-config=address=${TF_ADDRESS} \ -backend-config=lock_address=${TF_ADDRESS}/lock \ -backend-config=unlock_address=${TF_ADDRESS}/lock \ @@ -364,7 +370,7 @@ location. You can then go back to running it in GitLab CI/CD. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273592) in GitLab 13.8. -Users with Developer and greater [permissions](../../permissions.md) can view the +Users with at least the Developer role can view the state files attached to a project at **Infrastructure > Terraform**. Users with the Maintainer role can perform commands on the state files. The user interface contains these fields: @@ -383,9 +389,27 @@ Additional improvements to the [graphical interface for managing state files](https://gitlab.com/groups/gitlab-org/-/epics/4563) are planned. +## Manage individual Terraform state versions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207347) in GitLab 13.4. + +Individual state versions can be managed using the GitLab REST API. + +Users with the [Developer role](../../permissions.md) can retrieve state versions using their serial number. To retrieve a version: + +```shell +curl --header "Private-Token: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<your_project_id>/terraform/state/<your_state_name>/versions/<version-serial>" +``` + +Users with the [Maintainer role](../../permissions.md) can remove state versions using their serial number. To remove a version: + +```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>/versions/<version-serial>" +``` + ## Remove a state file -Users with Maintainer and greater [permissions](../../permissions.md) can use the +Users with at least the Maintainer role can use the following options to remove a state file: - **GitLab UI**: Go to **Infrastructure > Terraform**. In the **Actions** column, @@ -444,3 +468,15 @@ This happens because the value of `$CI_JOB_TOKEN` is only valid for the duration As a workaround, use [http backend configuration variables](https://www.terraform.io/docs/language/settings/backends/http.html#configuration-variables) in your CI job, which is what happens behind the scenes when following the [Get started using GitLab CI](#get-started-using-gitlab-ci) instructions. + +### Error: "address": required field is not set + +By default, we set `TF_ADDRESS` to `${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/${TF_STATE_NAME}`. +If you don't set `TF_STATE_NAME` or `TF_ADDRESS` in your job, the job fails with the error message +`Error: "address": required field is not set`. + +To resolve this, ensure that either `TF_ADDRESS` or `TF_STATE_NAME` is accessible in the +job that returned the error: + +1. Configure the [CI/CD environment scope](../../../ci/variables/#add-a-cicd-variable-to-a-project) for the job. +1. Set the job's [environment](../../../ci/yaml/#environment), matching the environment scope from the previous step. diff --git a/doc/user/infrastructure/iac/troubleshooting.md b/doc/user/infrastructure/iac/troubleshooting.md new file mode 100644 index 00000000000..ecefa20db99 --- /dev/null +++ b/doc/user/infrastructure/iac/troubleshooting.md @@ -0,0 +1,68 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Troubleshooting the Terraform integration with GitLab + +When you are using the integration with Terraform and GitLab, you might experience issues you need to troubleshoot. + +## `gitlab_group_share_group` resources not detected when subgroup state is refreshed + +The GitLab Terraform provider can fail to detect existing `gitlab_group_share_group` resources +due to the issue ["User with permissions cannot retrieve `share_with_groups` from the API"](https://gitlab.com/gitlab-org/gitlab/-/issues/328428). +This results in an error when running `terraform apply` because Terraform attempts to recreate an +existing resource. + +For example, consider the following group/subgroup configuration: + +```plaintext +parent-group +├── subgroup-A +└── subgroup-B +``` + +Where: + +- User `user-1` creates `parent-group`, `subgroup-A`, and `subgroup-B`. +- `subgroup-A` is shared with `subgroup-B`. +- User `terraform-user` is member of `parent-group` with inherited `owner` access to both subgroups. + +When the Terraform state is refreshed, the API query `GET /groups/:subgroup-A_id` issued by the provider does not return the +details of `subgroup-B` in the `shared_with_groups` array. This leads to the error. + +To workaround this issue, make sure to apply one of the following conditions: + +1. The `terraform-user` creates all subgroup resources. +1. Grant Maintainer or Owner role to the `terraform-user` user on `subgroup-B`. +1. The `terraform-user` inherited access to `subgroup-B` and `subgroup-B` contains at least one project. + +### Invalid CI/CD syntax error when using the `latest` base template + +On GitLab 14.2 and later, you might get a CI/CD syntax error when using the +`latest` Base Terraform template: + +```yaml +include: + - template: Terraform/Base.latest.gitlab-ci.yml + +my-Terraform-job: + extends: .init +``` + +The base template's [jobs were renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67719/) +with better Terraform-specific names. To resolve the syntax error, you can: + +- Use the stable `Terraform/Base.gitlab-ci.yml` template, which has not changed. +- Update your pipeline configuration to use the new job names in + `https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Terraform/Base.latest.gitlab-ci.yml`. + For example: + + ```yaml + include: + - template: Terraform/Base.latest.gitlab-ci.yml + + my-Terraform-job: + extends: .terraform:init # The updated name. + ``` diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 3d640185a55..a16f8fd39b1 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -539,6 +539,7 @@ GitLab Flavored Markdown recognizes the following: | repository file references | `[README](doc/README.md)` | | | | repository file line references | `[README](doc/README.md#L13)` | | | | [alert](../operations/incident_management/alerts.md) | `^alert#123` | `namespace/project^alert#123` | `project^alert#123` | +| contact | `[contact:test@example.com]` | | | 1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222483) in GitLab 13.7. diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 23bd140d4b7..5cfb4278a2c 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -349,6 +349,16 @@ used to access them: subgroups. - A project deploy token only has access to packages published to that particular project. +## Troubleshooting + +To improve performance, Composer caches files related to a package. Note that Composer doesn't remove data by +itself. The cache grows as new packages are installed. If you encounter issues, clear the cache with +this command: + +```shell +composer clearcache +``` + ## Supported CLI commands The GitLab Composer repository supports the following Composer CLI commands: diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index c77fc5a0f4b..b28f0cbfb35 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -489,11 +489,13 @@ Container Registry. ## Limitations - Moving or renaming existing Container Registry repositories is not supported -once you have pushed images, because the images are stored in a path that matches -the repository path. To move or rename a repository with a -Container Registry, you must delete all existing images. + once you have pushed images, because the images are stored in a path that matches + the repository path. To move or rename a repository with a + Container Registry, you must delete all existing images. + Community suggestions to work around this limitation have been shared in + [issue 18383](https://gitlab.com/gitlab-org/gitlab/-/issues/18383#possible-workaround). - Prior to GitLab 12.10, any tags that use the same image ID as the `latest` tag -are not deleted by the cleanup policy. + are not deleted by the cleanup policy. ## Disable the Container Registry for a project @@ -581,103 +583,27 @@ For information on how to update your images, see the [Docker help](https://docs ### `Blob unknown to registry` error when pushing a manifest list -When [pushing a Docker manifest list](https://docs.docker.com/engine/reference/commandline/manifest/#create-and-push-a-manifest-list) to the GitLab Container Registry, you may receive the error `manifest blob unknown: blob unknown to registry`. [This issue](https://gitlab.com/gitlab-org/gitlab/-/issues/209008) occurs when the individual child manifests referenced in the manifest list were not pushed to the same repository. +When [pushing a Docker manifest list](https://docs.docker.com/engine/reference/commandline/manifest/#create-and-push-a-manifest-list) +to the GitLab Container Registry, you may receive the error +`manifest blob unknown: blob unknown to registry`. This is likely caused by having multiple images +with different architectures, spread out over several repositories instead of the same repository. -For example, you may have two individual images, one for `amd64` and another for `arm64v8`, and you want to build a multi-arch image with them. The `amd64` and `arm64v8` images must be pushed to the same repository where you want to push the multi-arch image. +For example, you may have two images, each representing an architecture: -As a workaround, you should include the architecture in the tag name of individual images. For example, use `mygroup/myapp:1.0.0-amd64` instead of using sub repositories, like `mygroup/myapp/amd64:1.0.0`. You can then tag the manifest list with `mygroup/myapp:1.0.0`. +- The `amd64` platform +- The `arm64v8` platform -### The cleanup policy doesn't delete any tags +To build a multi-arch image with these images, you must push them to the same repository as the +multi-arch image. -There can be different reasons behind this: - -- In GitLab 13.6 and earlier, when you run the cleanup policy you may expect it to delete tags and - it does not. This occurs when the cleanup policy is saved without editing the value in the - **Remove tags matching** field. This field has a grayed out `.*` value as a placeholder. Unless - `.*` (or another regex pattern) is entered explicitly into the field, a `nil` value is submitted. - This value prevents the saved cleanup policy from matching any tags. As a workaround, edit the - cleanup policy. In the **Remove tags matching** field, enter `.*` and save. This value indicates - that all tags should be removed. - -- If you are on GitLab self-managed instances and you have 1000+ tags in a container repository, you - might run into a [Container Registry token expiration issue](https://gitlab.com/gitlab-org/gitlab/-/issues/288814), - with `error authorizing context: invalid token` in the logs. - - To fix this, there are two workarounds: - - - If you are on GitLab 13.9 or later, you can [set limits for the cleanup policy](reduce_container_registry_storage.md#set-cleanup-limits-to-conserve-resources). - This limits the cleanup execution in time, and avoids the expired token error. - - - Extend the expiration delay of the Container Registry authentication tokens. This defaults to 5 - minutes. You can set a custom value by running - `ApplicationSetting.last.update(container_registry_token_expire_delay: <integer>)` in the Rails - console, where `<integer>` is the desired number of minutes. For reference, 15 minutes is the - value currently in use for GitLab.com. Be aware that by extending this value you increase the - time required to revoke permissions. - -If the previous fixes didn't work or you are on earlier versions of GitLab, you can generate a list -of the tags that you want to delete, and then use that list to delete the tags. To do this, follow -these steps: - -1. Run the following shell script. The command just before the `for` loop ensures that - `list_o_tags.out` is always reinitialized when starting the loop. After running this command, all - the tags' names will be in the `list_o_tags.out` file: - - ```shell - # Get a list of all tags in a certain container repository while considering [pagination](../../../api/index.md#pagination) - echo -n "" > list_o_tags.out; for i in {1..N}; do curl --header 'PRIVATE-TOKEN: <PAT>' "https://gitlab.example.com/api/v4/projects/<Project_id>/registry/repositories/<container_repo_id>/tags?per_page=100&page=${i}" | jq '.[].name' | sed 's:^.\(.*\).$:\1:' >> list_o_tags.out; done - ``` - - If you have Rails console access, you can enter the following commands to retrieve a list of tags limited by date: - - ```shell - output = File.open( "/tmp/list_o_tags.out","w" ) - Project.find(<Project_id>).container_repositories.find(<container_repo_id>).tags.each do |tag| - output << tag.name + "\n" if tag.created_at < 1.month.ago - end;nil - output.close - ``` - - This set of commands creates a `/tmp/list_o_tags.out` file listing all tags with a `created_at` date of older than one month. - -1. Remove from the `list_o_tags.out` file any tags that you want to keep. Here are some example - `sed` commands for this. Note that these commands are simply examples. You may change them to - best suit your needs: - - ```shell - # Remove the `latest` tag from the file - sed -i '/latest/d' list_o_tags.out - - # Remove the first N tags from the file - sed -i '1,Nd' list_o_tags.out - - # Remove the tags starting with `Av` from the file - sed -i '/^Av/d' list_o_tags.out - - # Remove the tags ending with `_v3` from the file - sed -i '/_v3$/d' list_o_tags.out - ``` - - If you are running macOS, you must add `.bak` to the commands. For example: - - ```shell - sed -i .bak '/latest/d' list_o_tags.out - ``` - -1. Double-check the `list_o_tags.out` file to make sure it contains only the tags that you want to - delete. - -1. Run this shell script to delete the tags in the `list_o_tags.out` file: - - ```shell - # loop over list_o_tags.out to delete a single tag at a time - while read -r LINE || [[ -n $LINE ]]; do echo ${LINE}; curl --request DELETE --header 'PRIVATE-TOKEN: <PAT>' "https://gitlab.example.com/api/v4/projects/<Project_id>/registry/repositories/<container_repo_id>/tags/${LINE}"; sleep 0.1; echo; done < list_o_tags.out > delete.logs - ``` +To address the `Blob unknown to registry` error, include the architecture in the tag name of +individual images. For example, use `mygroup/myapp:1.0.0-amd64` and `mygroup/myapp:1.0.0-arm64v8`. +You can then tag the manifest list with `mygroup/myapp:1.0.0`. ### Troubleshoot as a GitLab server administrator Troubleshooting the GitLab Container Registry, most of the times, requires -you to log in to GitLab server with the Administrator role. +you to log in to GitLab server with administrator access. [Read how to troubleshoot the Container Registry](../../../administration/packages/container_registry.md#troubleshooting). diff --git a/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md b/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md new file mode 100644 index 00000000000..5f678a661f8 --- /dev/null +++ b/doc/user/packages/container_registry/reduce_container_registry_data_transfer.md @@ -0,0 +1,133 @@ +--- +stage: Package +group: Package +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Reduce Container Registry data transfers **(FREE)** + +Depending on the frequency with which images or tags are downloaded from the Container Registry, +data transfers can exceed the GitLab limit. This page offers several recommendations and tips for +reducing the amount of data you transfer with the Container Registry. +are downloaded from the Container Registry, data transfers can exceed the GitLab limit. This page +offers several recommendations and tips for reducing the amount of data you transfer with the +Container Registry. + +## Check data transfer use + +Transfer usage is not available within the GitLab UI. [GitLab-#350905](https://gitlab.com/gitlab-org/gitlab/-/issues/350905) +is the epic tracking the work to surface this information. In the interim, GitLab team members may reach out to customers that have +significantly exceeded their transfer limits to better understand their use case and offer ways to reduce data transfer +usage. + +## Determine image size + +Use these tools and techniques to determine your image's size: + +- [Skopeo](https://github.com/containers/skopeo): + use Skopeo's `inspect` command to examine layer count and sizes through API calls. You can + therefore inspect this data prior to running `docker pull IMAGE`. + +- Docker in CI: examine and record the image size when using GitLab CI prior to pushing an image + with Docker. For example: + + ```yaml + docker inspect "$CI_REGISTRY_IMAGE:$IMAGE_TAG" \ + | awk '/"Size": ([0-9]+)[,]?/{ printf "Final Image Size: %d\n", $2 }' + ``` + +- [Dive](https://github.com/wagoodman/dive) + is a tool for exploring a Docker image, layer contents, and discovering ways to reduce its size. + +## Reduce image size + +### Use a smaller base image + +Consider using a smaller base image, such as [Alpine Linux](https://alpinelinux.org/). +An Alpine image is around 5MB, which is several times smaller than popular base images such as +[Debian](https://hub.docker.com/_/debian). +If your application is distributed as a self-contained static binary, such as for Go applications, +you can also consider using Docker's [scratch](https://hub.docker.com/_/scratch/) +base image. + +If you need to use a specific base image OS, look for `-slim` or `-minimal` variants, as this helps +to reduce the image size. + +Also be mindful about the operating system packages you install on top of your base image. These can +add up to hundreds of megabytes. Try keeping the number of installed packages to the bare minimum. + +[Multi-stage builds](#use-multi-stage-builds) can be a powerful ally in cleaning up transient build +dependencies. + +You may also consider using tools such as these: + +- [DockerSlim](https://github.com/docker-slim/docker-slim) + provides a set of commands to reduce the size of your container images. +- [Distroless](https://github.com/GoogleContainerTools/distroless) images contain only your + application and its runtime dependencies. They don't contain package managers, shells, or any + other programs you would expect to find in a standard Linux distribution. + +### Minimize layers + +Every instruction in your Dockerfile leads to a new layer, which records the file system changes +applied during such an instruction. In general, more or larger layers lead to larger images. Try to +minimize the number of layers to install the packages in the Dockerfile. Otherwise, this may cause +each step in the build process to increase the image size. + +There are multiple strategies to reduce the number and size of layers. For example, instead of using +a `RUN` command per operating system package that you want to install (which would lead to a layer +per package), you can install all the packages on a single `RUN` command to reduce the number of +steps in the build process and reduce the size of the image. + +Another useful strategy is to ensure that you remove all transient build dependencies and disable or +empty the operating system package manager cache before and after installing a package. + +When building your images, make sure you only copy the relevant files. For Docker, using a +[`.dockerignore`](https://docs.docker.com/engine/reference/builder/#dockerignore-file) +helps ensure that the build process ignores irrelevant files. + +You can use other third-party tools to minify your images, such as [DockerSlim](https://github.com/docker-slim/docker-slim). +Be aware that if used improperly, such tools may remove dependencies that your application needs to +operate under certain conditions. Therefore, it's preferable to strive for smaller images during the +build process instead of trying to minify images afterward. + +### Use multi-stage builds + +With [multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/), +you use multiple `FROM` statements in your Dockerfile. Each `FROM` instruction can use a different +base, and each begins a new build stage. You can selectively copy artifacts from one stage to +another, leaving behind everything you don't want in the final image. This is especially useful when +you need to install build dependencies, but you don't need them to be present in your final image. + +## Use an image pull policy + +When using the `docker` or `docker+machine` executors, you can set a [`pull_policy`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) +parameter in your runner `config.toml` that defines how the runner works when pulling Docker images. +To avoid transferring data when using large and rarely updated images, consider using the +`if-not-present` pull policy when pulling images from remote registries. + +## Use Docker layer caching + +When running `docker build`, each command in `Dockerfile` results in a layer. These layers are kept +as a cache and can be reused if there haven't been any changes. You can specify a tagged image to be +used as a cache source for the `docker build` command by using the `--cache-from` argument. Multiple +images can be specified as a cache source by using multiple `--cache-from` arguments. This can speed +up your builds and reduce the amount of data transferred. For more information, see the +[documentation on Docker layer caching](../../../ci/docker/using_docker_build.md#make-docker-in-docker-builds-faster-with-docker-layer-caching). + +## Move to GitLab Premium or Ultimate + +GitLab data transfer limits are set at the tier level. If you need a higher limit, consider +upgrading to [GitLab Premium or Ultimate](https://about.gitlab.com/upgrade/). + +## Purchase additional data transfer + +Read more about managing your [data transfer limits](../../../subscriptions/gitlab_com/#purchase-more-storage-and-transfer). + +## Related issues + +- You may want to rebuild your image when the base Docker image is updated. However, the + [pipeline subscription limit is too low](https://gitlab.com/gitlab-org/gitlab/-/issues/225278) + to leverage this feature. As a workaround, you can rebuild daily or multiple times per day. + [GitLab-#225278](https://gitlab.com/gitlab-org/gitlab/-/issues/225278) + proposes raising the limit to help with this workflow. diff --git a/doc/user/packages/container_registry/reduce_container_registry_storage.md b/doc/user/packages/container_registry/reduce_container_registry_storage.md index e2242a85b75..a2a22f138e3 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_storage.md +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -16,8 +16,9 @@ to automatically manage your container registry usage. ## Check Container Registry Storage Use -The Usage Quotas page (**Settings > Usage Quotas > Storage**) displays storage usage for Packages, which includes Container Registry, -however, the storage is not being calculated. +The Usage Quotas page (**Settings > Usage Quotas > Storage**) displays storage usage for Packages, +which doesn't include the Container Registry. To track work on this, see the epic +[Storage management for the Container Registry](https://gitlab.com/groups/gitlab-org/-/epics/7226). ## Cleanup policy @@ -252,21 +253,108 @@ It is recommended you only enable container cleanup policies for projects that were created before GitLab 12.8 if you are confident the number of tags being cleaned up is minimal. -## Related topics +## More Container Registry storage reduction options -- [Delete images](index.md#delete-images) -- [Delete registry repository](../../../api/container_registry.md#delete-registry-repository) -- [Delete a registry repository tag](../../../api/container_registry.md#delete-a-registry-repository-tag) -- [Delete registry repository tags in bulk](../../../api/container_registry.md#delete-registry-repository-tags-in-bulk) -- [Delete a package](../package_registry/index.md#delete-a-package) +Here are some other options to reduce your project's use of Container Registry storage: -## Troubleshooting cleanup policies +- Use the [GitLab UI](index.md#delete-images) + to delete individual image tags or the entire repository containing all the tags. +- Use the API to [delete individual image tags](../../../api/container_registry.md#delete-a-registry-repository-tag). +- Use the API to [delete the entire container registry repository containing all the tags](../../../api/container_registry.md#delete-registry-repository). +- Use the API to [delete registry repository tags in bulk](../../../api/container_registry.md#delete-registry-repository-tags-in-bulk). -If you see the following message: +## Troubleshooting cleanup policies -"Something went wrong while updating the cleanup policy." +### `Something went wrong while updating the cleanup policy.` -Check the regex patterns to ensure they are valid. +If you see this error message, check the regex patterns to ensure they are valid. GitLab uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax) for regular expressions in the cleanup policy. You can test them with the [regex101 regex tester](https://regex101.com/). View some common [regex pattern examples](#regex-pattern-examples). + +### The cleanup policy doesn't delete any tags + +There can be different reasons behind this: + +- In GitLab 13.6 and earlier, when you run the cleanup policy you may expect it to delete tags and + it does not. This occurs when the cleanup policy is saved without editing the value in the + **Remove tags matching** field. This field has a grayed out `.*` value as a placeholder. Unless + `.*` (or another regex pattern) is entered explicitly into the field, a `nil` value is submitted. + This value prevents the saved cleanup policy from matching any tags. As a workaround, edit the + cleanup policy. In the **Remove tags matching** field, enter `.*` and save. This value indicates + that all tags should be removed. + +- If you are on GitLab self-managed instances and you have 1000+ tags in a container repository, you + might run into a [Container Registry token expiration issue](https://gitlab.com/gitlab-org/gitlab/-/issues/288814), + with `error authorizing context: invalid token` in the logs. + + To fix this, there are two workarounds: + + - If you are on GitLab 13.9 or later, you can [set limits for the cleanup policy](reduce_container_registry_storage.md#set-cleanup-limits-to-conserve-resources). + This limits the cleanup execution in time, and avoids the expired token error. + + - Extend the expiration delay of the Container Registry authentication tokens. This defaults to 5 + minutes. You can set a custom value by running + `ApplicationSetting.last.update(container_registry_token_expire_delay: <integer>)` in the Rails + console, where `<integer>` is the desired number of minutes. For reference, 15 minutes is the + value currently in use for GitLab.com. Be aware that by extending this value you increase the + time required to revoke permissions. + +If the previous fixes didn't work or you are on earlier versions of GitLab, you can generate a list +of the tags that you want to delete, and then use that list to delete the tags. To do this, follow +these steps: + +1. Run the following shell script. The command just before the `for` loop ensures that + `list_o_tags.out` is always reinitialized when starting the loop. After running this command, all + the tags' names will be in the `list_o_tags.out` file: + + ```shell + # Get a list of all tags in a certain container repository while considering [pagination](../../../api/index.md#pagination) + echo -n "" > list_o_tags.out; for i in {1..N}; do curl --header 'PRIVATE-TOKEN: <PAT>' "https://gitlab.example.com/api/v4/projects/<Project_id>/registry/repositories/<container_repo_id>/tags?per_page=100&page=${i}" | jq '.[].name' | sed 's:^.\(.*\).$:\1:' >> list_o_tags.out; done + ``` + + If you have Rails console access, you can enter the following commands to retrieve a list of tags limited by date: + + ```shell + output = File.open( "/tmp/list_o_tags.out","w" ) + Project.find(<Project_id>).container_repositories.find(<container_repo_id>).tags.each do |tag| + output << tag.name + "\n" if tag.created_at < 1.month.ago + end;nil + output.close + ``` + + This set of commands creates a `/tmp/list_o_tags.out` file listing all tags with a `created_at` date of older than one month. + +1. Remove from the `list_o_tags.out` file any tags that you want to keep. Here are some example + `sed` commands for this. Note that these commands are simply examples. You may change them to + best suit your needs: + + ```shell + # Remove the `latest` tag from the file + sed -i '/latest/d' list_o_tags.out + + # Remove the first N tags from the file + sed -i '1,Nd' list_o_tags.out + + # Remove the tags starting with `Av` from the file + sed -i '/^Av/d' list_o_tags.out + + # Remove the tags ending with `_v3` from the file + sed -i '/_v3$/d' list_o_tags.out + ``` + + If you are running macOS, you must add `.bak` to the commands. For example: + + ```shell + sed -i .bak '/latest/d' list_o_tags.out + ``` + +1. Double-check the `list_o_tags.out` file to make sure it contains only the tags that you want to + delete. + +1. Run this shell script to delete the tags in the `list_o_tags.out` file: + + ```shell + # loop over list_o_tags.out to delete a single tag at a time + while read -r LINE || [[ -n $LINE ]]; do echo ${LINE}; curl --request DELETE --header 'PRIVATE-TOKEN: <PAT>' "https://gitlab.example.com/api/v4/projects/<Project_id>/registry/repositories/<container_repo_id>/tags/${LINE}"; sleep 0.1; echo; done < list_o_tags.out > delete.logs + ``` diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index 52f5a1fcc0d..925a1b3e8e6 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -93,9 +93,8 @@ You can authenticate using: - A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `read_registry` and `write_registry`. - A [group deploy token](../../../user/project/deploy_tokens/index.md#group-deploy-token) with the scope set to `read_registry` and `write_registry`. -Users accessing the Dependency Proxy with a personal access token or username and password require -at least [Guest membership](../../permissions.md#group-members-permissions) -to the group they pull images from. +Users accessing the Dependency Proxy with a personal access token or username and password must +have at least the Guest role for the group they pull images from. #### SAML SSO @@ -210,65 +209,8 @@ from the GitLab server. ## Reduce storage usage -Blobs are kept forever on the GitLab server, and there is no hard limit on how much data can be -stored. - -### Using the API to clear the cache - -To reclaim disk space used by image blobs that are no longer needed, use -the [Dependency Proxy API](../../../api/dependency_proxy.md) to clear the entire -cache. - -If you clear the cache, the next time a pipeline runs it must pull an image or tag from Docker Hub. - -### Cleanup policies - -#### Enable cleanup policies from within GitLab - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340777) in GitLab 14.6 - -You can enable an automatic time-to-live (TTL) policy for the Dependency Proxy from the user -interface. To do this, navigate to your group's **Settings > Packages & Registries > Dependency Proxy** -and enable the setting to automatically clear items from the cache after 90 days. - -#### Enable cleanup policies with GraphQL - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294187) in GitLab 14.4. - -The cleanup policy is a scheduled job you can use to clear cached images that are no longer used, -freeing up additional storage space. The policies use time-to-live (TTL) logic: - -- The number of days is configured. -- All cached dependency proxy files that have not been pulled in that many days are deleted. - -Use the [GraphQL API](../../../api/graphql/reference/index.md#mutationupdatedependencyproxyimagettlgrouppolicy) -to enable and configure cleanup policies: - -```graphql -mutation { - updateDependencyProxyImageTtlGroupPolicy(input: - { - groupPath: "<your-full-group-path>", - enabled: true, - ttl: 90 - } - ) { - dependencyProxyImageTtlPolicy { - enabled - ttl - } - errors - } -} -``` - -See the [Getting started with GraphQL](../../../api/graphql/getting_started.md) -guide to learn how to make GraphQL queries. - -When the policy is initially enabled, the default TTL setting is 90 days. Once enabled, stale -dependency proxy files are queued for deletion each day. Deletion may not occur right away due to -processing time. If the image is pulled after the cached files are marked as expired, the expired -files are ignored and new files are downloaded and cached from the external registry. +For information on reducing your storage use on the Dependency Proxy, see +[Reduce Dependency Proxy storage use](reduce_dependency_proxy_storage.md). ## Docker Hub rate limits and the Dependency Proxy diff --git a/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md b/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md new file mode 100644 index 00000000000..cd04d2e696b --- /dev/null +++ b/doc/user/packages/dependency_proxy/reduce_dependency_proxy_storage.md @@ -0,0 +1,74 @@ +--- +stage: Package +group: Package +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Reduce Dependency Proxy Storage **(FREE)** + +There's no automatic removal process for blobs. Unless you delete them manually, they're stored +indefinitely. Since this impacts your +[storage usage quota](../../usage_quotas.md), +it's important that you clear unused items from the cache. This page covers several options for +doing so. + +## Check Dependency Proxy Storage Use + +The Usage Quotas page (**Settings > Usage Quotas > Storage**) displays storage usage for Packages, which includes the Dependency Proxy, +however, the storage is not yet displayed. + +## Use the API to clear the cache + +To reclaim disk space used by image blobs that are no longer needed, use the +[Dependency Proxy API](../../../api/dependency_proxy.md) +to clear the entire cache. If you clear the cache, the next time a pipeline runs it must pull an +image or tag from Docker Hub. + +## Cleanup policies + +### Enable cleanup policies from within GitLab + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340777) in GitLab 14.6 + +You can enable an automatic time-to-live (TTL) policy for the Dependency Proxy from the user +interface. To do this, navigate to your group's **Settings > Packages & Registries > Dependency Proxy** +and enable the setting to automatically clear items from the cache after 90 days. + +### Enable cleanup policies with GraphQL + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294187) in GitLab 14.4. + +The cleanup policy is a scheduled job you can use to clear cached images that are no longer used, +freeing up additional storage space. The policies use time-to-live (TTL) logic: + +- The number of days is configured. +- All cached dependency proxy files that have not been pulled in that many days are deleted. + +Use the [GraphQL API](../../../api/graphql/reference/index.md#mutationupdatedependencyproxyimagettlgrouppolicy) +to enable and configure cleanup policies: + +```graphql +mutation { + updateDependencyProxyImageTtlGroupPolicy(input: + { + groupPath: "<your-full-group-path>", + enabled: true, + ttl: 90 + } + ) { + dependencyProxyImageTtlPolicy { + enabled + ttl + } + errors + } +} +``` + +See the [Getting started with GraphQL](../../../api/graphql/getting_started.md) +guide to learn how to make GraphQL queries. + +When the policy is initially enabled, the default TTL setting is 90 days. Once enabled, stale +dependency proxy files are queued for deletion each day. Deletion may not occur right away due to +processing time. If the image is pulled after the cached files are marked as expired, the expired +files are ignored and new files are downloaded and cached from the external registry. diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 7b44b5bcbb7..ada6f033288 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -57,7 +57,7 @@ Example request using a personal access token: ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" \ --upload-file path/to/file.txt \ - "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt?status=hidden" + "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt" ``` Example response without attribute `select`: diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 21fecc16602..6e3af6a92d5 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -263,7 +263,7 @@ The `name` must be `Job-Token`. <httpHeaders> <property> <name>Job-Token</name> - <value>${env.CI_JOB_TOKEN}</value> + <value>${CI_JOB_TOKEN}</value> </property> </httpHeaders> </configuration> @@ -725,7 +725,7 @@ You can create a new package each time the `main` branch is updated. <httpHeaders> <property> <name>Job-Token</name> - <value>${env.CI_JOB_TOKEN}</value> + <value>${CI_JOB_TOKEN}</value> </property> </httpHeaders> </configuration> @@ -742,17 +742,17 @@ You can create a new package each time the `main` branch is updated. <repositories> <repository> <id>gitlab-maven</id> - <url>${env.CI_API_V4_URL}/projects/${env.CI_PROJECT_ID}/packages/maven</url> + <url>${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven</url> </repository> </repositories> <distributionManagement> <repository> <id>gitlab-maven</id> - <url>${CI_API_V4_URL}/projects/${env.CI_PROJECT_ID}/packages/maven</url> + <url>${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven</url> </repository> <snapshotRepository> <id>gitlab-maven</id> - <url>${CI_API_V4_URL}/projects/${env.CI_PROJECT_ID}/packages/maven</url> + <url>${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven</url> </snapshotRepository> </distributionManagement> ``` diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 5338e546625..1f37e5639c6 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -255,7 +255,8 @@ This regex allows almost all of the characters that npm allows, with a few excep The regex also allows for capital letters, while npm does not. -WARNING: +## Limitations + 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 diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index 3311b271126..a2228148447 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -12,6 +12,15 @@ With the GitLab Package Registry, you can use GitLab as a private or public regi of [supported package managers](#supported-package-managers). You can publish and share packages, which can be consumed as a dependency in downstream projects. +## Package workflows + +Learn how to use the GitLab Package Registry to build your own custom package workflow: + +- [Use a project as a package registry](../workflows/project_registry.md) + to publish all of your packages to one project. + +- Publish multiple different packages from one [monorepo project](../workflows/working_with_monorepos.md). + ## View packages You can view packages for your project or group. @@ -77,46 +86,10 @@ when you view the package details: You can view which pipeline published the package, and the commit and user who triggered it. However, the history is limited to five updates of a given package. -## Download a package +## Reduce storage usage -To download a package: - -1. Go to **Packages & Registries > Package Registry**. -1. Select the name of the package you want to download. -1. In the **Activity** section, select the name of the package you want to download. - -## Delete a package - -You cannot edit a package after you publish it in the Package Registry. Instead, you -must delete and recreate it. - -To delete a package, you must have suitable [permissions](../../permissions.md). - -You can delete packages by using [the API](../../../api/packages.md#delete-a-project-package) or the UI. - -To delete a package in the UI, from your group or project: - -1. Go to **Packages & Registries > Package Registry**. -1. Find the name of the package you want to delete. -1. Click **Delete**. - -The package is permanently deleted. - -## Delete files associated with a package - -To delete package files, you must have suitable [permissions](../../permissions.md). - -You can delete packages by using [the API](../../../api/packages.md#delete-a-package-file) or the UI. - -To delete package files in the UI, from your group or project: - -1. Go to **Packages & Registries > Package Registry**. -1. Find the name of the package you want to delete. -1. Select the package to view additional details. -1. Find the name of the file you would like to delete. -1. Expand the ellipsis and select **Delete file**. - -The package files are permanently deleted. +For information on reducing your storage use for the Package Registry, see +[Reduce Package Registry storage use](reduce_package_registry_storage.md). ## Disable the Package Registry @@ -135,15 +108,6 @@ You can also remove the Package Registry for your project specifically: The **Packages & Registries > Package Registry** entry is removed from the sidebar. -## Package workflows - -Learn how to use the GitLab Package Registry to build your own custom package workflow: - -- [Use a project as a package registry](../workflows/project_registry.md) - to publish all of your packages to one project. - -- Publish multiple different packages from one [monorepo project](../workflows/working_with_monorepos.md). - ## Supported package managers WARNING: @@ -166,7 +130,7 @@ The Package Registry supports the following formats: | [Go](../go_proxy/index.md) | 13.1+ | [Alpha](https://gitlab.com/groups/gitlab-org/-/epics/3043) | | [Ruby gems](../rubygems_registry/index.md) | 13.10+ | [Alpha](https://gitlab.com/groups/gitlab-org/-/epics/3200) | -[Status](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga): +[Status](../../../policy/alpha-beta-support.md): - Alpha: behind a feature flag and not officially supported. - Beta: several known issues that may prevent expected use. diff --git a/doc/user/packages/package_registry/reduce_package_registry_storage.md b/doc/user/packages/package_registry/reduce_package_registry_storage.md new file mode 100644 index 00000000000..c2e4cd8d889 --- /dev/null +++ b/doc/user/packages/package_registry/reduce_package_registry_storage.md @@ -0,0 +1,52 @@ +--- +stage: Package +group: Package +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Reduce Package Registry Storage **(FREE)** + +Without cleanup, package registries become large over time. When a large number of packages and +their files are added: + +- Fetching the list of packages becomes slower. +- They take up a large amount of storage space on the server, impacting your [storage usage quota](../../usage_quotas.md). + +We recommend deleting unnecessary packages and files. This page offers examples of how to do so. + +## Check Package Registry Storage Use + +The Usage Quotas page (**Settings > Usage Quotas > Storage**) displays storage usage for Packages. + +## Delete a package + +You cannot edit a package after you publish it in the Package Registry. Instead, you +must delete and recreate it. + +To delete a package, you must have suitable [permissions](../../permissions.md). + +You can delete packages by using [the API](../../../api/packages.md#delete-a-project-package) or the UI. + +To delete a package in the UI, from your group or project: + +1. Go to **Packages & Registries > Package Registry**. +1. Find the name of the package you want to delete. +1. Click **Delete**. + +The package is permanently deleted. + +## Delete files associated with a package + +To delete package files, you must have suitable [permissions](../../permissions.md). + +You can delete packages by using [the API](../../../api/packages.md#delete-a-package-file) or the UI. + +To delete package files in the UI, from your group or project: + +1. Go to **Packages & Registries > Package Registry**. +1. Find the name of the package you want to delete. +1. Select the package to view additional details. +1. Find the name of the file you would like to delete. +1. Expand the ellipsis and select **Delete file**. + +The package files are permanently deleted. diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 4151346ec98..bf007572ac7 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -407,6 +407,16 @@ 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`. +## Troubleshooting + +To improve performance, PyPI caches files related to a package. Note that PyPI doesn't remove data by +itself. The cache grows as new packages are installed. If you encounter issues, clear the cache with +this command: + +```shell +pip cache purge +``` + ## Supported CLI commands The GitLab PyPI repository supports the following CLI commands: diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index bb9f32d1144..6fc47a23373 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -41,7 +41,7 @@ PUT /projects/:id/packages/terraform/modules/:module-name/:module-system/:module Provide the file content in the request body. -Note that, in the following example, the request must end with `/file`. +As the following example shows, requests must end with `/file`. If you send a request ending with something else, it results in a 404 error `{"error":"404 Not Found"}`. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 36c49e39151..4476b0dd75b 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -46,199 +46,266 @@ The following table lists project permissions available for each role: <!-- Keep this table sorted: By topic first, then by minimum role, then alphabetically. --> -| Action | Guest | Reporter | Developer | Maintainer | Owner | -|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|----------|-----------|------------|-------| -| [Analytics](analytics/index.md):<br>View issue analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [merge request analytics](analytics/merge_request_analytics.md) **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View value stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [DORA metrics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [CI/CD analytics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [code review analytics](analytics/code_review_analytics.md) **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [repository analytics](analytics/repository_analytics.md) | | ✓ | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>View licenses in [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>Create and run [on-demand DAST scans](application_security/dast/index.md#on-demand-scans) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>Manage [security policy](application_security/policies/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>View [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>View [threats list](application_security/threat_monitoring/index.md#threat-monitoring) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>Create a [CVE ID Request](application_security/cve_id_request.md) **(FREE SAAS)** | | | | ✓ | ✓ | -| [Application security](application_security/index.md):<br>Create or assign [security policy project](application_security/policies/index.md) **(ULTIMATE)** | | | | | ✓ | -| [CI/CD](../ci/index.md):<br>Download and browse job artifacts | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>View a job log | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>View list of jobs | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>View [environments](../ci/environments/index.md) | | ✓ | ✓ | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Cancel and retry jobs | | | ✓ | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Create new [environments](../ci/environments/index.md) | | | ✓ | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Run CI/CD pipeline against a protected branch | | | ✓ (*5*) | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Stop [environments](../ci/environments/index.md) | | | ✓ | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>View a job with [debug logging](../ci/variables/index.md#debug-logging) | | | ✓ | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Manage CI/CD variables | | | | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Manage job triggers | | | | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Manage group runners | | | | | ✓ | -| [CI/CD](../ci/index.md):<br>Manage project runners | | | | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Run Web IDE's Interactive Web Terminals **(ULTIMATE ONLY)** | | | | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Use [environment terminals](../ci/environments/index.md#web-terminals-deprecated) | | | | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Delete pipelines | | | | | ✓ | -| [Clusters](infrastructure/clusters/index.md):<br>View [pod logs](project/clusters/kubernetes_pod_logs.md) | | | ✓ | ✓ | ✓ | -| [Clusters](infrastructure/clusters/index.md):<br>Manage clusters | | | | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete cleanup policies | | | ✓ | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Remove a container registry image | | | ✓ | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Update container registry | | | ✓ | ✓ | ✓ | -| [GitLab Pages](project/pages/index.md):<br>View Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [GitLab Pages](project/pages/index.md):<br>Manage | | | | ✓ | ✓ | -| [GitLab Pages](project/pages/index.md):<br>Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | -| [GitLab Pages](project/pages/index.md):<br>Remove GitLab Pages | | | | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>View [alerts](../operations/incident_management/alerts.md) | | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Assign an alert | ✓| ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>View [incident](../operations/incident_management/incidents.md) | ✓| ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Create [incident](../operations/incident_management/incidents.md) | (*17*) | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>View [on-call schedules](../operations/incident_management/oncall_schedules.md) | | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Participate in on-call rotation | ✓| ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>View [escalation policies](../operations/incident_management/escalation_policies.md) | | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Manage [on-call schedules](../operations/incident_management/oncall_schedules.md) | | | | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Manage [escalation policies](../operations/incident_management/escalation_policies.md) | | | | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Add Labels | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Assign | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Create | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Create [confidential issues](project/issues/confidential_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>View [Design Management](project/issues/design_management.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>View related issues | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Set weight | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>View [confidential issues](project/issues/confidential_issues.md) | (*2*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Close / reopen | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Lock threads | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Manage related issues | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Manage tracker | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Move issues (*15*) | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Set issue [time tracking](project/time_tracking.md) estimate and time spent | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Delete | | | | | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View allowed and denied licenses **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View License Compliance reports **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View License list **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>Manage license policy **(ULTIMATE)** | | | | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Assign reviewer | | ✓ | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>See list | | ✓ | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Apply code change suggestions | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Approve (*9*) | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Assign | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Create (*18*) | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Add labels | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Lock threads | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Manage or accept | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Manage merge approval rules (project settings) | | | | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Delete | | | | | ✓ | -| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Manage user-starred metrics dashboards (*7*) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | -| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | -| [Package registry](packages/index.md):<br>Pull package | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Package registry](packages/index.md):<br>Publish package | | | ✓ | ✓ | ✓ | -| [Package registry](packages/index.md):<br>Delete package | | | | ✓ | ✓ | -| [Project operations](../operations/index.md):<br>View [Error Tracking](../operations/error_tracking.md) list | | ✓ | ✓ | ✓ | ✓ | -| [Project operations](../operations/index.md):<br>Manage [Feature Flags](../operations/feature_flags.md) **(PREMIUM)** | | | ✓ | ✓ | ✓ | -| [Project operations](../operations/index.md):<br>Manage [Error Tracking](../operations/error_tracking.md) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Download project | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Reposition comments on images (posted by any user) | ✓ (*10*) | ✓ (*10*) | ✓ (*10*) | ✓ | ✓ | -| [Projects](project/index.md):<br>View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [releases](project/releases/index.md) | ✓ (*6*) | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View Requirements **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [time tracking](project/time_tracking.md) reports | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [wiki](project/wiki/index.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Create [snippets](snippets.md) | | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Manage labels | | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [project traffic statistics](../api/project_statistics.md) | | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Create, edit, delete [milestones](project/milestones/index.md). | | | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Create, edit, delete [releases](project/releases/index.md) | | | ✓ (*13*) | ✓ (*13*) | ✓ (*13*) | -| [Projects](project/index.md):<br>Create, edit [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Enable Review Apps | | | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View project [Audit Events](../administration/audit_events.md) | | | ✓ (*11*) | ✓ | ✓ | -| [Projects](project/index.md):<br>Add deploy keys | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Add new team members | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Change [project features visibility](../public_access/public_access.md) level | | | | ✓ (14) | ✓ | -| [Projects](project/index.md):<br>Configure [webhooks](project/integrations/webhooks.md) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Delete [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Edit comments (posted by any user) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Edit project badges | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Edit project settings | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Export project | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Manage [project access tokens](project/settings/project_access_tokens.md) **(FREE SELF)** **(PREMIUM SAAS)** (*12*) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Manage [Project Operations](../operations/index.md) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Share (invite) projects with groups | | | | ✓ (*8*) | ✓ (*8*) | -| [Projects](project/index.md):<br>View 2FA status of members | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Administer project compliance frameworks | | | | | ✓ | -| [Projects](project/index.md):<br>Archive project | | | | | ✓ | -| [Projects](project/index.md):<br>Change project visibility level | | | | | ✓ | -| [Projects](project/index.md):<br>Delete project | | | | | ✓ | -| [Projects](project/index.md):<br>Disable notification emails | | | | | ✓ | -| [Projects](project/index.md):<br>Rename project | | | | | ✓ | -| [Projects](project/index.md):<br>Transfer project to another namespace | | | | | ✓ | -| [Repository](project/repository/index.md):<br>Pull project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>View project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>View a commit status | | ✓ | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Add tags | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Create new branches | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Create or update commit status | | | ✓ (*5*) | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Force push to non-protected branches | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Push to non-protected branches | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Remove non-protected branches | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Rewrite or remove Git tags | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Enable or disable branch protection | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Enable or disable tag protection | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Manage [push rules](../push_rules/push_rules.md) | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Push to protected branches (*5*) | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Turn on or off protected branch push for developers | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Remove fork relationship | | | | | ✓ | -| [Repository](project/repository/index.md):<br>Force push to protected branches (*4*) | | | | | | -| [Repository](project/repository/index.md):<br>Remove protected branches (*4*) | | | | | | -| [Requirements Management](project/requirements/index.md):<br>Archive / reopen **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| [Requirements Management](project/requirements/index.md):<br>Create / edit **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| [Requirements Management](project/requirements/index.md):<br>Import / export **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>View Security reports **(ULTIMATE)** | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Create issue from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Create vulnerability from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Dismiss vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Dismiss vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Resolve vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Revert vulnerability to detected state **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability findings in [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Terraform](infrastructure/index.md):<br>Read Terraform state | | | ✓ | ✓ | ✓ | -| [Terraform](infrastructure/index.md):<br>Manage Terraform state | | | | ✓ | ✓ | -| [Test cases](../ci/test_cases/index.md):<br>Archive | | ✓ | ✓ | ✓ | ✓ | -| [Test cases](../ci/test_cases/index.md):<br>Create | | ✓ | ✓ | ✓ | ✓ | -| [Test cases](../ci/test_cases/index.md):<br>Move | | ✓ | ✓ | ✓ | ✓ | -| [Test cases](../ci/test_cases/index.md):<br>Reopen | | ✓ | ✓ | ✓ | ✓ | +| Action | Guest | Reporter | Developer | Maintainer | Owner | +|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|----------|-----------|------------|-------| +| [Analytics](analytics/index.md):<br>View issue analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [merge request analytics](analytics/merge_request_analytics.md) **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View value stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [DORA metrics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [CI/CD analytics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [code review analytics](analytics/code_review_analytics.md) **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [repository analytics](analytics/repository_analytics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>View licenses in [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Create and run [on-demand DAST scans](application_security/dast/index.md#on-demand-scans) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Manage [security policy](application_security/policies/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>View [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>View [threats list](application_security/threat_monitoring/index.md#threat-monitoring) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Create a [CVE ID Request](application_security/cve_id_request.md) **(FREE SAAS)** | | | | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Create or assign [security policy project](application_security/policies/index.md) **(ULTIMATE)** | | | | | ✓ | +| [Clusters](infrastructure/clusters/index.md):<br>View [pod logs](project/clusters/kubernetes_pod_logs.md) | | | ✓ | ✓ | ✓ | +| [Clusters](infrastructure/clusters/index.md):<br>View clusters | | | ✓ | ✓ | ✓ | +| [Clusters](infrastructure/clusters/index.md):<br>Manage clusters | | | | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete cleanup policies | | | ✓ | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Push an image to the Container Registry | | | ✓ | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Pull an image from the Container Registry | ✓ (*20*) | ✓ (*20*) | ✓ | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Remove a Container Registry image | | | ✓ | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>View Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>Manage | | | | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>Remove GitLab Pages | | | | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [alerts](../operations/incident_management/alerts.md) | | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Assign an alert | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [incident](../operations/incident_management/incidents.md) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Create [incident](../operations/incident_management/incidents.md) | (*16*) | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [on-call schedules](../operations/incident_management/oncall_schedules.md) | | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Participate in on-call rotation | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [escalation policies](../operations/incident_management/escalation_policies.md) | | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Manage [on-call schedules](../operations/incident_management/oncall_schedules.md) | | | | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Manage [escalation policies](../operations/incident_management/escalation_policies.md) | | | | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Add Labels | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Assign | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Create (*18*) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Create [confidential issues](project/issues/confidential_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>View [Design Management](project/issues/design_management.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>View related issues | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Set weight | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>View [confidential issues](project/issues/confidential_issues.md) | (*2*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Close / reopen (*19*) | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Lock threads | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Manage related issues | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Manage tracker | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Move issues (*14*) | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Set issue [time tracking](project/time_tracking.md) estimate and time spent | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Delete | | | | | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View allowed and denied licenses **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View License Compliance reports **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View License list **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>Manage license policy **(ULTIMATE)** | | | | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Assign reviewer | | ✓ | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>See list | | ✓ | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Apply code change suggestions | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Approve (*8*) | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Assign | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Create (*17*) | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Add labels | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Lock threads | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Manage or accept | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Manage merge approval rules (project settings) | | | | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Delete | | | | | ✓ | +| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Manage user-starred metrics dashboards (*6*) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | +| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Pull a package | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Publish a package | | | ✓ | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Delete a package | | | | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Delete a file associated with a package | | | | ✓ | ✓ | +| [Project operations](../operations/index.md):<br>View [Error Tracking](../operations/error_tracking.md) list | | ✓ | ✓ | ✓ | ✓ | +| [Project operations](../operations/index.md):<br>Manage [Feature Flags](../operations/feature_flags.md) **(PREMIUM)** | | | ✓ | ✓ | ✓ | +| [Project operations](../operations/index.md):<br>Manage [Error Tracking](../operations/error_tracking.md) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Download project | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Reposition comments on images (posted by any user) | ✓ (*9*) | ✓ (*9*) | ✓ (*9*) | ✓ | ✓ | +| [Projects](project/index.md):<br>View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [releases](project/releases/index.md) | ✓ (*5*) | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View Requirements **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [time tracking](project/time_tracking.md) reports | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [wiki](project/wiki/index.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Create [snippets](snippets.md) | | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Manage labels | | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [project traffic statistics](../api/project_statistics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Create, edit, delete [milestones](project/milestones/index.md). | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Create, edit, delete [releases](project/releases/index.md) | | | ✓ (*12*) | ✓ (*12*) | ✓ (*12*) | +| [Projects](project/index.md):<br>Create, edit [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Enable Review Apps | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View project [Audit Events](../administration/audit_events.md) | | | ✓ (*10*) | ✓ | ✓ | +| [Projects](project/index.md):<br>Add deploy keys | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Add new team members | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Change [project features visibility](../public_access/public_access.md) level | | | | ✓ (*13*) | ✓ | +| [Projects](project/index.md):<br>Configure [webhooks](project/integrations/webhooks.md) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Delete [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Edit comments (posted by any user) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Edit project badges | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Edit project settings | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Export project | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Manage [project access tokens](project/settings/project_access_tokens.md) **(FREE SELF)** **(PREMIUM SAAS)** (*11*) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Manage [Project Operations](../operations/index.md) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Rename project | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Share (invite) projects with groups | | | | ✓ (*7*) | ✓ (*7*) | +| [Projects](project/index.md):<br>View 2FA status of members | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Administer project compliance frameworks | | | | | ✓ | +| [Projects](project/index.md):<br>Archive project | | | | | ✓ | +| [Projects](project/index.md):<br>Change project visibility level | | | | | ✓ | +| [Projects](project/index.md):<br>Delete project | | | | | ✓ | +| [Projects](project/index.md):<br>Disable notification emails | | | | | ✓ | +| [Projects](project/index.md):<br>Transfer project to another namespace | | | | | ✓ | +| [Repository](project/repository/index.md):<br>Pull project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>View project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>View a commit status | | ✓ | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Add tags | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Create new branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Create or update commit status | | | ✓ (*4*) | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Force push to non-protected branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Push to non-protected branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Remove non-protected branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Rewrite or remove Git tags | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Enable or disable branch protection | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Enable or disable tag protection | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Manage [push rules](project/repository/push_rules.md) | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Push to protected branches (*4*) | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Turn on or off protected branch push for developers | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Remove fork relationship | | | | | ✓ | +| [Repository](project/repository/index.md):<br>Force push to protected branches (*3*) | | | | | | +| [Repository](project/repository/index.md):<br>Remove protected branches (*3*) | | | | | | +| [Requirements Management](project/requirements/index.md):<br>Archive / reopen **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| [Requirements Management](project/requirements/index.md):<br>Create / edit **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| [Requirements Management](project/requirements/index.md):<br>Import / export **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Create issue from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Create vulnerability from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Dismiss vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Dismiss vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Resolve vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Revert vulnerability to detected state **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability findings in [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Terraform](infrastructure/index.md):<br>Read Terraform state | | | ✓ | ✓ | ✓ | +| [Terraform](infrastructure/index.md):<br>Manage Terraform state | | | | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Archive | | ✓ | ✓ | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Create | | ✓ | ✓ | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Move | | ✓ | ✓ | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Reopen | | ✓ | ✓ | ✓ | ✓ | + +<!-- markdownlint-disable MD029 --> 1. On self-managed GitLab instances, guest users are able to perform this action only on public and internal projects (not on private projects). [External users](#external-users) must be given explicit access even if the project is internal. For GitLab.com, see the [GitLab.com visibility settings](gitlab_com/index.md#visibility-settings). -1. Guest users can only view the [confidential issues](project/issues/confidential_issues.md) 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), 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 commits and release evidence](project/releases/index.md#view-a-release-and-download-assets). -1. Actions are limited only to records owned (referenced) by user. -1. When [Share Group Lock](group/index.md#prevent-a-project-from-being-shared-with-groups) 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 +2. Guest users can only view the [confidential issues](project/issues/confidential_issues.md) they created themselves. +3. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [protected branches](project/protected_branches.md). +4. If the [branch is protected](project/protected_branches.md), this depends on the access Developers and Maintainers are given. +5. Guest users can access GitLab [**Releases**](project/releases/index.md) for downloading assets but are not allowed to download the source code nor see [repository information like commits and release evidence](project/releases/index.md#view-a-release-and-download-assets). +6. Actions are limited only to records owned (referenced) by user. +7. When [Share Group Lock](group/index.md#prevent-a-project-from-being-shared-with-groups) is enabled the project can't be shared with other groups. It does not affect group with group sharing. +8. For information on eligible approvers for merge requests, see [Eligible approvers](project/merge_requests/approvals/rules.md#eligible-approvers). -1. Applies only to comments on [Design Management](project/issues/design_management.md) designs. -1. Users can only view events based on their individual actions. -1. Project access tokens are supported for self-managed instances on Free and above. They are also - supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). -1. If the [tag is protected](#release-permissions-with-protected-tags), this depends on the access Developers and Maintainers are given. -1. A Maintainer can't change project features visibility level if - [project visibility](../public_access/public_access.md) is set to private. -1. Attached design files are moved together with the issue even if the user doesn't have the - Developer role. -1. Guest users can only set metadata (for example, labels, assignees, or milestones) - when creating an issue. They cannot change the metadata on existing issues. -1. In GitLab 14.5 or later, Guests are not allowed to [create incidents](../operations/incident_management/incidents.md#incident-creation). -1. In projects that accept contributions from external members, users can create, edit, and close their own merge requests. +9. Applies only to comments on [Design Management](project/issues/design_management.md) designs. +10. Users can only view events based on their individual actions. +11. Project access tokens are supported for self-managed instances on Free and above. They are also + supported on GitLab SaaS Premium and above (excluding [trial licenses](https://about.gitlab.com/free-trial/)). +12. If the [tag is protected](#release-permissions-with-protected-tags), this depends on the access Developers and Maintainers are given. +13. A Maintainer can't change project features visibility level if + [project visibility](../public_access/public_access.md) is set to private. +14. Attached design files are moved together with the issue even if the user doesn't have the + Developer role. +15. Guest users can only set metadata (for example, labels, assignees, or milestones) + when creating an issue. They cannot change the metadata on existing issues. +16. In GitLab 14.5 or later, Guests are not allowed to [create incidents](../operations/incident_management/incidents.md#incident-creation). + A guest who created an incident when they had the Reporter role or who is assigned to the incident can modify the title, description and metrics. They can also close and reopen the incident. +17. In projects that accept contributions from external members, users can create, edit, and close their own merge requests. +18. Authors and assignees of issues can modify the title and description even if they don't have the Reporter role. +19. Authors and assignees can close and reopen issues even if they don't have the Reporter role. +20. The ability to view the Container Registry and pull images is controlled by the [Container Registry's visibility permissions](packages/container_registry/index.md#container-registry-visibility-permissions). + +<!-- markdownlint-enable MD029 --> ## Project features permissions +More details about the permissions for some project-level features follow. + +### GitLab CI/CD permissions + +[GitLab CI/CD](../ci/index.md) permissions for some roles can be modified by these settings: + +- [Public pipelines](../ci/pipelines/settings.md#change-which-users-can-view-your-pipelines): + When set to public, gives access to certain CI/CD features to *Guest* project members. +- [Pipeline visibility](../ci/enable_or_disable_ci.md#enable-cicd-in-a-project): When set to **Everyone with Access**, + gives access to certain CI/CD "view" features to *non-project* members. + +| Action | Non-member | Guest | Reporter | Developer | Maintainer | Owner | +|-----------------------------------------------------------------------------------|------------|---------|----------|-----------|------------|-------| +| See that artifacts exist | ✓ (*3*) | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| View a list of jobs | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | +| View and download artifacts | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | +| View [environments](../ci/environments/index.md) | ✓ (*3*) | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| View job logs and job details page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | +| View pipeline details page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | +| View pipelines page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | +| View pipelines tab in MR | ✓ (*3*) | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| [View vulnerabilities in a pipeline](application_security/security_dashboard/index.md#view-vulnerabilities-in-a-pipeline) | | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | +| Cancel and retry jobs | | | | ✓ | ✓ | ✓ | +| Create new [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | +| Delete job logs or job artifacts | | | | ✓ (*4*) | ✓ | ✓ | +| Run CI/CD pipeline for a protected branch | | | | ✓ (*5*) | ✓ (*5*) | ✓ | +| Stop [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | +| View a job with [debug logging](../ci/variables/index.md#debug-logging) | | | | ✓ | ✓ | ✓ | +| Use pipeline editor | | | | ✓ | ✓ | ✓ | +| Add specific runners to project | | | | | ✓ | ✓ | +| Clear runner caches manually | | | | | ✓ | ✓ | +| Enable shared runners in project | | | | | ✓ | ✓ | +| Manage CI/CD settings | | | | | ✓ | ✓ | +| Manage job triggers | | | | | ✓ | ✓ | +| Manage project-level CI/CD variables | | | | | ✓ | ✓ | +| Run [interactive web terminals](../ci/interactive_web_terminal/index.md) | | | | | ✓ | ✓ | +| Use [environment terminals](../ci/environments/index.md#web-terminals-deprecated) | | | | | ✓ | ✓ | +| Delete pipelines | | | | | | ✓ | + +<!-- markdownlint-disable MD029 --> + +1. If the project is public and **Public pipelines** is enabled in **Project Settings > CI/CD**. +2. If **Public pipelines** is enabled in **Project Settings > CI/CD**. +3. If the project is public. +4. Only if the job was both: + - Triggered by the user. + - [In GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/35069) and later, + run for a non-protected branch. +5. If the user is [allowed to merge or push to the protected branch](../ci/pipelines/index.md#pipeline-security-on-protected-branches). + +<!-- markdownlint-enable MD029 --> + +#### Job permissions + +This table shows granted privileges for jobs triggered by specific types of users: + +| Action | Guest, Reporter | Developer | Maintainer| Administrator | +|---------------------------------------------|-----------------|-----------|-----------|---------------| +| Run CI job | | ✓ | ✓ | ✓ | +| Clone source and LFS from current project | | ✓ | ✓ | ✓ | +| Clone source and LFS from public projects | | ✓ | ✓ | ✓ | +| Clone source and LFS from internal projects | | ✓ (*1*) | ✓ (*1*) | ✓ | +| Clone source and LFS from private projects | | ✓ (*2*) | ✓ (*2*) | ✓ (*2*) | +| Pull container images from current project | | ✓ | ✓ | ✓ | +| Pull container images from public projects | | ✓ | ✓ | ✓ | +| Pull container images from internal projects| | ✓ (*1*) | ✓ (*1*) | ✓ | +| Pull container images from private projects | | ✓ (*2*) | ✓ (*2*) | ✓ (*2*) | +| Push container images to current project | | ✓ | ✓ | ✓ | +| Push container images to other projects | | | | | +| Push source and LFS | | | | | + +1. Only if the triggering user is not an external one. +1. Only if the triggering user is a member of the project. + ### Wiki and issues Project features like [wikis](project/wiki/index.md) and issues can be hidden from users depending on @@ -257,9 +324,9 @@ Maintainers and Developers from pushing to a protected branch. Read through the [protected branches](project/protected_branches.md) to learn more. -### Value Stream Analytics permissions +### Value stream analytics permissions -Find the current permissions on the Value Stream Analytics dashboard, as described in +Find the current permissions on the value stream analytics dashboard, as described in [related documentation](analytics/value_stream_analytics.md#permissions). ### Issue board permissions @@ -281,7 +348,8 @@ read through the documentation on [permissions and access to confidential issues ### Container Registry visibility permissions -Find the visibility permissions for the Container Registry, as described in the +The ability to view the Container Registry and pull images is controlled by the Container Registry's +visibility permissions. Find these permissions for the Container Registry as described in the [related documentation](packages/container_registry/index.md#container-registry-visibility-permissions). ## Group members permissions @@ -293,67 +361,74 @@ The following table lists group permissions available for each role: <!-- Keep this table sorted: first, by minimum role, then alphabetically. --> -| Action | Guest | Reporter | Developer | Maintainer | Owner | -|--------------------------------------------------------|-------|----------|-----------|------------|-------| -| Browse group | ✓ | ✓ | ✓ | ✓ | ✓ | -| Edit SAML SSO Billing **(PREMIUM SAAS)** | ✓ | ✓ | ✓ | ✓ | ✓ (4) | -| Pull a container image using the dependency proxy | ✓ | ✓ | ✓ | ✓ | ✓ | -| View Contribution analytics | ✓ | ✓ | ✓ | ✓ | ✓ | -| View group epic **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View group wiki pages **(PREMIUM)** | ✓ (6) | ✓ | ✓ | ✓ | ✓ | -| View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View Insights charts **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View Issue analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View Value Stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | -| Create/edit group epic **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | -| Create/edit/delete epic boards **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | -| Manage group labels | | ✓ | ✓ | ✓ | ✓ | -| Pull [packages](packages/index.md) | | ✓ | ✓ | ✓ | ✓ | -| View a container registry | | ✓ | ✓ | ✓ | ✓ | -| View Group DevOps Adoption **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | -| View Productivity analytics **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | -| Create and edit group wiki pages **(PREMIUM)** | | | ✓ | ✓ | ✓ | -| Create project in group | | | ✓ (3)(5) | ✓ (3) | ✓ (3) | -| Create/edit/delete group milestones | | | ✓ | ✓ | ✓ | -| Create/edit/delete iterations | | | ✓ | ✓ | ✓ | -| Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | -| Enable/disable a dependency proxy | | | ✓ | ✓ | ✓ | -| Purge the dependency proxy for a group | | | | | ✓ | -| Publish [packages](packages/index.md) | | | ✓ | ✓ | ✓ | -| Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| View group Audit Events | | | ✓ (7) | ✓ (7) | ✓ | -| Create subgroup | | | | ✓ (1) | ✓ | -| Delete group wiki pages **(PREMIUM)** | | | ✓ | ✓ | ✓ | -| Edit epic comments (posted by any user) **(ULTIMATE)** | | | | ✓ (2) | ✓ (2) | -| List group deploy tokens | | | | ✓ | ✓ | -| Manage [group push rules](group/index.md#group-push-rules) **(PREMIUM)** | | | | ✓ | ✓ | -| View/manage group-level Kubernetes cluster | | | | ✓ | ✓ | -| Administer project compliance frameworks | | | | | ✓ | -| Create/Delete group deploy tokens | | | | | ✓ | -| Change group visibility level | | | | | ✓ | -| Delete group | | | | | ✓ | -| Delete group epic **(PREMIUM)** | | | | | ✓ | -| Disable notification emails | | | | | ✓ | -| Edit group settings | | | | | ✓ | -| Filter members by 2FA status | | | | | ✓ | -| Manage group level CI/CD variables | | | | | ✓ | -| Manage group members | | | | | ✓ | -| Share (invite) groups with groups | | | | | ✓ | -| View 2FA status of members | | | | | ✓ | -| View Billing **(FREE SAAS)** | | | | | ✓ (4) | -| View Usage Quotas **(FREE SAAS)** | | | | | ✓ (4) | +| Action | Guest | Reporter | Developer | Maintainer | Owner | +|--------------------------------------------------------------------------|-------|----------|-----------|------------|-------| +| Browse group | ✓ | ✓ | ✓ | ✓ | ✓ | +| Pull a container image using the dependency proxy | ✓ | ✓ | ✓ | ✓ | ✓ | +| View Contribution analytics | ✓ | ✓ | ✓ | ✓ | ✓ | +| View group epic **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| View group wiki pages **(PREMIUM)** | ✓ (6) | ✓ | ✓ | ✓ | ✓ | +| View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| View Insights charts **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| View Issue analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| View value stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | +| Create/edit group epic **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | +| Create/edit/delete epic boards **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | +| Manage group labels | | ✓ | ✓ | ✓ | ✓ | +| Publish [packages](packages/index.md) | | | ✓ | ✓ | ✓ | +| Pull [packages](packages/index.md) | | ✓ | ✓ | ✓ | ✓ | +| Delete [packages](packages/index.md | | | | ✓ | ✓ | +| Pull a Container Registry image | ✓ (7) | ✓ | ✓ | ✓ | ✓ | +| Remove a Container Registry image | | | ✓ | ✓ | ✓ | +| View Group DevOps Adoption **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | +| View Productivity analytics **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | +| Create and edit group wiki pages **(PREMIUM)** | | | ✓ | ✓ | ✓ | +| Create project in group | | | ✓ (3)(5) | ✓ (3) | ✓ (3) | +| Create/edit/delete group milestones | | | ✓ | ✓ | ✓ | +| Create/edit/delete iterations | | | ✓ | ✓ | ✓ | +| Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | +| Enable/disable a dependency proxy | | | ✓ | ✓ | ✓ | +| Purge the dependency proxy for a group | | | | | ✓ | +| Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| View group Audit Events | | | ✓ (7) | ✓ (7) | ✓ | +| Create subgroup | | | | ✓ (1) | ✓ | +| Delete group wiki pages **(PREMIUM)** | | | ✓ | ✓ | ✓ | +| Edit epic comments (posted by any user) **(ULTIMATE)** | | | | ✓ (2) | ✓ (2) | +| List group deploy tokens | | | | ✓ | ✓ | +| Manage [group push rules](group/index.md#group-push-rules) **(PREMIUM)** | | | | ✓ | ✓ | +| View/manage group-level Kubernetes cluster | | | | ✓ | ✓ | +| Administer project compliance frameworks | | | | | ✓ | +| Create/Delete group deploy tokens | | | | | ✓ | +| Change group visibility level | | | | | ✓ | +| Delete group | | | | | ✓ | +| Delete group epic **(PREMIUM)** | | | | | ✓ | +| Disable notification emails | | | | | ✓ | +| Edit group settings | | | | | ✓ | +| Edit SAML SSO **(PREMIUM SAAS)** | | | | | ✓ (4) | +| Filter members by 2FA status | | | | | ✓ | +| Manage group level CI/CD variables | | | | | ✓ | +| Manage group members | | | | | ✓ | +| Share (invite) groups with groups | | | | | ✓ | +| View 2FA status of members | | | | | ✓ | +| View Billing **(FREE SAAS)** | | | | | ✓ (4) | +| View Usage Quotas **(FREE SAAS)** | | | | | ✓ (4) | +| Manage runners | | | | | ✓ | + +<!-- markdownlint-disable MD029 --> 1. Groups can be set to [allow either Owners or Owners and Maintainers to create subgroups](group/subgroups/index.md#creating-a-subgroup) -1. Introduced in GitLab 12.2. -1. Default project creation role can be changed at: +2. Introduced in GitLab 12.2. +3. Default project creation role can be changed at: - The [instance level](admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). - The [group level](group/index.md#specify-who-can-add-projects-to-a-group). -1. Does not apply to subgroups. -1. Developers can push commits to the default branch of a new project only if the [default branch protection](group/index.md#change-the-default-branch-protection-of-a-group) is set to "Partially protected" or "Not protected". -1. In addition, if your group is public or internal, all users who can see the group can also see group wiki pages. -1. Users can only view events based on their individual actions. +4. Does not apply to subgroups. +5. Developers can push commits to the default branch of a new project only if the [default branch protection](group/index.md#change-the-default-branch-protection-of-a-group) is set to "Partially protected" or "Not protected". +6. In addition, if your group is public or internal, all users who can see the group can also see group wiki pages. +7. Users can only view events based on their individual actions. + +<!-- markdownlint-enable MD029 --> ### Subgroup permissions @@ -470,11 +545,16 @@ with the permissions described on the documentation on [auditor users permission > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40942) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. -Owners can add members with a "minimal access" role to a parent group. Such users don't -automatically have access to projects and subgroups underneath. To support such access, owners must explicitly add these "minimal access" users to the specific subgroups/projects. +Owners can add members with a "minimal access" role to a parent group. Such users don't automatically have access to +projects and subgroups underneath. Owners must explicitly add these "minimal access" users to the specific subgroups and +projects. + +Because of an [outstanding issue](https://gitlab.com/gitlab-org/gitlab/-/issues/267996), when minimal access users: -Users with minimal access can list the group in the UI and through the API. However, they cannot see -details such as projects or subgroups. They do not have access to the group's page or list any of its subgroups or projects. +- Sign in with standard web authentication, they receive a `404` error when accessing the parent group. +- Sign in with Group SSO, they receive a `404` error immediately because they are redirected to the parent group page. + +To work around the issue, give these users the Guest role or higher to any project or subgroup within the parent group. ### Minimal access users take license seats @@ -492,66 +572,6 @@ which visibility level you select on project settings. - Everyone with access: everyone can see depending on your project visibility level. - Everyone: enabled for everyone (only available for GitLab Pages). -## GitLab CI/CD permissions - -GitLab CI/CD permissions rely on the role the user has in GitLab: - -- Maintainer -- Developer -- Guest/Reporter - -GitLab administrators can perform any action on GitLab CI/CD in scope of the GitLab -instance and project. - -| Action | Guest, Reporter | Developer |Maintainer| Administrator | -|---------------------------------------|-----------------|-------------|----------|---------------| -| See commits and jobs | ✓ | ✓ | ✓ | ✓ | -| Retry or cancel job | | ✓ | ✓ | ✓ | -| Erase job artifacts and job logs | | ✓ (*1*) | ✓ | ✓ | -| Delete project | | | ✓ | ✓ | -| Create project | | | ✓ | ✓ | -| Change project configuration | | | ✓ | ✓ | -| Add specific runners | | | ✓ | ✓ | -| Add shared runners | | | | ✓ | -| Clear runner caches manually | | | ✓ | ✓ | -| See events in the system | | | | ✓ | -| Admin Area | | | | ✓ | - -1. Only if the job was: - - Triggered by the user - - [In GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/35069) and later, run for a non-protected branch. - -### Job permissions - -This table shows granted privileges for jobs triggered by specific types of -users: - -| Action | Guest, Reporter | Developer |Maintainer| Administrator | -|---------------------------------------------|-----------------|-------------|----------|---------| -| Run CI job | | ✓ | ✓ | ✓ | -| Clone source and LFS from current project | | ✓ | ✓ | ✓ | -| Clone source and LFS from public projects | | ✓ | ✓ | ✓ | -| Clone source and LFS from internal projects | | ✓ (*1*) | ✓ (*1*) | ✓ | -| Clone source and LFS from private projects | | ✓ (*2*) | ✓ (*2*) | ✓ (*2*) | -| Pull container images from current project | | ✓ | ✓ | ✓ | -| Pull container images from public projects | | ✓ | ✓ | ✓ | -| Pull container images from internal projects| | ✓ (*1*) | ✓ (*1*) | ✓ | -| Pull container images from private projects | | ✓ (*2*) | ✓ (*2*) | ✓ (*2*) | -| Push container images to current project | | ✓ | ✓ | ✓ | -| Push container images to other projects | | | | | -| Push source and LFS | | | | | - -1. Only if the triggering user is not an external one -1. Only if the triggering user is a member of the project - -## Running pipelines on protected branches - -The permission to merge or push to protected branches is used to define if a user can -run CI/CD pipelines and execute actions on jobs that are related to those branches. - -See [Security on protected branches](../ci/pipelines/index.md#pipeline-security-on-protected-branches) -for details about the pipelines security model. - ## Release permissions with protected tags [The permission to create tags](project/protected_tags.md) is used to define if a user can diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index 32b8d2b33ee..7e1074aa50f 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -1,7 +1,7 @@ --- type: reference stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 365f96b48b3..c116b1fc00d 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -1,7 +1,7 @@ --- type: howto stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -55,16 +55,17 @@ There are two options for deleting users: - **Delete user and contributions** When using the **Delete user** option, not all associated records are deleted with the user. -Here's a list of things that are **not** deleted: +Here's a list of things created by the user that are **not** deleted: -- Issues that the user created. -- Merge requests that the user created. -- Notes that the user created. -- Abuse reports that the user reported. -- Award emoji that the user created. +- Abuse reports +- Award emoji +- Epics +- Issues +- Merge requests +- Notes Instead of being deleted, these records are moved to a system-wide -user with the username "Ghost User", whose sole purpose is to act as a container +user with the username Ghost User, whose sole purpose is to act as a container for such records. Any commits made by a deleted user still display the username of the original user. @@ -81,14 +82,21 @@ is a sole owner of. Administrators can also request this behavior when deleting users from the [API](../../../api/users.md#user-deletion) or the Admin Area. -<!-- ## Troubleshooting +## Troubleshooting -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. +### Deleting a user results in a PostgreSQL null value error -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +There is [a known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/349411) that results +in users not being deleted, and the following error generated: + +```plaintext +ERROR: null value in column "user_id" violates not-null constraint +``` + +The error can be found in the [PostgreSQL log](../../../administration/logs.md#postgresql-logs) and +in the **Retries** section of the [background jobs view](../../admin_area/index.md#background-jobs) in the Admin Area. + +If the user being deleted used the [iterations](../../group/iterations/index.md) feature, such +as adding an issue to an iteration, you must use +[the workaround documented in the issue](https://gitlab.com/gitlab-org/gitlab/-/issues/349411#workaround) +to delete the user. diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 3af8c1c1b5a..a820cf150e9 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/profile/img/personal_readme_setup_v14_5.png b/doc/user/profile/img/personal_readme_setup_v14_5.png Binary files differnew file mode 100644 index 00000000000..92d8e0ec936 --- /dev/null +++ b/doc/user/profile/img/personal_readme_setup_v14_5.png diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 89e4ea6ea5b..f201e04183c 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -1,7 +1,7 @@ --- type: index, howto stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -104,16 +104,34 @@ user profiles are only visible to signed-in users. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232157) in GitLab 14.5. -If you want to add more information to your profile page, you can create a README file. When you populate the README file with information, it's included on your profile page. +You can add more information to your profile page with a README file. When you populate +the README file with information, it's included on your profile page. -To add a README to your profile: +### From a new project -1. Create a new public project with the same project path as your GitLab username. +To create a new project and add its README to your profile: + +1. On the top bar, select **Menu > Project**. +1. Select **Create new project**. +1. Select **Create blank project**. +1. Enter the project details: + - In the **Project name** field, enter the name for your new project. + - In the **Project URL** field, select your GitLab username. + - In the **Project slug** field, enter your GitLab username. +1. For **Visibility Level**, select **Public**. +  +1. For **Project Configuration**, ensure **Initialize repository with a README** is selected. +1. Select **Create project**. 1. Create a README file inside this project. The file can be any valid [README or index file](../project/repository/index.md#readme-and-index-files). 1. Populate the README file with [Markdown](../markdown.md). -To use an existing project, [update the path](../project/settings/index.md#renaming-a-repository) of the project to match -your username. +GitLab displays the contents of your README below your contribution graph. + +### From an existing project + +To add the README from an existing project to your profile, +[update the path](../project/settings/index.md#renaming-a-repository) of the project +to match your username. ## Add external accounts to your user profile page diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 45cff326332..10d718fdf1a 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -1,7 +1,7 @@ --- type: concepts, howto stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -97,7 +97,7 @@ A personal access token can perform actions based on the assigned scopes. | `read_user` | Read-only for endpoints under `/users`. Essentially, access to any of the `GET` requests in the [Users API](../../api/users.md). | | `read_api` | Read-only for the complete API, including all groups and projects, the Container Registry, and the Package Registry. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28944) in GitLab 12.10.) | | `read_repository` | Read-only (pull) for the repository through `git clone`. | -| `write_repository` | Read-write (pull, push) for the repository through `git clone`. Required for accessing Git repositories over HTTP when 2FA is enabled. | +| `write_repository` | Read-write (pull, push) for the repository through `git clone`. | | `read_registry` | Read-only (pull) for [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. | | `write_registry` | Read-write (push) for [Container Registry](../packages/container_registry/index.md) images if a project is private and authorization is required. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28958) in GitLab 12.10.) | | `sudo` | API actions as any user in the system (if the authenticated user is an administrator). | @@ -111,7 +111,7 @@ Personal access tokens expire on the date you define, at midnight UTC. - In GitLab Ultimate, administrators can [limit the lifetime of personal access tokens](../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-personal-access-tokens). - In GitLab Ultimate, administrators can choose whether or not to - [enforce personal access token expiration](../admin_area/settings/account_and_limit_settings.md#allow-expired-personal-access-tokens-to-be-used). + [enforce personal access token expiration](../admin_area/settings/account_and_limit_settings.md#allow-expired-personal-access-tokens-to-be-used-deprecated). ## Create a personal access token programmatically **(FREE SELF)** diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 63be88f90d6..52baf5189e1 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -43,7 +43,7 @@ The default theme is Indigo. You can choose between 10 themes: GitLab has started work on dark mode! The dark mode Alpha release is available in the spirit of iteration and the lower expectations of -[Alpha versions](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). +[Alpha versions](../../policy/alpha-beta-support.md#alpha-features). Progress on dark mode is tracked in the [Dark theme epic](https://gitlab.com/groups/gitlab-org/-/epics/2902). See the epic for: diff --git a/doc/user/profile/unknown_sign_in_notification.md b/doc/user/profile/unknown_sign_in_notification.md index 0ed2a11d363..37bde3ce846 100644 --- a/doc/user/profile/unknown_sign_in_notification.md +++ b/doc/user/profile/unknown_sign_in_notification.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index a5473629d4f..e14a71a7e10 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -34,7 +34,7 @@ Prerequisites: - An [Amazon Web Services](https://aws.amazon.com/) account. - Permissions to manage IAM resources. -For instance-level clusters, see [additional requirements for self-managed instances](#additional-requirements-for-self-managed-instances). **(FREE SELF)** +For instance-level clusters, see [additional requirements for self-managed instances](#additional-requirements-for-self-managed-instances). To create new Kubernetes clusters for your project, group, or instance through the certificate-based method: @@ -174,7 +174,7 @@ When you create a new cluster, you have the following settings: | Kubernetes cluster name | Your cluster's name. | | Environment scope | The [associated environment](multiple_kubernetes_clusters.md#setting-the-environment-scope). | | Service role | The **EKS IAM role** (**role A**). | -| Kubernetes version | The [Kubernetes version](../../infrastructure/clusters/connect/index.md#supported-cluster-versions) for your cluster. | +| Kubernetes version | The [Kubernetes version](../../clusters/agent/index.md#supported-cluster-versions) for your cluster. | | Key pair name | 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. | | VPC | The [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) to use for your EKS Cluster resources. | | Subnets | The [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) in your VPC where your worker nodes run. Two are required. | @@ -256,7 +256,7 @@ IAM user in the Amazon AWS console, and follow these steps: #### EKS access key and ID -> Instance profiles were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291015) in GitLab 13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291015) instance profiles in GitLab 13.7. If you're using GitLab 13.7 or later, you can use instance profiles to dynamically retrieve temporary credentials from AWS when needed. diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index acc5ed4cb30..0c3827bcbb1 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Connect existing clusters through cluster certificates **(DEPRECATED)** +# Connect existing clusters through cluster certificates (DEPRECATED) **(FREE)** > [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. @@ -27,7 +27,7 @@ To add any cluster to GitLab, you need: - Either a GitLab.com account or an account for a self-managed installation running GitLab 12.5 or later. - The Maintainer role for group-level and project-level clusters. -- Access to the Admin area for instance-level clusters. **(FREE SELF)** +- Access to the Admin area for instance-level clusters. - A Kubernetes cluster. - Cluster administration access to the cluster with `kubectl`. diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index 19166a1ff8c..b5e2a1bad51 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -1,13 +1,13 @@ --- stage: Monitor -group: Monitor +group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Kubernetes Logs (DEPRECATED) **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4752) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26383) to [GitLab Free](https://about.gitlab.com/pricing/) 12.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4752) in GitLab 11.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26383) from GitLab Ultimate to GitLab Free 12.9. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. WARNING: diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md index 12527853b40..a56eaa9b953 100644 --- a/doc/user/project/clusters/multiple_kubernetes_clusters.md +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Multiple clusters per project with cluster certificates (DEPRECATED) **(FREE)** -> - Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3 -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) to GitLab Free in 13.2. +> - Introduced in GitLab 10.3 +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) from GitLab Premium to GitLab Free in 13.2. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. WARNING: diff --git a/doc/user/project/clusters/protect/container_host_security/index.md b/doc/user/project/clusters/protect/container_host_security/index.md index 98ba4a1f84d..a0297a7a86f 100644 --- a/doc/user/project/clusters/protect/container_host_security/index.md +++ b/doc/user/project/clusters/protect/container_host_security/index.md @@ -6,11 +6,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Container Host Security **(FREE)** -NOTE: -In GitLab 14.5, using a certificate to connect GitLab to a Kubernetes cluster is [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8). -You can continue using Container Host Security, even though it relies on this certificate-based -method. The work to allow all aspects of Container Host Security to function through the [GitLab Agent](../../../../clusters/agent/index.md) -instead of the certificate-based method can be tracked [in this GitLab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/299350). +> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. + +WARNING: +Container Host Security is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) +for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 15.0. Container Host Security in GitLab provides Intrusion Detection and Prevention capabilities that can monitor and (optionally) block activity inside the containers themselves. This is done by leveraging diff --git a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md index 466bcb7916f..4e56b7e5140 100644 --- a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md @@ -6,6 +6,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Getting started with Container Host Security **(FREE)** +> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. + +WARNING: +Container Host Security is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) +for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 15.0. + The following steps are recommended for installing Container Host Security. ## Installation steps diff --git a/doc/user/project/clusters/protect/container_network_security/index.md b/doc/user/project/clusters/protect/container_network_security/index.md index 06dc6b24620..7176a1cf1b9 100644 --- a/doc/user/project/clusters/protect/container_network_security/index.md +++ b/doc/user/project/clusters/protect/container_network_security/index.md @@ -6,11 +6,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Container Network Security **(FREE)** -NOTE: -In GitLab 14.5, using a certificate to connect GitLab to a Kubernetes cluster is [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8). -You can continue using Container Network Security, even though it relies on this certificate-based -method. The work to allow all aspects of Container Network Security to function through the [GitLab Agent](../../../../clusters/agent/index.md) -instead of the certificate-based method can be tracked [in this GitLab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/299350) and [this GitLab Epic](https://gitlab.com/groups/gitlab-org/-/epics/7057). +> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. + +WARNING: +Container Network Security is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) +for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 15.0. Container Network Security in GitLab provides basic firewall functionality by leveraging Cilium NetworkPolicies to filter traffic going in and out of the cluster as well as traffic between pods diff --git a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md index 340c9397e9c..e6c91302d7b 100644 --- a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md @@ -6,6 +6,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Getting started with Container Network Security **(FREE)** +> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. + +WARNING: +Container Network Security is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) +for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 15.0. + The following steps are recommended for installing Container Network Security. ## Installation steps diff --git a/doc/user/project/clusters/protect/index.md b/doc/user/project/clusters/protect/index.md index 1314a1948d5..473195f4c17 100644 --- a/doc/user/project/clusters/protect/index.md +++ b/doc/user/project/clusters/protect/index.md @@ -6,6 +6,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Protecting your deployed applications **(FREE)** +> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. + +WARNING: +The Container Network Security and Container Host Security features are in their end-of-life +processes. They're +[deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) +for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) +in GitLab 15.0. + GitLab makes it straightforward to protect applications deployed in [connected Kubernetes clusters](index.md). These protections are available in the Kubernetes network layer and in the container itself. At the network layer, the Container Network Security capabilities in GitLab provide basic firewall diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 265a60c6f2c..29164da307b 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/6) in GitLab 14.3. WARNING: -Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). +Serverless is currently in [alpha](../../../../policy/alpha-beta-support.md#alpha-features). ## Overview diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 4068d8e056c..eb18834cc6b 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -281,7 +281,7 @@ README.md @docs ### Approvals shown as optional -A Code Owner approval rule is optional if these conditions are not met: +A Code Owner approval rule is optional if any of these conditions are true: - The user or group are not a member of the project or parent group. - [Code Owner approval on a protected branch](protected_branches.md#require-code-owner-approval-on-a-protected-branch) has not been set up. diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 2e876b24b53..57f6efa3092 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -29,7 +29,7 @@ repository in automation, it's a simple solution. A drawback is that your repository could become vulnerable if a remote machine is compromised by a hacker. You should limit access to the remote machine before a deploy key is enabled on your repository. A good rule to follow is to provide access only to trusted users, -and make sure that the allowed users have at least the [Maintainer role](../../permissions.md) +and make sure that the allowed users have at least the Maintainer role in the GitLab project. If this security implication is a concern for your organization, diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index f57fa5aa57d..4d69209aafa 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -14,7 +14,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w 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). +Deploy tokens can be managed only by users with the Maintainer role. Deploy tokens cannot be used with the GitLab API. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 6c17964f3a5..539f5230063 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -114,7 +114,9 @@ To re-use templates [you've created](../project/description_templates.md#create- You might also be interested in templates for various [file types in groups](../group/index.md#group-file-templates). -### Set a default template for merge requests and issues **(PREMIUM)** +### Set a default template for merge requests and issues + +> `Default.md` template [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78302) in GitLab 14.8. In a project, you can choose a default description template for new issues and merge requests. As a result, every time a new merge request or issue is created, it's pre-filled with the text you @@ -125,17 +127,29 @@ Prerequisites: - On your project's left sidebar, select **Settings > General** and expand **Visibility, project features, permissions**. Ensure issues or merge requests are set to either **Everyone with access** or **Only Project Members**. -To set a default description template for merge requests: +To set a default description template for merge requests, either: -1. Go to your project's **Settings**. -1. Select **Expand** under the **Merge requests** header. -1. Fill in the **Default description template for merge requests** text area. -1. Select **Save changes**. +- [Create a merge request template](#create-a-merge-request-template) named `Default.md` and save it in `.gitlab/merge_request_templates/`. + This will not overwrite the default template if one has been set in the project settings. +- Users on GitLab Premium and higher: set the default template in project settings: + + 1. On the top bar, select **Menu > Projects** and find your project. + 1. On the left sidebar, select **Settings**. + 1. Expand **Merge requests**. + 1. Fill in the **Default description template for merge requests** text area. + 1. Select **Save changes**. + +To set a default description template for issues, either: -To set a default description template for issues: +- [Create an issue template](#create-an-issue-template) named `Default.md` and save it in `.gitlab/issue_templates/`. + This will not overwrite the default template if one has been set in the project settings. +- Users on GitLab Premium and higher: set the default template in project settings: -1. Select **Expand** under **Default issue template**. -1. Fill in the **Default description template for issues** text area. + 1. On the top bar, select **Menu > Projects** and find your project. + 1. On the left sidebar, select **Settings**. + 1. Expand **Default issue template**. + 1. Fill in the **Default description template for issues** text area. + 1. Select **Save changes**. Because GitLab merge request and issues support [Markdown](../markdown.md), you can use it to format headings, lists, and so on. @@ -143,6 +157,16 @@ headings, lists, and so on. You can also provide `issues_template` and `merge_requests_template` attributes in the [Projects REST API](../../api/projects.md) to keep your default issue and merge request templates up to date. +#### Priority of description templates + +When you set [merge request and issue description templates](#set-a-default-template-for-merge-requests-and-issues) +in various places, they have the following priorities in a project. +The ones higher up override the ones below: + +1. Template selected in project settings. +1. `Default.md` from the parent group. +1. `Default.md` from the project repository. + ## Example description template We use description templates for issues and merge requests in the diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 1d06b605aa9..9911c90863d 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -33,7 +33,7 @@ GitLab supports two different modes of file locking: ## Permissions Locks can be created by any person who has at least -[Developer role](../permissions.md) in the repository. +Developer role in the repository. Only the user who locked the file or directory can edit locked files. Other users are prevented from modifying locked files by pushing, merging, @@ -77,7 +77,7 @@ Check this document to learn more about [using Git LFS](../../topics/git/lfs/ind ### Configure Exclusive File Locks -You need the [Maintainer role](../permissions.md) to configure +You need the Maintainer role Exclusive File Locks for your project through the command line. The first thing to do before using File Locking is to tell Git LFS which @@ -226,4 +226,4 @@ To view and remove file locks: This list shows all the files locked either through LFS or GitLab UI. Locks can be removed by their author, or any user -with at least the [Maintainer role](../permissions.md). +with at least the Maintainer role. diff --git a/doc/user/project/img/time_tracking_example_v12_2.png b/doc/user/project/img/time_tracking_example_v12_2.png Binary files differdeleted file mode 100644 index 31d8c490ed1..00000000000 --- a/doc/user/project/img/time_tracking_example_v12_2.png +++ /dev/null diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 0c50fc77e33..62495872659 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -42,7 +42,7 @@ When issues/pull requests are being imported, the Bitbucket importer tries to fi the Bitbucket author/assignee in the GitLab database using the Bitbucket `nickname`. For this to work, the Bitbucket author/assignee should have signed in beforehand in GitLab and **associated their Bitbucket account**. Their `nickname` must also match their Bitbucket -`username.`. If the user is not found in the GitLab database, the project creator +`username`. If the user is not found in the GitLab database, the project creator (most of the times the current user that started the import process) is set as the author, but a reference on the issue about the original Bitbucket author is kept. diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index da47b673c29..4e3642eb3bd 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -5,130 +5,110 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Import your project from Bitbucket Server to GitLab **(FREE)** +# Import your project from Bitbucket Server **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20164) in GitLab 11.2. NOTE: -The Bitbucket Server importer does not work with [Bitbucket Cloud](https://bitbucket.org). -Use the [Bitbucket Cloud importer](bitbucket.md) for that. +This process is different than [importing from Bitbucket Cloud](bitbucket.md). -Import your projects from Bitbucket Server to GitLab with minimal effort. +From Bitbucket Server, you can import: -The Bitbucket importer can import: - -- Repository description (GitLab 11.2+) -- Git repository data (GitLab 11.2+) -- Pull requests (GitLab 11.2+) -- Pull request comments (GitLab 11.2+) +- Repository description +- Git repository data +- Pull requests +- Pull request comments When importing, repository public access is retained. If a repository is private in Bitbucket, it's created as private in GitLab as well. -## Limitations +## Import your Bitbucket repositories -- GitLab doesn't allow comments on arbitrary lines of code, so any Bitbucket comments out of bounds - are inserted as comments in the merge request. -- Bitbucket Server allows multiple levels of threading. GitLab import collapses this into one thread - and quote part of the original comment. -- Declined pull requests have unreachable commits, which prevents the GitLab importer from - generating a proper diff. These pull requests show up as empty changes. -- Pull request approvals are not imported. -- Attachments in Markdown are not imported. -- Task lists are not imported. -- Emoji reactions are not imported. -- Project filtering does not support fuzzy search (only `starts with` or `full match strings` are - supported). +Prerequisites: -## How it works +- An administrator must have enabled the **Bitbucket Server** in + **Admin > Settings > General > Visibility and access controls > Import sources**. +- Review the importer's [limitations](#limitations). -The Bitbucket Server importer works as follows: +To import your Bitbucket repositories: -1. The user is prompted to enter the URL, username, and password (or personal access token) to log in to Bitbucket. - These credentials are preserved only as long as the importer is running. -1. The importer attempts to list all the current repositories on the Bitbucket Server. -1. Upon selection, the importer clones the repository and import pull requests and comments. +1. Sign in to GitLab. +1. On the top bar, select **New** (**{plus}**). +1. Select **New project/repository**. +1. Select **Import project**. +1. Select **Bitbucket Server**. +1. Log in to Bitbucket and grant GitLab access to your Bitbucket account. +1. Select the projects to import, or import all projects. You can filter projects by name and select + the namespace for which to import each project. -### User assignment +## Limitations -When issues/pull requests are being imported, the Bitbucket importer tries to -find the author's email address with a confirmed email address in the GitLab -user database. If no such user is available, the project creator is set as -the author. The importer appends a note in the comment to mark the original -creator. +- GitLab doesn't allow comments on arbitrary lines of code. Any out-of-bounds Bitbucket comments are + inserted as comments in the merge request. +- Bitbucket Server allows multiple threading levels. The importer collapses this into one thread and + quotes part of the original comment. +- Declined pull requests have unreachable commits. This prevents the importer from generating a + proper diff. These pull requests show up as empty changes. +- Project filtering doesn't support fuzzy search. Only starts with or full match strings are + supported. -The importer creates any new namespaces (groups) if they don't exist or in -the case the namespace is taken, the repository is imported under the user's -namespace that started the import process. +The following aren't imported: -#### User assignment by username +- Pull request approvals +- Attachments in Markdown +- Task lists +- Emoji reactions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218609) 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. +## User assignment -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +When issues and pull requests are importing, the importer tries to find the author's email address +with a confirmed email address in the GitLab user database. If no such user is available, the +project creator is set as the author. The importer appends a note in the comment to mark the +original creator. -If you've enabled this feature, the importer tries to find a user in the GitLab user database with -the author's: +The importer creates any new namespaces (groups) if they don't exist. If the namespace is taken, the +repository imports under the namespace of the user who started the import process. -- `username` -- `slug` -- `displayName` +### User assignment by username -If the user is not found by any of these properties, the project creator is set as the author. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218609) in GitLab 13.4 [with a flag](../../../administration/feature_flags.md) named `bitbucket_server_user_mapping_by_username`. Disabled by default. +> - Not recommended for production use. -##### Enable or disable User assignment by username +FLAG: +On self-managed GitLab and GitLab.com, by default this feature is not available. To make it +available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) +named `bitbucket_server_user_mapping_by_username`. This feature is not ready for production use. -User assignment by username 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. +With this feature enabled, the importer tries to find a user in the GitLab user database with the +author's: -To enable it: +- `username` +- `slug` +- `displayName` -```ruby -Feature.enable(:bitbucket_server_user_mapping_by_username) -``` +If no user matches these properties, the project creator is set as the author. -To disable it: +## Troubleshooting -```ruby -Feature.disable(:bitbucket_server_user_mapping_by_username) -``` +### General -## Import your Bitbucket repositories +If the GUI-based import tool does not work, you can try to: -Prerequisite: +- Use the [GitLab Import API](../../../api/import.md#import-repository-from-bitbucket-server) + Bitbucket Server endpoint. +- Set up [repository mirroring](../repository/mirror/index.md). + It provides verbose error output. -- An administrator must have enabled the importer in - **Admin > Application Settings > Visibility and access controls > Import sources**. +See the [troubleshooting section](bitbucket.md#troubleshooting) +for Bitbucket Cloud. -To import your Bitbucket repositories: +### LFS objects not imported -1. Sign in to GitLab. -1. On the top bar, select **New** (**{plus}**). -1. Select **New project/repository**. -1. Select **Import project**. -1. Select **Bitbucket Server**. -1. Log in to Bitbucket and grant GitLab access to your Bitbucket account. -1. Select the projects that you'd like to import or import all projects. - You can filter projects by name and select the namespace - each project will be imported for. +If the project import completes but LFS objects can't be downloaded or cloned, you may be using a +password or personal access token containing special characters. For more information, see +[this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337769). -## Automate group and project import **(PREMIUM)** +## Related topics For information on automating user, group, and project import API calls, see [Automate group and project import](index.md#automate-group-and-project-import). - -## Troubleshooting - -If the GUI-based import tool does not work, you can try to: - -- Use the [GitLab Import API](../../../api/import.md#import-repository-from-bitbucket-server) Bitbucket server endpoint. -- Set up [Repository Mirroring](../repository/mirror/index.md), which provides verbose error output. - -See the [troubleshooting](bitbucket.md#troubleshooting) section for [Bitbucket](bitbucket.md). diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index d4cca723333..9f1c049045c 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -26,7 +26,7 @@ The following aspects of a project are imported: - Regular issue and pull request comments - [Git Large File Storage (LFS) Objects](../../../topics/git/lfs/index.md) - Pull request comments replies in discussions ([GitLab.com & 14.5+](https://gitlab.com/gitlab-org/gitlab/-/issues/336596)) -- Diff Notes suggestions ([GitLab.com & 14.7+](https://gitlab.com/gitlab-org/gitlab/-/issues/340624)) [with a flag](../../../administration/feature_flags.md) named `github_importer_use_diff_note_with_suggestions`. Enabled by default. +- Diff Notes suggestions ([GitLab.com & 14.7+](https://gitlab.com/gitlab-org/gitlab/-/issues/340624)) References to pull requests and issues are preserved (GitLab.com & 8.7+), and each imported repository maintains visibility level unless that [visibility @@ -181,8 +181,7 @@ Mirroring does not sync any new or updated pull requests from your GitHub projec ## Improve the speed of imports on self-managed instances -NOTE: -An administrator role on the GitLab server is required for this process. +Administrator access on the GitLab server is required for this process. For large projects it may take a while to import all data. To reduce the time necessary, you can increase the number of Sidekiq workers that process the following queues: diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 001f0d56cc5..41ef15108ec 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -50,7 +50,7 @@ information, see the prerequisites and important notes in these sections: NOTE: When migrating to GitLab.com, you must create users manually unless [SCIM](../../../user/group/saml_sso/scim_setup.md) will be used. Creating users with the API is limited to self-managed instances as it requires -the Administrator role. +administrator access. To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/index.md). Migrate the assets in this order: diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index c6992422733..5f7475eac36 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -40,9 +40,8 @@ iterations of the GitLab Jira importer. ### Permissions -In order to be able to import issues from a Jira project you need to have read access on Jira -issues and a [Maintainer or higher](../../permissions.md#project-members-permissions) role in the -GitLab project that you wish to import into. +To be able to import issues from a Jira project you must have read access on Jira +issues and at least the Maintainer role in the GitLab project that you wish to import into. ### Jira integration diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index 80f2d6d7e62..96b38b49960 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: The Phabricator task importer is in -[beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) and is +[beta](../../../policy/alpha-beta-support.md#beta-features) and is [**not** complete](https://gitlab.com/gitlab-org/gitlab/-/issues/284406). It imports only an issue's title and description. The GitLab project created during the import process contains only issues, and the associated repository is disabled. diff --git a/doc/user/project/index.md b/doc/user/project/index.md index bee097cdcbe..801c2520bda 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -105,7 +105,6 @@ Projects include the following [features](https://about.gitlab.com/features/): - [License Compliance](../compliance/license_compliance/index.md): Approve and deny licenses for projects. **(ULTIMATE)** - [Dependency List](../application_security/dependency_list/index.md): View project dependencies. **(ULTIMATE)** - [Requirements](requirements/index.md): Create criteria to check your products against. **(ULTIMATE)** -- [Static Site Editor](static_site_editor/index.md): Edit content on static websites without prior knowledge of the codebase or Git commands. - [Code Intelligence](code_intelligence.md): Navigate code. ## Project integrations diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 38de8d9f1af..bf343078634 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -46,6 +46,7 @@ integration in GitLab. 1. Select **Atlassian Bamboo**. 1. Ensure the **Active** checkbox is selected. 1. Enter the base URL of your Bamboo server. For example, `https://bamboo.example.com`. +1. Optional. Clear the **Enable SSL verification** checkbox to disable [SSL verification](overview.md#ssl-verification). 1. Enter the [build key](#identify-the-bamboo-build-plan-build-key) from your Bamboo build plan. 1. If necessary, enter a username and password for a Bamboo user that has diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index ac6e18e8e6a..9764c4d44a0 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can find the available integrations under your project's **Settings > Integrations** page. You need to have at least -the [Maintainer role](../../permissions.md) on the project. +the Maintainer role on the project. ## Integrations diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 1ff558b569b..b317e65bdf2 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -67,7 +67,7 @@ After you enable custom slash commands in Mattermost, you need configuration information from GitLab. To get this information: 1. In a different browser tab than your current Mattermost session, sign in to - GitLab as a user with [Administrator role](../../permissions.md). + GitLab as a user with administrator access. 1. On the top bar, select **Menu > Admin**. 1. In the left menu, select **Settings > Integrations**, then select **Mattermost slash commands**. diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 5b83df9b22e..8ecc16050be 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -82,6 +82,15 @@ instance configuration or provide custom settings. Read more about [Project integration management](../../admin_area/settings/project_integration_management.md). +## SSL verification + +By default, the SSL certificate for outgoing HTTP requests is verified based on +an internal list of Certificate Authorities. This means the certificate cannot +be self-signed. + +You can turn off SSL verification in the configuration settings for [webhooks](webhooks.md#configure-a-webhook) +and some integrations. + ## Troubleshooting integrations Some integrations use service hooks for integration with external applications. To confirm which ones use service hooks, see the [integrations listing](#integrations-listing) above. Learn more about [troubleshooting service hooks](webhooks.md#troubleshoot-webhooks). diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index de7ac6782d6..760b5030416 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index a07abf26fba..e8d611af30d 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index 97f69d65412..76d13d5487c 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index a5fc398e558..9bdd4945f5d 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 26d006adeb9..33a06958e0c 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index ad89543e9a6..ecf75d7b17a 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index 03bf9258659..e123000e0c5 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index 89c174f8fb9..fda7744e847 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Monitor +group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index de152aabde5..dd4cdb632e6 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -13,7 +13,7 @@ You can configure GitLab to send notifications to a Webex Teams space: ## Create a webhook for the space -1. Go to the [Incoming Webhooks app page](https://apphub.webex.com/applications/incoming-webhooks-cisco-systems-38054). +1. Go to the [Incoming Webhooks app page](https://apphub.webex.com/applications/incoming-webhooks-cisco-systems-38054-23307). 1. Select **Connect** and log in to Webex Teams, if required. 1. Enter a name for the webhook and select the space to receive the notifications. 1. Select **ADD**. diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index ab70a2d43f4..9d8b98edba1 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -773,6 +773,7 @@ Merge request events are triggered when: - A new merge request is created. - An existing merge request is updated, approved, unapproved, merged, or closed. - A commit is added in the source branch. +- All threads are resolved on the merge request. The available values for `object_attributes.action` in the payload are: @@ -838,6 +839,7 @@ Payload example: "updated_at": "2013-12-03T17:23:34Z", "milestone_id": null, "state": "opened", + "blocking_discussions_resolved": true, "merge_status": "unchecked", "target_project_id": 14, "iid": 1, diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 8bc2b51276a..ace5783c852 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -57,7 +57,7 @@ You can configure a webhook for a group or a project. The URL must be percent-encoded if it contains one or more special characters. 1. In **Secret token**, enter the [secret token](#validate-payloads-by-using-a-secret-token) to validate payloads. 1. In the **Trigger** section, select the [events](webhook_events.md) to trigger the webhook. -1. Optional. Clear the **Enable SSL verification** checkbox to disable [SSL verification](#verify-an-ssl-certificate). +1. Optional. Clear the **Enable SSL verification** checkbox to disable [SSL verification](overview.md#ssl-verification). 1. Select **Add webhook**. ## Test a webhook @@ -123,15 +123,6 @@ The token is sent with the hook request in the `X-Gitlab-Token` HTTP header. Your webhook endpoint can check the token to verify that the request is legitimate. -## Verify an SSL certificate - -By default, the SSL certificate of the webhook endpoint is verified based on -an internal list of Certificate Authorities. This means the certificate cannot -be self-signed. - -You can turn off SSL verification in the [webhook settings](#configure-a-webhook) -in your GitLab projects. - ## Filter push events by branch Push events can be filtered by branch using a branch name or wildcard pattern diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 47a2d215024..71440298d85 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -194,7 +194,7 @@ card includes: ## Permissions -Users with the [Reporter and higher roles](../permissions.md) can use all the functionality of the +Users with at least the Reporter role can use all the functionality of the issue board feature to create or delete lists. They can also drag issues from one list to another. ## Ordering issues in a list @@ -402,7 +402,7 @@ To set a WIP limit for a list: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34723) in GitLab 12.8. > - [View blocking issues when hovering over blocked icon](https://gitlab.com/gitlab-org/gitlab/-/issues/210452) in GitLab 13.10. -If an issue is blocked by another issue, an icon appears next to its title to indicate its blocked +If an issue is [blocked by another issue](issues/related_issues.md#blocking-issues), an icon appears next to its title to indicate its blocked status. When you hover over the blocked icon (**{issue-block}**), a detailed information popover is displayed. @@ -496,6 +496,9 @@ The steps depend on the scope of the list: ### Filter issues +> - Filtering by iteration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6. +> - Filtering by issue type [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/268152) in GitLab 14.6. + You can use the filters on top of your issue board to show only the results you want. It's similar to the filtering used in the [issue tracker](issues/index.md). @@ -504,11 +507,12 @@ You can filter by the following: - Assignee - Author - Epic -- Iteration ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6) +- Iteration - Label - Milestone - My Reaction - Release +- Type (issue/incident) - Weight #### Filtering issues in a group board @@ -565,7 +569,7 @@ You can move issues and lists by dragging them. Prerequisites: -- You must have at least the Reporter [role](../permissions.md#project-members-permissions) for a project in GitLab. +- You must have at least the Reporter role for a project in GitLab. To move an issue, select the issue card and drag it to another position in its current list or into a different list. Learn about possible effects in [Dragging issues between lists](#dragging-issues-between-lists). diff --git a/doc/user/project/issues/associate_zoom_meeting.md b/doc/user/project/issues/associate_zoom_meeting.md index aba8c45699c..41de91d9bd7 100644 --- a/doc/user/project/issues/associate_zoom_meeting.md +++ b/doc/user/project/issues/associate_zoom_meeting.md @@ -25,7 +25,7 @@ In an issue, leave a comment using the `/zoom` quick action followed by a valid /zoom https://zoom.us/j/123456789 ``` -If the Zoom meeting URL is valid and you have at least the Reporter [role](../../permissions.md), +If the Zoom meeting URL is valid and you have at least the Reporter role, a system alert notifies you of its successful addition. The issue's description is automatically edited to include the Zoom link, and a button appears right under the issue's title. @@ -44,5 +44,5 @@ Similarly to adding a Zoom meeting, you can remove it with a quick action: /remove_zoom ``` -If you have at least the Reporter [role](../../permissions.md), +If you have at least the Reporter role, a system alert notifies you that the meeting URL was successfully removed. diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index e8c58f2feb9..15130523da6 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -11,19 +11,20 @@ Confidential issues are [issues](index.md) visible only to members of a project Confidential issues can be used by open source projects and companies alike to keep security vulnerabilities private or prevent surprises from leaking out. -## Making an issue confidential +## Make an issue confidential -You can make an issue confidential during issue creation or by editing -an existing one. +You can make an issue confidential when you create or edit an issue. When you create a new issue, a checkbox right below the text area is available to mark the issue as confidential. Check that box and hit the **Create issue** button to create the issue. For existing issues, edit them, check the confidential checkbox and hit **Save changes**. +When you create a confidential issue in a project, the project becomes listed in the **Contributed projects** section in your [profile](../../profile/index.md). **Contributed projects** does not show information about the confidential issue; it only shows the project name. +  -## Modifying issue confidentiality +## Modify issue confidentiality There are two ways to change an issue's confidentiality. @@ -42,15 +43,15 @@ system note in the issue's comments.  -When an issue is made confidential, only users with at least the [Reporter role](../../permissions.md) +When an issue is made confidential, only users with at least the Reporter role for the project have access to the issue. Users with Guest or [Minimal](../../permissions.md#users-with-minimal-access) roles can't access the issue even if they were actively participating before the change. -## Indications of a confidential issue +## Confidential issue indicators There are a few things that visually separate a confidential issue from a -regular one. In the issues index page view, you can see the eye-slash (**(eye-slash)**) icon +regular one. In the issues index page view, you can see the eye-slash (**{eye-slash}**) icon next to the issues that are marked as confidential:  @@ -74,19 +75,18 @@ There is also an indicator on the sidebar denoting confidentiality. ## Merge requests for confidential issues -Although you can make issues be confidential in public projects, you cannot make -confidential merge requests. Learn how to create [merge requests for confidential issues](../merge_requests/confidential.md) -that prevent leaks of private data. +Although you can create confidential issues (and make existing issues confidential) in a public project, you cannot make confidential merge requests. +Learn how to create [merge requests for confidential issues](../merge_requests/confidential.md) that prevent leaks of private data. ## Permissions and access to confidential issues There are two kinds of level access for confidential issues. The general rule is that confidential issues are visible only to members of a project with at -least the Reporter [role](../../permissions.md#project-members-permissions). However, a guest user can also create +least the Reporter role. However, a guest user can also create confidential issues, but can only view the ones that they created themselves. Confidential issues are also hidden in search results for unprivileged users. -For example, here's what a user with the [Maintainer role](../../permissions.md) and the Guest role +For example, here's what a user with the Maintainer role and the Guest role sees in the project's search results respectively. | Maintainer role | Guest role | diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index a9fca4f2b75..947fbdcc2d1 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -61,29 +61,29 @@ fields if needed, and newlines to separate rows. The first row contains the headers, which are listed in the following table along with a description of the values: -| Column | Description | -|-------------------|-------------| -| Issue ID | Issue `iid` | -| URL | A link to the issue on GitLab | -| Title | Issue `title` | -| State | `Open` or `Closed` | -| Description | Issue `description` | -| Author | Full name of the issue author | -| Author Username | Username of the author, with the `@` symbol omitted | -| Assignee | Full name of the issue assignee | -| Assignee Username | Username of the author, with the `@` symbol omitted | -| Confidential | `Yes` or `No` | -| Locked | `Yes` or `No` | -| Due Date | Formatted as `YYYY-MM-DD` | -| Created At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | -| Updated At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | -| Milestone | Title of the issue milestone | -| Weight | Issue weight | -| Labels | Title of any labels joined with a `,` | -| Time Estimate | [Time estimate](../time_tracking.md#estimates) in seconds | -| Time Spent | [Time spent](../time_tracking.md#time-spent) in seconds | -| Epic ID | ID of the parent epic **(ULTIMATE)**, introduced in 12.7 | -| Epic Title | Title of the parent epic **(ULTIMATE)**, introduced in 12.7 | +| Column | Description | +|------------------------------------------|-----------------------------------------------------------| +| Issue ID | Issue `iid` | +| URL | A link to the issue on GitLab | +| Title | Issue `title` | +| State | `Open` or `Closed` | +| Description | Issue `description` | +| Author | Full name of the issue author | +| Author Username | Username of the author, with the `@` symbol omitted | +| Assignee | Full name of the issue assignee | +| Assignee Username | Username of the author, with the `@` symbol omitted | +| Confidential | `Yes` or `No` | +| Locked | `Yes` or `No` | +| Due Date | Formatted as `YYYY-MM-DD` | +| Created At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | +| Updated At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | +| Milestone | Title of the issue milestone | +| Weight | Issue weight | +| Labels | Title of any labels joined with a `,` | +| Time Estimate | [Time estimate](../time_tracking.md#estimates) in seconds | +| Time Spent | [Time spent](../time_tracking.md#time-spent) in seconds | +| [Epic](../../group/epics/index.md) ID | ID of the parent epic, introduced in 12.7 | +| [Epic](../../group/epics/index.md) Title | Title of the parent epic, introduced in 12.7 | ## Limitations diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index 69dc0cbafd8..e4b8efd27ed 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -14,9 +14,7 @@ retain columns such as labels and milestones, consider the [Move Issue feature]( The user uploading the CSV file is set as the author of the imported issues. -NOTE: -A permission level of [Developer](../../permissions.md), or higher, is required -to import issues. +You must have at least the Developer role for a project to import issues. ## Prepare for the import diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index ecf35fc4dcf..e7bb5ad4eeb 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -6,9 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Design Management **(FREE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in GitLab Premium 12.2. -> - Support for SVGs [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12771) in GitLab Premium 12.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Free in 13.0. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in GitLab 12.2. +> - Support for SVGs [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12771) in GitLab 12.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. Design Management allows you to upload design assets (including wireframes and mockups) to GitLab issues and keep them stored in a single place, accessed by the Design @@ -84,10 +84,10 @@ You can find to the **Design Management** section in the issue description: ## Adding designs -> - Drag and drop uploads [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab Premium 12.9. -> - New version creation on upload [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab Premium 12.9. +> - Drag and drop uploads [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab 12.9. +> - New version creation on upload [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab 12.9. > - Copy and paste uploads [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202634) in GitLab 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Free in 13.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. To upload Design images, drag files from your computer and drop them in the Design Management section, or select **click to upload** to select images from your file browser: @@ -142,9 +142,9 @@ to help summarize changes between versions. ### Exploring designs by zooming -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13217) in GitLab Premium 12.7. -> - Drag to move a zoomed image [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197324) in GitLab 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Free in 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13217) in GitLab 12.7. +> - Ability to drag a zoomed image to move it [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197324) in GitLab 12.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. Designs can be explored in greater detail by zooming in and out of the image. Control the amount of zoom with the `+` and `-` buttons at the bottom of the image. @@ -155,8 +155,8 @@ While zoomed in, you can drag the image to move around it. ## Deleting designs -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11089) in GitLab Premium 12.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Free in 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11089) in GitLab 12.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. There are two ways to delete designs: manually delete them individually, or select a few of them to delete at once, @@ -190,8 +190,8 @@ You can change the order of designs by dragging them to a new position. ## Starting discussions on designs -> - Adjusting a pin's position [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in GitLab Premium 12.8. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Free in 13.0. +> - Adjusting a pin's position [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) adjusting a pin's position in GitLab 12.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) from GitLab Premium to GitLab Free in 13.0. When a design is uploaded, you can start a discussion by selecting the image on the exact location you would like the discussion to be focused on. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 2c20ccdcee0..2630052d806 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Due dates **(FREE)** Due dates can be used in [issues](index.md) to keep track of deadlines and make sure features are -shipped on time. Users need at least the Reporter [role](../../permissions.md) +shipped on time. Users need at least the Reporter role to be able to edit the due date. All users with permission to view the issue can view the due date. diff --git a/doc/user/project/issues/issue_weight.md b/doc/user/project/issues/issue_weight.md index 8f17f399cb0..756fe9699f1 100644 --- a/doc/user/project/issues/issue_weight.md +++ b/doc/user/project/issues/issue_weight.md @@ -15,10 +15,8 @@ value, or complexity a given issue has or costs. You can set the weight of an issue during its creation, by changing the value in the dropdown menu. You can set it to a non-negative integer -value from 0, 1, 2, and so on. (The database stores a 4-byte value, so the -upper bound is essentially limitless.) -You can remove weight from an issue -as well. +value from 0, 1, 2, and so on. +You can remove weight from an issue as well. This value appears on the right sidebar of an individual issue, as well as in the issues page next to a weight icon (**{weight}**). diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index d120df82dbf..155d6260a5c 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -29,7 +29,7 @@ You can create an issue in many ways in GitLab: Prerequisites: -- You must have at least the [Guest role](../../permissions.md) for the project. +- You must have at least the Guest role for the project. To create an issue: @@ -52,7 +52,7 @@ to the projects in the group. Prerequisites: -- You must have at least the [Guest role](../../permissions.md) for the project in the group. +- You must have at least the Guest role for the project in the group. To create an issue from a group: @@ -78,7 +78,7 @@ You can create a new issue from an existing one. The two issues can then be mark Prerequisites: -- You must have at least the [Guest role](../../permissions.md) for the project. +- You must have at least the Guest role for the project. To create an issue from another issue: @@ -98,7 +98,7 @@ You can create a new issue from an [issue board](../issue_board.md). Prerequisites: -- You must have at least the [Guest role](../../permissions.md) for the project. +- You must have at least the Guest role for the project. To create an issue from a project issue board: @@ -133,7 +133,7 @@ Prerequisites: - Your GitLab instance must have [incoming email](../../../administration/incoming_email.md) configured. - There must be at least one issue in the issue list. -- You must have at least the [Guest role](../../permissions.md) for the project. +- You must have at least the Guest role for the project. To email an issue to a project: @@ -224,7 +224,7 @@ You can edit an issue's title and description. Prerequisites: -- You must have at least the [Reporter role](../../permissions.md) for the project. +- You must have at least the Reporter role for the project, be the author of the issue, or be assigned to the issue. To edit an issue: @@ -242,7 +242,7 @@ You can edit multiple issues at a time when you're in a project. Prerequisites: -- You must have at least the [Reporter role](../../permissions.md) for the project. +- You must have at least the Reporter role for the project. To edit multiple issues at the same time: @@ -275,7 +275,7 @@ You can edit multiple issues across multiple projects when you're in a group. Prerequisites: -- You must have at least the [Reporter role](../../permissions.md) for a group. +- You must have at least the Reporter role for a group. To edit multiple issues at the same time: @@ -300,9 +300,11 @@ When you move an issue, it's closed and copied to the target project. The original issue is not deleted. A system note, which indicates where it came from and went to, is added to both issues. +Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. + Prerequisites: -- You must have at least the [Reporter role](../../permissions.md) for the project. +- You must have at least the Reporter role for the project. To move an issue: @@ -317,7 +319,7 @@ You can move all open issues from one project to another. Prerequisites: -- You must have at least the [Reporter role](../../permissions.md) for the project. +- You must have access to the Rails console of the GitLab instance. To do it: @@ -351,7 +353,7 @@ The issue is marked as closed but is not deleted. Prerequisites: -- You must have at least the [Reporter role](../../permissions.md) for the project. +- You must have at least the Reporter role for the project, be the author of the issue, or be assigned to the issue. To close an issue, you can do the following: @@ -364,7 +366,7 @@ To close an issue, you can do the following: Prerequisites: -- You must have at least the [Reporter role](../../permissions.md) for the project. +- You must have at least the Reporter role for the project, be the author of the issue, or be assigned to the issue. To reopen a closed issue, at the top of the issue, select **Reopen issue**. A reopened issue is no different from any other open issue. @@ -440,7 +442,7 @@ in the [project's settings](../settings/index.md). Prerequisites: -- You must have at least the [Maintainer role](../../permissions.md) for the project. +- You must have at least the Maintainer role for the project. To disable automatic issue closing: @@ -466,7 +468,7 @@ Merge requests in other projects can still close another project's issues. Prerequisites: -- You must have the [administrator access level](../../../administration/index.md) for your GitLab instance. +- You must have [administrator access](../../../administration/index.md) to your GitLab instance. To change the default issue closing pattern, edit the [`gitlab.rb` or `gitlab.yml` file](../../../administration/issue_closing_pattern.md) @@ -476,7 +478,7 @@ of your installation. Prerequisites: -- You must be the issue author or have at least the [Reporter role](../../permissions.md) for the project. +- You must be the issue author or have at least the Reporter role for the project, be the author of the issue, or be assigned to the issue. To change issue type: @@ -494,7 +496,7 @@ To change issue type: Prerequisites: -- You must have the [Owner role](../../permissions.md) for a project. +- You must have the Owner role for a project. To delete an issue: @@ -508,9 +510,9 @@ Alternatively: ## Promote an issue to an epic **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in GitLab Ultimate 11.6. -> - Moved to GitLab Premium in 12.8. -> - Promoting issues to epics via the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233974) in GitLab Premium 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in GitLab 11.6. +> - Moved from GitLab Ultimate to GitLab Premium in 12.8. +> - Promoting issues to epics via the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233974) in GitLab 13.6. You can promote an issue to an [epic](../../group/epics/index.md) in the immediate parent group. @@ -622,7 +624,7 @@ This status marks issues as progressing as planned or needing attention to keep Prerequisites: -- You must have at least the [Reporter role](../../permissions.md) for the project. +- You must have at least the Reporter role for the project. To edit health status of an issue: diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index 98e940b6b51..f957d701a3b 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Multiple Assignees for Issues **(PREMIUM)** -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. In large teams, where there is shared ownership of an issue, it can be difficult to track who is working on it, who already completed their contributions, who diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 8a2a104c54d..f83ebc5e8a8 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -6,10 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Linked issues **(FREE)** -> The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.4. +> The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) from GitLab Premium to GitLab Free in 13.4. Linked issues are a bi-directional relationship between any two issues and appear in a block below -the issue description. Issues can be across groups and projects. +the issue description. You can link issues in different projects. The relationship only shows up in the UI if the user can see both issues. When you try to close an issue that has open blockers, a warning is displayed. @@ -23,13 +23,18 @@ To manage linked issues through our API, visit the [issue links API documentatio > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/34239) to warn when attempting to close an issue that is blocked by others in GitLab 13.0. > When you try to close an issue with open blockers, you see a warning that you can dismiss. -1. Link one issue to another by selecting the add linked issue button (**{plus}**) in the - **Linked issues** section of an issue. +Prerequisites: +- You must have at least the Reporter role for both projects. + +To link one issue to another: + +1. In the **Linked issues** section of an issue, + select the add linked issue button (**{plus}**). 1. Select the relationship between the two issues. Either: - **relates to** - - **blocks** **(PREMIUM)** - - **is blocked by** **(PREMIUM)** + - **[blocks](#blocking-issues)** + - **[is blocked by](#blocking-issues)** 1. Input the issue number or paste in the full URL of the issue.  @@ -64,3 +69,10 @@ Due to the bi-directional relationship, the relationship no longer appears in ei  Access our [permissions](../../permissions.md) page for more information. + +## Blocking issues **(PREMIUM)** + +When you [add a linked issue](#add-a-linked-issue), you can show that it **blocks** or +**is blocked by** another issue. + +Issues that block other issues have an icon (**{issue-block}**) shown in the issue lists and [boards](../issue_board.md). diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 0340f15c25c..329f65bfacd 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -27,7 +27,7 @@ The available sorting options can change based on the context of the list. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34247/) in GitLab 13.7. When you sort by **Blocking**, the issue list changes to sort descending by the -number of issues each issue is blocking. +number of issues each issue is [blocking](related_issues.md#blocking-issues). ## Sorting by created date diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 2dc29f5d725..8be2ade3f2f 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -12,20 +12,30 @@ Each member gets a role, which determines what they can do in the project. ## Add users to a project +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal window [with a flag](../../feature_flags.md). Disabled by default. +> - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 14.8. + +FLAG: +On self-managed GitLab, by default the modal window feature is available. +To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) +named `invite_members_group_modal`. +On GitLab.com, this feature is available. + Add users to a project so they become members and have permission to perform actions. Prerequisite: -- You must have the [Maintainer or Owner role](../../permissions.md). +- You must have the Maintainer or Owner role. To add a user to a project: -1. Go to your project and select **Project information > Members**. -1. On the **Invite member** tab, under **GitLab member or Email address**, type the username or email address. - In GitLab 13.11 and later, you can [replace this form with a modal window](#add-a-member-modal-window). -1. Select a [role](../../permissions.md). -1. Optional. Choose an expiration date. On that date, the user can no longer access the project. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Members**. +1. Select **Invite members**. +1. Enter an email address and select a [role](../../permissions.md). +1. Optional. Select an **Access expiration date**. + On that date, the user can no longer access the project. 1. Select **Invite**. If the user has a GitLab account, they are added to the members list. @@ -40,6 +50,15 @@ using the email address the invitation was sent to. ## Add groups to a project +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal window [with a flag](../../feature_flags.md). Disabled by default. +> - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 14.8. + +FLAG: +On self-managed GitLab, by default the modal window feature is available. +To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) +named `invite_members_group_modal`. +On GitLab.com, this feature is available. + When you add a group to a project, each user in the group gets access to the project. Each user's access is based on: @@ -48,15 +67,16 @@ Each user's access is based on: Prerequisite: -- You must have the [Maintainer or Owner role](../../permissions.md). +- You must have the Maintainer or Owner role. To add groups to a project: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Members**. -1. On the **Invite group** tab, under **Select a group to invite**, choose a group. -1. Select the highest max [role](../../permissions.md) for users in the group. -1. Optional. Choose an expiration date. On that date, the user can no longer access the project. +1. Select **Invite a group**. +1. Select a group. +1. Select the highest [role](../../permissions.md) for users in the group. +1. Optional. Select an **Access expiration date**. On that date, the group can no longer access the project. 1. Select **Invite**. The members of the group are not displayed on the **Members** tab. @@ -72,7 +92,7 @@ retain the same permissions as the project you import them from. Prerequisite: -- You must have the [Maintainer or Owner role](../../permissions.md). +- You must have the Maintainer or Owner role. To import users: @@ -111,7 +131,7 @@ group itself. Prerequisites: -- You must have the [Owner role](../../permissions.md). +- You must have the Owner role. - Optional. Unassign the member from all issues and merge requests that are assigned to them. @@ -203,44 +223,3 @@ Prerequisite: ## Share a project with a group Instead of adding users one by one, you can [share a project with an entire group](share_project_with_groups.md). - -### Add a member modal window - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11. -> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - Enabled on GitLab.com. -> - Recommended for production use. -> - Replaces the existing form with buttons to open a modal window. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-modal-window). - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -In GitLab 13.11, you can optionally replace the form to add a member with a modal window. -To add a member after enabling this feature: - -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Members**. -1. Select **Invite members**. -1. Enter an email address and select a role. -1. Optional. Select an **Access expiration date**. -1. Select **Invite**. - -### Enable or disable modal window **(FREE SELF)** - -The modal window for adding a member is under development and is 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(:invite_members_group_modal) -``` - -To disable it: - -```ruby -Feature.disable(:invite_members_group_modal) -``` diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index e67af8dc936..612f499bb65 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -1,8 +1,7 @@ --- stage: Verify -group: Testing +group: Pipeline Insights info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, howto --- # Accessibility testing **(FREE)** diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index b10d6597c1e..5826ebcab49 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -50,7 +50,7 @@ You can push directly to the branch of the forked repository if: - The author of the merge request has enabled contributions from upstream members. -- You have at least the [Developer role](../../permissions.md) in the +- You have at least the Developer role in the upstream project. In the following example: diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index dddd3925dbb..e940426dc67 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -8,7 +8,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/appro # Merge request approvals **(FREE)** -> Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0. +> Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in GitLab 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0. You can configure your merge requests so that they must be approved before they can be merged. While [GitLab Free](https://about.gitlab.com/pricing/) allows @@ -89,7 +89,7 @@ a merge request from merging without approval. ## Required approvals **(PREMIUM)** -> Moved to [GitLab Premium](https://about.gitlab.com/pricing/) in 13.9. +> Moved to GitLab Premium in 13.9. Required approvals enforce code reviews by the number and type of users you specify. Without the approvals, the work cannot merge. Required approvals enable multiple use cases: @@ -103,7 +103,7 @@ Without the approvals, the work cannot merge. Required approvals enable multiple to determine who should review the work. - Require an [approval before merging code that causes test coverage to decline](../../../../ci/pipelines/settings.md#coverage-check-approval-rule) - [Require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests) - before merging code that could introduce a vulnerability. **(ULTIMATE)** + before merging code that could introduce a vulnerability. ## Related topics diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 129010010e7..fa447ea35af 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -76,9 +76,9 @@ To edit a merge request approval rule: select **{remove}** **Remove**. 1. Select **Update approval rule**. -## Add multiple approval rules **(PREMIUM)** +## Add multiple approval rules -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in GitLab Premium 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in GitLab 11.10. In GitLab Premium and higher tiers, you can enforce multiple approval rules on a merge request, and multiple default approval rules for a project. If your tier @@ -127,8 +127,8 @@ users were not explicitly listed in the approval rules. ### Group approvers You can add a group of users as approvers, but those users count as approvers only if -they have direct membership to the group. In the future, group approvers may be -restricted to only groups [with share access to the project](https://gitlab.com/gitlab-org/gitlab/-/issues/2048). +they have direct membership to the group. Group approvers are +restricted to only groups [with share access to the project](../../members/share_project_with_groups.md). A user's membership in an approvers group affects their individual ability to approve in these ways: @@ -143,7 +143,7 @@ approve in these ways: [**Prevent committers approval**](settings.md#prevent-approvals-by-users-who-add-commits) project setting. -### Code owners as eligible approvers **(PREMIUM)** +### Code owners as eligible approvers > Moved to GitLab Premium in 13.9. @@ -158,14 +158,14 @@ become eligible approvers in the project. To enable this merge request approval You can also [require code owner approval](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch) -for protected branches. **(PREMIUM)** +for protected branches. -## Merge request approval segregation of duties **(PREMIUM)** +## Merge request approval segregation of duties > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. > - Moved to GitLab Premium in 13.9. -You may have to grant users with the Reporter [role](../../../permissions.md#project-members-permissions) +You may have to grant users with the Reporter role permission to approve merge requests before they can merge to a protected branch. Some users (like managers) may not need permission to push or merge code, but still need oversight on proposed work. To enable approval permissions for these users without @@ -202,7 +202,7 @@ on a merge request, you can either add or remove approvers: Administrators can change the [merge request approvals settings](settings.md#prevent-editing-approval-rules-in-merge-requests) to prevent users from overriding approval rules for merge requests. -## Configure optional approval rules **(PREMIUM)** +## Configure optional approval rules Merge request approvals can be optional for projects where approvals are appreciated, but not required. To make an approval rule optional: @@ -211,9 +211,9 @@ appreciated, but not required. To make an approval rule optional: - Use the [Merge requests approvals API](../../../../api/merge_request_approvals.md#update-merge-request-level-rule) to set the `approvals_required` attribute to `0`. -## Approvals for protected branches **(PREMIUM)** +## Approvals for protected branches -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in GitLab Premium 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in GitLab 12.8. Approval rules are often relevant only to specific branches, like your [default branch](../../repository/branches/default.md). To configure an @@ -229,3 +229,16 @@ approval rule for certain branches:  1. To enable this configuration, read [Code Owner's approvals for protected branches](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch). + +## Troubleshooting + +### Approval rule name can't be blank + +As a workaround for this validation error, you can delete the approval rule through +the API. + +1. [GET a project-level rule](../../../../api/merge_request_approvals.md#get-a-single-project-level-rule). +1. [DELETE the rule](../../../../api/merge_request_approvals.md#delete-project-level-rule). + +For more information about this validation error, read +[issue 285129](https://gitlab.com/gitlab-org/gitlab/-/issues/285129). diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index 4ae59a76a9a..37ecc1b8d06 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -16,7 +16,7 @@ There are two main ways to have a merge request flow with GitLab: With the protected branch flow everybody works within the same GitLab project. -The project maintainers get the [Maintainer role](../../permissions.md) and the regular developers +The project maintainers get the Maintainer role and the regular developers get the Developer role. Maintainers mark the authoritative branches as 'Protected'. @@ -25,7 +25,7 @@ Developers push feature branches to the project and create merge requests to have their feature branches reviewed and merged into one of the protected branches. -By default, only users with the [Maintainer role](../../permissions.md) can merge changes into a +By default, only users with the Maintainer role can merge changes into a protected branch. **Advantages** @@ -39,7 +39,7 @@ protected branch. ## Forking workflow -With the forking workflow, maintainers get the [Maintainer role](../../permissions.md) and regular +With the forking workflow, maintainers get the Maintainer role and regular developers get the Reporter role on the authoritative repository, which prohibits them from pushing any changes to it. diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 6668e1736cf..9c7d9e2bf19 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -1,13 +1,12 @@ --- stage: Verify -group: Testing +group: Pipeline Insights info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, howto --- # Browser Performance Testing **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3507) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3507) in GitLab 10.3. If your application offers a web interface and you're using [GitLab CI/CD](../../../ci/index.md), you can quickly determine the rendering performance diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index d348c00bdc2..8796ea0635b 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -5,149 +5,151 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Changes tab in merge requests **(FREE)** +# Changes in merge requests **(FREE)** -The **Changes** tab on a [merge request](index.md), below the main merge request details and next to the discussion tab, -shows the changes to files between branches or commits. This view of changes to a -file is also known as a **diff**. By default, the diff view compares the file in the -merge request branch and the file in the target branch. +A [merge request](index.md) proposes a set of changes to files in a branch in your repository. These +changes are shown as a _diff_ (difference) between the current state and the proposed +changes. -The diff view includes the following: +By default, the diff view compares the versions of files in the merge request source branch +to the files in the target branch, and shows only the parts of a file that have changed. -- The file's name and path. -- The number of lines added and deleted. -- Buttons for the following options: - - Toggle comments for this file; useful for inline reviews. - - Edit the file in the merge request's branch. - - Show full file, in case you want to look at the changes in context with the rest of the file. - - View file at the current commit. - - Preview the changes with [Review Apps](../../../ci/review_apps/index.md). -- The changed lines, with the specific changes highlighted. + - +## Show all changes in a merge request -## Merge request diff file navigation +To view the diff of changes included in a merge request: -When reviewing changes in the **Changes** tab, the diff can be navigated using -the file tree or file list. As you scroll through large diffs with many -changes, you can quickly jump to any changed file using the file tree or file -list. +1. Go to your merge request. +1. Below the merge request title, select **Changes**. +1. If the merge request changes many files, you can jump directly to a specific file: + 1. Select **Show file browser** (**{file-tree}**) to display the file tree. + 1. Select the file you want to view. + 1. To hide the file browser, select **Show file browser** again. - +In [GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/issues/232820) and later, files +with many changes are collapsed to improve performance. GitLab displays the message: +**Some changes are not shown**. To view the changes for that file, select **Expand file**. -## Collapsed files in the Changes view +## Show one file at a time -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232820) in GitLab 13.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229848) in GitLab 13.7. -When you review changes in the **Changes** tab, files with a large number of changes are collapsed -to improve performance. When files are collapsed, a warning appears at the top of the changes. -Select **Expand file** on any file to view the changes for that file. +For larger merge requests, you can review one file at a time. You can change this setting +[temporarily in a merge request](#in-a-merge-request-show-only-one-file-at-a-time), or +so it [applies to all merge requests](#in-all-merge-requests-show-only-one-file-at-a-time). -## File-by-file diff navigation +### In a merge request, show only one file at a time -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229848) in GitLab 13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) in GitLab 13.7. + +To temporarily change your viewing preferences for a specific merge request: + +1. Go to your merge request, and below the merge request title, select **Changes**. +1. Select **Preferences** (**{settings}**). +1. Select or clear the **Show one file at a time** checkbox. -For larger merge requests, consider reviewing one file at a time. To enable this feature: +This change overrides your choice in your user preferences. It persists until you +clear your browser's cookies or change this behavior again. + +### In all merge requests, show only one file at a time + +To view one file at a time for all of your merge requests: 1. In the top-right corner, select your avatar. 1. Select **Preferences**. -1. Scroll to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**. +1. Scroll to the **Behavior** section and select the **Show one file at a time on merge request's Changes tab** checkbox. 1. Select **Save changes**. -After you enable this setting, GitLab displays only one file at a time in the **Changes** tab when you review merge requests. You can select **Prev** and **Next** to view other changed files. +After you enable this setting, GitLab displays only one file at a time when you review +merge requests. To view other changed files, either: + +- Scroll to the end of the file and select either **Prev** or **Next**. +- Select **Show file browser** (**{file-tree}**) and select another file to view. + +## Compare changes inline + +You can view the changes inline: - +1. Go to your merge request, and below the title, select **Changes**. +1. Select **Preferences** (**{settings}**). +1. In the **Compare changes** area, select **Inline**. -In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) and later, if you want to change -this behavior, you can do so from your **User preferences** (as explained above) or directly in a -merge request: +The changes are displayed after the original text. -1. Go to the merge request's **Changes** tab. -1. Select the cog icon (**{settings}**) to reveal the merge request's settings dropdown. -1. Select or clear the checkbox **Show one file at a time** to change the setting accordingly. + -This change overrides the choice you made in your user preferences and persists until you clear your -browser's cookies or change this behavior again. +## Compare changes side-by-side -## Incrementally expand merge request diffs +Depending on the length of the changes in your merge request, you may find it +easier to view the changes inline, or side-by-side: -By default, the diff shows only the parts of a file which are changed. -To view more unchanged lines above or below a change select the -**Expand up** or **Expand down** icons. You can also select **Show unchanged lines** -to expand the entire file. +1. Go to your merge request, and below the title, select **Changes**. +1. Select **Preferences** (**{settings}**). +1. In the **Compare changes** area, select **Side-by-side**. - +The changes are displayed across from one another. -In GitLab [versions 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/205401), when viewing a -merge request's **Changes** tab, if a certain file was only renamed, you can expand it to see the -entire content by selecting **Show file contents**. + -## Ignore whitespace changes in Merge Request diff view +## Expand or collapse comments + +When reviewing code changes, you can hide inline comments: + +1. Go to your merge request, and below the title, select **Changes**. +1. Scroll to the file that contains the comments you want to hide. +1. Scroll to the line the comment is attached to, and select **Collapse** (**{collapse}**): +  + +To expand inline comments and show them again: + +1. Go to your merge request, and below the title, select **Changes**. +1. Scroll to the file that contains the collapsed comments you want to show. +1. Scroll to the line the comment is attached to, and select the user avatar: +  + +## Ignore whitespace changes Whitespace changes can make it more difficult to see the substantive changes in a merge request. You can choose to hide or show whitespace changes: -1. Go to your merge request, and select the **Changes** tab. -1. Above the list of changed files, select **(settings)** **Preferences** to - display the preferences menu. -1. Select or deselect **Show whitespace changes**: +1. Go to your merge request, and below the title, select **Changes**. +1. Before the list of changed files, select **Preferences** (**{settings}**). +1. Select or clear the **Show whitespace changes** checkbox:  ## Mark files as viewed -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9 behind a feature flag, enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9 [with a flag](../../../administration/feature_flags.md) named `local_file_reviews`. Enabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/296674) in GitLab 14.3. -When reviewing a merge request with many files multiple times, it may be useful to the reviewer -to focus on new changes and ignore the files that they have already reviewed and don't want to -see anymore unless they are changed again. +When reviewing a merge request with many files multiple times, you can ignore files +you've already reviewed. To hide files that haven't changed since your last review: -To mark a file as viewed: +1. Go to your merge request, and below the title, select **Changes**. +1. In the file's header, select the **Viewed** checkbox. -1. Go to the merge request's **Diffs** tab. -1. On the right-top of the file, locate the **Viewed** checkbox. -1. Select it to mark the file as viewed. +Files marked as viewed are not shown to you again unless either: -Once checked, the file remains marked for that reviewer unless there are newly introduced -changes to its content or the checkbox is unchecked. +- New changes are made to its content. +- You clear the **Viewed** checkbox. -## Show merge request conflicts in diff +## Show merge request conflicts in diff **(FREE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232484) in GitLab 13.5. -> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - Disabled on GitLab.com. -> - Not recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-merge-request-conflicts-in-diff). **(FREE SELF)** +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232484) in GitLab 13.5 [with a flag](../../../administration/feature_flags.md) named `display_merge_conflicts_in_diff`. Disabled by default. -This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](../../../administration/feature_flags.md#risks-when-enabling-features-still-in-development). -Refer to this feature's version history for more details. +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) +named `display_merge_conflicts_in_diff`. On GitLab.com, this feature is not available. +The feature is not ready for production use. To avoid displaying the changes that are already on target branch in the diff, we compare the merge request's source branch with HEAD of the target branch. When there are conflicts between the source and target branch, we show the -conflicts on the merge request diff as well: +conflicts on the merge request diff:  - -### Enable or disable merge request conflicts in diff **(FREE SELF)** - -Merge request conflicts in diff is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:display_merge_conflicts_in_diff) -``` - -To disable it: - -```ruby -Feature.disable(:display_merge_conflicts_in_diff) -``` diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 30d463efa69..d735ce0ef91 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -53,7 +53,7 @@ See also the Code Climate list of [Supported Languages for Maintainability](http ## Code Quality in diff view **(ULTIMATE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.11, disabled by default behind the `codequality_mr_diff` [feature flag](../../../administration/feature_flags.md). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in GitLab 13.11, disabled by default behind the `codequality_mr_diff` [feature flag](../../../administration/feature_flags.md). > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 13.12. > - [Disabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) in GitLab 14.0 due to [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/334116). > - [Inline annotation added](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 14.1. @@ -248,9 +248,9 @@ This can be done: ### Using with merge request pipelines The configuration provided by the Code Quality template does not let the `code_quality` job -run on [pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md). +run on [merge request pipelines](../../../ci/pipelines/merge_request_pipelines.md). -If pipelines for merge requests is enabled, the `code_quality:rules` must be redefined. +If merge request pipelines is enabled, the `code_quality:rules` must be redefined. The template has these [`rules`](../../../ci/yaml/index.md#rules) for the `code quality` job: @@ -379,7 +379,7 @@ at the beginning of the file. ## Code Quality reports **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21527) in GitLab Premium 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21527) in GitLab 12.9.  @@ -392,7 +392,7 @@ After the Code Quality job completes: [downloadable artifact](../../../ci/pipelines/job_artifacts.md#download-job-artifacts) for the `code_quality` job. - The full list of code quality violations generated by a pipeline is shown in the - Code Quality tab of the Pipeline Details page. **(PREMIUM)** + Code Quality tab of the Pipeline Details page. ## Generate an HTML report @@ -591,3 +591,22 @@ plugins: If your merge requests do not show any code quality changes when using a custom tool, ensure that the line property is an `integer`. + +### Code Quality CI job with Code Climate plugins enabled fails with error "engine <plugin_name> ran for 900 seconds and was killed" + +If you enabled any of the Code Climate plugins, and the Code Quality CI job fails with the error below, +it's likely the job takes longer than the default timeout of 900 seconds. + +```shell +error: (CC::CLI::Analyze::EngineFailure) engine pmd ran for 900 seconds and was killed +Could not analyze code quality for the repository at /code +``` + +To work around this problem, set `TIMEOUT_SECONDS` to a higher value in your `.gitlab.-ci.yml` file. + +For example: + +```yaml +variables: + TIMEOUT_SECONDS: 3600 +``` diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md index 3d3032bb193..0014c1ba994 100644 --- a/doc/user/project/merge_requests/commits.md +++ b/doc/user/project/merge_requests/commits.md @@ -29,21 +29,17 @@ To seamlessly navigate among commits in a merge request: ## View merge request commits in context -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29274) in GitLab 13.12. -> - [Deployed behind a feature flag](../../feature_flags.md), enabled by default. -> - Disabled on GitLab.com. -> - Not recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-viewing-merge-request-commits-in-context). **(FREE SELF)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29274) in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `context_commits`. Enabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) in GitLab 14.8. WARNING: -This feature is in [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) +This feature is in [beta](../../../policy/alpha-beta-support.md#beta-features) and is [incomplete](https://gitlab.com/groups/gitlab-org/-/epics/1192). -Previously merged commits can be added, but they can't be removed due to -[this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/325538). -This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](../../../administration/feature_flags.md#risks-when-enabling-features-still-in-development). -Refer to this feature's version history for more details. +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, +ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `context_commits`. +On GitLab.com, this feature is available. When reviewing a merge request, it helps to have more context about the changes made. That includes unchanged lines in unchanged files, and previous commits @@ -66,22 +62,3 @@ To view the changes done on those previously merged commits: 1. Scroll to **(file-tree)** **Compare** and select **previously merged commits**:  - -### Enable or disable viewing merge request commits in context **(FREE SELF)** - -Viewing merge request commits in context 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(:context_commits) -``` - -To disable it: - -```ruby -Feature.disable(:context_commits) -``` diff --git a/doc/user/project/merge_requests/confidential.md b/doc/user/project/merge_requests/confidential.md index 10c63421876..6900880417f 100644 --- a/doc/user/project/merge_requests/confidential.md +++ b/doc/user/project/merge_requests/confidential.md @@ -4,7 +4,7 @@ group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Merge requests for confidential issues +# Merge requests for confidential issues **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58583) in GitLab 12.1. diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index a91679ffd63..637b682d603 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -17,7 +17,8 @@ the **Merge** button until you remove the **Draft** flag: ## Mark merge requests as drafts -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. Support for using **WIP** is scheduled for removal in GitLab 14.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32692) in GitLab 13.2, Work-In-Progress (WIP) merge requests were renamed to **Draft**. +> - [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/228685) all support for using **WIP** in GitLab 14.8. > - **Mark as draft** and **Mark as ready** buttons [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227421) in GitLab 13.5. There are several ways to flag a merge request as a draft: @@ -35,16 +36,12 @@ There are several ways to flag a merge request as a draft: is not a toggle, and adding this text again in a later commit doesn't mark the merge request as ready. -WARNING: -Adding `WIP:` to the start of the merge request's title still marks a merge request -as a draft. This feature is scheduled for removal in GitLab 14.0. Use `Draft:` instead. - ## Mark merge requests as ready When a merge request is ready to be merged, you can remove the `Draft` flag in several ways: - **Viewing a merge request**: In the top right corner of the merge request, click **Mark as ready**. - Users with [Developer or greater permissions](../../permissions.md) + Users with at least the Developer role can also scroll to the bottom of the merge request description and click **Mark as ready**:  @@ -79,11 +76,11 @@ draft merge requests: ## Pipelines for drafts -When the [pipelines for merged results](../../../ci/pipelines/pipelines_for_merged_results.md) +When the [merged results pipelines](../../../ci/pipelines/merged_results_pipelines.md) feature is enabled, draft merge requests run [merge request pipelines](../../../ci/pipelines/merge_request_pipelines.md) only. -To run pipelines for merged results, you must +To run merged results pipelines, you must [mark the merge request as ready](#mark-merge-requests-as-ready). <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/fail_fast_testing.md b/doc/user/project/merge_requests/fail_fast_testing.md index 3cb50195f5a..355661516a7 100644 --- a/doc/user/project/merge_requests/fail_fast_testing.md +++ b/doc/user/project/merge_requests/fail_fast_testing.md @@ -1,8 +1,7 @@ --- stage: Verify -group: Testing +group: Pipeline Insights info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, howto --- # Fail Fast Testing **(PREMIUM)** @@ -42,8 +41,8 @@ This template requires: - A project built in Rails that uses RSpec for testing. - CI/CD configured to: - Use a Docker image with Ruby available. - - Use [Pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md#prerequisites) -- [Pipelines for Merged Results](../../../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results) + - Use [Merge request pipelines](../../../ci/pipelines/merge_request_pipelines.md#prerequisites) +- [Merged results pipelines](../../../ci/pipelines/merged_results_pipelines.md#enable-merged-results-pipelines) enabled in the project settings. - A Docker image with Ruby available. The template uses `image: ruby:2.6` by default, but you [can override](../../../ci/yaml/includes.md#override-included-configuration-values) this. diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index ec509f58723..8699a42dd5d 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -56,7 +56,7 @@ request's page at the top-right side, or by using - [Assign](#assignee) the merge request to a colleague for review. With [multiple assignees](#multiple-assignees), you can assign it to more than one person at a time. - Set a [milestone](../milestones/index.md) to track time-sensitive changes. - Add [labels](../labels.md) to help contextualize and filter your merge requests over time. -- [Require approval](approvals/index.md#required-approvals) from your team. **(PREMIUM)** +- [Require approval](approvals/index.md#required-approvals) from your team. - [Close issues automatically](#merge-requests-to-close-issues) when they are merged. - Enable the [delete source branch when merge request is accepted](#deleting-the-source-branch) option to keep your repository clean. - Enable the [squash commits when merge request is accepted](squash_and_merge.md) option to combine all the commits into one before merging, thus keep a clean commit history in your repository. @@ -66,7 +66,7 @@ After you have created the merge request, you can also: - [Discuss](../../discussions/index.md) your implementation with your team in the merge request thread. - [Perform inline code reviews](reviews/index.md). -- Add [merge request dependencies](merge_request_dependencies.md) to restrict it to be merged only when other merge requests have been merged. **(PREMIUM)** +- Add [merge request dependencies](merge_request_dependencies.md) to restrict it to be merged only when other merge requests have been merged. - Preview continuous integration [pipelines on the merge request widget](widgets.md). - Preview how your changes look directly on your deployed application with [Review Apps](widgets.md#live-preview-with-review-apps). - [Allow collaboration on merge requests across forks](allow_collaboration.md). @@ -162,7 +162,7 @@ enabled by default for all new merge requests, enable it in the This option is also visible in an existing merge request next to the merge request button and can be selected or deselected before merging. -It is only visible to users with the [Maintainer role](../../permissions.md) +It is only visible to users with the Maintainer role in the source project. If the user viewing the merge request does not have the correct diff --git a/doc/user/project/merge_requests/img/changes-inline_v14_8.png b/doc/user/project/merge_requests/img/changes-inline_v14_8.png Binary files differnew file mode 100644 index 00000000000..f3b6515283c --- /dev/null +++ b/doc/user/project/merge_requests/img/changes-inline_v14_8.png diff --git a/doc/user/project/merge_requests/img/changes-sidebyside_v14_8.png b/doc/user/project/merge_requests/img/changes-sidebyside_v14_8.png Binary files differnew file mode 100644 index 00000000000..981274dbb86 --- /dev/null +++ b/doc/user/project/merge_requests/img/changes-sidebyside_v14_8.png diff --git a/doc/user/project/merge_requests/img/collapse-comment_v14_8.png b/doc/user/project/merge_requests/img/collapse-comment_v14_8.png Binary files differnew file mode 100644 index 00000000000..93a802454f2 --- /dev/null +++ b/doc/user/project/merge_requests/img/collapse-comment_v14_8.png diff --git a/doc/user/project/merge_requests/img/expand-comment_v14_8.png b/doc/user/project/merge_requests/img/expand-comment_v14_8.png Binary files differnew file mode 100644 index 00000000000..a800eab83e9 --- /dev/null +++ b/doc/user/project/merge_requests/img/expand-comment_v14_8.png diff --git a/doc/user/project/merge_requests/img/file_by_file_v13_2.png b/doc/user/project/merge_requests/img/file_by_file_v13_2.png Binary files differdeleted file mode 100644 index e3114ebabad..00000000000 --- a/doc/user/project/merge_requests/img/file_by_file_v13_2.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png b/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png Binary files differdeleted file mode 100644 index e3a2ff7960c..00000000000 --- a/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png b/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png Binary files differdeleted file mode 100644 index 1cdac5ef573..00000000000 --- a/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/mr-diff-example_v14_8.png b/doc/user/project/merge_requests/img/mr-diff-example_v14_8.png Binary files differnew file mode 100644 index 00000000000..1984defde9a --- /dev/null +++ b/doc/user/project/merge_requests/img/mr-diff-example_v14_8.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 8222d696853..9872bd2e936 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -94,7 +94,7 @@ You cannot undo the deletion of a merge request. To delete a merge request: -1. Sign in to GitLab as a user with the project Owner [role](../../permissions.md). +1. Sign in to GitLab as a user with the project Owner role. Only users with this role can delete merge requests in a project. 1. Go to the merge request you want to delete, and select **Edit**. 1. Scroll to the bottom of the page, and select **Delete merge request**. @@ -137,3 +137,4 @@ For a web developer writing a webpage for your company's website: - [Suggest code changes](reviews/suggestions.md) - [Commits](commits.md) - [CI/CD pipelines](../../../ci/index.md) +- [Push options](../push_options.md) for merge requests diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 40859c6b572..cc4ad186771 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -1,13 +1,12 @@ --- stage: Verify -group: Testing +group: Pipeline Insights info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, howto --- # Load Performance Testing **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10683) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10683) in GitLab 13.2. With Load Performance Testing, you can test the impact of any pending code changes to your application's backend in [GitLab CI/CD](../../../ci/index.md). diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index aace1f58c62..6bfef6ab134 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -7,9 +7,9 @@ type: reference, concepts # Merge request dependencies **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9688) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17291) from "Cross-project dependencies" to "Merge request dependencies" in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. -> - Intra-project MR dependencies were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16799) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9688) in GitLab 12.2. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17291) from "Cross-project dependencies" to "Merge request dependencies" in GitLab 12.4. +> - Intra-project MR dependencies were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16799) in GitLab 12.4. Merge request dependencies allows a required order of merging between merge requests to be expressed. If a merge request "depends on" another, diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index c34a8116625..280ae07b401 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -23,8 +23,8 @@ review merge requests in Visual Studio Code. ## Review a merge request -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in GitLab Premium 11.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/28154) to GitLab Free in 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in GitLab 11.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/28154) from GitLab Premium to GitLab Free in 13.1. When you review a merge request, you can create comments that are visible only to you. When you're ready, you can publish them together in a single action. @@ -160,7 +160,7 @@ Multiline comments display the comment's line numbers above the body of the comm ## Bulk edit merge requests at the project level -Users with permission level of [Developer or higher](../../../permissions.md) can manage merge requests. +Users with at least the Developer role can manage merge requests. When bulk-editing merge requests in a project, you can edit the following attributes: @@ -179,11 +179,11 @@ To update multiple project merge requests at the same time: 1. Select the appropriate fields and their values from the sidebar. 1. Click **Update all**. -## Bulk edit merge requests at the group level +## Bulk edit merge requests at the group level **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12719) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12719) in GitLab 12.2. -Users with permission level of [Developer or higher](../../../permissions.md) can manage merge requests. +Users with at least the Developer role can manage merge requests. When bulk editing merge requests in a group, you can edit the following attributes: diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 1b2a35ba139..9868f2619ba 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -42,7 +42,7 @@ After the author applies a suggestion: 1. The suggestion is marked as **Applied**. 1. The thread is resolved. 1. GitLab creates a new commit with the changes. -1. If the user has the [Developer role](../../../permissions.md), GitLab pushes +1. If the user has the Developer role, GitLab pushes the suggested change directly into the codebase in the merge request's branch. ## Multi-line suggestions @@ -114,7 +114,7 @@ introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381). ## Batch suggestions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) with a flag named `batch_suggestions`, disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](../../../../policy/alpha-beta-support.md#alpha-features) with a flag named `batch_suggestions`, disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. [Feature flag `batch_suggestions`](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) removed. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) custom commit messages for batch suggestions in GitLab 14.4. diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index f5ebfb3668c..a952c0550bc 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -28,6 +28,32 @@ You can configure merge request status checks for each individual project. These To learn more about use cases, feature discovery, and development timelines, see the [external status checks epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). +## Lifecycle + +External status checks have an **asynchronous** workflow. Merge requests emit a merge request webhook payload to an external service whenever: + +- The merge request is changed. For example, title or description. +- Code is pushed to the source branch of the merge request. +- A comment is made in the merge request discussion. + +```mermaid +sequenceDiagram + Merge request->>+External service: Merge request payload + External service-->>-Merge request: Status check response + Note over External service,Merge request: Response includes SHA at HEAD +``` + +When the payload is received, the external service can then run any required processes before posting its response back to the merge request [using the REST API](../../../api/status_checks.md#set-status-of-an-external-status-check). + +Merge requests return a `409 Conflict` error to any responses that do not refer to the current `HEAD` of the source branch. As a result, it's safe for the external service to process and respond to out-of-date commits. + +External status checks have the following states: + +- `pending` - The default state. No response can been received by the merge request from the external service. +- `response received` - A response from the external service has been received and approved by it. + +Support for adding a `failed` state is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/338827). + ## View the status checks on a project Within each project's settings, you can see a list of status checks added to the project: diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 1f84964c619..bd54eda42f5 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -1,8 +1,7 @@ --- stage: Verify -group: Testing +group: Pipeline Insights info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, howto --- # Test coverage visualization **(FREE)** @@ -40,6 +39,7 @@ Other coverage analysis frameworks support the format out of the box, for exampl - [Istanbul](https://istanbul.js.org/docs/advanced/alternative-reporters/#cobertura) (JavaScript) - [Coverage.py](https://coverage.readthedocs.io/en/coverage-5.0.4/cmd.html#xml-reporting) (Python) +- [PHPUnit](https://github.com/sebastianbergmann/phpunit-documentation-english/blob/master/src/textui.rst#command-line-options) (PHP) Once configured, if you create a merge request that triggers a pipeline which collects coverage reports, the coverage is shown in the diff view. This includes reports @@ -52,6 +52,8 @@ from any job in any stage in the pipeline. The coverage displays for each line: Hovering over the coverage bar provides further information, such as the number of times the line was checked by tests. +Uploading a test coverage report does not enable [test coverage results in Merge Requests](../../../ci/pipelines/settings.md#add-test-coverage-results-to-a-merge-request-deprecated) or [code coverage history](../../../ci/pipelines/settings.md#view-code-coverage-history). You must configure these separately. + ### Limits A limit of 100 `<source>` nodes for Cobertura format XML files applies. If your Cobertura report exceeds @@ -133,6 +135,9 @@ The `source` is ignored if the path does not follow this pattern. The parser ass ## Example test coverage configurations +This section provides test coverage configuration examples for different programming languages. You can also see a working example in +the [`coverage-report`](https://gitlab.com/gitlab-org/ci-sample-projects/coverage-report/) demonstration project. + ### JavaScript example The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example uses [Mocha](https://mochajs.org/) @@ -236,7 +241,7 @@ run tests: image: python:3 script: - pip install pytest pytest-cov - - coverage run -m pytest + - coverage run -m pytest - coverage report - coverage xml artifacts: @@ -244,6 +249,42 @@ run tests: cobertura: coverage.xml ``` +### PHP example + +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for PHP uses [PHPUnit](https://phpunit.readthedocs.io/) +to collect test coverage data and generate the report. + +With a minimal [`phpunit.xml`](https://phpunit.readthedocs.io/en/9.5/configuration.html) file (you may reference +[this example repository](https://gitlab.com/yookoala/code-coverage-visualization-with-php/)), you can run the test and +generate the coverage xml: + +```yaml +run tests: + stage: test + image: php:latest + variables: + XDEBUG_MODE: coverage + before_script: + - apt-get update && apt-get -yq install git unzip zip libzip-dev zlib1g-dev + - docker-php-ext-install zip + - pecl install xdebug && docker-php-ext-enable xdebug + - php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" + - php composer-setup.php --install-dir=/usr/local/bin --filename=composer + - composer install + - composer require --dev phpunit/phpunit phpunit/php-code-coverage + script: + - php ./vendor/bin/phpunit --coverage-text --coverage-cobertura=coverage.cobertura.xml + artifacts: + reports: + cobertura: coverage.cobertura.xml +``` + +[Codeception](https://codeception.com/), through PHPUnit, also supports generating Cobertura report with +[`run`](https://codeception.com/docs/reference/Commands#run). The path for the generated file +depends on the `--coverage-cobertura` option and [`paths`](https://codeception.com/docs/reference/Configuration#paths) +configuration for the [unit test suite](https://codeception.com/docs/05-UnitTests). Configure `.gitlab-ci.yml` +to find Cobertura in the appropriate path. + ### C/C++ example The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for C/C++ with @@ -272,3 +313,62 @@ run tests: reports: cobertura: build/coverage.xml ``` + +### Go example + +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for Go uses: + +- [`go test`](https://go.dev/doc/tutorial/add-a-test) to run tests. +- [`gocover-cobertura`](https://github.com/t-yuki/gocover-cobertura) to convert Go's coverage profile into the Cobertura XML format. + +This example assumes that [Go modules](https://go.dev/ref/mod) are being used. +Using Go modules causes paths within the coverage profile to be prefixed with your +project's module identifier, which can be found in the `go.mod` file. This +prefix must be removed for GitLab to parse the Cobertura XML file correctly. You can use the following `sed` command to remove the prefix: + +```shell +sed -i 's;filename=\"<YOUR_MODULE_ID>/;filename=\";g' coverage.xml +``` + +Replace the `gitlab.com/my-group/my-project` placeholder in the following example with your own module identifier to make it work. + +```yaml +run tests: + stage: test + image: golang:1.17 + script: + - go install + - go test . -coverprofile=coverage.txt -covermode count + - go run github.com/t-yuki/gocover-cobertura < coverage.txt > coverage.xml + - sed -i 's;filename=\"gitlab.com/my-group/my-project/;filename=\";g' coverage.xml + artifacts: + reports: + cobertura: coverage.xml +``` + +### Ruby example + +The following [`.gitlab-ci.yml`](../../../ci/yaml/index.md) example for Ruby uses + +- [`rspec`](https://rspec.info/) to run tests. +- [`simplecov`](https://github.com/simplecov-ruby/simplecov) and [`simplecov-cobertura`](https://github.com/dashingrocket/simplecov-cobertura) + to record the coverage profile and create a report in the Cobertura XML format. + +This example assumes: + +- That [`bundler`](https://bundler.io/) is being used for dependency management. + The `rspec`, `simplecov` and `simplecov-cobertura` gems have been added to your `Gemfile`. +- The `CoberturaFormatter` has been added to your `SimpleCov.formatters` + configuration within the `spec_helper.rb` file. + +```yaml +run tests: + stage: test + image: ruby:3.1 + script: + - bundle install + - bundle exec rspec + artifacts: + reports: + cobertura: coverage/coverage.xml +``` diff --git a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md index 0a9a2a37bfe..741ac325cca 100644 --- a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md +++ b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md @@ -1,8 +1,7 @@ --- stage: Verify -group: Testing +group: Pipeline Insights info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: index description: "Test your code and display reports in merge requests" --- @@ -11,21 +10,21 @@ description: "Test your code and display reports in merge requests" GitLab has the ability to test the changes included in a feature branch and display reports or link to useful information directly from merge requests: -| Feature | Description | -|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [Accessibility Testing](accessibility_testing.md) | Automatically report A11y violations for changed pages in merge requests. | -| [Browser Performance Testing](browser_performance_testing.md) **(PREMIUM)** | Quickly determine the browser performance impact of pending code changes. | -| [Load Performance Testing](load_performance_testing.md) **(PREMIUM)** | Quickly determine the server performance impact of pending code changes. | -| [Code Quality](code_quality.md) | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. | -| [Display arbitrary job artifacts](../../../ci/yaml/index.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../../../ci/pipelines/job_artifacts.md) in merge requests. | -| [GitLab CI/CD](../../../ci/index.md) | Build, test, and deploy your code in a per-branch basis with built-in CI/CD. | -| [Unit test reports](../../../ci/unit_test_reports.md) | Configure your CI jobs to use Unit test reports, and let GitLab display a report on the merge request so that it's easier and faster to identify the failure without having to check the entire job log. | -| [License Compliance](../../compliance/license_compliance/index.md) **(ULTIMATE)** | Manage the licenses of your dependencies. | -| [Metrics Reports](../../../ci/metrics_reports.md) **(PREMIUM)** | Display the Metrics Report on the merge request so that it's fast and easy to identify changes to important metrics. | -| [Multi-Project pipelines](../../../ci/pipelines/multi_project_pipelines.md) **(PREMIUM)** | When you set up GitLab CI/CD across multiple projects, you can visualize the entire pipeline, including all cross-project interdependencies. | -| [Pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md) | Customize a specific pipeline structure for merge requests in order to speed the cycle up by running only important jobs. | -| [Pipeline Graphs](../../../ci/pipelines/index.md#visualize-pipelines) | View the status of pipelines within the merge request, including the deployment process. | -| [Test Coverage visualization](test_coverage_visualization.md) | See test coverage results for merge requests, within the file diff. | +| Feature | Description | +|----------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Accessibility Testing](accessibility_testing.md) | Automatically report A11y violations for changed pages in merge requests. | +| [Browser Performance Testing](browser_performance_testing.md) | Quickly determine the browser performance impact of pending code changes. | +| [Load Performance Testing](load_performance_testing.md) | Quickly determine the server performance impact of pending code changes. | +| [Code Quality](code_quality.md) | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. | +| [Display arbitrary job artifacts](../../../ci/yaml/index.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../../../ci/pipelines/job_artifacts.md) in merge requests. | +| [GitLab CI/CD](../../../ci/index.md) | Build, test, and deploy your code in a per-branch basis with built-in CI/CD. | +| [Unit test reports](../../../ci/unit_test_reports.md) | Configure your CI jobs to use Unit test reports, and let GitLab display a report on the merge request so that it's easier and faster to identify the failure without having to check the entire job log. | +| [License Compliance](../../compliance/license_compliance/index.md) | Manage the licenses of your dependencies. | +| [Metrics Reports](../../../ci/metrics_reports.md) | Display the Metrics Report on the merge request so that it's fast and easy to identify changes to important metrics. | +| [Multi-Project pipelines](../../../ci/pipelines/multi_project_pipelines.md) | When you set up GitLab CI/CD across multiple projects, you can visualize the entire pipeline, including all cross-project interdependencies. | +| [Merge request pipelines](../../../ci/pipelines/merge_request_pipelines.md) | Customize a specific pipeline structure for merge requests in order to speed the cycle up by running only important jobs. | +| [Pipeline Graphs](../../../ci/pipelines/index.md#visualize-pipelines) | View the status of pipelines within the merge request, including the deployment process. | +| [Test Coverage visualization](test_coverage_visualization.md) | See test coverage results for merge requests, within the file diff. | ## Security Reports **(ULTIMATE)** diff --git a/doc/user/project/milestones/burndown_and_burnup_charts.md b/doc/user/project/milestones/burndown_and_burnup_charts.md index 7c22b271ec2..05cc424e5ee 100644 --- a/doc/user/project/milestones/burndown_and_burnup_charts.md +++ b/doc/user/project/milestones/burndown_and_burnup_charts.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w  -## Burndown charts **(PREMIUM)** +## Burndown charts > - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6495) to GitLab 11.2 for group milestones. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) [fixed burndown charts](#fixed-burndown-charts) in GitLab 13.6. @@ -73,10 +73,8 @@ The chart indicates the project's progress throughout that milestone (for issues In particular, it shows how many issues were or are still open for a given day in the milestone's corresponding period. -The burndown chart can also be toggled to display the cumulative open issue -weight for a given day. When using this feature, make sure issue weights have -been properly assigned, since an open issue with no weight adds zero to the -cumulative value. +You can also toggle the burndown chart to display the +[cumulative open issue weight](#switch-between-number-of-issues-and-issue-weight) for a given day. ### Fixed burndown charts @@ -100,7 +98,7 @@ Therefore, when the milestone start date is changed, the number of opened issues change. Reopened issues are considered as having been opened on the day after they were last closed. -## Burnup charts **(PREMIUM)** +## Burnup charts > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6903) in GitLab 13.6. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268350) in GitLab 13.7. @@ -123,12 +121,21 @@ To view a group's burnup chart: ### How burnup charts work Burnup charts have separate lines for total work and completed work. The total line -shows when scope is reduced or added to a milestone. The completed work is a count -of issues closed. +shows changes to the scope of a milestone. When an open issue is moved to another +milestone, the "total issues" goes down but the "completed issues" stays the same. +The completed work is a count of issues closed. When an issue is closed, the "total +issues" remains the same and "completed issues" goes up. -Burnup charts can show either the total number of issues or total weight for each -day of the milestone. Use the toggle above the charts to switch between total -and weight. +## Switch between number of issues and issue weight + +In both burndown or burnup charts you can view them +either by the total number of issues +or the total weight for each day of the milestone. + +To switch between the two settings, select either **Issues** or **Issue weight** above the charts. + +When sorting by weight, make sure all your issues +have weight assigned, because issues with no weight don't show on the chart. <!-- ## Troubleshooting diff --git a/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png b/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png Binary files differdeleted file mode 100644 index ffe1328b7d3..00000000000 --- a/doc/user/project/milestones/img/milestones_new_group_milestone_v13_5.png +++ /dev/null diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index fb61e123faf..4501cf500b0 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -53,35 +53,23 @@ If you're in a project and select **Issues > Milestones**, GitLab displays only ## Creating milestones -NOTE: -A permission level of [Developer or higher](../../permissions.md) is required to create milestones. - -### New project milestone - -To create a project milestone: - -1. In a project, go to **{issues}** **Issues > Milestones**. -1. Select **New milestone**. -1. Enter the title, an optional description, an optional start date, and an optional due date. -1. Select **New milestone**. - - +Users with at least the Developer role can create milestones. -### New group milestone +Milestones can be created either at project or group level. -To create a group milestone: +To create a milestone: -1. In a group, go to **{issues}** **Issues > Milestones**. +1. On the top bar, select **Menu > Projects** and find your project or **Menu > Groups** and find your group. +1. On the left sidebar, select **Issues > Milestones**. 1. Select **New milestone**. 1. Enter the title, an optional description, an optional start date, and an optional due date. 1. Select **New milestone**. - + ## Editing milestones -NOTE: -A permission level of [Developer or higher](../../permissions.md) is required to edit milestones. +Users with at least the Developer role can edit milestones. To edit a milestone: @@ -155,23 +143,18 @@ There are also tabs below these that show the following: - Completed Issues (closed) - **Merge Requests**: Shows all merge requests assigned to the milestone. These are displayed in four columns named: - Work in progress (open and unassigned) - - Waiting for merge (open and unassigned) + - Waiting for merge (open and assigned) - Rejected (closed) - Merged - **Participants**: Shows all assignees of issues assigned to the milestone. - **Labels**: Shows all labels that are used in issues assigned to the milestone. -### Project Burndown Charts +### Burndown Charts -For project milestones, a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, +The milestone view contains a [burndown and burnup chart](burndown_and_burnup_charts.md), showing the progress of completing a milestone. - - -### Group Burndown Charts - -For group milestones, a [burndown chart](burndown_and_burnup_charts.md) is in the milestone view, -showing the progress of completing a milestone. + ### Milestone sidebar diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 283ed0b61b9..82b1a824f7a 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -81,7 +81,7 @@ GitLab Pages website. You can either use the GitLab [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-default-domain-names), `*.gitlab.io`, or your own domain (`example.com`). In that case, you -must have the Administrator role in your domain's registrar (or control panel) to set it up with Pages. +must be an administrator in your domain's registrar (or control panel) to set it up with Pages. The following diagrams show the workflows you might follow to get started with Pages. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 10fbc57fa0b..65e1579001b 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -63,7 +63,7 @@ If the case of `404.html`, there are different scenarios. For example: You can configure redirects for your site using a `_redirects` file. To learn more, read the [redirects documentation](redirects.md). -## GitLab Pages Access Control **(FREE)** +## GitLab Pages Access Control To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md). diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 6c18fc158f5..8bb18905222 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -18,7 +18,7 @@ When a branch is protected, the default behavior enforces these restrictions on | Action | Who can do it | |:-------------------------|:------------------------------------------------------------------| -| Protect a branch | Maintainers only. | +| Protect a branch | At least the Maintainer role. | | Push to the branch | GitLab administrators and anyone with **Allowed** permission. (1) | | Force push to the branch | No one. | | Delete the branch | No one. | @@ -35,7 +35,7 @@ Administrators can set a default branch protection level in the Prerequisite: -- You must have at least the [Maintainer role](../permissions.md). +- You must have at least the Maintainer role. To protect a branch: @@ -52,7 +52,7 @@ The protected branch displays in the list of protected branches. Prerequisite: -- You must have at least the [Maintainer role](../permissions.md). +- You must have at least the Maintainer role. To protect multiple branches at the same time: @@ -75,7 +75,7 @@ The protected branch displays in the list of protected branches. ## Create a protected branch -Users with the Developer or higher [role](../permissions.md) can create a protected branch. +Users with at least the Developer role can create a protected branch. Prerequisites: @@ -217,16 +217,16 @@ for details about the pipelines security model. ## Delete a protected branch -Users with the [Maintainer role](../permissions.md) and greater can manually delete protected +Users with at least the Maintainer role can manually delete protected branches by using the GitLab web interface: 1. Go to **Repository > Branches**. 1. Next to the branch you want to delete, select the **Delete** button (**{remove}**). 1. On the confirmation dialog, type the branch name and select **Delete protected branch**. -You can delete a protected branch from the UI only. -This prevents you from accidentally deleting a branch -from the command line or from a Git client application. +Protected branches can only be deleted by using GitLab either from the UI or API. +This prevents accidentally deleting a branch through local Git commands or +third-party Git clients. <!-- ## Troubleshooting diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index e4743c82a3b..7d071a45d63 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -22,12 +22,12 @@ This feature evolved out of [protected branches](protected_branches.md) By default: -- To create tags, you must have the [Maintainer role](../permissions.md). +- To create tags, you must have the Maintainer role. - No one can update or delete tags. ## Configuring protected tags -To protect a tag, you need to have at least the [Maintainer role](../permissions.md). +To protect a tag, you need to have at least the Maintainer role. 1. Go to the project's **Settings > Repository**. @@ -66,6 +66,26 @@ all matching tags:  +## Prevent tag creation with the same name as branches + +A tag and a branch with identical names can contain different commits. If your +tags and branches use the same names, users running `git checkout` +commands might check out the _tag_ `qa` when they instead meant to check out +the _branch_ `qa`. + +To prevent this problem: + +1. Identify the branch names you do not want used as tags. +1. As described in [Configuring protected tags](#configuring-protected-tags), + create a protected tag: + + - For the **Name**, provide a name, such as `stable`. You can also create a wildcard + like `stable-*` to match multiple names, like `stable-v1` and `stable-v2`. + - For **Allowed to Create**, select **No one**. + - Select **Protect**. + +Users can still create branches, but not tags, with the protected names. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 846d4732533..20dd37578fd 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Push Options **(FREE)** GitLab supports using client-side [Git push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) -to perform various actions at the same time as pushing changes. Additionally, [Push Rules](../../push_rules/push_rules.md) offer server-side control and enforcement options. +to perform various actions at the same time as pushing changes. Additionally, [Push Rules](repository/push_rules.md) offer server-side control and enforcement options. Currently, there are push options available for: diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 21a080de404..8070c37db78 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -49,7 +49,7 @@ threads. Some quick actions might not be available to all subscription tiers. | Command | Issue | Merge request | Epic | Action | |:-------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `/add_contacts email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add one or more [CRM contacts](../crm/index.md) ([introduced in GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413)). | +| `/add_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add one or more [CRM contacts](../crm/index.md) ([introduced in GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413)). | | `/approve` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Approve the merge request. | | `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users. | | `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself. | @@ -78,7 +78,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/lock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Lock the discussions. | | `/merge` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), or adding to a [Merge Train](../../ci/pipelines/merge_trains.md). | | `/milestone %milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set milestone. | -| `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. | +| `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. | | `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). | | `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. | | `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced in GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/issues/296787)). | @@ -89,7 +89,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. | | `/relate #issue1 #issue2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark issues as related. | | `/remove_child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). | -| `/remove_contacts email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove one or more [CRM contacts](../crm/index.md) ([introduced in GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413)). | +| `/remove_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove one or more [CRM contacts](../crm/index.md) ([introduced in GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413)). | | `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove due date. | | `/remove_epic` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove from epic. | | `/remove_estimate` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time estimate. | diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 747b41d07f2..8049ee9726d 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -393,7 +393,7 @@ deploy_to_production: To set a deploy freeze window in the UI, complete these steps: -1. Sign in to GitLab as a user with the [Maintainer role](../../permissions.md). +1. Sign in to GitLab as a user with the Maintainer role. 1. On the left sidebar, select **Project information**. 1. In the left navigation menu, navigate to **Settings > CI/CD**. 1. Scroll to **Deploy freezes**. @@ -480,7 +480,7 @@ to use the same URL. This is defined during [link creation](../../../api/release The format of the URL is: ```plaintext -https://host/namespace/project/releases/:release/downloads/:filepath +https://host/namespace/project/-/releases/:release/downloads/:filepath ``` If you have an asset for the `v11.9.0-rc2` release in the `gitlab-org` @@ -498,7 +498,7 @@ namespace and `gitlab-runner` project on `gitlab.com`, for example: This asset has a direct link of: ```plaintext -https://gitlab.com/gitlab-org/gitlab-runner/releases/v11.9.0-rc2/downloads/binaries/gitlab-runner-linux-amd64 +https://gitlab.com/gitlab-org/gitlab-runner/-/releases/v11.9.0-rc2/downloads/binaries/gitlab-runner-linux-amd64 ``` The physical location of the asset can change at any time and the direct link remains unchanged. @@ -706,7 +706,7 @@ Here is an example of a release evidence object: ### Collect release evidence **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in GitLab 12.10. When a release is created, release evidence is automatically collected. To initiate evidence collection any other time, use an [API call](../../../api/releases/index.md#collect-release-evidence). You can collect release evidence multiple times for one release. @@ -714,7 +714,7 @@ Evidence collection snapshots are visible on the Releases page, along with the t ### Include report artifacts as release evidence **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32773) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32773) in GitLab 13.2. When you create a release, if [job artifacts](../../../ci/yaml/index.md#artifactsreports) are included in the last pipeline that ran, they are automatically included in the release as release evidence. @@ -767,22 +767,22 @@ In the API: > [Changes were made to the Guest role access](https://gitlab.com/gitlab-org/gitlab/-/issues/335209) in GitLab 14.5. -- Users with the [Reporter role or above](../../../user/permissions.md#project-members-permissions) +- Users with at least the Reporter role have read and download access to the project releases. -- Users with the [Guest role](../../../user/permissions.md#project-members-permissions) +- Users with the Guest role have read and download access to the project releases. This includes associated Git-tag-names, release description, author information of the releases. However, other repository-related information, such as [source code](#source-code), [release evidence](#release-evidence) are redacted. ### Create, update, and delete a release and its assets -- Users with [Developer role or above](../../../user/permissions.md#project-members-permissions) +- Users with at least the Developer role have write access to the project releases and assets. - If a release is associated with a [protected tag](../protected_tags.md), the user must be [allowed to create the protected tag](../protected_tags.md#configuring-protected-tags) too. As an example of release permission control, you can allow only -[Maintainer role or above](../../../user/permissions.md#project-members-permissions) +users with at least the Maintainer role to create, update, and delete releases by protecting the tag with a wildcard (`*`), and set **Maintainer** in the **Allowed to create** column. diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index 65b7c4a9881..d706a0e8f8a 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -38,7 +38,7 @@ the [Git commands you need](#update-the-default-branch-name-in-your-repository) To update the default branch name for an individual [project](../../index.md): -1. Sign in to GitLab with at least the [Maintainer](../../../permissions.md) role. +1. Sign in to GitLab with at least the Maintainer role. 1. In the left navigation menu, go to **Settings > Repository**. 1. Expand **Default branch**, and select a new default branch. 1. Optional. Select the **Auto-close referenced issues on default branch** checkbox to close @@ -57,8 +57,8 @@ GitLab administrators can configure a new default branch name at the ### Instance-level custom initial branch name **(FREE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221013) in GitLab 13.2. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/325163) in GitLab 13.12. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221013) in GitLab 13.2 [with a flag](../../../../administration/feature_flags.md) named `global_default_branch_name`. Enabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/325163) in GitLab 13.12. Feature flag `global_default_branch_name` removed. GitLab [administrators](../../../permissions.md) of self-managed instances can customize the initial branch for projects hosted on that instance. Individual @@ -129,7 +129,7 @@ renames a Git repository's (`example`) default branch. git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main ``` -1. Sign in to GitLab with at least the [Maintainer](../../../permissions.md) +1. Sign in to GitLab with at least the Maintainer role and follow the instructions to [change the default branch for this project](#change-the-default-branch-name-for-a-project). Select `main` as your new default branch. diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 1ab21286a8e..b085372c8f2 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -27,16 +27,15 @@ To fork an existing project in GitLab: 1. Select the project to fork to: - Recommended method. Below **Select a namespace to fork the project**, identify - the project you want to fork to, and click **Select**. Only namespaces you have - Developer and higher [permissions](../../permissions.md) for are shown. + the project you want to fork to, and click **Select**. Only namespaces where you have + at least the Developer role for are shown.  - Experimental method. If your GitLab administrator has - [enabled the experimental fork project form](#enable-or-disable-the-fork-project-form), read + enabled the experimental fork project form, read [Create a fork with the fork project form](#create-a-fork-with-the-fork-project-form). - Only namespaces you have at least the Developer - [role](../../permissions.md) for are shown. + Only namespaces where you have at least the Developer role for are shown. NOTE: The project path must be unique in the namespace. @@ -85,14 +84,14 @@ You can unlink your fork from its upstream project in the [advanced settings](.. ## Create a fork with the fork project form **(FREE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15013) in GitLab 13.11. -> - It's [deployed behind a feature flag](../../../user/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-the-fork-project-form). **(FREE SELF)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15013) in GitLab 13.11 [with a flag](../../../administration/feature_flags.md) named `fork_project_form`. Disabled by default. +> - [Enabled on self-managed and GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64967) in GitLab 13.8. -This experimental version of the fork project form is available only if your GitLab -administrator has [enabled it](#enable-or-disable-the-fork-project-form): +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `fork_project_form`. +On GitLab.com, this feature is available. + +This version of the fork project form is experimental:  @@ -103,23 +102,3 @@ To use it, follow the instructions at [Creating a fork](#creating-a-fork) and pr - The project slug. - Optional. The project description. - The visibility level for your fork. - -### Enable or disable the fork project form **(FREE SELF)** - -The new [fork project form](#create-a-fork-with-the-fork-project-form) 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(:fork_project_form) -``` - -To disable it: - -```ruby -Feature.disable(:fork_project_form) -``` diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 0c5c0d5fa7c..f5cea8a8075 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -273,7 +273,7 @@ To remove a GPG key from your account: ## Rejecting commits that are not signed **(PREMIUM)** You can configure your project to reject commits that aren't GPG-signed -via [push rules](../../../../push_rules/push_rules.md). +via [push rules](../push_rules.md). ## GPG signing API diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index c8950d39f28..cddbc6fd891 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -37,7 +37,7 @@ Mirror a repository when: Prerequisite: -- You must have at least the [Maintainer role](../../../permissions.md) for the project. +- You must have at least the Maintainer role for the project. - If your mirror connects with `ssh://`, the host key must be detectable on the server, or you must have a local copy of the key. @@ -45,8 +45,8 @@ Prerequisite: 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Mirroring repositories**. 1. Enter a **Git repository URL**. For security reasons, the URL to the original - repository is only displayed to users with the [Maintainer role](../../../permissions.md) - or the [Owner role](../../../permissions.md) for the mirrored project. + repository is only displayed to users with the Maintainer role + or the Owner role for the mirrored project. 1. Select a **Mirror direction**. 1. If you entered a `ssh://` URL, select either: - **Detect host keys**: GitLab fetches the host keys from the server and displays the fingerprints. @@ -87,7 +87,7 @@ While mirrors are scheduled to update automatically, you can force an immediate Prerequisite: -- You must have at least the [Maintainer role](../../../permissions.md) for the project. +- You must have at least the Maintainer role for the project. 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md new file mode 100644 index 00000000000..bb473a2830b --- /dev/null +++ b/doc/user/project/repository/push_rules.md @@ -0,0 +1,288 @@ +--- +stage: Create +group: Source Code +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +--- + +# Push rules **(PREMIUM)** + +Gain additional control over what can and can't be pushed to your repository by using +regular expressions to reject pushes based on commit contents, branch names or file details. + +GitLab already offers [protected branches](../protected_branches.md), but there are +cases when you need some specific rules. Some common scenarios: preventing Git tag removal, or +enforcing a special format for commit messages. + +Push rules are [pre-receive Git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) you +can enable in a user-friendly interface. They are defined either: + +- Globally if you are an administrator. +- Per project, so you can have different rules applied to different + projects depending on your needs. + +## Use cases + +Every push rule could have its own use case, but let's consider some examples. + +### Commit messages with a specific reference + +Let's assume you have the following requirements for your workflow: + +- every commit should reference a Jira issue, for example: `Refactored css. Fixes JIRA-123.` +- users should not be able to remove Git tags with `git push` + +Write a regular expression that requires the mention +of a Jira issue in the commit message, like `JIRA\-\d+`. + +Now when a user tries to push a commit with a message `Bugfix`, their push is +declined. Only pushing commits with messages like `Bugfix according to JIRA-123` +is accepted. + +### Restrict branch names + +If your company has a strict policy for branch names, you may want the branches to start +with a certain name. This approach enables different +GitLab CI/CD jobs (such as `feature`, `hotfix`, `docker`, `android`) that rely on the +branch name. + +Your developers may not remember that policy, so they might push to +various branches, and CI pipelines might not work as expected. By restricting the +branch names globally in Push Rules, such mistakes are prevented. +All branch names that don't match your push rule are rejected. + +Note that the name of your default branch is always allowed, regardless of the branch naming +regular expression (regex) specified. GitLab is configured this way +because merges typically have the default branch as their target. +If you have other target branches, include them in your regex. (See [Enabling push rules](#enabling-push-rules)). + +The default branch also defaults to being a [protected branch](../protected_branches.md), +which already limits users from pushing directly. + +Some example regular expressions you can use in push rules: + +- `^JIRA-` Branches must start with `JIRA-`. +- `-JIRA$` Branches must end with `-JIRA`. +- `^[a-z0-9\\-]{4,15}$` Branches must be between `4` and `15` characters long, + accepting only lowercase letters, numbers and dashes. + +#### Default restricted branch names + +> Introduced in GitLab 12.10. + +By default, GitLab restricts certain formats of branch names for security purposes. +40-character hexadecimal names, similar to Git commit hashes, are prohibited. + +### Custom Push Rules **(PREMIUM SELF)** + +It's possible to create custom push rules rather than the push rules available in +**Admin Area > Push Rules** by using more advanced server hooks. + +See [server hooks](../../../administration/server_hooks.md) for more information. + +## Enabling push rules + +You can create push rules for all new projects to inherit, but they can be overridden +at the project level or the [group level](../../group/index.md#group-push-rules). + +To create global push rules: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Push Rules**. + +To override global push rules in a project's settings: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Push rules**. +1. Set the rule you want. +1. Select **Save push rules**. + +The following options are available: + +| Push rule | Description | +|---------------------------------|-------------| +| Removal of tags with `git push` | Forbid users to remove Git tags with `git push`. Tags can be deleted through the web UI. | +| Check whether the commit author is a GitLab user | Restrict commits to existing GitLab users (checked against their emails). <sup>1</sup> | +| Reject unverified users | GitLab rejects any commit that was not committed by the same user as the user who pushed it, or where the committer's email address is not [confirmed](../../../security/user_email_confirmation.md). | +| Check whether commit is signed through GPG | Reject commit when it is not signed through GPG. Read [signing commits with GPG](gpg_signed_commits/index.md). | +| Prevent pushing secret files | GitLab rejects any files that are likely to contain secrets. See the [forbidden file names](#prevent-pushing-secrets-to-the-repository). | +| Require expression in commit messages | Only commit messages that match this regular expression are allowed to be pushed. <sup>2</sup> Leave empty to allow any commit message. Uses multiline mode, which can be disabled using `(?-m)`. | +| Reject expression in commit messages | Only commit messages that do not match this regular expression are allowed to be pushed. <sup>2</sup> Leave empty to allow any commit message. Uses multiline mode, which can be disabled using `(?-m)`. | +| Restrict by branch name | Only branch names that match this regular expression are allowed to be pushed. <sup>2</sup> Leave empty to allow all branch names. | +| Restrict by commit author's email | Only commit author's email that match this regular expression are allowed to be pushed. <sup>1</sup> <sup>2</sup> Leave empty to allow any email. | +| Prohibited file names | Any committed filenames that match this regular expression and do not already exist in the repository are not allowed to be pushed. <sup>2</sup> Leave empty to allow any filenames. See [common examples](#prohibited-file-names). | +| Maximum file size | Pushes that contain added or updated files that exceed this file size (in MB) are rejected. Set to 0 to allow files of any size. Files tracked by Git LFS are exempted. | + +1. Checks both the commit author and committer. +1. GitLab uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax) for regular expressions in push rules, and you can test them at the [regex101 regex tester](https://regex101.com/). + +### Caveat to "Reject unsigned commits" push rule + +This push rule ignores commits that are authenticated and created by GitLab +(either through the UI or API). When the **Reject unsigned commits** push rule is +enabled, unsigned commits may still show up in the commit history if a commit was +created **in** GitLab itself. As expected, commits created outside GitLab and +pushed to the repository are rejected. For more information about how GitLab +plans to fix this issue, read [issue #19185](https://gitlab.com/gitlab-org/gitlab/-/issues/19185). + +#### "Reject unsigned commits" push rule disables Web IDE + +In 13.10, if a project has the "Reject unsigned commits" push rule, the user is not allowed to +commit through GitLab Web IDE. + +To allow committing through the Web IDE on a project with this push rule, a GitLab administrator +must disable the feature flag `reject_unsigned_commits_by_gitlab`. This can be done through a +[rails console](../../../administration/operations/rails_console.md) and running: + +```ruby +Feature.disable(:reject_unsigned_commits_by_gitlab) +``` + +## Prevent pushing secrets to the repository + +> Moved to GitLab Premium in 13.9. + +Secrets, such as credential files and SSH private keys, should never be committed to a version control +system. In GitLab, you can use a predefined list of files to block those files from a +repository. Any merge request containing a file matching the list is blocked from being merged. +Files already committed to the repository are not restricted by this push rule. + +Files blocked by this rule are listed below. For a complete list of criteria, see +[`files_denylist.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml). + +- AWS CLI credential blobs: + + - `.aws/credentials` + - `aws/credentials` + - `homefolder/aws/credentials` + +- Private RSA SSH keys: + + - `/ssh/id_rsa` + - `/.ssh/personal_rsa` + - `/config/server_rsa` + - `id_rsa` + - `.id_rsa` + +- Private DSA SSH keys: + + - `/ssh/id_dsa` + - `/.ssh/personal_dsa` + - `/config/server_dsa` + - `id_dsa` + - `.id_dsa` + +- Private ED25519 SSH keys: + + - `/ssh/id_ed25519` + - `/.ssh/personal_ed25519` + - `/config/server_ed25519` + - `id_ed25519` + - `.id_ed25519` + +- Private ECDSA SSH keys: + + - `/ssh/id_ecdsa` + - `/.ssh/personal_ecdsa` + - `/config/server_ecdsa` + - `id_ecdsa` + - `.id_ecdsa` + +- Private ECDSA_SK SSH keys (GitLab 14.8 and later): + + - `/ssh/id_ecdsa_sk` + - `/.ssh/personal_ecdsa_sk` + - `/config/server_ecdsa_sk` + - `id_ecdsa_sk` + - `.id_ecdsa_sk` + +- Private ED25519_SK SSH keys (GitLab 14.8 and later): + + - `/ssh/id_ed25519_sk` + - `/.ssh/personal_ed25519_sk` + - `/config/server_ed25519_sk` + - `id_ed25519_sk` + - `.id_ed25519_sk` + +- Any files ending with these suffixes: + + - `*.pem` + - `*.key` + - `*.history` + - `*_history` + +### Prevent pushing secrets to all projects + +To set a global push rule to prevent pushing secrets to all projects: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Push Rules**. +1. Expand **Push rules**. +1. Select **Prevent pushing secret files**. +1. Select **Save push rules**. + +### Prevent pushing secrets to a project + +The push rule of a project overrides the global push rule. + +To prevent pushing secrets to a project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Push rules**. +1. Select **Prevent pushing secret files**. +1. Select **Save push rules**. + +## Prohibited file names + +> Moved to GitLab Premium in 13.9. + +Each filename contained in a Git push is compared to the regular expression in this field. Filenames in Git consist of both the file's name and any directory that may precede it. A singular regular expression can contain multiple independent matches used as exclusions. File names can be broadly matched to any location in the repository, or restricted to specific locations. Filenames can also be partial matches used to exclude file types by extension. + +The following examples make use of regex string boundary characters which match the beginning of a string (`^`), and the end (`$`). They also include instances where either the directory path or the filename can include `.` or `/`. Both of these special regex characters have to be escaped with a backslash `\\` to be used as normal characters in a match condition. + +Example: prevent pushing any `.exe` files to any location in the repository. This uses a partial match, which matches any filename that contains `.exe` at the end: + +```plaintext +\.exe$ +``` + +Example: prevent a specific configuration file in the repository root from being pushed: + +```plaintext +^config\.yml$ +``` + +Example: prevent a specific configuration file in a known directory from being pushed: + +```plaintext +^directory-name\/config\.yml$ +``` + +Example: prevent the specific file named `install.exe` from being pushed to any +location in the repository. The parenthesized expression `(^|\/)` matches either +a file following a directory separator or a file in the root directory of the repository: + +```plaintext +(^|\/)install\.exe$ +``` + +Example: combining all of the above in a single expression. The preceding expressions rely +on the end-of-string character `$`. We can move that part of each expression to the +end of the grouped collection of match conditions where it is appended to all matches: + +```plaintext +(\.exe|^config\.yml|^directory-name\/config\.yml|(^|\/)install\.exe)$ +``` + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index 23cead7e8a7..37b16d90d93 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 @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto --- -# Reduce repository size +# Reduce repository size **(FREE)** Git repositories become larger over time. When large files are added to a Git repository: @@ -193,7 +193,7 @@ When using repository cleanup, note: Repository size limits: - Can [be set by an administrator](../../admin_area/settings/account_and_limit_settings.md#account-and-limit-settings) - on self-managed instances. **(PREMIUM SELF)** +- Can [be set by an administrator](../../admin_area/settings/account_and_limit_settings.md) on self-managed instances. - Are [set for GitLab.com](../../gitlab_com/index.md#account-and-limit-settings). When a project has reached its size limit, you cannot: diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index f9d9af3e672..27ef14d31c5 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -1,8 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: concepts, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Sign commits and tags with X.509 certificates **(FREE)** @@ -335,7 +334,7 @@ step of the previous [main verification checks](#main-verification-checks). signature.__send__(:p7).verify([], signature.__send__(:cert_store), signature.__send__(:signed_text)) ``` - 1. If this fails, add the missing certificate(s) required to establish trust + 1. If this fails, add the missing certificates required to establish trust [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). 1. After adding more certificates, (if these troubleshooting steps then pass) @@ -347,7 +346,7 @@ step of the previous [main verification checks](#main-verification-checks). pp signature.__send__(:p7).certificates ; nil ``` -Ensure any additional intermediate certificate(s) and the root certificate are added +Ensure any additional intermediate certificates and the root certificate are added to the certificate store. For consistency with how certificate chains are built on web servers: diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 5fe0e0ef3a2..d549a22910a 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -40,7 +40,7 @@ can create a new requirement. Prerequisite: -- You must have at least the Reporter [role](../../permissions.md). +- You must have at least the Reporter role. To create a requirement: @@ -70,7 +70,7 @@ You can edit a requirement from the requirements list page. Prerequisite: -- You must have at least the Reporter [role](../../permissions.md). +- You must have at least the Reporter role. To edit a requirement: @@ -86,7 +86,7 @@ you're in the **Open** tab. Prerequisite: -- You must have at least the Reporter [role](../../permissions.md). +- You must have at least the Reporter role. To archive a requirement, select **Archive** (**{archive}**). @@ -98,7 +98,7 @@ You can view the list of archived requirements in the **Archived** tab. Prerequisite: -- You must have at least the Reporter [role](../../permissions.md). +- You must have at least the Reporter role.  @@ -217,7 +217,7 @@ requirements_confirmation: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/246857) in GitLab 13.7. -You must have at least the Reporter [role](../../permissions.md). +You must have at least the Reporter role. You can import requirements to a project by uploading a [CSV file](https://en.wikipedia.org/wiki/Comma-separated_values) with the columns `title` and `description`. @@ -291,7 +291,7 @@ audit and regulatory compliance tasks. Prerequisite: -- You must have at least the Reporter [role](../../permissions.md). +- You must have at least the Reporter role. To export requirements: diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 1b30f14ac90..1e5b818c99d 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -87,7 +87,7 @@ To improve your project's security, we recommend the following: Unblocked email spam can result in many spam issues being created. The unique internal email address is visible to project members at least -the Reporter [role](../permissions.md) in your GitLab instance. +the Reporter role in your GitLab instance. An external user (issue creator) cannot see the internal email address displayed in the information note. @@ -333,3 +333,10 @@ Note that: Behind the scenes, Service Desk works by the special Support Bot user creating issues. This user does not count toward the license limit count. + +## Troubleshooting Service Desk + +### Emails to Service Desk do not create issues + +Your emails might be ignored because they contain one of the +[email headers that GitLab ignores](../../administration/incoming_email.md#rejected-headers). diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 06bdf4ca14b..8cee567ae93 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -122,8 +122,7 @@ As described in the API documentation, the query may return an import error or e The following items are imported but changed slightly: -- Project members with the [Owner role](../../permissions.md) - are imported as Maintainers. +- Project members with the Owner role are imported as Maintainers. - If an imported project contains merge requests originating from forks, then new branches associated with such merge requests are created in a project during the import/export. Thus, the number of branches in the exported project might be bigger than in the original project. @@ -160,6 +159,8 @@ Imported users can be mapped by their public email addresses on self-managed ins for mapping to work correctly. - For contributions to be mapped correctly, users must be an existing member of the namespace, or they can be added as a member of the project. Otherwise, a supplementary comment is left to mention that the original author and the MRs, notes, or issues that are owned by the importer. +- Imported users are set as [direct members](../members/index.md) + in the imported project. For project migration imports performed over GitLab.com groups, preserving author information is possible through a [professional services engagement](https://about.gitlab.com/services/migration/). diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 9df545b52ec..4c6be3511f2 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -16,7 +16,7 @@ In GitLab versions [13.10 and later](https://gitlab.com/groups/gitlab-org/-/epic GitLab displays a search box to help you find the settings you want to view. NOTE: -Only users who have the [Maintainer role](../../permissions.md) for the project and administrators can +Only users who have the Maintainer role for the project and administrators can access project settings. ## General settings @@ -93,7 +93,7 @@ executed in place of the local project's `gitlab-ci.yml` file. As part of this p files are merged together any time the pipeline runs. Jobs and variables defined in the compliance pipeline can't be changed by variables in the local project's `gitlab-ci.yml` file. -When used to enforce scan execution, this feature has some overlap with [scan execution policies](../../application_security/policies/#scan-execution-policies), +When used to enforce scan execution, this feature has some overlap with [scan execution policies](../../application_security/policies/scan-execution-policies.md), as we have not [unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). For details on the similarities and differences between these features, see [Enforce scan execution](../../application_security/#enforce-scan-execution). @@ -249,7 +249,7 @@ Use the switches to enable or disable the following features: |:---------------------------------|:--------------------------|:--------------| | **Issues** | ✓ | Activates the GitLab issues tracker. | | **Repository** | ✓ | Enables [repository](../repository/) functionality | -| **Merge Requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#merge-request-settings). | +| **Merge requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#merge-request-settings). | | **Forks** | ✓ | Enables [forking](../repository/forking_workflow.md) functionality. | | **Git Large File Storage (LFS)** | | Enables the use of [large files](../../../topics/git/lfs/index.md#git-large-file-storage-lfs). | | **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration) functionality. | @@ -281,7 +281,7 @@ Some features depend on others: - If you disable **Repository** functionality, GitLab also disables the following features for your project: - - **Merge Requests** + - **Merge requests** - **CI/CD** - **Container Registry** - **Git Large File Storage** @@ -360,7 +360,7 @@ available in project listings. Only project owners and administrators have the To find an archived project: -1. Sign in to GitLab as the project owner or a user with the Administrator role. +1. Sign in to GitLab as the project owner or a user with administrator access. 1. If you: - Have the project's URL, open the project's page in your browser. - Don't have the project's URL: @@ -404,11 +404,17 @@ NOTE: Only project owners and administrators have the [permissions](../../permissions.md#project-members-permissions) to transfer a project. -You can transfer an existing project into a [group](../../group/index.md) if: +You can transfer an existing project into a [group](../../group/index.md). -- You have at least **Maintainer** [role](../../permissions.md#project-members-permissions) in that group. -- You're at least an **Owner** of the project to be transferred. +Prerequisites: + +- You must have at least the Maintainer role in that group. +- You must be the Owner of that project. - The group to which the project is being transferred to must allow creation of new projects. +- The project must not contain any [container images](../../packages/container_registry/index.md#limitations). + - If you transfer a project to a different root namespace, + the project must not contain any + [NPM packages](../../packages/npm_registry/index.md#limitations). To transfer a project: @@ -423,8 +429,8 @@ read what happens with the [redirects from the old project to the new one](../repository/index.md#what-happens-when-a-repository-path-changes). NOTE: -GitLab administrators can use the administration interface to move any project to any -namespace if needed. +GitLab administrators can use the [administration interface](../../admin_area/index.md#administering-projects) +to move any project to any namespace if needed. ##### Transferring a GitLab.com project to a different subscription tier diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 3fcfe202d38..aa30c576c7c 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Authentication & Authorization +group: Authentication and Authorization info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -42,7 +42,7 @@ To create a project access token: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Access Tokens**. -1. Enter a name. +1. Enter a name. The token name is visible to any user with permissions to view the project. 1. Optional. Enter an expiry date for the token. The token will expire on that date at midnight UTC. 1. Select a role for the token. 1. Select the [desired scopes](#scopes-for-a-project-access-token). @@ -84,16 +84,16 @@ To enable or disable project access token creation for all projects in a top-lev Even when creation is disabled, you can still use and revoke existing project access tokens. -## Project bot users +## Bot users for projects > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210181) in GitLab 13.0. > - [Excluded from license seat use](https://gitlab.com/gitlab-org/gitlab/-/issues/223695) in GitLab 13.5. -Project bot users are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users). +Bot users for projects are [GitLab-created service accounts](../../../subscriptions/self_managed/index.md#billable-users). Each time you create a project access token, a bot user is created and added to the project. These bot users do not count as licensed seats. -The bot users have [permissions](../../permissions.md#project-members-permissions) that correspond with the +The bot users for projects have [permissions](../../permissions.md#project-members-permissions) that correspond with the selected role and [scope](#scopes-for-a-project-access-token) of the project access token. - The name is set to the name of the token. @@ -106,7 +106,7 @@ selected role and [scope](#scopes-for-a-project-access-token) of the project acc API calls made with a project access token are associated with the corresponding bot user. -Bot users: +Bot users for projects: - Are included in a project's member list but cannot be modified. - Cannot be added to any other project. @@ -114,5 +114,6 @@ Bot users: When the project access token is [revoked](#revoke-a-project-access-token): - The bot user is deleted. -- 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). +- All records are moved to a system-wide user with the username [Ghost User](../../profile/account/delete_account.md#associated-records). + +See also [Bot users for groups](../../group/settings/group_access_tokens.md#bot-users-for-groups). diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index 50b1a3a929d..072f5bf1927 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -12,6 +12,14 @@ description: "The static site editor enables users to edit content on static web > - WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214559) in GitLab 13.0. > - Non-Markdown content blocks not editable on the WYSIWYG mode [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216836) in GitLab 13.3. > - Formatting Markdown [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49052) in GitLab 13.7. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77246) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is +[deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77246) +for use in GitLab 14.7, and is planned for +[removal](https://gitlab.com/groups/gitlab-org/-/epics/7351) in GitLab 15.0. +Users should instead use the [Web Editor](../repository/web_editor.md) or [Web IDE](../web_ide/index.md). Static Site Editor (SSE) enables users to edit content on static websites without prior knowledge of the underlying templating language, site architecture, or diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index 6ceb8c94934..5f747d99ce7 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -8,76 +8,81 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Time tracking **(FREE)** -With time tracking you can track estimates and time spent on issues and merge -requests in GitLab. +You can estimate and track the time you spend on [issues](issues/index.md) +and [merge requests](merge_requests/index.md). + +Then you can [view a report](#view-a-time-tracking-report) that shows totals over time. Use time tracking for these tasks: - Record the time spent working on an issue or a merge request. - Add or update an estimate of the total time to complete an issue or a merge -request. + request. - View a breakdown of time spent working on an issue or a merge request. You don't have to indicate an estimate to enter the time spent, and vice versa. -Data about time tracking shows up on the issue and merge request sidebar: +To enter and remove time tracking data, you must use [quick actions](quick_actions.md). +Type all quick actions on their own lines. +If you use any quick action more than once in a single comment, only its last occurrence is applied. + +You can see the data about time tracking on the right sidebar in issues and merge requests:  -## How to enter data +## Estimates -Time tracking uses two [quick actions](quick_actions.md): `/spend` and `/estimate`. +The estimate is designed to show the total time needed to complete an issue or merge request. -If you use either quick action more than once in a single comment, only the last occurrence is applied. +You can see the estimated time remaining when you hover over the time tracking information in the right sidebar. -Below is an example of how you can use those new quick actions inside a comment. + - +### Add an estimate -Adding time entries (time spent or estimates) is limited to project members -with [Reporter and higher permission levels](../permissions.md). +Prerequisites: -### Estimates +- You must have at least the Reporter role for the project. -To enter an estimate, type `/estimate`, followed by the time. +To enter an estimate, use the `/estimate` [quick action](quick_actions.md), followed by the time. For example, if you need to enter an estimate of 1 month, 2 weeks, 3 days, 4 hours, and 5 minutes, type `/estimate 1mo 2w 3d 4h 5m`. -Check the [time units you can use](#configuration). +Check the [time units you can use](#available-time-units). -The estimate is designed to show the total estimated time. The estimated -time remaining is automatically calculated and displayed when hovering over -the time tracking information in the right sidebar. +An issue or a merge request can have only one estimate. +Every time you enter a new time estimate, it overwrites the previous value. - +### Remove an estimate -An issue or a merge request can have only one estimate. Every time you enter a -new time estimate, it overwrites the previous value. +Prerequisites: -To remove an estimation entirely, use `/remove_estimate`. +- You must have at least the Reporter role for the project. -### Time spent +To remove an estimate entirely, use the `/remove_estimate` [quick action](quick_actions.md). -To enter time spent, type `/spend`, followed by the time. +## Time spent -For example, if you need -to log 1 month, 2 weeks, 3 days, 4 hours, and 5 minutes, type `/spend 1mo 2w 3d 4h 5m`. -Check the [time units you can use](#configuration). +As you work, you can log the time you've spent. Every new time spent entry is added to the current total time spent for the issue or the merge request. -To subtract time, enter a negative value. For example, `/spend -3d` removes three -days from the total time spent. You can't go below 0 minutes of time spent, -so if you remove more time than already entered, GitLab ignores the subtraction. +### Add time spent -You can log time in the past by providing a date after the time. -For example, if you want to log 1 hour of time spent on the 31 January 2021, -you would type `/spend 1h 2021-01-31`. If you supply a date in the future, the -command fails and no time is logged. +Prerequisites: + +- You must have at least the Reporter role for the project. + +To enter time spent, use the `/spend` [quick action](quick_actions.md), followed by the time. + +For example, if you need +to log 1 month, 2 weeks, 3 days, 4 hours, and 5 minutes, type `/spend 1mo 2w 3d 4h 5m`. +Check the [time units you can use](#available-time-units). -To add a timelog entry with a note, create a comment with a description and the quick action. -It then shows in the timelog "Summary/Notes" column. For example: +To add a [time tracking report](#view-a-time-tracking-report) entry with a note, create a comment +with a description and the quick action. +It then shows in the time tracking report **Summary/Notes** column. For example: ```plaintext Draft MR and respond to initial comments @@ -85,7 +90,29 @@ Draft MR and respond to initial comments /spend 30m ``` -To remove all the time spent at once, use `/remove_time_spent`. +### Add time spent on a specific date + +Prerequisites: + +- You must have at least the Reporter role for the project. + +You can log time in the past by providing a date after the time. +For example, to log 1 hour of time spent on 31 January 2021, +type `/spend 1h 2021-01-31`. + +If you type a future date, no time is logged. + +### Remove time spent + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To subtract time, enter a negative value. For example, `/spend -3d` removes three +days from the total time spent. You can't go below 0 minutes of time spent, +so if you remove more time than already entered, GitLab ignores the subtraction. + +To remove all the time spent at once, use the `/remove_time_spent` [quick action](quick_actions.md). ## View a time tracking report @@ -93,35 +120,32 @@ To remove all the time spent at once, use `/remove_time_spent`. You can view a breakdown of time spent on an issue or merge request. -Prerequisites: - -- You must have at least the [Reporter role](../permissions.md#project-members-permissions) for a project. +To view a time tracking report: -To view a time tracking report, go to an issue or a merge request and select **Time tracking report** -in the right sidebar. +1. Go to an issue or a merge request. +1. In the right sidebar, select **Time tracking report**.  The breakdown of spent time is limited to a maximum of 100 entries. -## Configuration +## Available time units The following time units are available: -| Time unit | What to type | Default conversion rate | -| --------- | ------------ | ----------------------- | -| Month | `mo` | 4w | -| Week | `w` | 5d | -| Day | `d` | 8h | -| Hour | `h` | 60m | -| Minute | `m` | | +| Time unit | What to type | Conversion rate | +| --------- | --------------------------- | --------------- | +| Month | `mo`, `month`, or `months` | 4w (160h) | +| Week | `w`, `week`, or `weeks` | 5d (40h) | +| Day | `d`, `day`, or `days` | 8h | +| Hour | `h`, `hour`, or `hours` | 60m | +| Minute | `m`, `minute`, or `minutes` | | ### Limit displayed units to hours **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29469/) in GitLab 12.1. -In GitLab self-managed instances, you can limit the display of time units to -hours. +In GitLab self-managed instances, you can limit the display of time units to hours. To do so: 1. On the top bar, select **Menu > Admin**. diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index 731fed2595a..2c499af123c 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -22,7 +22,7 @@ Group wikis are similar to [project wikis](index.md), with a few limitations: For updates, follow [the epic that tracks feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). -Similar to project wikis, group members with the [Developer role](../../permissions.md#group-members-permissions) +Similar to project wikis, group members with at least the Developer role and higher can edit group wikis. Group wiki repositories can be moved using the [Group repository storage moves API](../../../api/group_repository_storage_moves.md). @@ -40,7 +40,7 @@ To access a group wiki: > Introduced in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247). -Users with the [Owner role](../../permissions.md) in a group can +Users with the Owner role in a group can [import and export group wikis](../../group/settings/import_export.md) when importing or exporting a group. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 95ea1b4d0bc..33f6c32d334 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -74,7 +74,7 @@ to be used as your wiki's home page. To create it: ## Create a new wiki page -Users with the [Developer role](../../permissions.md) can create new wiki pages: +Users with at least the Developer role can create new wiki pages: 1. On the top bar, select **Menu**. - For project wikis, select **Projects** and find your project. @@ -137,7 +137,7 @@ may not be able to check out the wiki locally afterward. ## Edit a wiki page -You need at least the [Developer role](../../permissions.md) to edit a wiki page: +You need at least the Developer role to edit a wiki page: 1. On the top bar, select **Menu**. - For project wikis, select **Projects** and find your project. @@ -156,7 +156,7 @@ For an example, read [Table of contents](../../markdown.md#table-of-contents). ## Delete a wiki page -You need at least the [Developer role](../../permissions.md) to delete a wiki page: +You need at least the Developer role to delete a wiki page: 1. On the top bar, select **Menu**. - For project wikis, select **Projects** and find your project. @@ -169,7 +169,7 @@ You need at least the [Developer role](../../permissions.md) to delete a wiki pa ## Move a wiki page -You need at least the [Developer role](../../permissions.md) to move a wiki page: +You need at least the Developer role to move a wiki page: 1. On the top bar, select **Menu**. - For project wikis, select **Projects** and find your project. @@ -239,7 +239,7 @@ Commits to wikis are not counted in [repository analytics](../../analytics/repos > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by selecting the **Edit sidebar** button. -You need at least the [Developer role](../../permissions.md) to customize the wiki +You need at least the Developer role to customize the wiki navigation sidebar. This process creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation: @@ -323,9 +323,17 @@ Previously added wiki pages are preserved in case you want to re-enable the wiki. To re-enable it, repeat the process to disable the wiki but toggle it on (in blue). -## Content Editor **(FREE)** +## Content Editor -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5643) in GitLab 14.0. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5643) in GitLab 14.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345398) switching between editing experiences in GitLab 14.7 [with a flag](../../../administration/feature_flags.md) named `wiki_switch_between_content_editor_raw_markdown`. Enabled by default. + +FLAG: +On self-managed GitLab, by default this feature is available. +To hide the feature, ask an administrator to +[disable the feature flag](../../../administration/feature_flags.md) named +`wiki_switch_between_content_editor_raw_markdown`. +On GitLab.com, this feature is available. GitLab version 14.0 introduces a WYSIWYG editing experience for GitLab Flavored Markdown in Wikis through the [Content Editor](../../../development/fe_guide/content_editor.md). diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 61eca19a67b..9cfcaf4ee81 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -99,6 +99,8 @@ To create a blank project: slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. - In the **Project description (optional)** field, enter the description of your project's dashboard. + - In the **Project target (optional)** field, select your project's deployment target. + This information helps GitLab better understand its users and their deployment requirements. - To modify the project's [viewing and access rights](../../public_access/public_access.md) for users, change the **Visibility Level**. - To create README file so that the Git repository is initialized, has a default branch, and @@ -297,6 +299,29 @@ To delete a project: 1. Select **Delete project** 1. Confirm this action by completing the field. +## Projects pending deletion **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37014) in GitLab 13.3 for Administrators. +> - [Tab renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/347468) from **Deleted projects** in GitLab 14.6. +> - [Available to all users](https://gitlab.com/gitlab-org/gitlab/-/issues/346976) in GitLab 14.8 [with a flag](../../administration/feature_flags.md) named `project_owners_list_project_pending_deletion`. Enabled by default. + +FLAG: +On self-managed GitLab, by default this feature is available to all users. To make it available for administrators only, +ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `project_owners_list_project_pending_deletion`. +On GitLab.com, this feature is available to all users. + +When delayed project deletion is [enabled for a group](../group/index.md#enable-delayed-project-deletion), +projects within that group are not deleted immediately, but only after a delay. To access a list of all projects that are pending deletion: + +1. On the top bar, select **Menu > Projects > Explore projects**. +1. Select the **Pending deletion** tab (in GitLab 14.6 and later) or the **Deleted projects** tab (GitLab 14.5 and earlier). + +Listed for each project is: + +- The time the project was marked for deletion. +- The time the project is scheduled for final deletion. +- A **Restore** link to stop the project being eventually deleted. + ## View project activity To view the activity of a project: diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index 13fba126169..05579696d35 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -140,3 +140,28 @@ its performance: | Issues | `global_search_issues_tab` | When enabled, the global search includes issues as part of the search. | | Merge Requests | `global_search_merge_requests_tab` | When enabled, the global search includes merge requests as part of the search. | | Wiki | `global_search_wiki_tab` | When enabled, the global search includes wiki as part of the search. [Group wikis](../project/wiki/group.md) are not included. | + +## Global Search validation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346263) in GitLab 14.6 [with a flag](../../administration/feature_flags.md) named `prevent_abusive_searches`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, + ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `prevent_abusive_searches`. + The feature is not ready for production use. + +To prevent abusive searches, such as searches that may result in a Distributed Denial of Service (DDoS), Global Search ignores, logs, and +doesn't return any results for searches considered abusive according to the following criteria, if `prevent_abusive_searches` feature flag is enabled: + +- Searches with less than 2 characters. +- Searches with any term greater than 100 characters. URL search terms have a maximum of 200 characters. +- Searches with a stop word as the only term (ie: "the", "and", "if", etc.). +- Searches with a `group_id` or `project_id` parameter that is not completely numeric. +- Searches with a `repository_ref` or `project_ref` parameter that has special characters not allowed by [Git refname](https://git-scm.com/docs/git-check-ref-format). +- Searches with a `scope` that is unknown. + +Regardless of the status of the `prevent_abusive_searches` feature flag, searches that don't +comply with the criteria described below aren't logged as abusive but are flagged with an error: + +- Searches with more than 4096 characters. +- Searches with more than 64 terms. diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 0e2be455a0c..0a799843d3c 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Search issues and merge requests -To search through issues and merge requests in multiple projects, on the top bar, select the **Issues** or **Merge Requests** links. +To search through issues and merge requests in multiple projects, on the top bar, select the **Issues** or **Merge requests** links. The numbers indicate how many issues, merge requests, and to-do items are assigned to you: @@ -32,24 +32,33 @@ in the search field in the upper right corner: ### Filter issue and merge request lists -> - Filter by Epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195704) in GitLab Ultimate 12.9. -> - Filter by child Epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9029) in GitLab Ultimate 13.0. -> - Filter by Iterations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6. Moved to GitLab Premium in 13.9. +> - Filtering by epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195704) in GitLab 12.9. +> - Filtering by child epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9029) in GitLab 13.0. +> - Filtering by iterations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6. Moved from GitLab Ultimate to Premium in 13.9. +> - Filtering by type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322755) in GitLab 13.10 [with a flag](../../administration/feature_flags.md) named `vue_issues_list`. Disabled by default. -Follow these steps to filter the **Issues** and **Merge Requests** list pages in projects and +Follow these steps to filter the **Issues** and **Merge requests** list pages in projects and groups: 1. Click in the field **Search or filter results...**. 1. In the dropdown menu that appears, select the attribute you wish to filter by: - - Author - Assignee - - [Milestone](../project/milestones/index.md) + - Author + - Confidential + - [Epic and child Epic](../group/epics/index.md) (available only for the group the Epic was created, not for [higher group levels](https://gitlab.com/gitlab-org/gitlab/-/issues/233729)). - [Iteration](../group/iterations/index.md) - - Release - [Label](../project/labels.md) + - [Milestone](../project/milestones/index.md) - My-reaction - - Confidential - - [Epic and child Epic](../group/epics/index.md) (available only for the group the Epic was created, not for [higher group levels](https://gitlab.com/gitlab-org/gitlab/-/issues/233729)). + - Release + - Type + + FLAG: + On self-managed GitLab, by default filtering by type is not available. + To make it available per group, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `vue_issues_list`. + On GitLab.com, this feature is not available. + + - Weight - Search for this text 1. Select or type the operator to use for filtering the attribute. The following operators are available: @@ -95,7 +104,7 @@ You can add this URL to your feed reader. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39908) in GitLab 12.1. -You can filter the **Issues** list to individual instances by their ID. For example, enter filter `#10` to return only issue 10. The same applies to the **Merge Requests** list. Enter filter `#30` to return only merge request 30. +You can filter the **Issues** list to individual instances by their ID. For example, enter filter `#10` to return only issue 10. The same applies to the **Merge requests** list. Enter filter `#30` to return only merge request 30.  @@ -270,8 +279,13 @@ search, or choose a specific group or project. To search through code or other documents in a single project, you can use the search field on the top-right of your screen while the project page is open. -Code search shows only the first result in the file. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327052) -in GitLab 14.7, you can access Git blame from any line that returned a result from the code search: +Code search shows only the first result in the file. + +#### Git blame from code search **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327052) in GitLab 14.7. + +You can access Git blame from any line that returned a result from the code search:  diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index d6cbbf352fc..ebaa5da8e05 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -1,6 +1,6 @@ --- -stage: none -group: unassigned +stage: Create +group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference disqus_identifier: 'https://docs.gitlab.com/ee/workflow/shortcuts.html' @@ -149,6 +149,57 @@ This shortcut is available when viewing a [wiki page](project/wiki/index.md): |-------------------|-------------| | <kbd>e</kbd> | Edit wiki page. | +### Content editor + +These shortcuts are available when editing a file with the [Content Editor](https://about.gitlab.com/direction/create/editor/content_editor/): + +| Keyboard shortcut | Description | +|-------------------|-------------| +| <kbd>⌘</kbd> + <kbd>C</kbd> (Mac) / <kbd>Control</kbd> + <kbd>C</kbd> | Copy | +| <kbd>⌘</kbd> + <kbd>X</kbd> (Mac) / <kbd>Control</kbd> + <kbd>X</kbd> | Cut | +| <kbd>⌘</kbd> + <kbd>V</kbd> (Mac) / <kbd>Control</kbd> + <kbd>V</kbd> | Paste | +| <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>V</kbd> (Mac) / <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>V</kbd> | Paste without formatting | +| <kbd>⌘</kbd> + <kbd>Z</kbd> (Mac) / <kbd>Control</kbd> + <kbd>Z</kbd> | Undo | +| <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>V</kbd> (Mac) / <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>V</kbd> | Redo | +| <kbd>Shift</kbd> + <kbd>Enter</kbd> | Add a line break | + +#### Formatting + +| Mac | Windows/Linux | Description | +|-----|---------------|-------------| +| <kbd>⌘</kbd> + <kbd>b</kbd> | <kbd>Control</kbd> + <kbd>b</kbd> | Bold | +| <kbd>⌘</kbd> + <kbd>i</kbd> | <kbd>Control</kbd> + <kbd>i</kbd> | Italic | +| <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>s</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>s</kbd> | Strikethrough | +| <kbd>⌘</kbd> + <kbd>e</kbd> | <kbd>Control</kbd> + <kbd>e</kbd> | Code | +| <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>0</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>0</kbd> | Apply normal text style | +| <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>1</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>1</kbd> | Apply heading style 1 | +| <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>2</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>2</kbd> | Apply heading style 2 | +| <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>3</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>3</kbd> | Apply heading style 3 | +| <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>4</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>4</kbd> | Apply heading style 4 | +| <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>5</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>5</kbd> | Apply heading style 5 | +| <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>6</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>6</kbd> | Apply heading style 6 | +| <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>7</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>7</kbd> | Ordered list | +| <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>8</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>7</kbd> | Bullet list | +| <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>9</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>7</kbd> | Task list | +| <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>b</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>b</kbd> | Blockquote | +| <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>c</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>c</kbd> | Code block | +| <kbd>⌘</kbd> + <kbd>,</kbd> | <kbd>Control</kbd> + <kbd>,</kbd> | Subscript | +| <kbd>⌘</kbd> + <kbd>.</kbd> | <kbd>Control</kbd> + <kbd>,</kbd> | Superscript | +| <kbd>Tab</kbd> | | Indent list | +| <kbd>Shift</kbd> + <kbd>Tab</kbd> | | Outdent list | + +#### Text selection + +| Keyboard shortcut | Description | +|-------------------|-------------| +| <kbd>⌘</kbd> + <kbd>a</kbd> (Mac) / <kbd>Control</kbd> + <kbd>a</kbd> | Select all | +| <kbd>Shift</kbd> + <kbd>←</kbd> | Extend selection one character to left | +| <kbd>Shift</kbd> + <kbd>→</kbd> | Extend selection one character to right | +| <kbd>Shift</kbd> + <kbd>↑</kbd> | Extend selection one line up | +| <kbd>Shift</kbd> + <kbd>↓</kbd> | Extend selection one line down | +| <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>↑</kbd> (Mac) / <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>↑</kbd> | Extend selection to the beginning of the document | +| <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>↓</kbd> (Mac) / <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>↓</kbd> | Extend selection to the end of the document | + ### Filtered search These shortcuts are available when using a [filtered search input](search/index.md): @@ -158,7 +209,7 @@ These shortcuts are available when using a [filtered search input](search/index. | <kbd>⌘</kbd> (Mac) + <kbd>⌫</kbd> | Clear entire search filter. | | <kbd>⌥</kbd> (Mac) / <kbd>Control</kbd> + <kbd>⌫</kbd> | Clear one token at a time. | -## Epics **(ULTIMATE)** +## Epics **(PREMIUM)** These shortcuts are available when viewing [epics](group/epics/index.md): diff --git a/doc/user/upgrade_email_bypass.md b/doc/user/upgrade_email_bypass.md index 3272ff30e72..8cd9a47f3e6 100644 --- a/doc/user/upgrade_email_bypass.md +++ b/doc/user/upgrade_email_bypass.md @@ -58,7 +58,7 @@ User.where(confirmed_at: nil).where('LENGTH(confirmation_token) = 32') ## What does it look like when a user is blocked? -A regular user might receive a message that says "You have to confirm your email address before continuing". This message could includes a 404 or 422 error code, when the user tries to sign in. +A user might receive a message that says "You have to confirm your email address before continuing". This message could includes a 404 or 422 error code, when the user tries to sign in. NOTE: We hope to improve the [sign-in experience for an unverified user](https://gitlab.com/gitlab-org/gitlab/-/issues/29279) in a future release. diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index 16b6424b232..75d10084328 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -49,7 +49,7 @@ The following storage usage statistics are available to an owner: Excess storage usage is the amount that a project's repository exceeds the free storage quota. If no purchased storage is available the project is locked. You cannot push changes to a locked project. -To unlock a project you must [purchase more storage](../subscriptions/gitlab_com/index.md#purchase-more-storage) +To unlock a project you must [purchase more storage](../subscriptions/gitlab_com/index.md#purchase-more-storage-and-transfer) for the namespace. When the purchase is completed, locked projects are automatically unlocked. The amount of purchased storage available must always be greater than zero. diff --git a/doc/user/workspace/img/1.1-Instance_overview.png b/doc/user/workspace/img/1.1-Instance_overview.png Binary files differdeleted file mode 100644 index a3c642cda3f..00000000000 --- a/doc/user/workspace/img/1.1-Instance_overview.png +++ /dev/null diff --git a/doc/user/workspace/img/1.2-Groups_overview.png b/doc/user/workspace/img/1.2-Groups_overview.png Binary files differdeleted file mode 100644 index 7771e5f4c3c..00000000000 --- a/doc/user/workspace/img/1.2-Groups_overview.png +++ /dev/null diff --git a/doc/user/workspace/img/1.3-Admin.png b/doc/user/workspace/img/1.3-Admin.png Binary files differdeleted file mode 100644 index 5f531e4ef5e..00000000000 --- a/doc/user/workspace/img/1.3-Admin.png +++ /dev/null diff --git a/doc/user/workspace/img/Admin_Settings.png b/doc/user/workspace/img/Admin_Settings.png Binary files differdeleted file mode 100644 index b0d13f43ccb..00000000000 --- a/doc/user/workspace/img/Admin_Settings.png +++ /dev/null diff --git a/doc/user/workspace/img/hardware_settings.png b/doc/user/workspace/img/hardware_settings.png Binary files differdeleted file mode 100644 index 919ff46f8c8..00000000000 --- a/doc/user/workspace/img/hardware_settings.png +++ /dev/null diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index cf35f082880..0befcbe25d2 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/index.md @@ -14,6 +14,9 @@ As with all projects, the items mentioned on this page are subject to change or The development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc. +NOTE: +Workspace is currently in development. + Workspace will be above the [top-level namespaces](../group/index.md#namespaces) for you to manage everything you do as a GitLab administrator, including: @@ -27,33 +30,12 @@ Our goal is to reach feature parity between SaaS and self-managed installations, - Hardware Controls. For functionality that does not apply to groups, Hardware Controls are only applicable to self-managed installations. There is one Hardware Controls section per installation. -NOTE: -Workspace is currently in development. - -## Demo: New hierarchy concept for groups and projects for epics - -The following demo introduces the new hierarchy concept for groups and projects for epics. - -<div class="video-fallback"> - See the video: <a href="https://www.youtube.com/embed/fE74lsG_8yM">Consolidating groups and projects update (2021-08-23)</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube.com/embed/fE74lsG_8yM" frameborder="0" allowfullscreen="true"> </iframe> -</figure> - -## Concept previews - -The following provide a preview to the Workspace concept. - - - - - - - - +To learn about the current state of workspace development, +see [epic 4257](https://gitlab.com/groups/gitlab-org/-/epics/4257). - +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a video introduction to the new hierarchy concept for groups and projects for epics, see +[Consolidating groups and projects update (August 2021)](https://www.youtube.com/watch?v=fE74lsG_8yM). ## Related topics |
