diff options
Diffstat (limited to 'doc/user')
202 files changed, 2724 insertions, 2717 deletions
diff --git a/doc/user/admin_area/analytics/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index ede9e342a2e..df34cd03d71 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -59,7 +59,7 @@ You can use Group DevOps Adoption to: - Identify specific subgroups that are lagging in their adoption of GitLab features, so you can guide them on their DevOps journey. -- Find subgroups that have adopted certain features, and provide guidance to other subgroups on +- Find subgroups that have adopted certain features, and provide guidance to other subgroups on how to use those features. - Verify if you are getting the return on investment that you expected from GitLab. diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index 0b264ef22b9..2083cb06f93 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -2,7 +2,6 @@ stage: none group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: howto disqus_identifier: 'https://docs.gitlab.com/ee/customization/branded_login_page.html' --- @@ -28,8 +27,6 @@ GitLab pipeline emails also display the custom logo. ## Favicon -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14497) in GitLab 11.0. - By default, the favicon (used by the browser as the tab icon, as well as the CI status icon) uses the GitLab logo, but this can be customized with any icon desired. It must be a 32x32 `.png` or `.ico` image. @@ -39,8 +36,6 @@ of the page to activate it in the GitLab instance. ## System header and footer messages -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55057) from GitLab Premium to GitLab Free in 11.9. - You can add a small header message, a small footer message, or both, to the interface of your GitLab instance. These messages appear on all projects and pages of the instance, including the sign in / sign up page. The default color is white text on diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index d79508e5b68..f9b5168fb08 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +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 type: howto --- diff --git a/doc/user/admin_area/geo_nodes.md b/doc/user/admin_area/geo_nodes.md index f2b899f0be9..b3b2c14adbd 100644 --- a/doc/user/admin_area/geo_nodes.md +++ b/doc/user/admin_area/geo_nodes.md @@ -2,7 +2,6 @@ stage: Enablement group: Geo info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: howto --- # Geo sites Admin Area **(PREMIUM SELF)** @@ -50,20 +49,27 @@ download them all at once; so, GitLab places an upper limit on the concurrency o these operations. How long the backfill takes is dependent on the maximum concurrency, but higher -values place more strain on the **primary** site. From [GitLab 10.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3107), -the limits are configurable. If your **primary** site has lots of surplus capacity, +values place more strain on the **primary** site. The limits are configurable. +If your **primary** site has lots of surplus capacity, you can increase the values to complete backfill in a shorter time. If it's under heavy load and backfill reduces its availability for normal requests, you can decrease them. -## Using a different URL for synchronization +## Set up the internal URLs + +> Setting up internal URLs in secondary sites was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77179) in GitLab 14.7. + +You can set up a different URL for synchronization between the primary and secondary site. The **primary** site's Internal URL is used by **secondary** sites to contact it (to sync repositories, for example). The name Internal URL distinguishes it from [External URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-the-external-url-for-gitlab), which is used by users. Internal URL does not need to be a private address. -Internal URL defaults to external URL, but you can also customize it: +When [Geo secondary proxying](../../administration/geo/secondary_proxy/index.md) is enabled, +the primary uses the secondary's internal URL to contact it directly. + +The internal URL defaults to external URL. To change it: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. @@ -71,6 +77,9 @@ Internal URL defaults to external URL, but you can also customize it: 1. Edit the internal URL. 1. Select **Save changes**. +When enabled, the Admin Area for Geo shows replication details for each site directly +from the primary site's UI, and through the Geo secondary proxy, if enabled. + WARNING: We recommend using an HTTPS connection while configuring the Geo sites. To avoid breaking communication between **primary** and **secondary** sites when using @@ -85,7 +94,7 @@ to the internal URL instead of the external one. ## Multiple secondary sites behind a load balancer -In GitLab 11.11, **secondary** sites can use identical external URLs if +**Secondary** sites can use identical external URLs if a unique `name` is set for each Geo site. The `gitlab.rb` setting `gitlab_rails['geo_node_name']` must: diff --git a/doc/user/admin_area/img/admin_labels.png b/doc/user/admin_area/img/admin_labels.png Binary files differdeleted file mode 100644 index a9ea059ccf9..00000000000 --- a/doc/user/admin_area/img/admin_labels.png +++ /dev/null diff --git a/doc/user/admin_area/img/admin_labels_v14_7.png b/doc/user/admin_area/img/admin_labels_v14_7.png Binary files differnew file mode 100644 index 00000000000..01a4ea0c2cc --- /dev/null +++ b/doc/user/admin_area/img/admin_labels_v14_7.png diff --git a/doc/user/admin_area/img/license_upload_v13_12.png b/doc/user/admin_area/img/license_upload_v13_12.png Binary files differdeleted file mode 100644 index 81dc162c1f0..00000000000 --- a/doc/user/admin_area/img/license_upload_v13_12.png +++ /dev/null diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index b0f38e8cfb9..ba0802b3b7a 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -110,13 +110,13 @@ You can combine the filter options. For example, to list only public projects wi #### 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.7. +> - [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.7 and later) or the **Deleted projects** tab (GitLab 14.6 and earlier). +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: @@ -202,6 +202,8 @@ The following data is included in the export: - Access level ([Project](../permissions.md#project-members-permissions) and [Group](../permissions.md#group-members-permissions)) - Date of last activity ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345388) in GitLab 14.6). For a list of activities that populate this column, see the [Users API documentation](../../api/users.md#get-user-activities-admin-only). +Only the first 100,000 user accounts are exported. +  #### Users statistics diff --git a/doc/user/admin_area/labels.md b/doc/user/admin_area/labels.md index b5dbf835d70..93114186e75 100644 --- a/doc/user/admin_area/labels.md +++ b/doc/user/admin_area/labels.md @@ -7,13 +7,12 @@ type: reference # Labels administration **(FREE SELF)** -In the Admin Area, you can manage labels for the GitLab instance. For more details, see [Labels](../project/labels.md). +To manage labels for the GitLab instance, select **Labels** (**{labels}**) from the Admin Area sidebar. For more details on how to manage labels, see [Labels](../project/labels.md). -## Default Labels +Labels created in the Admin Area are automatically added to new projects. +Updating or adding labels in the Admin Area does not modify labels in existing projects. -Labels created in the Admin Area become available to each _new_ project. - - + <!-- ## Troubleshooting diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index d984f6f4092..c3f0c94db21 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -2,173 +2,179 @@ stage: Growth group: Conversion info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: howto --- -# Activating GitLab EE **(PREMIUM SELF)** +# Activate GitLab Enterprise Edition (EE) **(PREMIUM SELF)** -To enable features of GitLab Enterprise Edition (EE), you need to activate your instance. Ensure you are running an enterprise edition. To verify, sign in to GitLab and browse to `/help`. The GitLab edition and version are listed at the top of the **Help** page. +When you install a new GitLab instance without a license, it only has the Free features +enabled. To enable all features of GitLab Enterprise Edition (EE), activate +your instance with an activation code or a license file. When [the license expires](#what-happens-when-your-license-expires), +some functionality is locked. -If you are running GitLab Community Edition (CE), upgrade your installation to GitLab Enterprise Edition (EE). For more details, see [Upgrading between editions](../../update/index.md#upgrading-between-editions). If you have questions or need assistance upgrading from GitLab CE to EE please [contact GitLab Support](https://about.gitlab.com/support/#contact-support). +## Verify your GitLab edition -As of GitLab Enterprise Edition 9.4.0, a newly-installed instance without an -uploaded license only has the Free features active. A trial license activates all Ultimate features, but after [the trial expires](#what-happens-when-your-license-expires), some functionality -is locked. +To activate your instance, make sure you are running GitLab Enterprise Edition (EE). -## Activate GitLab EE with an Activation Code +To verify the edition, sign in to GitLab and select +**Help** (**{question-o}**) > **Help**. The GitLab edition and version are listed +at the top of the page. -As of GitLab Enterprise Edition 14.1, you need an activation code to activate your instance. You can obtain an activation code by [purchasing a license](https://about.gitlab.com/pricing/) or by signing up for a [free trial](https://about.gitlab.com/free-trial/). This 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. +If you are running GitLab Community Edition (CE), upgrade your installation to GitLab +EE. For more details, see [Upgrading between editions](../../update/index.md#upgrading-between-editions). +If you have questions or need assistance upgrading from GitLab CE to EE, +[contact GitLab Support](https://about.gitlab.com/support/#contact-support). -To begin the activation process with your activation code: +## 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. +You can also sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) +to copy the activation code to your clipboard. + +To activate your instance with an activation code: 1. Sign in to your GitLab self-managed instance. -1. From the top menu, select the Admin Area **{admin}**. -1. From the left sidebar, select **Subscription**. -1. Paste the activation code onto the input field. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Subscription**. +1. Enter the activation code in **Activation code**. 1. Read and accept the terms of service. 1. Select **Activate**. -## Activate GitLab EE with a License File - -If you receive a license file from GitLab (for example a new trial), you can upload it by signing into your GitLab instance as an administrator or adding it during installation. The license is a base64-encoded ASCII text file with a `.gitlab-license` extension. +## Activate GitLab EE with a license file -## Uploading your license +If you receive a license file from GitLab (for example, for a trial), you can +upload it to your instance or add it during installation. The license file is +a base64-encoded ASCII text file with a `.gitlab-license` extension. -The first time you visit your GitLab EE installation signed in as an administrator, -you should see a note urging you to upload a license with a link that takes you -to the **Subscription** area. +## Upload your license -Otherwise, to manually go to the **Subscription** area: - -1. Sign in to your GitLab self-managed instance. -1. From the top menu, select the Admin Area **{admin}**. -1. From the left sidebar, select **Subscription**, and select **Upload a license file**. +The first time you sign in to your GitLab instance, a note with a +link to the **Upload license** page should be displayed. - - *If you've received a `.gitlab-license` file:* - 1. Download the license file to your local machine. - 1. Select **Upload `.gitlab-license` file**. - 1. Select **Choose file** and select the license file. - In this example the license file is named `GitLab.gitlab-license`. - 1. Select the **Terms of Service** checkbox. - 1. Select **Upload License**. +Otherwise, to upload your license: -  +1. Sign in to GitLab as an administrator. +1. On the top bar, select **Menu > Admin**. +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 plain text, select **Enter license key** and paste the contents in + **License key**. +1. Select the **Terms of Service** checkbox. +1. Select **Upload License**. - - *If you've received your license as plain text:* - 1. Select **Enter license key**. - 1. Copy the license and paste it into the **License key** field. - 1. Select the **Terms of Service** checkbox. - 1. Select **Upload License**. +## Add your license during installation -## Add your license at install time +You can import a license file when you install GitLab. -A license can be automatically imported at install time by placing a file named -`Gitlab.gitlab-license` in `/etc/gitlab/` for Omnibus GitLab, or `config/` for source installations. +- **For installations from source** + - Place the `Gitlab.gitlab-license` file in the `config/` directory. + - To specify a custom location and filename for the license, set the + `GITLAB_LICENSE_FILE` environment variable with the path to the file: -You can also specify a custom location and filename for the license: + ```shell + export GITLAB_LICENSE_FILE="/path/to/license/file" + ``` -- Source installations should set the `GITLAB_LICENSE_FILE` environment - variable with the path to a valid GitLab Enterprise Edition license. +- **For Omnibus package** + - Place the `Gitlab.gitlab-license` file in the `/etc/gitlab/` directory. + - To specify a custom location and filename for the license, add this entry to `gitlab.rb`: - ```shell - export GITLAB_LICENSE_FILE="/path/to/license/file" - ``` - -- Omnibus GitLab installations should add this entry to `gitlab.rb`: - - ```ruby - gitlab_rails['initial_license_file'] = "/path/to/license/file" - ``` + ```ruby + gitlab_rails['initial_license_file'] = "/path/to/license/file" + ``` WARNING: -These methods only add a license at the time of installation. Use the -**{admin}** **Admin Area** in the web user interface to renew or upgrade licenses. - ---- - -After the license is uploaded, all GitLab Enterprise Edition functionality -is active until the end of the license period. When that period ends, the -instance will [fall back](#what-happens-when-your-license-expires) to Free-only -functionality. - -You can review the license details at any time by going to **Admin Area > Subscription**. - -## Notification before the license expires - -One month before the license expires, a message informing about the expiration -date is displayed to GitLab administrators. Make sure that you update your -license, otherwise you miss all the paid features if your license expires. +These methods only add a license at the time of installation. To renew or upgrade +a license, upload the license in the **Admin Area** in the web user interface. ## What happens when your license expires -When your license expires, GitLab locks down features, like Git pushes -and issue creation. Then, your instance becomes read-only and -an expiration message is displayed to all administrators. +Fifteen days before the license expires, a notification banner with the upcoming expiration +date displays to GitLab administrators. -For GitLab self-managed instances, you have a 14-day grace period +When your license expires, GitLab locks features, like Git pushes +and issue creation. Your instance becomes read-only and +an expiration message displays to all administrators. You have a 14-day grace period before this occurs. -- To resume functionality, upload a new license. -- To fall back to Free features, delete all expired licenses. +To resume functionality, [upload a new license](#upload-your-license). -### Remove a license file +To go back to Free features, [delete all expired licenses](#remove-a-license-file). + +## Remove a license file To remove a license file from a self-managed instance: -1. From the top menu, select the Admin Area **{admin}**. -1. From the left sidebar, select **Subscription**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Subscription**. 1. Select **Remove license**. -These steps may need to be repeated to completely remove all licenses, including those applied in the past. +Repeat these steps to remove all licenses, including those applied in the past. + +## View license details and history -## License history +To view your license details: -You can upload and view more than one license, but only the latest license in the current date -range is used as the active license. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Subscription**. + +You can upload and view more than one license, but only the latest license in +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 of your active subscriptions in the **Subscription history** table. +You can view all active subscriptions in the **Subscription history** table. NOTE: -In GitLab 13.6 and earlier, a notification banner about an expiring license may continue to be displayed even after a new license has been uploaded. -This happens when the newly uploaded license's start date is in the future and the expiring one is still active. +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 +is in the future and the expiring one is still active. The banner disappears after the new license becomes active. ## Troubleshooting -### There is no Subscription tab in the Admin Area +### No Subscription area in the Admin Area -If you originally installed Community Edition rather than Enterprise Edition you must -[upgrade to Enterprise Edition](../../update/index.md#community-to-enterprise-edition) -before uploading your license. +You cannot upload your license because there is no **Subscription** area. +This issue might occur if: -GitLab.com users can't upload and use a self-managed license. If you -want to use paid features on GitLab.com, you can -[purchase a separate subscription](../../subscriptions/gitlab_com/index.md). +- You're running GitLab Community Edition. Before you upload your license, you + must [upgrade to Enterprise Edition](../../update/index.md#community-to-enterprise-edition). +- You're using GitLab.com. You cannot upload a self-managed license to GitLab.com. + To use paid features on GitLab.com, [purchase a separate subscription](../../subscriptions/gitlab_com/index.md). ### Users exceed license limit upon renewal -If you've added new users to your GitLab instance prior to renewal, you may need to -purchase additional seats to cover those users. If this is the case, and a license -without enough users is uploaded, GitLab displays a message prompting you to purchase -additional users. More information on how to determine the required number of users -and how to add additional seats can be found in the -[licensing FAQ](https://about.gitlab.com/pricing/licensing-faq/). +GitLab displays a message prompting you to purchase +additional users. This issue occurs if you upload a license that does not have enough +users to cover the number of users in your instance. + +To fix this issue, purchase additional seats to cover those users. +For more information, read the [licensing FAQ](https://about.gitlab.com/pricing/licensing-faq/). -In GitLab 14.2 and later, for instances that use a license file, you can exceed the number of purchased users and still activate your license. +In GitLab 14.2 and later, for instances that use a license file, the following +rules apply: -- If the users over license are less than or equal to 10% of the users in the subscription, - the license is applied and the overage is paid in the next true-up. -- If the users over license are more than 10% of the users in the subscription, +- If the users over license are less than or equal to 10% of the users in the license + file, the license is applied and you pay the overage in the next renewal. +- If the users over license are more than 10% of the users in the license file, you cannot apply the license without purchasing more users. -For example, if you purchased a license for 100 users, you can have 110 users when you activate -your license. However, if you have 111, you must purchase more users before you can activate. +For example, if you purchase a license for 100 users, you can have 110 users when you activate +your license. However, if you have 111 users, you must purchase more users before you can activate +the license. -### There is a connectivity issue +### Cannot activate instance due to connectivity error -In GitLab 14.1 and later, to activate your subscription, your GitLab instance must be connected to the internet. +In GitLab 14.1 and later, to activate your subscription with an activation code, +your GitLab instance must be connected to the internet. -If you have an offline or airgapped environment, you can [upload a license file](license.md#activate-gitlab-ee-with-a-license-file) instead. +If you have an offline or airgapped environment, +[upload a license file](license.md#activate-gitlab-ee-with-a-license-file) instead. -If you have questions or need assistance activating your instance, please [contact GitLab Support](https://about.gitlab.com/support/#contact-support). +If you have questions or need assistance activating your instance, +[contact GitLab Support](https://about.gitlab.com/support/#contact-support). diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index 3f15bd5b4e6..ee38664fa66 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +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 type: howto --- @@ -100,7 +100,7 @@ A blocked user can be unblocked from the Admin Area. To do this: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. -1. Select on the **Blocked** tab. +1. Select the **Blocked** tab. 1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown. 1. Select **Unblock**. @@ -111,6 +111,16 @@ The user's state is set to active and they consume a NOTE: Users can also be unblocked using the [GitLab API](../../api/users.md#unblock-user). +The unblock option may be unavailable for LDAP users. To enable the unblock option, +the LDAP identity first needs to be deleted: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Users**. +1. Select the **Blocked** tab. +1. Select a user. +1. Select the **Identities** tab. +1. Find the LDAP provider and select **Delete**. + ## Activate and deactivate users GitLab administrators can deactivate and activate users. diff --git a/doc/user/admin_area/monitoring/background_migrations.md b/doc/user/admin_area/monitoring/background_migrations.md index 66001a987a4..260a8515a1a 100644 --- a/doc/user/admin_area/monitoring/background_migrations.md +++ b/doc/user/admin_area/monitoring/background_migrations.md @@ -145,6 +145,8 @@ or [manually finish it](#manually-finishing-a-batched-background-migration). ### Manually finishing a batched background migration +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62634) in GitLab 14.1 + If you need to manually finish a batched background migration due to an error, you can run: diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 1d2d7be146c..75905d60c4e 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -6,12 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Health Check **(FREE SELF)** -> - Liveness and readiness probes were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10416) in GitLab 9.1. -> - The `health_check` endpoint was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3888) in GitLab 8.8 and was -> deprecated in GitLab 9.1. -> - [Access token](#access-token-deprecated) has been deprecated in GitLab 9.4 -> in favor of [IP whitelist](#ip-whitelist). - GitLab provides liveness and readiness probes to indicate service health and reachability to required services. These probes report on the status of the database connection, Redis connection, and access to the file system. These @@ -137,28 +131,9 @@ On failure, the endpoint returns a `503` HTTP status code. This check is being exempt from Rack Attack. -## Access token (Deprecated) - -NOTE: -Access token has been deprecated in GitLab 9.4 in favor of [IP whitelist](#ip-whitelist). - -An access token needs to be provided while accessing the probe endpoints. You can -find the current accepted token in the user interface: - -1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Monitoring > Health Check**. (`admin/health_check`) - - - -The access token can be passed as a URL parameter: - -```plaintext -https://gitlab.example.com/-/readiness?token=ACCESS_TOKEN -``` +## Sidekiq -NOTE: -In case the database or Redis service are inaccessible, the probe endpoints response is not guaranteed to be correct. -You should switch to [IP whitelist](#ip-whitelist) from deprecated access token to avoid it. +Learn how to configure the [Sidekiq health checks](../../../administration/sidekiq_health_check.md). <!-- ## Troubleshooting diff --git a/doc/user/admin_area/monitoring/img/health_check_token.png b/doc/user/admin_area/monitoring/img/health_check_token.png Binary files differdeleted file mode 100644 index 8d4cf710176..00000000000 --- a/doc/user/admin_area/monitoring/img/health_check_token.png +++ /dev/null diff --git a/doc/user/admin_area/review_abuse_reports.md b/doc/user/admin_area/review_abuse_reports.md index 6a8b48e7ba7..4c5a241ab18 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: Access +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 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 5868f20d0d8..f748f575419 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -36,17 +36,19 @@ can create in their personal namespace: ## Max attachment size -You can change the maximum file size for attachments in comments and replies in GitLab: +The maximum file size for attachments in GitLab comments and replies is 10 MB. +To change the maximum attachment size: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. 1. Increase or decrease by changing the value in **Maximum attachment size (MB)**. -NOTE: If you choose a size larger than the configured value for the web server, -you may receive errors. See the [troubleshooting section](#troubleshooting) for more +you may receive errors. Read the [troubleshooting section](#troubleshooting) for more details. +For GitLab.com repository size limits, read [accounts and limit settings](../../gitlab_com/index.md#account-and-limit-settings). + ## Max push size You can change the maximum push size for your repository: @@ -64,17 +66,20 @@ Use [Git LFS](../../../topics/git/lfs/index.md) to add large files to a reposito ## Max import size -You can change the maximum file size for imports in GitLab: +> [Modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to unlimited in GitLab 13.8. + +To modify the maximum file size for imports in GitLab: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. 1. Increase or decrease by changing the value in **Maximum import size (MB)**. -NOTE: If you choose a size larger than the configured value for the web server, you may receive errors. See the [troubleshooting section](#troubleshooting) for more details. +For GitLab.com repository size limits, read [accounts and limit settings](../../gitlab_com/index.md#account-and-limit-settings). + ## Personal access token prefix > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20968) in GitLab 13.7. @@ -118,6 +123,9 @@ For instance, consider the following workflow: 1. Before you exceed available storage, you set up a limit of 10 GB per repository. +NOTE: +For GitLab.com repository size limits, read [accounts and limit settings](../../gitlab_com/index.md#account-and-limit-settings). + ### How it works Only a GitLab administrator can set those limits. Setting the limit to `0` means @@ -150,9 +158,6 @@ wiki, packages, or snippets. The repository size limit applies to both private a For details on manually purging files, see [reducing the repository size using Git](../../project/repository/reducing_the_repo_size_using_git.md). -NOTE: -For GitLab.com repository size limits, see [accounts and limit settings](../../gitlab_com/index.md#account-and-limit-settings). - ## Troubleshooting ### 413 Request Entity Too Large @@ -196,11 +201,7 @@ To set a limit on how long these sessions are valid: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1007) in GitLab 14.6 [with a flag](../../../administration/feature_flags.md) named `ff_limit_ssh_key_lifetime`. Disabled by default. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/346753) in GitLab 14.6. - -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 `ff_limit_ssh_key_lifetime`. -On GitLab.com, this feature is not available. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/1007) in GitLab 14.7. [Feature flag ff_limit_ssh_key_lifetime](https://gitlab.com/gitlab-org/gitlab/-/issues/347408) removed. Users can optionally specify a lifetime for [SSH keys](../../../ssh/index.md). diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index c6ebce03b06..e18808ffb41 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -134,44 +134,9 @@ A new pipeline must run before the latest artifacts can expire and be deleted. NOTE: All application settings have a [customizable cache expiry interval](../../../administration/application_settings_cache.md) which can delay the settings affect. -## Shared runners pipeline minutes quota **(PREMIUM SELF)** +## Shared runners CI/CD minutes -> [Moved](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) to GitLab Premium in 13.9. - -If you have enabled shared runners for your GitLab instance, you can limit their -usage by setting a maximum number of pipeline minutes that a group can use on -shared runners per month. Setting this to `0` (default value) grants -unlimited pipeline minutes. While build limits are stored as minutes, the -counting is done in seconds. Usage resets on the first day of each month. -On GitLab.com, the quota is calculated based on your -[subscription plan](../../../subscriptions/gitlab_com/index.md#ci-pipeline-minutes). - -To change the pipelines minutes quota: - -1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. -1. Expand **Continuous Integration and Deployment**. -1. In the **Pipeline minutes quota** box, enter the maximum number of minutes. -1. Click **Save changes** for the changes to take effect. - -While the setting in the Admin Area has a global effect, as an administrator you can -also change each group's pipeline minutes quota to override the global value. - -1. Navigate to the **Admin Area > Overview > Groups** and hit the **Edit** - button for the group you wish to change the pipeline minutes quota. -1. In the **Pipeline Minutes Quota** box, enter the maximum number of minutes. -1. Click **Save changes** for the changes to take effect. - -Once saved, you can see the build quota in the group settings. -The quota can also be viewed in the project settings if shared runners -are enabled. - - - -You can see an overview of the pipeline minutes quota of all projects of -a group in the **Usage Quotas** page available to the group page settings list. - - +As an administrator you can set either a global or namespace-specific limit on the number of [CI/CD minutes](../../../ci/pipelines/cicd_minutes.md) you can use. ## Archive jobs @@ -303,13 +268,12 @@ To set the maximum file size: 1. Enter the maximum file size, in bytes. 1. Click **Save size limits**. -## Runner registration +## Prevent users from registering runners + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22225) in GitLab 14.1. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22225) in GitLab 14.1. -> - [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. +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../feature_flags.md) named `runner_registration_control`. On GitLab.com, this feature is not available. GitLab administrators can adjust who is allowed to register runners, by showing and hiding areas of the UI. @@ -318,29 +282,14 @@ By default, all members of a project and group are able to register runners. To change this: 1. On the top bar, select **Menu > Admin**. -1. Go to **Settings > CI/CD**. -1. Expand the **Runner registration** section. -1. Select the desired options. -1. Click **Save changes**. - -When the registration sections are hidden in the UI, members of the project or group that need to register runners must contact the administrators. - -This feature is currently behind a feature flag. -To enable it: - -**In Omnibus installations:** - -1. Enter the Rails console: - - ```shell - sudo gitlab-rails console - ``` - -1. Flip the switch and enable the feature flag: +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Runner registration**. +1. Clear the checkbox if you don't want to display runner registration + information in the UI for group or project members. +1. Select **Save changes**. - ```ruby - Feature.enable(:runner_registration_control) - ``` +WARNING: +When the registration sections are hidden in the UI, members of the project or group that need to register runners must contact the administrators. If you plan to prevent registration, ensure users have access to the runners they need to run jobs. ## Troubleshooting diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 5f007c83e4b..4fd7c59ef24 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: Access +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 --- @@ -29,39 +29,13 @@ functionality that render cross-project data. That includes: Labels, Milestones, Merge requests). - Global and Group search are disabled. -This is to prevent performing to many requests at once to the external +This is to prevent performing too many requests at once to the external authorization service. Whenever access is granted or denied this is logged in a log file called `external-policy-access-control.log`. Read more about the logs GitLab keeps in the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/logs.html). -## Configuration - -The external authorization service can be enabled by an administrator: - -1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Settings > General**: -  - -The available required properties are: - -- **Service URL**: The URL to make authorization requests to. When leaving the - URL blank, cross project features remain available while still being able - to specify classification labels for projects. -- **External authorization request timeout**: The timeout after which an - authorization request is aborted. When a request times out, access is denied - to the user. -- **Client authentication certificate**: The certificate to use to authenticate - with the external authorization service. -- **Client authentication key**: Private key for the certificate when - authentication is required for the external authorization service, this is - encrypted when stored. -- **Client authentication key password**: Passphrase to use for the private key - when authenticating with the external service this is encrypted when stored. -- **Default classification label**: The classification label to use when - requesting authorization if no specific label is defined on the project - When using TLS Authentication with a self signed certificate, the CA certificate needs to be trusted by the OpenSSL installation. When using GitLab installed using Omnibus, learn to install a custom CA in the @@ -69,6 +43,16 @@ using Omnibus, learn to install a custom CA in the Alternatively, learn where to install custom certificates by using `openssl version -d`. +## Configuration + +The external authorization service can be enabled by an administrator: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. +1. Expand **External authorization**. +1. Complete the fields. +1. Select **Save changes**. + ## How it works When GitLab requests access, it sends a JSON POST request to the external diff --git a/doc/user/admin_area/settings/img/admin_project_quota_view.png b/doc/user/admin_area/settings/img/admin_project_quota_view.png Binary files differdeleted file mode 100644 index 8320be860da..00000000000 --- a/doc/user/admin_area/settings/img/admin_project_quota_view.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/external_authorization_service_settings.png b/doc/user/admin_area/settings/img/external_authorization_service_settings.png Binary files differdeleted file mode 100644 index 9b8658fd1a1..00000000000 --- a/doc/user/admin_area/settings/img/external_authorization_service_settings.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/file_template_admin_area_v14_0.png b/doc/user/admin_area/settings/img/file_template_admin_area_v14_0.png Binary files differdeleted file mode 100644 index 33fce8a2b77..00000000000 --- a/doc/user/admin_area/settings/img/file_template_admin_area_v14_0.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/group_pipelines_quota.png b/doc/user/admin_area/settings/img/group_pipelines_quota.png Binary files differdeleted file mode 100644 index 318527426bd..00000000000 --- a/doc/user/admin_area/settings/img/group_pipelines_quota.png +++ /dev/null diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 7945e5d790f..2820f3ae9df 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -64,7 +64,7 @@ The **CI/CD** settings contain: This pipeline configuration is run after the project's own configuration. - [Package Registry](continuous_integration.md#package-registry-configuration) - Settings related to the use and experience of using the GitLab Package Registry. Some - [risks are involved](../../packages/container_registry/index.md#use-with-external-container-registries) + [risks are involved](../../packages/container_registry/reduce_container_registry_storage.md#use-with-external-container-registries) in enabling some of these settings. ### Geo **(PREMIUM SELF)** @@ -91,7 +91,8 @@ The **Integrations** settings contain: Slack integration allows you to interact with GitLab via slash commands in a chat window. This option is only available on GitLab.com, though it may be [available for self-managed instances in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/28164). -- [Third party offers](third_party_offers.md) - Control the display of third-party offers. +- [Customer experience improvement and third-party offers](third_party_offers.md) - + Control the display of customer experience improvement content and third-party offers. - [Snowplow](../../../development/snowplow/index.md) - Configure the Snowplow integration. - [Google GKE](../../project/clusters/add_gke_clusters.md) - Google GKE integration enables you to provision GKE clusters from GitLab. diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index 71eb7bbbdc9..51695ef7fd2 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -7,7 +7,8 @@ type: reference # Instance template repository **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5986) in GitLab 11.3. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) to behave like group-level templates in GitLab 13.9. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321247) in GitLab 14.0. In hosted systems, enterprises often have a need to share their own templates across teams. This feature allows an administrator to pick a project to be the @@ -21,10 +22,9 @@ To select a project to serve as the custom template repository: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Templates**. -1. Select the project: - -  - +1. Expand **Templates** +1. From the dropdown list, select the project to use as the template repository. +1. Select **Save changes**. 1. Add custom templates to the selected repository. After you add templates, you can use them for the entire instance. diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 8cee63b0ac2..52b20d5b437 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -2,7 +2,6 @@ stage: none group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference --- # Sign-in restrictions **(FREE SELF)** @@ -21,8 +20,11 @@ To access sign-in restriction settings: You can restrict the password authentication for web interface and Git over HTTP(S): -- **Web interface**: When this feature is disabled, the **Standard** sign-in tab is removed and an [external authentication provider](../../../administration/auth/index.md) must be used. -- **Git over HTTP(S)**: When this feature is disabled, a [Personal Access Token](../../profile/personal_access_tokens.md) must be used to authenticate. +- **Web interface**: When this feature is disabled, the **Standard** sign-in tab + is removed and an [external authentication provider](../../../administration/auth/index.md) + must be used. +- **Git over HTTP(S)**: When this feature is disabled, a [Personal Access Token](../../profile/personal_access_tokens.md) + or LDAP password must be used to authenticate. In the event of an external authentication provider outage, use the [GitLab Rails console](../../../administration/operations/rails_console.md) to [re-enable the standard web sign-in form](../../../administration/troubleshooting/gitlab_rails_cheat_sheet.md#re-enable-standard-web-sign-in-form). This configuration can also be changed over the [Application settings REST API](../../../api/settings.md#change-application-settings) while authenticating with an administrator account's personal access token. diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index c9d48b14a6c..04ec9ed652f 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.md @@ -1,11 +1,11 @@ --- -stage: none -group: unassigned +stage: Manage +group: Workspace info: To 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 --- -# Third-party offers **(FREE SELF)** +# Customer experience improvement and third-party offers **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20379) in GitLab 11.1. @@ -13,11 +13,14 @@ Within GitLab, we inform users of available third-party offers they might find v to enhance the development of their projects. An example is the Google Cloud Platform free credit for using [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/). -To toggle the display of third-party offers: +Furthermore, we use content to improve customer experience. An example are the personalization +questions when creating a group. + +To toggle the display of customer experience improvement content and third-party offers: 1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Settings**, and expand **Third-party offers**. -1. Select **Do not display offers from third parties**. +1. On the left sidebar, select **Settings**, and expand **Customer experience improvement & third-party offers**. +1. Select **Do not display content for customer experience improvement and offers from third parties**. 1. Select **Save changes**. <!-- ## Troubleshooting 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 1087f50b215..82e0d3d27d4 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -188,6 +188,9 @@ To restrict visibility levels for projects, snippets, and selected pages: 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. In the **Restricted visibility levels** section, select the desired visibility levels to restrict. + If you restrict the **Public** level: + - User profiles are only visible to logged in users via the Web interface. + - User attributes are only visible to authenticated users via the GraphQL API. 1. Select **Save changes**. For more details on project visibility, see diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index f083f886924..1bc0c2b8fb0 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -10,8 +10,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/38318) to CI/CD Analytics in GitLab 12.8. -GitLab tracks the history of your pipeline successes and failures, as well as how long each pipeline -ran. To view this information for a project, go to **Analytics > CI/CD Analytics**. +CI/CD Analytics shows the history of your pipeline successes and failures, as well as how long each pipeline +ran. View successful pipelines: @@ -27,6 +27,13 @@ on when the pipeline was created. The total pipeline calculation includes child pipelines and pipelines that failed with invalid YAML. If you are interested in filtering pipelines based on other attributes, consider using the [Pipelines API](../../api/pipelines.md#list-project-pipelines). +## View CI/CD analytics + +To view CI/CD analytics: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > CI/CD Analytics**. + ## DevOps Research and Assessment (DORA) key metrics **(ULTIMATE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.7. diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index 496e768456f..066b45aeb39 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -17,16 +17,10 @@ requests, and: - Take action on individual merge requests. - Reduce overall cycle time. -NOTE: -Initially, no data appears. Data is populated as users comment on open merge requests. - -## Overview - Code Review Analytics 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. -To access Code Review Analytics, from your project's menu, go to **Analytics > Code Review**. - -You can filter the list of merge requests by milestone and label. +NOTE: +Initially, no data appears. Data is populated as users comment on open merge requests.  @@ -36,6 +30,14 @@ The table is sorted by: or to be broken down into smaller parts. - Other columns: Display the author, approvers, comment count, and line change (-/+) counts. +## View Code Review Analytics + +To view Code Review Analytics: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Code Review**. +1. Filter merge requests by milestone and label. + ## Use cases This feature is designed for [development team leaders](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#delaney-development-team-lead) diff --git a/doc/user/analytics/img/repository_analytics_v13_0.png b/doc/user/analytics/img/repository_analytics_v13_0.png Binary files differdeleted file mode 100644 index dd943b4f44d..00000000000 --- a/doc/user/analytics/img/repository_analytics_v13_0.png +++ /dev/null diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 6a157dbb5ae..01ee9857060 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -23,7 +23,7 @@ in one place. GitLab provides several analytics features at the group level. Some of these features require you to use a higher tier than GitLab Free. -- [Application Security](../application_security/security_dashboard/#group-security-dashboard) +- [Application Security](../application_security/security_dashboard/index.md) - [Contribution](../group/contribution_analytics/index.md) - [DevOps Adoption](../group/devops_adoption/index.md) - [Insights](../group/insights/index.md) @@ -36,7 +36,7 @@ GitLab provides several analytics features at the group level. Some of these fea You can use GitLab to review analytics at the project level. Some of these features require you to use a higher tier than GitLab Free. -- [Application Security](../application_security/security_dashboard/#project-security-dashboard) +- [Application Security](../application_security/security_dashboard/index.md) - [CI/CD](ci_cd_analytics.md) - [Code Review](code_review_analytics.md) - [Insights](../project/insights/index.md) diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md index af7307eab39..6aa2f594532 100644 --- a/doc/user/analytics/issue_analytics.md +++ b/doc/user/analytics/issue_analytics.md @@ -5,11 +5,11 @@ group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Issue Analytics **(PREMIUM)** +# Issue analytics for projects **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in GitLab 12.9. -Issue Analytics is a bar graph which illustrates the number of issues created each month. +Issue analytics is a bar graph which illustrates the number of issues created each month. The default time span is 13 months, which includes the current month, and the 12 months prior. diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index 936504187b4..5fd4a567b58 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -4,38 +4,36 @@ group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Repository Analytics **(FREE)** +# Repository analytics for projects **(FREE)** -Get high-level overview of the project's Git repository. +Use repository analytics to view information about a project's Git repository: - +- Programming languages used in the repository. +- Code coverage history from last 3 months ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33743) in GitLab 13.1). +- Commit statistics (last month). +- Commits per day of month. +- Commits per weekday. +- Commits per day hour (UTC). -## Availability +Repository analytics is part of [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-foss). It's available to anyone who has permission to clone the repository. -Repository Analytics is part of [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-foss). It's available to anyone who has permission to clone the repository. - -The feature requires: +Repository analytics requires: - An initialized Git repository. - At least one commit in the default branch (`master` by default). -## Overview - -You can find Repository Analytics in the project's sidebar. To access the page, go to **{chart}** **Analytics > Repository**. - NOTE: -Without a Git commit in the default branch, the menu item won't be visible. +Without a Git commit in the default branch, the menu item isn't visible. Commits in a project's [wiki](../project/wiki/index.md#track-wiki-events) are not included in the analysis. -### Charts +## View repository analytics + +To review repository analytics for a project: -The data in the charts are queued. Background workers update the charts 10 minutes after each commit in the default branch. Depending on the size of the GitLab installation, it may take longer for data to refresh due to variations in the size of background job queues. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Repository**. -Available charts: +## How repository analytics chart data is updated -- Programming languages used in the repository -- Code coverage history (last 3 months) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33743) in GitLab 13.1) -- Commit statistics (last month) -- Commits per day of month -- Commits per weekday -- Commits per day hour (UTC) +Data in the charts are queued. Background workers update the charts 10 minutes after each commit in the default branch. +Depending on the size of the GitLab installation, it may take longer for data to refresh due to variations in the size of background job queues. diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index cb6b2e49f60..6bad374c371 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -4,31 +4,34 @@ group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Value Stream Analytics **(FREE)** +# Value stream analytics for projects **(FREE)** -> - Introduced as Cycle Analytics prior to GitLab 12.3 at the project level. +> - Introduced as cycle analytics prior to GitLab 12.3 at the project level. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12077) in GitLab Premium 12.3 at the group level. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23427) from Cycle Analytics to Value Stream Analytics in GitLab 12.8. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23427) from cycle analytics to value stream analytics in GitLab 12.8. -Value Stream Analytics measures the time spent to go from an +Value stream analytics measures the time spent to go from an [idea to production](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) -(also known as cycle time) for each of your projects or groups. Value Stream Analytics displays the median time +(also known as cycle time) for each of your projects or groups. Value stream analytics displays the median time spent in each stage defined in the process. -You can use Value Stream Analytics to determine the velocity of a given +You can use value stream analytics to determine the velocity of a given project. It points to bottlenecks in the development process, enabling management to uncover, triage, and identify the root cause of slowdowns in the software development life cycle. -For information about how to contribute to the development of Value Stream Analytics, see our [contributor documentation](../../development/value_stream_analytics.md). +For information about how to contribute to the development of value stream analytics, see our [contributor documentation](../../development/value_stream_analytics.md). -Project-level Value Stream Analytics is available by using **Project > Analytics > Value Stream**. +To access value stream analytics for a project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Value stream**. NOTE: -[Group-level Value Stream Analytics](../group/value_stream_analytics) is also available. +[Value stream analytics for groups](../group/value_stream_analytics) is also available. ## Default stages -The stages tracked by Value Stream Analytics by default represent the [GitLab flow](../../topics/gitlab_flow.md). You can customize these stages in group-level Value Stream Analytics. +The stages tracked by value stream analytics by default represent the [GitLab flow](../../topics/gitlab_flow.md). You can customize these stages in value stream analytics for groups. - **Issue** (Tracker) - Time to schedule an issue (by milestone or by adding it to an issue board) @@ -43,7 +46,7 @@ The stages tracked by Value Stream Analytics by default represent the [GitLab fl - **Staging** (Continuous Deployment) - Time between merging and deploying to production -## Filter Value Stream Analytics data +## Filter value stream analytics data > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326701) in GitLab 14.3 @@ -60,7 +63,7 @@ To filter results: 1. Select a parameter. 1. Select a value. To find a value in the list, enter the value name. - + ### Date ranges @@ -72,7 +75,7 @@ from the date picker (default: last 30 days). > Sorting the stage table [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335974) in GitLab 14.4. - + The stage table shows a list of related workflow items for the selected stage. This can include: @@ -108,18 +111,18 @@ The **Time** metrics near the top of the page are measured as follows: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) in GitLab 11.3. -Value Stream Analytics exposes two deployment related metrics near the top of the page: +Value stream analytics exposes two deployment related metrics near the top of the page: - **Deploys:** The number of successful deployments in the date range. - **Deployment Frequency:** The average number of successful deployments. The deployment metrics calculation uses the same method as the -[group-level Value Stream Analytics](../group/value_stream_analytics/index.md#how-metrics-are-measured). +[value stream analytics for groups](../group/value_stream_analytics/index.md#how-metrics-are-measured). Both of them are based on the [DORA API](../../api/dora/metrics.md#devops-research-and-assessment-dora-key-metrics-api). ## How the stages are measured -Value Stream Analytics uses start events and end events to measure the time that an issue or merge request spends in each stage. +Value stream analytics uses start events and end events to measure the time that an issue or merge request spends in each stage. For example, a stage might start when one label is added to an issue and end when another label is added. Items aren't included in the stage time calculation if they have not reached the end event. @@ -143,7 +146,7 @@ How this works: 1. For the remaining pairs, review information needed for stages, including issue creation date and merge request merge time. -In short, the Value Stream Analytics dashboard tracks data related to [GitLab flow](../../topics/gitlab_flow.md). It does not include data for: +In short, the value stream analytics dashboard tracks data related to [GitLab flow](../../topics/gitlab_flow.md). It does not include data for: - Merge requests that do not close an issue. - Issues that do not include labels present in the issue board. @@ -152,7 +155,7 @@ In short, the Value Stream Analytics dashboard tracks data related to [GitLab fl ## How the production environment is identified -Value Stream Analytics identifies production environments based on the +Value stream analytics identifies production environments based on the [deployment tier of environments](../../ci/environments/index.md#deployment-tier-of-environments). ## Example workflow @@ -197,12 +200,12 @@ More information: the cycle. The time is included in the **Review** process, as every merge request should be tested. - The previous example illustrates only one cycle of the multiple stages. Value - Stream Analytics, on its dashboard, shows the calculated median elapsed time + stream analytics, on its dashboard, shows the calculated median elapsed time for these issues. ## Permissions -The permissions for the project-level Value Stream Analytics dashboard include: +The permissions for the value stream analytics for projects dashboard include: | Project type | Permissions | |--------------|---------------------------------------| @@ -214,8 +217,8 @@ You can [read more about permissions](../../user/permissions.md) in general. ## More resources -Learn more about Value Stream Analytics with the following resources: +Learn more about value stream analytics with the following resources: -- [Value Stream Analytics feature page](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). -- [Value Stream Analytics feature preview](https://about.gitlab.com/blog/2016/09/16/feature-preview-introducing-cycle-analytics/). -- [Value Stream Analytics feature highlight](https://about.gitlab.com/blog/2016/09/21/cycle-analytics-feature-highlight/). +- [Value stream analytics feature page](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). +- [Value stream analytics feature preview](https://about.gitlab.com/blog/2016/09/16/feature-preview-introducing-cycle-analytics/). +- [Value stream analytics feature highlight](https://about.gitlab.com/blog/2016/09/21/cycle-analytics-feature-highlight/). diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index a0f14ea59a1..be6b06a0797 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -12,10 +12,6 @@ parameters to unexpected values in an effort to cause unexpected behavior and er backend. This helps you discover bugs and potential security issues that other QA processes may miss. -INFO: -Try fuzz testing in GitLab Ultimate. -[It's free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-api-fuzzing-docs). - We recommend that you use fuzz testing in addition to [GitLab Secure](../index.md)'s other security scanners and your own test processes. If you're using [GitLab CI/CD](../../../ci/index.md), you can run fuzz tests as part your CI/CD workflow. @@ -572,6 +568,7 @@ profile increases as the number of tests increases. |[`FUZZAPI_PROFILE`](#api-fuzzing-profiles) | Configuration profile to use during testing. Defaults to `Quick-10`. | |[`FUZZAPI_EXCLUDE_PATHS`](#exclude-paths) | Exclude API URL paths from testing. | |[`FUZZAPI_OPENAPI`](#openapi-specification) | OpenAPI Specification file or URL. | +|[`FUZZAPI_OPENAPI_RELAXED_VALIDATION`](#openapi-specification) | Relax document validation. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345950) in GitLab 14.7. | |[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | |[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | |[`FUZZAPI_POSTMAN_COLLECTION_VARIABLES`](#postman-variables) | Path to a JSON file to extract Postman variable values. | @@ -1293,6 +1290,41 @@ The API Fuzzing template supports launching a docker container containing an API TODO --> +### Use OpenAPI with an invalid schema + +There are cases where the document is autogenerated with an invalid schema or cannot be edited manually in a timely manner. In those scenarios, the API Security is able to perform a relaxed validation by setting the variable `FUZZAPI_OPENAPI_RELAXED_VALIDATION`. We recommend providing a fully compliant OpenAPI document to prevent unexpected behaviors. + +#### Edit a non-compliant OpenAPI file + +To detect and correct elements that don't comply with the OpenAPI specifications, we recommend using an editor. An editor commonly provides document validation, and suggestions to create a schema-compliant OpenAPI document. Suggested editors include: + +| Editor | OpenAPI 2.0 | OpenAPI 3.0.x | OpenAPI 3.1.x | +| -- | -- | -- | -- | +| [Swagger Editor](https://editor.swagger.io/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{dotted-circle}** YAML, JSON | +| [Stoplight Studio](https://stoplight.io/studio/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | + +If your OpenAPI document is generated manually, load your document in the editor and fix anything that is non-compliant. If your document is generated automatically, load it in your editor to identify the issues in the schema, then go to the application and perform the corrections based on the framework you are using. + +#### Enable OpenAPI relaxed validation + +Relaxed validation is meant for cases when the OpenAPI document cannot meet OpenAPI specifications, but it still has enough content to be consumed by different tools. A validation is performed but less strictly in regards to document schema. + +API Security can still try to consume an OpenAPI document that does not fully comply with OpenAPI specifications. To instruct API Security to perform a relaxed validation, set the variable `FUZZAPI_OPENAPI_RELAXED_VALIDATION` to any value, for example: + +```yaml + stages: + - fuzz + + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_OPENAPI_RELAXED_VALIDATION: On +``` + ## Get support or request an improvement To get support for your particular problem please use the [getting help channels](https://about.gitlab.com/get-help/). diff --git a/doc/user/application_security/cluster_image_scanning/index.md b/doc/user/application_security/cluster_image_scanning/index.md index c3a2c179590..5f2dd626526 100644 --- a/doc/user/application_security/cluster_image_scanning/index.md +++ b/doc/user/application_security/cluster_image_scanning/index.md @@ -41,6 +41,8 @@ in your existing `.gitlab-ci.yml` file. To enable cluster image scanning in your pipeline, you need the following: +- Cluster Image 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. - [GitLab Runner](https://docs.gitlab.com/runner/) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) @@ -172,10 +174,10 @@ You can [configure](#customize-the-cluster-image-scanning-settings) analyzers by | CI/CD Variable | Default | Description | | ------------------------------ | ------------- | ----------- | | `CIS_KUBECONFIG` | `""` | File used to configure access to the Kubernetes cluster. See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) for more details. | -| `CIS_CONTAINER_NAME` | `""` | Name of the container used in the Kubernetes resource you want to filter vulnerabilities for. For example, `alpine`. | -| `CIS_RESOURCE_NAME` | `""` | Name of the Kubernetes resource you want to filter vulnerabilities for. For example, `nginx`. | -| `CIS_RESOURCE_NAMESPACE` | `""` | Namespace of the Kubernetes resource you want to filter vulnerabilities for. For example, `production`. | -| `CIS_RESOURCE_KIND` | `""` | Kind of the Kubernetes resource you want to filter vulnerabilities for. For example, `deployment`. | +| `CIS_CONTAINER_NAMES` | `""` | A comma-separated list of container names used in the Kubernetes resources you want to filter vulnerabilities for. For example, `alpine,postgres`. | +| `CIS_RESOURCE_NAMES` | `""` | A comma-separated list of Kubernetes resources you want to filter vulnerabilities for. For example, `nginx,redis`. | +| `CIS_RESOURCE_NAMESPACES` | `""` | A comma-separated list of namespaces of the Kubernetes resources you want to filter vulnerabilities for. For example, `production,staging`. | +| `CIS_RESOURCE_KINDS` | `""` | A comma-separated list of the kinds of Kubernetes resources to filter vulnerabilities for. For example, `deployment,pod`. | | `CIS_CLUSTER_IDENTIFIER` | `""` | ID of the Kubernetes cluster integrated with GitLab. This is used to map vulnerabilities to the cluster so they can be filtered in the Vulnerability Report page. | | `CIS_CLUSTER_AGENT_IDENTIFIER` | `""` | ID of the Kubernetes cluster agent integrated with GitLab. This maps vulnerabilities to the agent so they can be filtered in the Vulnerability Report page. | diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index bea9284873c..5a2dd5eb54f 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -9,10 +9,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3672) in GitLab 10.4. -INFO: -Try out Container Scanning in GitLab Ultimate. -[It's free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-container-scanning-docs). - Your application's Docker image may itself be based on Docker images that contain known vulnerabilities. By including an extra Container Scanning job in your pipeline that scans for those vulnerabilities and displays them in a merge request, you can use GitLab to audit your Docker-based @@ -52,6 +48,7 @@ information directly in the merge request. To enable container scanning in your pipeline, you need the following: +- Container 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. - [GitLab Runner](https://docs.gitlab.com/runner/) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. - Docker `18.09.03` or higher installed on the same computer as the runner. If you're using the @@ -62,6 +59,7 @@ To enable container scanning in your pipeline, you need the following: - If you're using a third-party container registry, you might need to provide authentication credentials through the `DOCKER_USER` and `DOCKER_PASSWORD` [configuration variables](#available-cicd-variables). For more details on how to use these variables, see [authenticate to a remote registry](#authenticate-to-a-remote-registry). +- GitLab CI/CD pipeline must include the `test` stage, which is available unless overridden with the [`stages`](../../../ci/yaml/index.md#stages) keyword. ## Configuration diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index b35c2ed79cf..89b4cdcc34d 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -7,14 +7,14 @@ type: reference, howto # Coverage-guided fuzz testing **(ULTIMATE)** -Coverage-guided fuzzing sends random inputs to an instrumented version of your application in an -effort to cause unexpected behavior. Such behavior indicates a bug that you should address. +Coverage-guided fuzz testing sends random inputs to an instrumented version of your application in +an effort to cause unexpected behavior. Such behavior indicates a bug that you should address. GitLab allows you to add coverage-guided fuzz testing to your pipelines. This helps you discover bugs and potential security issues that other QA processes may miss. We recommend that you use fuzz testing in addition to the other security scanners in [GitLab Secure](../index.md) and your own test processes. If you're using [GitLab CI/CD](../../../ci/index.md), -you can run your coverage-guided fuzz tests as part your CI/CD workflow. +you can run your coverage-guided fuzz testing as part your CI/CD workflow. ## Coverage-guided fuzz testing process @@ -30,30 +30,40 @@ The results of the coverage-guided fuzz testing are available in the CI/CD pipel ## Supported fuzzing engines and languages -GitLab supports these languages through the fuzzing engine listed for each. We currently provide a -Docker image for apps written in Go, but you can test the other languages below by providing a -Docker image with the fuzz engine to run your app. - -| Language | Fuzzing Engine | Example | -|----------|----------------|---------| -| C/C++ | [libFuzzer](https://llvm.org/docs/LibFuzzer.html) | [c-cpp-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/c-cpp-fuzzing-example) | -| GoLang | [go-fuzz (libFuzzer support)](https://github.com/dvyukov/go-fuzz) | [go-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example) | -| Swift | [libFuzzer](https://github.com/apple/swift/blob/master/docs/libFuzzerIntegration.md) | [swift-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/swift-fuzzing-example) | -| Rust | [cargo-fuzz (libFuzzer support)](https://github.com/rust-fuzz/cargo-fuzz) | [rust-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/rust-fuzzing-example) | -| Java | [Javafuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/javafuzz) (recommended) | [javafuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/javafuzz-fuzzing-example) | -| Java | [JQF](https://github.com/rohanpadhye/JQF) (not preferred) | [jqf-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/java-fuzzing-example) | -| JavaScript | [`jsfuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/jsfuzz)| [jsfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/jsfuzz-fuzzing-example) | -| Python | [`pythonfuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/pythonfuzz)| [pythonfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/pythonfuzz-fuzzing-example) | -| 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) | +You can use the following fuzzing engines to test the specified languages. + +| Language | Fuzzing Engine | Example | +|---------------------------------------------|------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------| +| C/C++ | [libFuzzer](https://llvm.org/docs/LibFuzzer.html) | [c-cpp-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/c-cpp-fuzzing-example) | +| GoLang | [go-fuzz (libFuzzer support)](https://github.com/dvyukov/go-fuzz) | [go-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example) | +| Swift | [libFuzzer](https://github.com/apple/swift/blob/master/docs/libFuzzerIntegration.md) | [swift-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/swift-fuzzing-example) | +| Rust | [cargo-fuzz (libFuzzer support)](https://github.com/rust-fuzz/cargo-fuzz) | [rust-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/rust-fuzzing-example) | +| Java | [Javafuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/javafuzz) (recommended) | [javafuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/javafuzz-fuzzing-example) | +| Java | [JQF](https://github.com/rohanpadhye/JQF) (not preferred) | [jqf-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/java-fuzzing-example) | +| JavaScript | [`jsfuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/jsfuzz) | [jsfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/jsfuzz-fuzzing-example) | +| Python | [`pythonfuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/pythonfuzz) | [pythonfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/pythonfuzz-fuzzing-example) | +| 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 -To enable fuzzing, you must -[include](../../../ci/yaml/index.md#includetemplate) -the [`Coverage-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Coverage-Fuzzing.gitlab-ci.yml) -provided as part of your GitLab installation. +To enable coverage-guided fuzz testing, edit the `.gitlab-ci.yml` file: + +1. Add the `fuzz` stage to the list of stages. + +1. If your application is not written in Go, [provide a Docker image](../../../ci/yaml/index.md#image) using the matching fuzzing + engine. For example: + + ```yaml + image: python:latest + ``` + +1. [Include](../../../ci/yaml/index.md#includetemplate) the + [`Coverage-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Coverage-Fuzzing.gitlab-ci.yml) + provided as part of your GitLab installation. -To do so, add the following to your `.gitlab-ci.yml` file: +1. Customize the `my_fuzz_target` job to meet your requirements. + +### Example extract of coverage-guided fuzzing configuration ```yaml stages: @@ -65,96 +75,62 @@ include: my_fuzz_target: extends: .fuzz_base script: - # Build your fuzz target binary in these steps, then run it with gitlab-cov-fuzz> + # Build your fuzz target binary in these steps, then run it with gitlab-cov-fuzz # See our example repos for how you could do this with any of our supported languages - ./gitlab-cov-fuzz run --regression=$REGRESSION -- <your fuzz target> ``` -The included template makes available the [hidden job](../../../ci/jobs/index.md#hide-jobs) -`.fuzz_base`, which you must [extend](../../../ci/yaml/index.md#extends) for each of your fuzz -targets. Each fuzz target **must** have a separate job. For example, the +The `Coverage-Fuzzing` template includes the [hidden job](../../../ci/jobs/index.md#hide-jobs) +`.fuzz_base`, which you must [extend](../../../ci/yaml/index.md#extends) for each of your fuzzing +targets. Each fuzzing target **must** have a separate job. For example, the [go-fuzzing-example project](https://gitlab.com/gitlab-org/security-products/demos/go-fuzzing-example) -contains one job that extends `.fuzz_base` for its single fuzz target. +contains one job that extends `.fuzz_base` for its single fuzzing target. Note that the hidden job `.fuzz_base` uses several YAML keys that you must not override in your own -job. If you include these keys in your own job, you must copy their original content. These keys -are: +job. If you include these keys in your own job, you must copy their original content: - `before_script` - `artifacts` - `rules` -The `my_fuzz_target` job (the separate job for your fuzz target) does the following: +### Available CI/CD variables + +Use the following variables to configure coverage-guided fuzz testing in your CI/CD pipeline. -- Extends `.fuzz_base`. -- Compiles the fuzz target with [go-fuzz](https://github.com/dvyukov/go-fuzz). -- Runs the target with the `gitlab-cov-fuzz` command, which is available to each job that extends - `.fuzz_base`. -- Runs on a fuzz stage that usually comes after a test stage. +| 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_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`. | -The `gitlab-cov-fuzz` is a command-line tool that runs the instrumented application. It parses and -analyzes the exception information that the fuzzer outputs. It also downloads the [corpus](../terminology/index.md#corpus) -and crash events from previous pipelines automatically. This helps your fuzz targets build on the -progress of previous fuzzing jobs. The parsed crash events and data are written to -`gl-coverage-fuzzing-report.json`. +#### Seed corpus -### Artifacts +Files in the [seed corpus](../terminology/index.md#seed-corpus) must be updated manually. They are +not updated or overwritten by the coverage-guide fuzz testing job. + +## Output Each fuzzing step outputs these artifacts: -- `gl-coverage-fuzzing-report.json`: This file's format may change in future releases. +- `gl-coverage-fuzzing-report.json`: A report containing details of the coverage-guided fuzz testing + and its results. - `artifacts.zip`: This file contains two directories: - - `corpus`: Holds all test cases generated by the current and all previous jobs. - - `crashes`: Holds all crash events the current job encountered as well as those not fixed in + - `corpus`: Contains all test cases generated by the current and all previous jobs. + - `crashes`: Contains all crash events the current job found and those not fixed in previous jobs. -### Types of fuzzing jobs - -There are two types of jobs: - -- Fuzzing: Standard fuzzing session. You can configure a long session through a user defined - timeout. -- Regression: Run the fuzz targets through the accumulated test cases generated by previous fuzzing - sessions plus fixed crashes from previous sessions. This is usually very quick. - -Here's our current suggestion for configuring your fuzz target's timeout: - -- Set `COVFUZZ_BRANCH` to the branch where you want to run long-running (asynchronous) fuzzing - jobs. This is normally the default branch. -- Use regression or short-running fuzzing jobs for other branches or merge requests. - -This suggestion helps find new bugs on the development branch and catch old bugs in merge requests -(like unit tests). - -You can configure this by passing `--regression=false/true` to `gitlab-cov-fuzz` as the [Go example](https://gitlab.com/gitlab-org/security-products/demos/go-fuzzing-example/-/blob/master/.gitlab-ci.yml) -shows. Also note that `gitlab-cov-fuzz` is a wrapper, so you can pass those arguments to configure -any option available in the underlying fuzzing engine. - -### Available CI/CD variables - -| CI/CD variable | Description | -|-----------------------|--------------------------------------------------------------------------------| -| `COVFUZZ_BRANCH` | The branch for long-running fuzzing jobs. This is normally the default branch. | -| `COVFUZZ_SEED_CORPUS` | Path to a seed corpus directory. The default is empty. | -| `COVFUZZ_URL_PREFIX` | Path to the `gitlab-cov-fuzz` repository cloned for use with an offline environment. You should only change this when using an offline environment. The default value is `https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz/-/raw`. | - -The files in the [seed corpus](../terminology/index.md#seed-corpus) (`COVFUZZ_SEED_CORPUS`), if provided, aren't updated unless you commit new -files to your Git repository. There's usually no need to frequently update the seed corpus. As part -of the GitLab artifacts system, GitLab saves in a corpus directory the new test cases that every run -generates. In any subsequent runs, GitLab also reuses the generated corpus together with the seed -corpus. +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). -### Reports JSON format +### Coverage-guided fuzz testing report > [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). -The `gitlab-cov-fuzz` 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/coverage-fuzzing-report-format.json). - -You can download the JSON report file from the CI pipelines page. For more information, see -[Downloading artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). +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). -Here's an example coverage fuzzing report: +Example coverage-guided fuzzing report: ```json-doc { @@ -183,38 +159,30 @@ Here's an example coverage fuzzing report: } ``` -### Additional configuration - -The `gitlab-cov-fuzz` command passes all arguments it receives to the underlying fuzzing engine. You -can therefore use all the options available in that fuzzing engine. For more information on these -options, see the underlying fuzzing engine's documentation. - -### Offline environment +## Duration of coverage-guided fuzz testing -To use coverage fuzzing in an offline environment, follow these steps: +The available durations for coverage-guided fuzz testing are: 10 minutes (default) and 60 minutes. -1. Clone [`gitlab-cov-fuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz) - to a private repository that your offline GitLab instance can access. +- 10-minute duration: 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`. -1. For each fuzzing step, set `COVFUZZ_URL_PREFIX` to `${NEW_URL_GITLAB_COV_FUZ}/-/raw`, where - `NEW_URL_GITLAB_COV_FUZ` is the URL of the private `gitlab-cov-fuzz` clone that you set up in the - first step. +For a complete example, read the [Go coverage-guided fuzzing example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/blob/master/.gitlab-ci.yml). -### Continuous fuzzing (long-running asynchronous fuzzing jobs) +### Continuous coverage-guided fuzz testing -It's also possible to run the fuzzing jobs longer and without blocking your main pipeline. This -configuration uses the GitLab [parent-child pipelines](../../../ci/pipelines/parent_child_pipelines.md). -The full example is available in the [repository](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/tree/continuous_fuzzing#running-go-fuzz-from-ci). -This example uses Go, but is applicable for any other supported languages. +It's also possible to run the coverage-guided fuzzing jobs longer and without blocking your main +pipeline. This configuration uses the GitLab +[parent-child pipelines](../../../ci/pipelines/parent_child_pipelines.md). -The suggested workflow in this scenario is to have long-running, asynchronous fuzzing jobs on a -main/development branch, and short, blocking sync fuzzing jobs on all other branches and MRs. This -is a good way to balance the needs of letting a developer's per-commit pipeline complete quickly, -and also giving the fuzzer a large amount of time to fully explore and test the app. +The suggested workflow in this scenario is to have long-running, asynchronous fuzzing jobs on the +main or development branch, and short synchronous fuzzing jobs on all other branches and MRs. This +balances the needs of completing the per-commit pipeline complete quickly, while also giving the +fuzzer a large amount of time to fully explore and test the app. Long-running fuzzing jobs are +usually necessary for the coverage-guided fuzzer to find deeper bugs in your codebase. -Long-running fuzzing jobs are usually necessary for the coverage guided fuzzer to find deeper bugs -in your latest codebase. The following is an example of what `.gitlab-ci.yml` looks like in this -workflow (for the full example, see the [repository](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/tree/continuous_fuzzing)): +The following is an extract of the `.gitlab-ci.yml` file for this +workflow. For the full example, see the [Go fuzzing example's repository](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/tree/continuous_fuzzing): ```yaml @@ -236,7 +204,7 @@ async_fuzzing: - if: $CI_COMMIT_BRANCH == 'continuous_fuzzing' && $CI_PIPELINE_SOURCE != 'merge_request_event' ``` -This essentially creates two steps: +This creates two jobs: 1. `sync_fuzzing`: Runs all your fuzz targets for a short period of time in a blocking configuration. This finds simple bugs and allows you to be confident that your MRs aren't @@ -246,6 +214,17 @@ This essentially creates two steps: The `covfuzz-ci.yml` is the same as that in the [original synchronous example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example#running-go-fuzz-from-ci). +## Offline environment + +To use coverage fuzzing in an offline environment: + +1. Clone [`gitlab-cov-fuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz) + to a private repository that your offline GitLab instance can access. + +1. For each fuzzing step, set `COVFUZZ_URL_PREFIX` to `${NEW_URL_GITLAB_COV_FUZ}/-/raw`, where + `NEW_URL_GITLAB_COV_FUZ` is the URL of the private `gitlab-cov-fuzz` clone that you set up in the + first step. + ## Interacting with the vulnerabilities After a vulnerability is found, you can [address it](../vulnerabilities/index.md). diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 4de7a566769..aeaa93f4a85 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -16,10 +16,6 @@ Dynamic Application Security Testing (DAST) examines applications for vulnerabilities like these in deployed environments. DAST uses the open source tool [OWASP Zed Attack Proxy](https://www.zaproxy.org/) for analysis. -INFO: -Want to try out security scanning? -[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-dast-docs). - After DAST creates its report, GitLab evaluates it for discovered vulnerabilities between the source and target branches. Relevant findings are noted in the merge request. @@ -57,6 +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. ### Deployment options @@ -638,7 +635,7 @@ These CI/CD variables are specific to DAST. They can be used to customize the be | `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_WEBSITE` <sup>1</sup> | URL | The URL of the website to scan. The variable `DAST_API_OPENAPI` must be specified if this is omitted. | | `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. Example: `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` | +| `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. Example: `logger.httpsender.name=org.parosproxy.paros.network.HttpSender;logger.httpsender.level=debug;logger.sitemap.name=org.parosproxy.paros.model.SiteMap;logger.sitemap.level=debug;` | | `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | 1. Available to an on-demand DAST scan. @@ -969,6 +966,8 @@ To view running completed and scheduled on-demand DAST scans for a project, go t failed, or was canceled. - To view scheduled scans, select **Scheduled**. It shows on-demand scans that have a schedule set up. Those are _not_ included in the **All** tab. +- To view saved on-demand scan profiles, select **Scan library**. + Those are _not_ included in the **All** tab. #### Cancel an on-demand scan @@ -1036,10 +1035,8 @@ The on-demand DAST scan runs and the project's dashboard shows the results. To run a saved on-demand scan: 1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Security & Compliance > Configuration**. -1. Select **Manage DAST scans**. -1. In the **DAST Profiles** row, select **Manage**. -1. Select the **Saved Scans** tab. +1. On the left sidebar, select **Security & Compliance > On-demand Scans**. +1. Select the **Scan library** tab. 1. In the scan's row, select **Run scan**. If the branch saved in the scan no longer exists, you must first @@ -1075,27 +1072,23 @@ To schedule a scan: To list saved on-demand scans: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select the **Saved Scans** tab. +1. From your project's home page, go to **Security & Compliance > On-demand Scans**. +1. Select the **Scan library** tab. #### View details of an on-demand scan To view details of an on-demand scan: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select **Manage DAST scans**. -1. Select **Manage** in the **DAST Profiles** row. -1. Select the **Saved Scans** tab. +1. From your project's home page, go to **Security & Compliance > On-demand Scans**. +1. Select the **Scan library** tab. 1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. #### Edit an on-demand scan To edit an on-demand scan: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select **Manage DAST scans**. -1. Select **Manage** in the **DAST Profiles** row. -1. Select the **Saved Scans** tab. +1. From your project's home page, go to **Security & Compliance > On-demand Scans**. +1. Select the **Scan library** tab. 1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. 1. Edit the form. 1. Select **Save scan**. @@ -1104,10 +1097,8 @@ To edit an on-demand scan: To delete an on-demand scan: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select **Manage DAST scans**. -1. Select **Manage** in the **DAST Profiles** row. -1. Select the **Saved Scans** tab. +1. From your project's home page, go to **Security & Compliance > On-demand Scans**. +1. Select the **Scan library** tab. 1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Delete**. 1. Select **Delete** to confirm the deletion. @@ -1132,6 +1123,9 @@ A site profile contains the following: When an API site type is selected, a [host override](#host-override) is used to ensure the API being scanned is on the same host as the target. This is done to reduce the risk of running an active scan against the wrong API. +When configured, request headers and password fields are encrypted using [`aes-256-gcm`](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) before being stored in the database. +This data can only be read and decrypted with a valid secrets file. + #### Site profile validation > - Site profile validation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233020) in GitLab 13.8. diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 0db5fb2d868..f1eba505589 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -214,7 +214,7 @@ target API to test: DAST_API_PROFILE: Quick ``` -1. Provide the location of the HAR specification. You can provide the specification as a file +1. Provide the location of the HAR file. You can provide the location as a file path or URL. [URL support was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285020) in GitLab 13.10 and later. Specify the location by adding the `DAST_API_HAR` variable: ```yaml @@ -314,7 +314,7 @@ information about the target API to test: DAST_API_PROFILE: Quick ``` -1. Provide the location of the Postman Collection specification. You can provide the specification as a file or URL. Specify the location by adding the `DAST_API_POSTMAN_COLLECTION` variable: +1. Provide the location of the Postman Collection file. You can provide the location as a file or URL. Specify the location by adding the `DAST_API_POSTMAN_COLLECTION` variable: ```yaml stages: @@ -637,6 +637,7 @@ can be added, removed, and modified by creating a custom configuration. |[`DAST_API_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | |[`DAST_API_EXCLUDE_PATHS`](#exclude-paths) | Exclude API URL paths from testing. | |[`DAST_API_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | +|[`DAST_API_OPENAPI_RELAXED_VALIDATION`](#openapi-specification) | Relax document validation. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345950) in GitLab 14.7. | |[`DAST_API_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | |[`DAST_API_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | |[`DAST_API_POSTMAN_COLLECTION_VARIABLES`](#postman-variables) | Path to a JSON file to extract postman variable values. | @@ -1209,6 +1210,41 @@ deploy-test-target: - environment_url.txt ``` +### Use OpenAPI with an invalid schema + +There are cases where the document is autogenerated with an invalid schema or cannot be edited manually in a timely manner. In those scenarios, the API Security is able to perform a relaxed validation by setting the variable `DAST_API_OPENAPI_RELAXED_VALIDATION`. We recommend providing a fully compliant OpenAPI document to prevent unexpected behaviors. + +#### Edit a non-compliant OpenAPI file + +To detect and correct elements that don't comply with the OpenAPI specifications, we recommend using an editor. An editor commonly provides document validation, and suggestions to create a schema-compliant OpenAPI document. Suggested editors include: + +| Editor | OpenAPI 2.0 | OpenAPI 3.0.x | OpenAPI 3.1.x | +| -- | -- | -- | -- | +| [Swagger Editor](https://editor.swagger.io/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{dotted-circle}** YAML, JSON | +| [Stoplight Studio](https://stoplight.io/studio/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | + +If your OpenAPI document is generated manually, load your document in the editor and fix anything that is non-compliant. If your document is generated automatically, load it in your editor to identify the issues in the schema, then go to the application and perform the corrections based on the framework you are using. + +#### Enable OpenAPI relaxed validation + +Relaxed validation is meant for cases when the OpenAPI document cannot meet OpenAPI specifications, but it still has enough content to be consumed by different tools. A validation is performed but less strictly in regards to document schema. + +API Security can still try to consume an OpenAPI document that does not fully comply with OpenAPI specifications. To instruct API Security to perform a relaxed validation, set the variable `DAST_API_OPENAPI_RELAXED_VALIDATION` to any value, for example: + +```yaml + stages: + - dast + + include: + - template: DAST-API.gitlab-ci.yml + + variables: + DAST_API_PROFILE: Quick + DAST_API_TARGET_URL: http://test-deployment/ + DAST_API_OPENAPI: test-api-specification.json + DAST_API_OPENAPI_RELAXED_VALIDATION: On +``` + ## Get support or request an improvement To get support for your particular problem please use the [getting help channels](https://about.gitlab.com/get-help/). diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 192d8449297..a8cc33d5545 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -7,10 +7,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency Scanning **(ULTIMATE)** -INFO: -Try out Dependency Scanning in GitLab Ultimate. -[It's free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-dependency-scanning-docs). - The Dependency Scanning feature can automatically find security vulnerabilities in your software dependencies while you're developing and testing your applications. For example, dependency scanning lets you know if your application uses an external (open source) @@ -67,6 +63,9 @@ vulnerability. ## Requirements +Dependency 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 run dependency scanning jobs, by default, you need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. @@ -922,6 +921,8 @@ gemnasium-dependency_scanning: ## Warnings +We recommend that you use the most recent version of all containers, and the most recent supported version of all package managers and languages. Using previous versions carries an increased security risk because unsupported versions may no longer benefit from active security reporting and backporting of security fixes. + ### Python projects Extra care needs to be taken when using the [`PIP_EXTRA_INDEX_URL`](https://pipenv.pypa.io/en/latest/cli/#envvar-PIP_EXTRA_INDEX_URL) diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index c17ebc68b4d..4d5c1da3c47 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -14,6 +14,8 @@ Currently, IaC scanning supports configuration files for Terraform, Ansible, AWS ## Requirements +IaC 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 run IaC scanning jobs, by default, you need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. @@ -48,7 +50,7 @@ as shown in the following table: | Capability | In Free | In Ultimate | |:---------------------------------------------------------------------------------------|:--------------------|:-------------------| -| [Configure IaC Scanners](#configuration) v | **{check-circle}** | **{check-circle}** | +| [Configure IaC Scanners](#configuration) | **{check-circle}** | **{check-circle}** | | View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | | Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | | [Address vulnerabilities](../../application_security/vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 5500f5a10c4..f5c727a1418 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -16,10 +16,6 @@ GitLab can check your application for security vulnerabilities including: Statistics and details on vulnerabilities are included in the merge request. Providing actionable information _before_ changes are merged enables you to be proactive. -INFO: -Want to try out security scanning? -[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-application-security-docs). - GitLab also provides high-level statistics of vulnerabilities across projects and groups: - The [Security Dashboard](security_dashboard/index.md) provides a @@ -119,7 +115,9 @@ rules: If you add the security scanning jobs as described in [Security scanning with Auto DevOps](#security-scanning-with-auto-devops) or [Security scanning without Auto DevOps](#security-scanning-without-auto-devops) to your `.gitlab-ci.yml` each added [security scanning tool](#security-scanning-tools) behave as described below. -For each compatible analyzer, a job is created in the `test`, `dast` or `fuzz` stage of your pipeline and runs on the next new branch pipeline. Features such as the [Security Dashboard](security_dashboard/index.md), [Vulnerability Report](vulnerability_report/index.md), and [Dependency List](dependency_list/index.md) that rely on this scan data only show results from pipelines on the default branch. One tool might use many analyzers. +For each compatible analyzer, a job is created in the `test`, `dast` or `fuzz` stage of your pipeline and runs on the next new branch pipeline. +Features such as the [Security Dashboard](security_dashboard/index.md), [Vulnerability Report](vulnerability_report/index.md), and [Dependency List](dependency_list/index.md) +that rely on this scan data only show results from pipelines on the default branch, only if all jobs are finished, including manual ones. One tool might use many analyzers. Our language and package manager specific jobs attempt to assess which analyzer(s) they should run for your project so that you can do less configuration. @@ -172,7 +170,7 @@ From the merge request security widget, select **Expand** to unfold the widget, A pipeline's security tab lists all findings in the current branch. It includes new findings introduced by this branch and existing vulnerabilities that were already present when the branch was created. These results likely do not match the findings displayed in the Merge Request security widget as those do not include the existing vulnerabilities (with the exception of showing any existing vulnerabilities that are no longer detected in the feature branch). -For more details, see [security tab](security_dashboard/index.md#pipeline-security). +For more details, see [security tab](security_dashboard/index.md#view-vulnerabilities-in-a-pipeline). ## View security scan information in the Security Dashboard @@ -406,9 +404,9 @@ sast: You can interact with the results of the security scanning tools in several locations: - [Scan information in merge requests](#view-security-scan-information-in-merge-requests) -- [Project Security Dashboard](security_dashboard/#project-security-dashboard) -- [Security pipeline tab](security_dashboard/#pipeline-security) -- [Group Security Dashboard](security_dashboard/#group-security-dashboard) +- [Project Security Dashboard](security_dashboard/index.md) +- [Security pipeline tab](security_dashboard/index.md) +- [Group Security Dashboard](security_dashboard/index.md) - [Security Center](security_dashboard/#security-center) - [Vulnerability Report](vulnerability_report/index.md) - [Vulnerability Pages](vulnerabilities/index.md) @@ -441,6 +439,46 @@ When customizing the configuration: version contains the most recent changes, but may have significant changes between minor GitLab versions. - Only override values in the template as needed. All other values are inherited from the template. +### Enforce scan execution + +Security and compliance teams must ensure that security scans: + +- Run on a regular basis for all projects. +- Can't be disabled by developers. + +GitLab provides two methods of accomplishing this, each with advantages and disadvantages. + +- [Compliance framework pipelines](../project/settings/#compliance-pipeline-configuration) + are recommended when: + + - Scan execution enforcement is required for SAST IaC, Container Scanning, 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) + 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. + - 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. | +| **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. | +| **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. | + +Feedback is welcome on our vision for [unifying the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312) + ## Troubleshooting ### Secure job failing with exit code 1 @@ -609,3 +647,15 @@ such as changing `variables` or the `stage`, but they cannot be used to define s There [is an issue open to improve extendability](https://gitlab.com/gitlab-org/gitlab/-/issues/218444). Please upvote the issue to help with prioritization, and [contributions are welcomed](https://about.gitlab.com/community/contribute/). + +### Empty Vulnerability Report, Dependency List, License list pages + +If the pipeline has manual steps with a job that has the `allow_failure: false` option, and this job is not finished, +GitLab can't populate listed pages with the data from security reports. +In this case, [the Vulnerability Report](vulnerability_report/index.md), [the Dependency List](dependency_list/index.md), +and [the License list](../compliance/license_compliance/index.md#license-list) pages will be empty. +These security pages can be populated by running the jobs from the manual step of the pipeline. + +There is [an issue open to handle this scenario](https://gitlab.com/gitlab-org/gitlab/-/issues/346843). +Please upvote the issue to help with prioritization, and +[contributions are welcomed](https://about.gitlab.com/community/contribute/). diff --git a/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_3.png b/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_3.png Binary files differdeleted file mode 100644 index d04905eda59..00000000000 --- a/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_3.png +++ /dev/null diff --git a/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_7.png b/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_7.png Binary files differnew file mode 100644 index 00000000000..04768d2e18a --- /dev/null +++ b/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_7.png diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index e6dbd96537f..11f2b91177a 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -236,20 +236,32 @@ Project owners can unlink Security Policy projects from development projects. To 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 merge request** +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. @@ -301,10 +313,10 @@ Use this schema to define `clusters` objects in the [`schedule` rule type](#sche | Field | Type | Possible values | Description | |--------------|---------------------|--------------------------|-------------| -| `containers` | `array` of `string` | | The container name to be scanned (only the first value is currently supported). | -| `resources` | `array` of `string` | | The resource name to be scanned (only the first value is currently supported). | -| `namespaces` | `array` of `string` | | The namespace to be scanned (only the first value is currently supported). | -| `kinds` | `array` of `string` | `deployment`/`daemonset` | The resource kind to be scanned (only the first value is currently supported). | +| `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 @@ -389,7 +401,7 @@ scan_execution_policy: enabled: true rules: - type: schedule - cadence: "15 3 * * * + cadence: "15 3 * * *" clusters: production-cluster: containers: diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 8c7e03f69fd..7529bf90ccf 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -6,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # SAST Analyzers **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in GitLab 10.3. -> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) from GitLab Ultimate to GitLab Free in 13.3. +> [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) from GitLab Ultimate to GitLab Free in 13.3. SAST relies on underlying third party tools that are wrapped into what we call "Analyzers". An analyzer is a diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index fd05ecad8f2..de2f9af82c7 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -2,13 +2,11 @@ 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 --- # Static Application Security Testing (SAST) **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in GitLab 10.3. -> - All open source (OSS) analyzers were moved from GitLab Ultimate to GitLab Free in GitLab 13.3. +> All open source (OSS) analyzers were moved from GitLab Ultimate to GitLab Free in GitLab 13.3. NOTE: The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) @@ -51,6 +49,8 @@ the analyzer outputs an [exit code](../../../development/integrations/secure.md# ## Requirements +SAST 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 run SAST jobs, by default, you need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. @@ -168,10 +168,9 @@ To configure SAST for a project you can: ### Configure SAST manually -For GitLab 11.9 and later, to enable SAST you must [include](../../../ci/yaml/index.md#includetemplate) +To enable SAST you must [include](../../../ci/yaml/index.md#includetemplate) the [`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) -provided as a part of your GitLab installation. For GitLab versions earlier than 11.9, you -can copy and use the job as defined that template. +provided as a part of your GitLab installation. Add the following to your `.gitlab-ci.yml` file: @@ -269,7 +268,7 @@ versions are pulled, there are certain cases where it can be beneficial to pin an analyzer to a specific release. To do so, override the `SAST_ANALYZER_IMAGE_TAG` CI/CD variable in the job template directly. -In the example below, we pin to a specific patch version of the `spotbugs` analyzer and minor version of the `semgrep` analyzer: +In the example below, we pin to a minor version of the `semgrep` analyzer and a specific patch version of the `brakeman` analyzer: ```yaml include: @@ -277,11 +276,11 @@ include: semgrep-sast: variables: - SAST_ANALYZER_IMAGE_TAG: "2.12" + SAST_ANALYZER_IMAGE_TAG: "2.16" -spotbugs-sast: +brakeman-sast: variables: - SAST_ANALYZER_IMAGE_TAG: "2.28.1" + SAST_ANALYZER_IMAGE_TAG: "2.21.1" ``` ### Customize rulesets **(ULTIMATE)** @@ -311,9 +310,9 @@ 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` sub sections, list the rules that you want disabled. Every `ruleset.identifier` section has: +1. In one or more `ruleset.identifier` sub sections, list the rules that you want disabled. Every `ruleset.identifier` section has: -- a `type` field, to name the predefined rule identifier that the targeted analyzer uses. +- a `type` field, to name the predefined rule identifier that the targeted analyzer uses. - a `value` field, to name the rule to be disabled. @@ -346,7 +345,7 @@ and `sobelow` by matching the `type` and `value` of identifiers: #### Synthesize a custom configuration -To create a custom configuration, you can use passthrough chains. +To create a custom configuration, you can use passthrough chains. A passthrough is a single step in a passthrough chain. The passthrough is evaluated in a sequence to incrementally build a configuration. The configuration is then @@ -360,8 +359,8 @@ parameters: | `description` | Description about the analyzer configuration section. | | `targetdir` | The `targetdir` parameter defines the directory where the final configuration is located. If `targetdir` is empty, the analyzer uses a random directory. The maximum size of `targetdir` is 100MB. | | `validate` | If set to `true`, the target files for passthroughs (`raw`, `file` and `url`) are validated. The validation works for `yaml`, `xml`, `json` and `toml` files. The proper validator is identified based on the extension of the target file. By default, `validate` is set to `false`. | -| `interpolate` | If set to `true`, environment variable interpolation is enabled so that the configuration uses secrets/tokens. We advise using this feature with caution to not leak any secrets. By default, `interpolate` is set to `false`. | -| `timeout` | The total `timeout` for the evaluation of a passthrough chain is set to 60 seconds. If `timeout` is not set, the default timeout is 60 seconds. The timeout cannot exceed 300 seconds. | +| `interpolate` | If set to `true`, environment variable interpolation is enabled so that the configuration uses secrets/tokens. We advise using this feature with caution to not leak any secrets. By default, `interpolate` is set to `false`. | +| `timeout` | The total `timeout` for the evaluation of a passthrough chain is set to 60 seconds. If `timeout` is not set, the default timeout is 60 seconds. The timeout cannot exceed 300 seconds. | A configuration section can include one or more passthrough sections. The maximum number of passthrough sections is 20. There are several types of passthroughs: @@ -374,12 +373,12 @@ There are several types of passthroughs: | `url` | Fetch the analyzer configuration through HTTP. | If multiple passthrough sections are defined in a passthrough chain, their -position in the chain defines the order in which they are evaluated. +position in the chain defines the order in which they are evaluated. -- Passthroughs listed later in the chain sequence have a higher precedence. +- Passthroughs listed later in the chain sequence have a higher precedence. - Passthroughs with a higher precedence overwrite (default) and append data yielded by previous passthroughs. This is useful for cases where you need to - use or modify an existing configuration. + use or modify an existing configuration. Configure a passthrough these parameters: @@ -454,7 +453,7 @@ file `gosec-config.json`: ##### Passthrough chain for semgrep In the below example, we generate a custom configuration under the `/sgrules` -target directory with a total `timeout` of 60 seconds. +target directory with a total `timeout` of 60 seconds. Several passthrouh types generate a configuration for the target analyzer: @@ -463,17 +462,17 @@ Several passthrouh types generate a configuration for the target analyzer: `97f7686` from the `sast-rules` Git repostory. From the `sast-rules` Git repository, only data from the `go` subdirectory is considered. - The `sast-rules` entry has a higher precedence because it appears later in - the configuration. + the configuration. - If there is a filename collision between files in both repositories, files from the `sast` repository overwrite files from the `myrules` repository, as `sast-rules` has higher precedence. - The `raw` entry creates a file named `insecure.yml` under `/sgrules`. The - full path is `/sgrules/insecure.yml`. + full path is `/sgrules/insecure.yml`. - The `url` entry fetches a configuration made available through a URL and - stores it in the `/sgrules/gosec.yml` file. + stores it in the `/sgrules/gosec.yml` file. Afterwards, semgrep is invoked with the final configuration located under -`/sgrules`. +`/sgrules`. ```toml [semgrep] @@ -537,17 +536,17 @@ It does not explicitly store credentials in the configuration file. To reduce th ##### Configure the append mode for passthroughs To append data to previous passthroughs, use the `append` mode for the -passthrough types `file`, `url`, and `raw`. +passthrough types `file`, `url`, and `raw`. Passthroughs in `override` mode overwrite files created when preceding passthroughs in the chain find a naming collision. If `mode` is set to `append`, a passthrough appends data to the -files created by its predecessors instead of overwriting. +files created by its predecessors instead of overwriting. In the below semgrep configuration,`/sgrules/insecure.yml` assembles two passthroughs. The rules are: - `insecure` -- `secret` +- `secret` These rules add a search pattern to the analyzer and extends semgrep capabilities. @@ -1057,6 +1056,12 @@ For Maven builds, add the following to your `pom.xml` file: </properties> ``` +### SpotBugs Error: `Project couldn't be built` + +If your job is failing at the build step with the message "Project couldn't be built", it's most likely because your job is asking SpotBugs to build with a tool that isn't part of its default tools. For a list of the SpotBugs default tools, see [SpotBugs' asdf dependencies](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs/-/raw/master/config/.tool-versions). + +The solution is to use [pre-compilation](#pre-compilation). Pre-compilation ensures the images required by SpotBugs are available in the job's container. + ### Flawfinder encoding error This occurs when Flawfinder encounters an invalid UTF-8 character. To fix this, convert all source code in your project to UTF-8 character encoding. This can be done with [`cvt2utf`](https://github.com/x1angli/cvt2utf) or [`iconv`](https://www.gnu.org/software/libiconv/documentation/libiconv-1.13/iconv.1.html) either over the entire project or per job using the [`before_script`](../../../ci/yaml/index.md#before_script) feature. diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index b5e54e35e58..c5761a5743f 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -1,5 +1,4 @@ --- -type: reference, howto stage: Secure group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments @@ -7,38 +6,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Secret Detection **(FREE)** -> - [Introduced](https://about.gitlab.com/releases/2019/03/22/gitlab-11-9-released/#detect-secrets-and-credentials-in-the-repository) in GitLab 11.9. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) from GitLab Ultimate to GitLab Free in 13.3. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) from GitLab Ultimate to GitLab Free in 13.3. -A recurring problem when developing applications is that developers may unintentionally commit -secrets and credentials to their remote repositories. If other people have access to the source, -or if the project is public, the sensitive information is then exposed and can be leveraged by -malicious users to gain access to resources like deployment environments. +A recurring problem when developing applications is that people may accidentally commit secrets to +their remote Git repositories. Secrets include keys, passwords, API tokens, and other sensitive +information. Anyone with access to the repository could use the secrets for malicious purposes. +Secrets exposed in this way must be treated as compromised, and be replaced, which can be costly. +It's important to prevent secrets from being committed to a Git repository. -GitLab 11.9 includes a new check called Secret Detection. It scans the content of the repository -to find API keys and other information that should not be there. +Secret Detection uses the [Gitleaks](https://github.com/zricethezav/gitleaks) tool to scan the +repository for secrets. All identified secrets are reported in the: -GitLab displays identified secrets visibly in a few places: - -- [Security Dashboard](../security_dashboard/) +- Merge request widget - Pipelines' **Security** tab -- Report in the merge request widget +- [Security Dashboard](../security_dashboard/)  -## Use cases - -- Detecting unintentional commit of secrets like keys, passwords, and API tokens. -- Performing a single or recurring scan of the full history of your repository for secrets. - -## Supported secrets +WARNING: +Secret Detection does not support scanning binary files. -Secret Detection detects a variety of common secrets by default. You can also customize the secret detection patterns using [custom rulesets](#custom-rulesets). -The [default ruleset](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks.toml) includes **90+ secret detection patterns**. -You can contribute "well-identifiable" secrets by follow the steps detailed in the [community contributions guidelines](https://gitlab.com/gitlab-org/gitlab/-/issues/345453). +## Detected secrets -WARNING: -Gitleaks does not support scanning binary files. +Secret Detection uses a [default ruleset](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks.toml) +containing more than 90 secret detection patterns. You can also customize the secret detection +patterns using [custom rulesets](#custom-rulesets). If you want to contribute rulesets for +"well-identifiable" secrets, follow the steps detailed in the +[community contributions guidelines](https://gitlab.com/gitlab-org/gitlab/-/issues/345453). ## Requirements @@ -376,10 +370,10 @@ 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 -is set to 50 (a [project default](../../../ci/pipelines/settings.md#limit-the-number-of-changes-fetched-during-clone)), -the Secret Detection job fails as the clone is not deep enough to contain all of the -relevant commits. +If a pipeline is triggered from a Merge Request containing 60 commits while the `GIT_DEPTH` variable'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). To confirm this as the cause of the error, set the [logging level](../../application_security/secret_detection/index.md#logging-level) to `debug`, then diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_3.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_3.png Binary files differdeleted file mode 100644 index 4d51f57a98d..00000000000 --- a/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_3.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png Binary files differdeleted file mode 100644 index ad9122ee23c..00000000000 --- a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_11.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_11.png Binary files differdeleted file mode 100644 index cc9f0061a31..00000000000 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_11.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png b/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png Binary files differdeleted file mode 100644 index 6578c0bf4cf..00000000000 --- a/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 5afbe1ca54e..937ca33c3a1 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -7,193 +7,186 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Security Dashboards and Security Center **(ULTIMATE)** -INFO: -Want to try out security scanning? -[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-security-dashboard-docs). +You can use Security Dashboards to view details about vulnerabilities +detected by [security scanners](../index.md#security-scanning-tools). +These details are shown in pipelines, projects, and groups. -GitLab provides a comprehensive set of features for viewing and managing vulnerabilities: +To use the Security Dashboards, you must: -- Security dashboards: An overview of the security status in your personal [Security Center](#security-center), [groups](#group-security-dashboard), and - [projects](#project-security-dashboard). -- [Vulnerability reports](../vulnerability_report/index.md): Detailed lists of all vulnerabilities for the Security Center, group, project, or - pipeline. This is where you triage and manage vulnerabilities. -- [Security Center](#security-center): A dedicated area for personalized vulnerability management. This - includes a security dashboard, vulnerability report, and settings. +- Configure at least one [security scanner](../index.md#security-scanning-tools) in a project. +- Configure jobs to use the [`reports` syntax](../../../ci/yaml/index.md#artifactsreports). +- Use [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or later. If you use the + shared runners on GitLab.com, you are using the correct version. -You can also drill down into a vulnerability and get extra information on the -[Vulnerability Page](../vulnerabilities/index.md). This view includes the project it -comes from, any related file(s), and metadata that helps you analyze the risk it poses. -You can also confirm, dismiss, or resolve a vulnerability, create an issue for it, -and in some cases, generate a merge request to fix the vulnerability. +## When Security Dashboards are updated -To benefit from these features, you must first configure one of the -[security scanners](../index.md). +The Security Dashboards show results of the most recent security scan on the +[default branch](../../project/repository/branches/default.md). +Security scans run only when the default branch updates, so +information on the Security Dashboard might not reflect newly-discovered vulnerabilities. -## Supported reports +To run a daily security scan, +[configure a scheduled pipeline](../../../ci/pipelines/schedules.md). -The security dashboard and vulnerability report displays information about vulnerabilities detected by scanners such as: +## Reduce false negatives in dependency scans -- [Container Scanning](../container_scanning/index.md) -- [Dynamic Application Security Testing](../dast/index.md) -- [Dependency Scanning](../dependency_scanning/index.md) -- [Static Application Security Testing](../sast/index.md) -- [Cluster Image Scanning](../cluster_image_scanning/index.md) -- And [others](../index.md#security-scanning-tools)! +WARNING: +False negatives occur when you resolve dependency versions during a scan, which differ from those +resolved when your project built and released in a previous pipeline. -## Prerequisites +To reduce false negatives in [dependency scans](../../../user/application_security/dependency_scanning/index.md) in scheduled pipelines, ensure you: -1. At least one project inside a group must be configured with at least one of - the [supported reports](#supported-reports). -1. The configured jobs must use the [new `reports` syntax](../../../ci/yaml/index.md#artifactsreports). -1. [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or newer must be used. - If you're using the shared runners on GitLab.com, this is already the case. +- Include a lock file in your project. A lock file lists all transient dependencies and tracks their versions. + - Java projects can't have lock files. + - Python projects can have lock files, but GitLab Secure tools don't support them. +- Configure your project for [Continuous Delivery](../../../ci/introduction/index.md). -## Pipeline Security +## View vulnerabilities in a pipeline > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13496) in GitLab 12.3. -At the pipeline level, the Security section displays the vulnerabilities present in the branch of -the project the pipeline ran against. - - +To view vulnerabilities in a pipeline: -Visit the page for any pipeline that ran any of the [supported reports](#supported-reports). To view -the pipeline's security findings, select the **Security** tab when viewing the pipeline. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **CI/CD > Pipelines**. +1. From the list, select the pipeline you want to check for vulnerabilities. +1. Select the **Security** tab. -A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish -for any reason, the security dashboard doesn't show SAST scanner output. For example, if the SAST +A pipeline consists of multiple jobs, such as SAST and DAST scans. If a job fails to finish, +the security dashboard doesn't show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard doesn't show SAST results. On failure, -the analyzer outputs an -[exit code](../../../development/integrations/secure.md#exit-code). +the analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code). + +## View total number of vulnerabilities per scan + +To view the total number of vulnerabilities per scan: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **CI/CD > Pipelines**. +1. Select the **Status** of a branch. +1. Select the **Security** tab. -### Scan details +**Scan details** show the total number of vulnerabilities found per scan in the pipeline. + +### Download security scan outputs > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3728) in GitLab 13.10. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/333660) in GitLab 14.2. -The **Scan details** section lists the scans run in the pipeline and 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 CSV file that contains URLs and endpoints scanned by the security scanner. + +To download a security scan output: -You can download the JSON artifacts from each security scan. Select **Download results** then -select the JSON artifact. Additionally for the DAST scan, from the **Download results** dropdown select -**Download scanned resources** to download a CSV file containing details of the resources scanned. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **CI/CD > Pipelines**. +1. Select the **Status** of a branch. +1. Select the **Security** tab. +1. In **Scan details**, select **Download results**: + - To download a JSON file, select the JSON artifact. + - To download a CSV file, select **Download scanned resources**. -## Project Security Dashboard +## View vulnerabilities over time for a project > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235558) in GitLab 13.6. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285476) in GitLab 13.10, options to zoom in on a date range, and download the vulnerabilities chart. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285477) in GitLab 13.11, date range slider to visualize data between given dates. -A project's Security Dashboard displays a chart with the total number of vulnerabilities -over time with up to 365 days of historical data. Data is refreshed daily at 1:15am UTC. By default, -it shows statistics for all vulnerability severities. +The project Security Dashboard shows the total number of vulnerabilities +over time, with up to 365 days of historical data. Data refreshes daily at 01:15 UTC. +It shows statistics for all vulnerabilities. -To access the dashboard, from your project's home page go to **Security & Compliance > Security Dashboard**. +To view total number of vulnerabilities over time: - +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Security Dashboard**. +1. Filter and search for what you need. + - To filter the chart by severity, select the legend name. + - To view a specific time frame, use the time range handles (**{scroll-handle}**). + - To view a specific area of the chart, select the left-most icon (**{marquee-selection}**) and drag + across the chart. + - To reset to the original range, select **Remove Selection** (**{redo}**). -### Filter the vulnerabilities chart +### Download the vulnerabilities chart -To filter the chart by vulnerability severity, select the corresponding legend name. +To download an SVG image of the vulnerabilities chart: -In the previous example, the chart shows statistics only for vulnerabilities of medium or unknown severity. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Security dashboard**. +1. Select **Save chart as an image** (**{download}**). -### Customize vulnerabilities chart display +## View vulnerabilities over time for a group -To customize the view of the vulnerability chart, you can select: +The group Security Dashboard gives an overview of vulnerabilities found in the default +branches of projects in a group and its subgroups. -- A specific time frame by using the time range handles (**{scroll-handle}**). -- A specific area of the chart by using the left-most icon (**{marquee-selection}**) then drag - across the chart. To reset to the original range, select **Remove Selection** (**{redo}**). +To view vulnerabilities over time for a group: -### Download a copy of the vulnerabilities chart +1. On the top bar, select **Menu > Groups** and select a group. +1. Select **Security > Security Dashboard**. +1. Hover over the chart to get more details about vulnerabilities. + - You can display the vulnerability trends over a 30, 60, or 90-day time frame (the default is 90 days). + - To view aggregated data beyond a 90-day time frame, use the + [VulnerabilitiesCountByDay GraphQL API](../../../api/graphql/reference/index.md#vulnerabilitiescountbyday). + GitLab retains the data for 365 days. -To download an SVG image of the chart, select **Save chart to an image** (**{download}**). +## View project security status for a group -## Group Security Dashboard +Use the group Security Dashboard to view the security status of projects. The security status is based +on the number of detected vulnerabilities. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6709) in GitLab 11.5. +To view project security status for a group: -The group Security Dashboard gives an overview of the vulnerabilities found in the default branches of the -projects in a group and its subgroups. Access it by navigating to **Security > Security Dashboard** -after selecting your group. By default, the Security Dashboard displays all detected and confirmed -vulnerabilities. If you don't see the vulnerabilities over time graph, the likely cause is that you -have not selected a group. +1. On the top bar, select **Menu > Groups** and select a group. +1. Select **Security > Security Dashboard**. -Note that the Security Dashboard only shows projects with -[security reports](#supported-reports) -enabled in a group. +Projects are [graded](#project-vulnerability-grades) by vulnerability severity. Dismissed vulnerabilities are excluded. - +To view vulnerabilities, go to the group's [vulnerability report](../vulnerability_report/index.md). -There is a timeline chart that shows how many open -vulnerabilities your projects had at various points in time. You can display the vulnerability -trends over a 30, 60, or 90-day time frame (the default is 90 days). Hover over the chart to get -more details about the open vulnerabilities at a specific time. Aggregated data beyond 90 days can be accessed by querying our [VulnerabilitiesCountByDay GraphQL API](../../../api/graphql/reference/index.md#vulnerabilitiescountbyday). This data is retained for 365 days. - -Next to the timeline chart is a list of projects, grouped and sorted by the severity of the vulnerability found: +### Project vulnerability grades | Grade | Description | -| F | One or more "critical" | -| D | One or more "high" or "unknown" | -| C | One or more "medium" | -| B | One or more "low" | -| A | Zero vulnerabilities | - -Projects with no vulnerability tests configured don't appear in the list. Additionally, dismissed -vulnerabilities are excluded. - -Navigate to the group's [vulnerability report](../vulnerability_report/index.md) to view the vulnerabilities found. +| --- | --- | +| **F** | One or more `critical` vulnerabilities | +| **D** | One or more `high` or `unknown` vulnerabilities | +| **C** | One or more `medium` vulnerabilities | +| **B** | One or more `low` vulnerabilities | +| **A** | Zero vulnerabilities | ## Security Center > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3426) in GitLab 13.4. -The Security Center is personal space where you manage vulnerabilities across all your projects. It -displays the vulnerabilities present in the default branches of all the projects you configure. It includes -the following: +The Security Center is a personal space where you view vulnerabilities across all your projects. It +shows the vulnerabilities present in the default branches of the projects. + +The Security Center includes: -- The [group security dashboard's](#group-security-dashboard) features. +- The group Security Dashboard. - A [vulnerability report](../vulnerability_report/index.md). -- A dedicated settings area to configure which projects to display. +- A settings area to configure which projects to display.  +### View the Security Center + To view the Security Center, on the top bar, select **Menu > Security**. -### Adding projects to the Security Center +### Add projects to the Security Center To add projects to the Security Center: -1. Click **Settings** in the left navigation bar or click the **Add projects** button. -1. Search for and add one or more projects using the **Search your projects** field. -1. Click the **Add projects** button. +1. On the top bar, select **Menu > Security**. +1. On the left sidebar, select **Settings**, or select **Add projects**. +1. Use the **Search your projects** text box to search for and select projects. +1. Select **Add projects**. - - -After you add projects, the security dashboard and vulnerability report display the vulnerabilities +After you add projects, the security dashboard and vulnerability report show the vulnerabilities found in those projects' default branches. -## Keep dashboards up to date - -The Security Dashboard displays results of the most recent security scan on the -[default branch](../../project/repository/branches/default.md). By default, security scans are run -only when the default branch is updated. Information on the Security Dashboard may not reflect -newly-discovered vulnerabilities. - -To ensure the information on the Security Dashboard is regularly updated, -[configure a scheduled pipeline](../../../ci/pipelines/schedules.md) to run a daily security scan. -This updates the information displayed on the Security Dashboard regardless of how often the default -branch is updated. - -WARNING: -Running Dependency Scanning from a scheduled pipeline might result in false negatives if your -project doesn't have a lock file and isn't configured for Continuous Delivery. A lock file is a file -that lists all transient dependencies and keeps track of their exact versions. The false negative -can occur because the dependency version resolved during the scan might differ from the ones -resolved when your project was built and released, in a previous pipeline. Java projects can't have -lock files. Python projects can have lock files, but GitLab Secure tools don't support them. - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues @@ -206,4 +199,8 @@ 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. --> -Read more on how to [address the vulnerabilities](../vulnerabilities/index.md). +## Related topics + +- [Address the vulnerabilities](../vulnerabilities/index.md) +- [Vulnerability reports](../vulnerability_report/index.md) +- [Vulnerability Page](../vulnerabilities/index.md) diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 7bdc8cc8479..9aa8a0cd3cd 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -37,7 +37,7 @@ A vulnerability's status can be one of the following: | Status | Description | |:----------|:------------| -| Detected | The default state for a newly discovered vulnerability. | +| Detected | The default state for a newly discovered vulnerability. Appears as "Needs triage" in the UI. | | Confirmed | A user has seen this vulnerability and confirmed it to be accurate. | | Dismissed | A user has seen this vulnerability and dismissed it because it is not accurate or otherwise not to be resolved. | | Resolved | The vulnerability has been fixed or is no longer present. | @@ -168,7 +168,7 @@ 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 at least once a week. See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | +| [Dependency Scanning](../dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for npm packages), and `gemnasium` (the GitLab tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated 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. | diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index 3773bb59c5a..05ff5c511f9 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -100,7 +100,7 @@ The content of the Project filter depends on the current level: | Level | Content of the Project filter | |:---------------|:------------------------------| -| Security Center | Only projects you've [added to your personal Security Center](../security_dashboard/index.md#adding-projects-to-the-security-center). | +| Security Center | Only projects you've [added to your personal Security Center](../security_dashboard/index.md#add-projects-to-the-security-center). | | Group level | All projects in the group. | | Project level | Not applicable. | diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md index 93768164df2..f1c49b87383 100644 --- a/doc/user/clusters/agent/ci_cd_tunnel.md +++ b/doc/user/clusters/agent/ci_cd_tunnel.md @@ -19,11 +19,8 @@ Only CI/CD jobs set in the configuration project can access one of the configure ## Prerequisites -- A running [`kas` instance](install/index.md#set-up-the-agent-server). -- A [configuration repository](install/index.md#define-a-configuration-repository) with an agent config file - installed (`.gitlab/agents/<agent-name>/config.yaml`). -- A [registered agent](install/index.md#register-an-agent-with-gitlab). -- The agent [installed in the cluster](install/index.md#install-the-agent-into-the-cluster). +- An existing Kubernetes cluster. +- An agent [installed on your cluster](install/index.md#install-the-agent-into-the-cluster). ## Use the CI/CD Tunnel to run Kubernetes commands from GitLab CI/CD diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index c950a4f0dc0..a235c0ef6f8 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -18,10 +18,6 @@ is an active in-cluster component for connecting Kubernetes clusters to GitLab s The Agent is installed into the cluster through code, providing you with a fast, safe, stable, and scalable solution. -INFO: -Get Network Security Alerts in GitLab by upgrading to Ultimate. -[Try a free 30-day trial now](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-cluster-agent-docs). - With GitOps, you can manage containerized clusters and applications from a Git repository that: - Is the single source of truth of your system. @@ -136,7 +132,22 @@ with the following differences: ## Remove an agent -1. Get the `<cluster-agent-id>` and the `<cluster-agent-token-id>` from a query in the interactive GraphQL explorer. +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). + +### Remove an agent through the GitLab UI + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323055) in GitLab 14.7. + +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**. + +### 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. @@ -157,7 +168,7 @@ For self-managed GitLab instances, go to `https://gitlab.example.com/-/graphql-e } ``` -1. Remove an Agent record with GraphQL by deleting the `clusterAgent` and the `clusterAgentToken`. +1. Remove an agent record with GraphQL by deleting the `clusterAgentToken`. ```graphql mutation deleteAgent { @@ -190,6 +201,10 @@ For self-managed GitLab instances, go to `https://gitlab.example.com/-/graphql-e 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 diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index cf8467a8d28..b2372789284 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -10,42 +10,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w To get started with the Agent, install it in your cluster. -Pre-requisites: +## Prerequisites **(SELF)** - An existing Kubernetes cluster. -- An account on GitLab. +- 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: -1. [Set up the Agent Server](#set-up-the-agent-server) for your GitLab instance. 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. [Generate and copy a Secret token used to connect to the agent](#create-the-kubernetes-secret). -1. [Create manifest files](#create-manifest-files). <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. -### Set up the Agent Server - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10, the GitLab Agent Server (KAS) became available on GitLab.com under `wss://kas.gitlab.com`. - -To use the KAS: - -- If you are a self-managed user, follow the instructions to [install the Agent Server](../../../../administration/clusters/kas.md). -- If you are a GitLab.com user, when you [set up the configuration repository](#define-a-configuration-repository) for your agent, use `wss://kas.gitlab.com` as the `--kas-address`. - ### 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: - -1. A GitLab repository to hold the configuration file. -1. Install the Agent in a cluster. +To create an agent, you need a GitLab repository to hold the configuration file. After installed, when you update the configuration file, GitLab transmits the information to the cluster automatically without downtime. @@ -62,7 +47,7 @@ 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. It doesn't do anything so far, but, later on, you can use this +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: - Groups and projects that can access the agent via the [CI/CD Tunnel](../ci_cd_tunnel.md). @@ -71,10 +56,6 @@ file to [configure the agent](../repository.md) by setting up parameters such as To see all the settings available, read the [Agent configuration repository documentation](../repository.md). -### Access your cluster from GitLab CI/CD - -Use the [CI/CD Tunnel](../ci_cd_tunnel.md#example-for-a-kubectl-command-using-the-cicd-tunnel) to access your cluster from GitLab CI/CD. - ### Register an 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. @@ -92,242 +73,53 @@ In GitLab: 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**. +### Install the agent into the cluster + In your computer: 1. Open your local terminal and connect to your cluster. -1. Run the command you copied from the installation form. +1. Run the command you copied when registering your cluster in the previous step. -### Install the agent into the cluster +See the following sections to learn about customizing the installation. -To install the in-cluster component of the Agent, first you need to define a namespace. To create a new namespace, -for example, `gitlab-kubernetes-agent`, run: +## Simple installation method -```shell -kubectl create namespace gitlab-kubernetes-agent -``` +The command provided by GitLab does the following things: -To perform a one-liner installation, run the command below. Make sure to replace: +- 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. +- Creates a `Deployment` resource for the `agentk` pod. -- `your-agent-token` with the token received from the previous step (identified as `secret` in the JSON output). -- `gitlab-kubernetes-agent` with the namespace you defined in the previous step. -- `wss://kas.gitlab.example.com` with the configured access of the Agent Server (KAS). For GitLab.com users, the KAS is available under `wss://kas.gitlab.com`. -- `--agent-version=vX.Y.Z` with the latest released patch version matching your GitLab installation's major and minor versions. For example, for GitLab v13.9.0, use `--agent-version=v13.9.1`. You can find your GitLab version under the "Help/Help" menu. +The one-liner installer can be customized at the command line. To find out the various options the above Docker container supports, run: ```shell -docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version=vX.Y.Z --namespace gitlab-kubernetes-agent | kubectl apply -f - +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. -To find out the various options the above Docker container supports, run: - -```shell -docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help -``` - -## Advanced installation +## Advanced installation method 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). Otherwise, follow the manual installation steps described below. -### Create the Kubernetes secret - -After generating the token, you must apply it to the Kubernetes cluster. - -To create your Secret, run: - -```shell -kubectl create secret generic -n gitlab-kubernetes-agent gitlab-kubernetes-agent-token --from-literal=token='YOUR_AGENT_TOKEN' -``` - -The following example file contains the -Kubernetes resources required for the Agent to be installed. You can modify this -example [`resources.yml` file](#example-resourcesyml-file) in the following ways: - -- Replace `namespace: gitlab-kubernetes-agent` with `namespace: <YOUR-DESIRED-NAMESPACE>`. -- You can configure `kas-address` (Agent Server) in several ways. - The agent can use the WebSockets or gRPC protocols to connect to the Agent Server. - Select the option appropriate for your cluster configuration and GitLab architecture: - - The `wss` scheme (an encrypted WebSockets connection) is specified by default - after you install the `gitlab-kas` sub-chart, or enable `gitlab-kas` for Omnibus GitLab. - When using the sub-chart, you must set `wss://kas.host.tld:443` as - `kas-address`, where `host.tld` is the domain you've setup for your GitLab installation. - When using Omnibus GitLab, you must set `wss://GitLab.host.tld:443/-/kubernetes-agent/` as - `kas-address`, where `GitLab.host.tld` is your GitLab hostname. - - When using the sub-chart, specify the `ws` scheme (such as `ws://kas.host.tld:80`) - to use an unencrypted WebSockets connection. - When using the Omnibus GitLab, specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent/`). - - Specify the `grpc` scheme if both Agent and Server are installed in one cluster. - In this case, you may specify `kas-address` value as - `grpc://gitlab-kas.<your-namespace>:8150`) to use gRPC directly, where `gitlab-kas` - is the name of the service created by `gitlab-kas` chart, and `<your-namespace>` - is the namespace where the chart was installed. - - Specify the `grpcs` scheme to use an encrypted gRPC connection. - - When deploying KAS through the [GitLab chart](https://docs.gitlab.com/charts/), it's possible to customize the - `kas-address` for `wss` and `ws` schemes to whatever you need. - Check the [chart's KAS Ingress documentation](https://docs.gitlab.com/charts/charts/gitlab/kas/#ingress) - to learn more about it. - - In the near future, Omnibus GitLab intends to provision `gitlab-kas` under a sub-domain by default, instead of the `/-/kubernetes-agent/` path. Please follow [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5784) for details. -- If you defined your own secret name, replace `gitlab-kubernetes-agent-token` with your - secret name in the `secretName:` section. - -To apply this file, run the following command: +### Customize the permissions for the `agentk` service account -```shell -kubectl apply -n gitlab-kubernetes-agent -f ./resources.yml -``` - -To review your configuration, run the following command: - -```shell -$ kubectl get pods -n gitlab-kubernetes-agent - -NAMESPACE NAME READY STATUS RESTARTS AGE -gitlab-kubernetes-agent gitlab-kubernetes-agent-77689f7dcb-5skqk 1/1 Running 0 51s -``` - -#### Example `resources.yml` file - -```yaml ---- -apiVersion: v1 -kind: Namespace -metadata: - name: gitlab-kubernetes-agent ---- -apiVersion: v1 -kind: ServiceAccount -metadata: - name: gitlab-kubernetes-agent ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: gitlab-kubernetes-agent -spec: - replicas: 1 - selector: - matchLabels: - app: gitlab-kubernetes-agent - template: - metadata: - labels: - app: gitlab-kubernetes-agent - spec: - serviceAccountName: gitlab-kubernetes-agent - containers: - - name: agent - # Make sure to specify a matching version for production - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:vX.Y.Z" - 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 - volumes: - - name: token-volume - secret: - secretName: gitlab-kubernetes-agent-token - strategy: - type: RollingUpdate - rollingUpdate: - maxSurge: 0 - maxUnavailable: 1 ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: gitlab-kubernetes-agent-write -rules: -- resources: - - '*' - apiGroups: - - '*' - verbs: - - create - - update - - delete - - patch ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: gitlab-kubernetes-agent-write-binding -roleRef: - name: gitlab-kubernetes-agent-write - kind: ClusterRole - apiGroup: rbac.authorization.k8s.io -subjects: -- name: gitlab-kubernetes-agent - kind: ServiceAccount - namespace: gitlab-kubernetes-agent ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: gitlab-kubernetes-agent-read -rules: -- resources: - - '*' - apiGroups: - - '*' - verbs: - - get - - list - - watch ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: gitlab-kubernetes-agent-read-binding -roleRef: - name: gitlab-kubernetes-agent-read - kind: ClusterRole - apiGroup: rbac.authorization.k8s.io -subjects: -- name: gitlab-kubernetes-agent - kind: ServiceAccount - namespace: gitlab-kubernetes-agent -``` - -### Create manifest files +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. -In a previous step, you configured a `config.yaml` to point to the GitLab projects -the Agent should synchronize. Agent monitors each of those projects for changes to the manifest files it contains. You can auto-generate manifest files with a -templating engine or other means. +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. -The agent is authorized to download manifests for the configuration -project, and public projects. Support for other private projects is -planned in the issue [Agent authorization for private manifest -projects](https://gitlab.com/gitlab-org/gitlab/-/issues/220912). +To create restricted permissions: -Each time you push a change to a monitored manifest repository, the Agent logs the change: +1. Copy the `cluster` directory. +1. Edit the `kustomization.yaml` and `components/*` files based on your requirements. +1. Run `kustomize build <your copied directory> | kubectl apply -f -` to apply your configuration. -```plaintext -2020-09-15_14:09:04.87946 gitlab-k8s-agent : time="2020-09-15T10:09:04-04:00" level=info msg="Config: new commit" agent_id=1 commit_id=e6a3651f1faa2e928fe6120e254c122451be4eea -``` - -#### Example manifest file - -This file creates a minimal `ConfigMap`: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: demo-map - namespace: gitlab-kubernetes-agent # Can be any namespace managed by you that the agent has access to. -data: - key: value -``` +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 diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index c8ab037118e..22964fde395 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -12,9 +12,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - The [GitLab Agent](index.md) supports hosting your configuration for multiple agents in a single repository. These agents can be running in the same cluster or in multiple clusters, and potentially with more than one agent per cluster. diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 88382648b04..f880e603133 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -54,7 +54,7 @@ Supported applications: - [PostHog](#install-posthog-using-gitlab-cicd) - [Prometheus](#install-prometheus-using-gitlab-cicd) -### Usage +### Prerequisites You can find and import all the files referenced below in the [example cluster applications @@ -95,7 +95,7 @@ applications you have configured. In case of pipeline failure, the output of the [Helm Tiller](https://v2.helm.sh/docs/install/#running-tiller-locally) binary is saved as a [CI job artifact](../../ci/pipelines/job_artifacts.md). -#### Usage in GitLab versions earlier than 13.5 +#### Prerequisites in GitLab versions earlier than 13.5 For GitLab versions 13.5 and earlier, the Ingress, Fluentd, Prometheus, and Sentry apps were fetched from the central Helm stable repository (`https://kubernetes-charts.storage.googleapis.com/`). @@ -443,7 +443,7 @@ You can check the recommended variables for each cluster type in the official do - [Google GKE](https://docs.cilium.io/en/v1.8/gettingstarted/k8s-install-gke/#deploy-cilium) - [AWS EKS](https://docs.cilium.io/en/v1.8/gettingstarted/k8s-install-eks/#deploy-cilium) -Do not use `clusterType` for sandbox environments like [Minikube](https://minikube.sigs.k8s.io/docs/). +Do not use `clusterType` for sandbox environments like [minikube](https://minikube.sigs.k8s.io/docs/). You can customize Cilium's Helm variables by defining the `.gitlab/managed-apps/cilium/values.yaml` file in your cluster diff --git a/doc/user/compliance/index.md b/doc/user/compliance/index.md index 61b65bf254f..7b46886e236 100644 --- a/doc/user/compliance/index.md +++ b/doc/user/compliance/index.md @@ -7,15 +7,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Compliance **(ULTIMATE)** -The compliance tools provided by GitLab let you keep an eye on various aspects of your project. The -following compliance tools are available: - -- [Compliance report](compliance_report/index.md): View recent merge request activity across - all projects in a group. This lets you see if merge requests were approved, and by whom. -- [License Compliance](license_compliance/index.md): Search your project's dependencies for their - licenses. This lets you determine if the licenses of your project's dependencies are compatible - with your project's license. -- [Compliance framework labels](../project/settings/index.md#compliance-frameworks): Label your projects that have unique compliance requirements. -- [Compliance pipelines](../project/settings/index.md#compliance-pipeline-configuration): Ensure that needed compliance jobs are always run for compliance-labeled projects. -- [Audit Events](../../administration/audit_events.md): Get visibility into individual actions that have taken place in your GitLab instance, group, or project. -- [Audit Reports](../../administration/audit_reports.md): Create and access reports based on the audit events that have occurred. Use pre-built GitLab reports or the API to build your own. +The compliance tools provided by GitLab help you keep an eye on various aspects of your project. For more information +on GitLab compliance features for projects, groups, and instances, see +[Compliance features](../../administration/compliance.md). diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index f89165e7e2d..04d3cc0595e 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -5,7 +5,7 @@ group: Composition Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# License Compliance **(ULTIMATE)** +# License compliance **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5483) in GitLab 11.0. @@ -14,10 +14,6 @@ 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. -INFO: -Try License Compliance scanning to search project dependencies in GitLab Ultimate. -[It's free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-compliance-docs). - You can take advantage of License Compliance by either: - [Including the job](#configuration) @@ -73,7 +69,7 @@ Gradle 1.x projects are not supported. The minimum supported version of Maven is | Language | Package managers | Notes | |------------|----------------------------------------------------------------------------------------------|-------| | JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/) (7 and earlier) | | -| Go | [Godep](https://github.com/tools/godep), [go mod](https://github.com/golang/go/wiki/Modules) | | +| Go | [Godep](https://github.com/tools/godep) ([deprecated](../../../update/deprecations.md#godep-support-in-license-compliance)), [go mod](https://github.com/golang/go/wiki/Modules) | | | Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | | | .NET | [NuGet](https://www.nuget.org/) | The .NET Framework is supported via the [mono project](https://www.mono-project.com/). There are, however, some limitations. The scanner doesn't support Windows-specific dependencies and doesn't report dependencies of your project's listed dependencies. Also, the scanner always marks detected licenses for all dependencies as `unknown`. | | Python | [pip](https://pip.pypa.io/en/stable/) | Python is supported through [requirements.txt](https://pip.pypa.io/en/stable/user_guide/#requirements-files) and [Pipfile.lock](https://github.com/pypa/pipfile#pipfilelock). | @@ -92,7 +88,6 @@ The reported licenses might be incomplete or inaccurate. | Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage), [CocoaPods](https://cocoapods.org/) v0.39 and below | | Elixir | [Mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) | | C++/C | [Conan](https://conan.io/) | -| Scala | [sbt](https://www.scala-sbt.org/) | | Rust | [Cargo](https://crates.io) | | PHP | [Composer](https://getcomposer.org/) | @@ -809,6 +804,10 @@ An approval is optional when a license report: - Contains no software license violations. - Contains only new licenses that are `allowed` or unknown. +## Warnings + +We recommend that you use the most recent version of all containers, and the most recent supported version of all package managers and languages. Using previous versions carries an increased security risk because unsupported versions may no longer benefit from active security reporting and backporting of security fixes. + ## Troubleshooting ### ASDF_PYTHON_VERSION does not automatically install the version diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md index d68ce0a4f7a..f0f9a907a73 100644 --- a/doc/user/crm/index.md +++ b/doc/user/crm/index.md @@ -6,13 +6,7 @@ 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. - -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. -You should not use this feature for production environments. +> - [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. With customer relations management (CRM) you can create a record of contacts (individuals) and organizations (companies) and relate them to issues. @@ -20,6 +14,25 @@ With customer relations management (CRM) you can create a record of contacts You can use contacts and organizations to tie work to customers for billing and reporting purposes. To read more about what is planned for the future, see [issue 2256](https://gitlab.com/gitlab-org/gitlab/-/issues/2256). +## Permissions + +| Permission | Guest | Reporter | Developer, Maintainer, and Owner | +| ---------- | ---------------- | -------- | -------------------------------- | +| View contacts/organizations | | ✓ | ✓ | +| View issue contacts | | ✓ | ✓ | +| Add/remove issue contacts | | ✓ | ✓ | +| Create/edit contacts/organizations | | | ✓ | + +## Enable customer relations management (CRM) + +To enable customer relations management in a group: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand the **Permissions and group features** section. +1. Select **Enable customer relations**. +1. Select **Save changes**. + ## Contacts ### View contacts linked to a group @@ -118,10 +131,6 @@ API. ### Add or remove issue contacts -Prerequisites: - -- You must have at least the [Developer role](../permissions.md#project-members-permissions) for a group. - ### Add contacts to an issue To add contacts to an issue use the `/add_contacts` diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 8d858a282dd..f02073b477b 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -70,7 +70,7 @@ To back up an entire project on GitLab.com, you can export it either: can also use the API to programmatically upload exports to a storage platform, such as Amazon S3. -With exports, be aware of [what is and is not](../project/settings/import_export.md#exported-contents) +With exports, be aware of [what is and is not](../project/settings/import_export.md#items-that-are-exported) included in a project export. GitLab is built on Git, so you can back up just the repository of a project by @@ -162,17 +162,18 @@ varies by format: ## Account and limit settings -GitLab.com has the following [account limits](../admin_area/settings/account_and_limit_settings.md) -enabled. If a setting is not listed, it is set to the default value. +GitLab.com has the following account limits enabled. If a setting is not listed, +the default value [is the same as for self-managed instances](../admin_area/settings/account_and_limit_settings.md): -If you are near or over the repository size limit, you can either -[reduce your repository size with Git](../project/repository/reducing_the_repo_size_using_git.md) or [purchase additional storage](https://about.gitlab.com/pricing/licensing-faq/#can-i-buy-more-storage). +| Setting | GitLab.com default | +|-------------------------------|--------------------| +| [Repository size including LFS](../admin_area/settings/account_and_limit_settings.md#repository-size-limit) | 10 GB | +| Maximum import size | 5 GB | +| Maximum attachment size | 10 MB | -| Setting | GitLab.com | Default | -|-------------------------------|-------------|---------| -| [Repository size including LFS](../admin_area/settings/account_and_limit_settings.md#repository-size-limit) | 10 GB | Unlimited | -| Maximum import size | 5 GB | Unlimited ([Modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to unlimited in GitLab 13.8.) | -| Maximum attachment size | 10 MB | 10 MB | +If you are near or over the repository size limit, you can either +[reduce your repository size with Git](../project/repository/reducing_the_repo_size_using_git.md) +or [purchase additional storage](https://about.gitlab.com/pricing/licensing-faq/#can-i-buy-more-storage). NOTE: `git push` and GitLab project imports are limited to 5 GB per request through @@ -209,13 +210,17 @@ also load certain page content directly from common public CDN hostnames. ## Webhooks -The following limits apply for [Webhooks](../project/integrations/webhooks.md): +The following limits apply for [webhooks](../project/integrations/webhooks.md): + +| Setting | Default for GitLab.com | +|----------------------|-------------------------| +| Webhook rate limit | `120` calls per minute for GitLab Free, unlimited for GitLab Premium and GitLab Ultimate | +| Number of webhooks | `100` per project, `50` per group | +| Maximum payload size | 25 MB | -| Setting | GitLab.com | Default | -|----------------------|-------------|---------| -| [Webhook rate limit](../../administration/instance_limits.md#webhook-rate-limit) | `120` calls per minute for GitLab Free, unlimited for GitLab Premium and GitLab Ultimate | Unlimited | -| [Number of webhooks](../../administration/instance_limits.md#number-of-webhooks) | `100` per project, `50` per group | `100` per project, `50` per group | -| Maximum payload size | 25 MB | 25 MB | +For self-managed instance limits, see +[Webhook rate limit](../../administration/instance_limits.md#webhook-rate-limit) +and [Number of webhooks](../../administration/instance_limits.md#number-of-webhooks). ## Runner SaaS diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md index 1bc1e4d703b..d184030718a 100644 --- a/doc/user/group/epics/epic_boards.md +++ b/doc/user/group/epics/epic_boards.md @@ -9,10 +9,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5067) in GitLab 13.10. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/290039) in GitLab 14.1. -INFO: -Try epic boards and more with a -[free 30-day trial of GitLab Ultimate](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-epics-boards-docs). - Epic boards build on the existing [epic tracking functionality](index.md) and [labels](../../project/labels.md). Your epics appear as cards in vertical lists, organized by their assigned labels. diff --git a/doc/user/group/epics/img/epics_search_v13_11.png b/doc/user/group/epics/img/epics_search_v13_11.png Binary files differdeleted file mode 100644 index c11aca96a99..00000000000 --- a/doc/user/group/epics/img/epics_search_v13_11.png +++ /dev/null diff --git a/doc/user/group/epics/img/epics_search_v14_7.png b/doc/user/group/epics/img/epics_search_v14_7.png Binary files differnew file mode 100644 index 00000000000..baed532c736 --- /dev/null +++ b/doc/user/group/epics/img/epics_search_v14_7.png diff --git a/doc/user/group/epics/img/epics_sort.png b/doc/user/group/epics/img/epics_sort.png Binary files differdeleted file mode 100644 index b23c65fd0ef..00000000000 --- a/doc/user/group/epics/img/epics_sort.png +++ /dev/null diff --git a/doc/user/group/epics/img/epics_sort_14_7.png b/doc/user/group/epics/img/epics_sort_14_7.png Binary files differnew file mode 100644 index 00000000000..df84dccd06c --- /dev/null +++ b/doc/user/group/epics/img/epics_sort_14_7.png diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 3889398e2f8..d6f87a026b8 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -8,10 +8,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Single-level epics were [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) from GitLab Ultimate to GitLab Premium in 12.8. -INFO: -Check out [multi-level child epics](manage_epics.md#multi-level-child-epics) with a -[free 30-day trial of GitLab Ultimate](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-epics-docs). - When [issues](../../project/issues/index.md) share a theme across projects and milestones, you can manage them by using epics. diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index f5b1a2a6ee6..caca10a05a2 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -163,6 +163,8 @@ than 1000. The cached value is rounded to thousands or millions and updated ever > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) from GitLab Ultimate to GitLab Premium in 12.8. > - Searching by the user's reaction emoji [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325630) in GitLab 13.11. > - 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. You can search for an epic from the list of epics using filtered search bar based on following parameters: @@ -170,9 +172,11 @@ parameters: - Title or description - Author name / username - Labels +- Milestones +- Confidentiality - Reaction emoji - + To search: @@ -184,8 +188,6 @@ To search: You can also sort epics list by: -- Created date -- Last updated - Start date - Due date - Title @@ -194,7 +196,7 @@ Each option contains a button that can toggle the order between **Ascending** an The sort option and order is saved and used wherever you browse epics, including the [Roadmap](../roadmap/index.md). - + ## Change activity sort order diff --git a/doc/user/group/img/group_code_coverage_analytics_v13_9.png b/doc/user/group/img/group_code_coverage_analytics_v13_9.png Binary files differdeleted file mode 100644 index 8cd71396381..00000000000 --- a/doc/user/group/img/group_code_coverage_analytics_v13_9.png +++ /dev/null diff --git a/doc/user/group/index.md b/doc/user/group/index.md index db6ed02f405..8aa9b8e799d 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Manage -group: Access +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 --- @@ -100,6 +100,14 @@ You can give a user access to all projects in a group. 1. Fill in the fields. - The role applies to all projects in the group. [Learn more about permissions](../permissions.md). - On the **Access expiration date**, the user can no longer access projects in the group. +1. Select **Invite**. + +Members that are not automatically added are displayed on the **Invited** tab. +Users can be on this tab because they: + +- Have not yet accepted the invitation. +- Are waiting for [approval from an administrator](../admin_area/moderate_users.md). +- [Exceed the group user cap](#user-cap-for-groups). ## Request access to a group @@ -123,7 +131,7 @@ your group. 1. Select **Your Groups**. 1. Find the group and select it. 1. From the left menu, select **Settings > General**. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Clear the **Allow users to request access** checkbox. 1. Select **Save changes**. @@ -219,7 +227,7 @@ To change this setting for a specific group: 1. Select **Your Groups**. 1. Find the group and select it. 1. From the left menu, select **Settings > General**. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Select the desired option in the **Default branch protection** dropdown list. 1. Select **Save changes**. @@ -250,7 +258,7 @@ To change this setting for a specific group: 1. Select **Your Groups**. 1. Find the group and select it. 1. From the left menu, select **Settings > General**. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Select the desired option in the **Allowed to create projects** dropdown list. 1. Select **Save changes**. @@ -489,7 +497,7 @@ If you select this setting in the **Animals** group: To prevent sharing outside of the group's hierarchy: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Select **Prevent members from sending invitations to groups outside of `<group_name>` and its subgroups**. 1. Select **Save changes**. @@ -501,13 +509,81 @@ a project with another group](../project/members/share_project_with_groups.md) t To prevent a project from being shared with other groups: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Select **Prevent sharing a project within `<group_name>` with other groups**. 1. Select **Save changes**. This setting applies to all subgroups unless overridden by a group owner. Groups already added to a project lose access when the setting is enabled. +## User cap for groups + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330027) in GitLab 14.7. + +FLAG: +On self-managed GitLab, this feature is not available. On GitLab.com, this feature is available for some groups. +This feature is not ready for production use. + +When the number of billable members reaches the user cap, new users can't be added to the group +without being approved by the group owner. + +Groups with the user cap feature enabled have [group sharing](#share-a-group-with-another-group) +disabled for the group and its subgroups. + +### Specify a user cap for a group + +Prerequisite: + +- You must be assigned the [Owner role](../permissions.md#group-members-permissions) for the group. + +To specify a user cap: + +1. On the top bar, select **Menu > Groups** and find your group. + You can set a cap on the top-level group only. +1. On the left sidebar, select **Settings > General**. +1. Expand **Permissions and group features**. +1. In the **User cap** box, enter the desired number of users. +1. Select **Save changes**. + +If you already have more users in the group than the user cap value, users +are not removed. However, you can't add more without approval. + +Increasing the user cap does not approve pending members. + +### Remove the user cap for a group + +You can remove the user cap, so there is no limit on the number of members you can add to a group. + +Prerequisite: + +- You must be assigned the [Owner role](../permissions.md#group-members-permissions) for the group. + +To remove the user cap: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand **Permissions and group features**. +1. In the **User cap** box, delete the value. +1. Select **Save changes**. + +Decreasing the user cap does not approve pending members. + +### Approve pending members for a group + +When the number of billable users reaches the user cap, any new member is put in a pending state +and must be approved. + +Prerequisite: + +- You must be assigned the [Owner role](../permissions.md#group-members-permissions) for the group. + +To approve members that are pending because they've exceeded the user cap: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > Usage Quotas**. +1. On the **Seats** tab, under the alert, select **View pending approvals**. +1. For each member you want to approve, select **Approve**. + ## Prevent members from being added to projects in a group **(PREMIUM)** As a group owner, you can prevent any new project membership for all @@ -523,7 +599,7 @@ The setting does not cascade. Projects in subgroups observe the subgroup configu To prevent members from being added to projects in a group: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Under **Member lock**, select **Prevent adding new members to project membership within this group**. 1. Select **Save changes**. @@ -535,9 +611,9 @@ API requests to add a new user to a project are not possible. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/287940) in GitLab 14.2. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/336520) in GitLab 14.5. -You can export a list of members in a group as a CSV. +You can export a list of members in a group or subgroup as a CSV. -1. Go to your project and select **Project information > Members**. +1. Go to your group or subgroup and select either **Group information > Members** or **Subgroup information > Members**. 1. Select **Export as CSV**. 1. Once the CSV file has been generated, it is emailed as an attachment to the user that requested it. @@ -574,7 +650,7 @@ You should consider these security implications before configuring IP address re To restrict group access by IP address: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +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. Select **Save changes**. @@ -591,13 +667,15 @@ You can prevent users with email addresses in specific domains from being added To restrict group access by domain: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. In the **Restrict membership by email** field, enter the domain names. 1. Select **Save changes**.  -Any time you attempt to add a new user, they are compared against this list. +Any time you attempt to add a new user, the user's [primary email](../profile/index.md#change-your-primary-email) is compared against this list. +Only users with a [primary email](../profile/index.md#change-your-primary-email) that matches any of the configured email domain restrictions +can be added to the group. Some domains cannot be restricted. These are the most popular public email domains, such as: @@ -645,7 +723,7 @@ You can disable all email notifications related to the group, which includes its To disable email notifications: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Select **Disable email notifications**. 1. Select **Save changes**. @@ -663,7 +741,7 @@ This is particularly helpful for groups with a large number of users. To disable group mentions: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Select **Disable group mentions**. 1. Select **Save changes**. @@ -688,7 +766,7 @@ the default setting. To enable delayed deletion of projects in a group: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Check **Enable delayed project deletion**. 1. Optional. To prevent subgroups from changing this setting, select **Enforce for all subgroups**. 1. Select **Save changes**. @@ -713,7 +791,7 @@ If even one is set to `true`, then the group does not allow outside forks. To prevent projects from being forked outside the group: 1. Go to the top-level group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Check **Prevent project forking outside current group**. 1. Select **Save changes**. @@ -774,7 +852,7 @@ To view the merge request approval rules for a group: - [Webhooks](../project/integrations/webhooks.md). - [Kubernetes cluster integration](clusters/index.md). - [Audit Events](../../administration/audit_events.md#group-events). -- [Pipelines quota](../admin_area/settings/continuous_integration.md): Keep track of the pipeline quota for the group. +- [CI/CD minutes quota](../../ci/pipelines/cicd_minutes.md): Keep track of the CI/CD minute quota for the group. - [Integrations](../admin_area/settings/project_integration_management.md). - [Transfer a project into a group](../project/settings/index.md#transferring-an-existing-project-into-another-namespace). - [Share a project with a group](../project/members/share_project_with_groups.md): Give all group members access to the project at once. diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index ac5df6b052f..62337dabcc0 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -5,15 +5,18 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Issue Analytics **(PREMIUM)** +# Issue analytics for groups **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7478) in GitLab 11.5. -Issue Analytics is a bar graph which illustrates the number of issues created each month. +Issue analytics is a bar graph which illustrates the number of issues created each month. The default time span is 13 months, which includes the current month, and the 12 months prior. -To access the chart, navigate to your group sidebar and select **{chart}** **Analytics > Issue Analytics**. +To access the chart: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Issue Analytics**. Hover over each bar to see the total number of issues. diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index c6cd763355b..2487ab188e8 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -5,11 +5,15 @@ group: Testing info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Repositories Analytics **(PREMIUM)** +# Repositories analytics for groups **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in GitLab 13.4. - +Repositories analytics for groups provides information about test coverage for all projects in a group. An +[issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/273527) to also extend support for all projects in +subgroups. + +It is similar to [repository analytics for projects](../../analytics/repository_analytics.md). ## Current group code coverage diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md index d62b569a795..06e666f4d24 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: Access +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 --- @@ -113,7 +113,7 @@ on the lifetime of personal access tokens apply. To set a limit on how long personal access tokens are valid for users in a group managed account: 1. Navigate to the **Settings > General** page in your group's sidebar. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Fill in the **Maximum allowable lifetime for personal access tokens (days)** field. 1. Click **Save changes**. diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 7443be250bb..20ff4a201f5 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: Access +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 --- @@ -14,10 +14,6 @@ This page describes SAML for groups. For instance-wide SAML on self-managed GitL SAML on GitLab.com allows users to sign in through their SAML identity provider. If the user is not already a member, the sign-in process automatically adds the user to the appropriate group. -INFO: -Use your own SAML authentication to log in to [GitLab.com](http://gitlab.com/). -[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-saml-sso-docs). - User synchronization of SAML SSO groups is supported through [SCIM](scim_setup.md). SCIM supports adding and removing users from the GitLab group automatically. For example, if you remove a user from the SCIM app, SCIM removes that same user from the GitLab group. @@ -72,10 +68,10 @@ To create users with the correct information for improved [user access and manag the user's details must be passed to GitLab as attributes in the SAML assertion. At a minimum, the user's email address must be specified as an attribute named `email` or `mail`. -GitLab.com supports the following attributes: +You can configure the following attributes with GitLab.com Group SAML: - `username` or `nickname`. We recommend you configure only one of these. -- The [attributes also available](../../../integration/saml.md#assertions) to self-managed GitLab instances. +- The [attributes available](../../../integration/saml.md#assertions) to self-managed GitLab instances. ### Metadata configuration @@ -110,6 +106,7 @@ The certificate [fingerprint algorithm](../../../integration/saml.md#notes-on-co > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/292811) in GitLab 13.8, with an updated timeout experience. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/211962) in GitLab 13.8 with allowing group owners to not go through SSO. > - [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. @@ -127,6 +124,7 @@ SSO has the following effects when enabled: even if the project is forked. - For Git activity over SSH and HTTPS, users must have at least one active session signed-in through SSO before they can push to or pull from a GitLab repository. +- 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 --> @@ -137,8 +135,6 @@ When SSO is enforced, users are not immediately revoked. If the user: - Has an active session, they can continue accessing the group for up to 24 hours until the identity provider session times out. -When SCIM updates, the user's access is immediately revoked. - ## Providers 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. @@ -167,10 +163,11 @@ objectID mapping and the [SCIM documentation should be followed](scim_setup.md#a | Identity provider single sign-on URL | Login URL | | Certificate fingerprint | Thumbprint | -We recommend: +The recommended attributes and claims settings are: - **Unique User Identifier (Name identifier)** set to `user.objectID`. - **nameid-format** set to persistent. +- Additional claims set to [supported attributes](#user-attributes). If using [Group Sync](#group-sync), customize the name of the group claim to match the required attribute. @@ -304,7 +301,14 @@ If a user is already a member of the group, linking the SAML identity does not c ### Blocking access -Please refer to [Blocking access via SCIM](scim_setup.md#blocking-access). +To rescind a user's access to the group when only SAML SSO is configured, either: + +- Remove (in order) the user from: + 1. The user data store on the identity provider or the list of users on the specific app. + 1. The GitLab.com group. +- Use Group Sync at the top-level of your group to [automatically remove the user](#automatic-member-removal). + +To rescind a user's access to the group when also using SCIM, refer to [Blocking access](scim_setup.md#blocking-access). ### Unlinking accounts @@ -349,6 +353,10 @@ 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) diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 2651bcb9e12..d7d663f4115 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: Access +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 --- @@ -184,8 +184,7 @@ For role information, please see the [Group SAML page](index.md#user-access-and- ### Blocking access To rescind access to the top-level group, all sub-groups, and projects, remove or deactivate the user -on the identity provider. SCIM providers generally update GitLab with the changes on demand, which -is minutes at most. The user's membership is revoked and they immediately lose access. +on the identity provider. After the identity provider performs a sync, based on its configured schedule, the user's membership is revoked and they lose access. NOTE: Deprovisioning does not delete the GitLab user account. diff --git a/doc/user/group/settings/group_access_tokens.md b/doc/user/group/settings/group_access_tokens.md new file mode 100644 index 00000000000..816edb629f5 --- /dev/null +++ b/doc/user/group/settings/group_access_tokens.md @@ -0,0 +1,147 @@ +--- +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" +type: reference, howto +--- + +# Group access tokens + +With group access tokens, you can use a single token to: + +- Perform actions for groups. +- Manage the projects within the group. + +You can use a group access token to authenticate: + +- With the [GitLab API](../../../api/index.md#personalprojectgroup-access-tokens). +- In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/330718) and later, authenticate with Git over HTTPS. + +After you configure a group access token, you don't need a password when you authenticate. +Instead, you can enter any non-blank value. + +Group access tokens are similar to [project access tokens](../../project/settings/project_access_tokens.md) +and [personal access tokens](../../profile/personal_access_tokens.md), except they are +associated with a group rather than a project or user. + +You can use group access tokens: + +- On GitLab SaaS if you have the Premium license tier or higher. Group access tokens are not available with a [trial license](https://about.gitlab.com/free-trial/). +- On self-managed instances of GitLab, with any license tier. If you have the Free tier: + - Review your security and compliance policies around + [user self-enrollment](../../admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups). + - Consider [disabling group access tokens](#enable-or-disable-group-access-token-creation) to + lower potential abuse. + +Group access tokens inherit the [default prefix setting](../../admin_area/settings/account_and_limit_settings.md#personal-access-token-prefix) +configured for personal access tokens. + +## Create a group access token using UI + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214045) in GitLab 14.7. + +To create a group access token: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > Access Tokens**. +1. Enter a name. +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-group-access-token). +1. Select **Create group access token**. + +A group access token is displayed. Save the group access token somewhere safe. After you leave or refresh the page, you can't view it again. + +## Create a group access token using Rails console + +GitLab 14.6 and earlier doesn't support creating group access tokens using the UI +or API. However, administrators can use a workaround: + +1. Run the following commands in a [Rails console](../../../administration/operations/rails_console.md): + + ```ruby + # Set the GitLab administration user to use. If user ID 1 is not available or is not an administrator, use 'admin = User.admins.first' instead to select an administrator. + admin = User.find(1) + + # Set the group group you want to create a token for. For example, group with ID 109. + group = Group.find(109) + + # Create the group bot user. For further group access tokens, the username should be group_#{group.id}_bot#{bot_count}. For example, group_109_bot2 and email address group_109_bot2@example.com. + bot = Users::CreateService.new(admin, { name: 'group_token', username: "group_#{group.id}_bot", email: "group_#{group.id}_bot@example.com", user_type: :project_bot }).execute + + # Confirm the group bot. + bot.confirm + + # Add the bot to the group with the required role. + group.add_user(bot, :maintainer) + + # Give the bot a personal access token. + token = bot.personal_access_tokens.create(scopes:[:api, :write_repository], name: 'group_token') + + # Get the token value. + gtoken = token.token + ``` + +1. Test if the generated group access token works: + + 1. Use the group access token in the `PRIVATE-TOKEN` header with GitLab REST APIs. For example: + + - [Create an epic](../../../api/epics.md#new-epic) in the group. + - [Create a project pipeline](../../../api/pipelines.md#create-a-new-pipeline) in one of the group's projects. + - [Create an issue](../../../api/issues.md#new-issue) in one of the group's projects. + + 1. Use the group token to [clone a group's project](../../../gitlab-basics/start-using-git.md#clone-with-https) + using HTTPS. + +## Revoke a group access token using the UI + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214045) in GitLab 14.7. + +To revoke a group access token: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > Access Tokens**. +1. Next to the group access token to revoke, select **Revoke**. + +## Revoke a group access token using Rails console + +GitLab 14.6 and earlier doesn't support revoking group access tokens using the UI +or API. However, administrators can use a workaround. + +To revoke a group access token, run the following command in a [Rails console](../../../administration/operations/rails_console.md): + +```ruby +bot = User.find_by(username: 'group_109_bot') # the owner of the token you want to revoke +token = bot.personal_access_tokens.last # the token you want to revoke +token.revoke! +``` + +## Scopes for a group access token + +The scope determines the actions you can perform when you authenticate with a group access token. + +| Scope | Description | +|:-------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `api` | Grants complete read and write access to the scoped group and related project API, including the [Package Registry](../../packages/package_registry/index.md). | +| `read_api` | Grants read access to the scoped group and related project API, including the [Package Registry](../../packages/package_registry/index.md). | +| `read_registry` | Allows read access (pull) to the [Container Registry](../../packages/container_registry/index.md) images if any project within a group is private and authorization is required. | +| `write_registry` | Allows write access (push) to the [Container Registry](../../packages/container_registry/index.md). | +| `read_repository` | Allows read access (pull) to all repositories within a group. | +| `write_repository` | Allows read and write access (pull and push) to all repositories within a group. | + +## Enable or disable group access token creation + +To enable or disable group access token creation for all sub-groups in a top-level group: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand **Permissions and group features**. +1. Under **Permissions**, turn on or off **Allow project and group access token creation**. + +Even when creation is disabled, you can still use and revoke existing group access tokens. + +## Bot users + +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). diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index acce296da93..ef984a76a7d 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +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 type: reference, howto, concepts --- @@ -101,7 +101,7 @@ You can change this setting: - As group owner: 1. Select the group. 1. On the left sidebar, select **Settings > General**. - 1. Expand **Permissions, LFS, 2FA**. + 1. Expand **Permissions and group features**. - As an administrator: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Groups**. diff --git a/doc/user/group/value_stream_analytics/img/vsa_stage_table_v13_12.png b/doc/user/group/value_stream_analytics/img/vsa_stage_table_v13_12.png Binary files differdeleted file mode 100644 index 24d485306be..00000000000 --- a/doc/user/group/value_stream_analytics/img/vsa_stage_table_v13_12.png +++ /dev/null diff --git a/doc/user/group/value_stream_analytics/img/vsa_stage_table_v14_7.png b/doc/user/group/value_stream_analytics/img/vsa_stage_table_v14_7.png Binary files differnew file mode 100644 index 00000000000..c9074cbb5ea --- /dev/null +++ b/doc/user/group/value_stream_analytics/img/vsa_stage_table_v14_7.png diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index b91e258b04a..4663cfc8bfd 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -5,34 +5,35 @@ group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Value Stream Analytics **(PREMIUM)** +# Value stream analytics for groups **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196455) in GitLab 12.9 for groups. -Value Stream Analytics measures the time spent to go from an +Value stream analytics measures the time spent to go from an [idea to production](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) -(also known as cycle time) for each of your projects or groups. Value Stream Analytics displays the median time +(also known as cycle time) for each of your projects or groups. Value stream analytics displays the median time spent in each stage defined in the process. -Value Stream Analytics can help you quickly determine the velocity of a given +Value stream analytics can help you quickly determine the velocity of a given group. It points to bottlenecks in the development process, enabling management to uncover, triage, and identify the root cause of slowdowns in the software development life cycle. -For information on how to contribute to the development of Value Stream Analytics, see our [contributor documentation](../../../development/value_stream_analytics.md). +For information on how to contribute to the development of value stream analytics, see our [contributor documentation](../../../development/value_stream_analytics.md). -To view group-level Value Stream Analytics: +To view value stream analytics for groups: 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value stream**. -Value Stream Analytics at the group level includes data for the selected group and its subgroups. +Value stream analytics at the group level includes data for the selected group and its subgroups. NOTE: -[Project-level Value Stream Analytics](../../analytics/value_stream_analytics.md) is also available. +[Value stream analytics for projects](../../analytics/value_stream_analytics.md) is also available. ## Default stages -The stages tracked by Value Stream Analytics by default represent the [GitLab flow](../../../topics/gitlab_flow.md). These stages can be customized in Group Level Value Stream Analytics. +The stages tracked by value stream analytics by default represent the [GitLab flow](../../../topics/gitlab_flow.md). +These stages can be customized in value stream analytics for groups. - **Issue** (Tracker) - Time to schedule an issue (by milestone or by adding it to an issue board) @@ -100,8 +101,7 @@ sole discretion of GitLab Inc. ## How metrics are measured -> DORA API-based deployment metrics for group-level Value Stream Analytics were -> [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) from GitLab Ultimate to GitLab Premium in 14.3. +> DORA API-based deployment metrics for value stream analytics for groups were [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) from GitLab Ultimate to GitLab Premium in 14.3. The "Time" metrics near the top of the page are measured as follows: @@ -134,11 +134,11 @@ You can learn more about these metrics in our [analytics definitions](../../anal ## How the stages are measured -Value Stream Analytics measures each stage from its start event to its end event. +Value stream analytics measures each stage from its start event to its end event. For example, a stage might start when one label is added to an issue, and end when another label is added. -Value Stream Analytics excludes work in progress, meaning it ignores any items that have not reached the end event. +Value stream analytics excludes work in progress, meaning it ignores any items that have not reached the end event. -Each stage of Value Stream Analytics is further described in the table below. +Each stage of value stream analytics is further described in the table below. | **Stage** | **Description** | | --------- | --------------- | @@ -162,7 +162,7 @@ How this works, behind the scenes: and so on. To sum up, anything that doesn't follow [GitLab flow](../../../topics/gitlab_flow.md) is not tracked and the -Value Stream Analytics dashboard does not present any data for: +value stream analytics dashboard does not present any data for: - Merge requests that do not close an issue. - Issues not labeled with a label present in the issue board or for issues not assigned a milestone. @@ -170,7 +170,7 @@ Value Stream Analytics dashboard does not present any data for: ## How the production environment is identified -Value Stream Analytics identifies production environments by looking for project +Value stream analytics identifies production environments by looking for project [environments](../../../ci/yaml/index.md#environment) with a name matching any of these patterns: - `prod` or `prod/*` @@ -228,7 +228,7 @@ A few notes: tested). - The example above was just **one cycle** of the seven stages. Add multiple cycles, calculate their median time and the result is what the dashboard of - Value Stream Analytics is showing. + value stream analytics is showing. ## Custom value streams @@ -236,7 +236,7 @@ A few notes: The default stages are designed to work straight out of the box, but they might not be suitable for all teams. Different teams use different approaches to building software, so some teams might want -to customize their Value Stream Analytics. +to customize their value stream analytics. GitLab allows users to create multiple value streams, hide default stages and create custom stages that align better to their development workflow. @@ -272,7 +272,7 @@ Hovering over a stage item displays a popover with the following information: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321438) in GitLab 13.11. - + The stream overview provides access to key metrics and charts summarizing all the stages in the value stream based on selected filters. @@ -288,7 +288,7 @@ Shown metrics and charts includes: > Sorting the stage table [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301082) in GitLab 13.12. - + The stage table shows a list of related workflow items for the selected stage. This can include: @@ -378,7 +378,7 @@ In this example, we'd like to measure times for deployment from a staging enviro - When the code is deployed to staging, the `workflow::staging` label is added to the merge request. - When the code is deployed to production, the `workflow::production` label is added to the merge request. - + ### Editing a value stream @@ -443,14 +443,14 @@ select up to a total of 15 labels. ## Permissions -To access Group-level Value Stream Analytics, users must have at least the Reporter role. +To access value stream analytics for groups, users must have at least the Reporter role. You can [read more about permissions](../../permissions.md) in general. ## More resources -Learn more about Value Stream Analytics in the following resources: +Learn more about value stream analytics in the following resources: -- [Value Stream Analytics feature page](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). -- [Value Stream Analytics feature preview](https://about.gitlab.com/blog/2016/09/16/feature-preview-introducing-cycle-analytics/). -- [Value Stream Analytics feature highlight](https://about.gitlab.com/blog/2016/09/21/cycle-analytics-feature-highlight/). +- [Value stream analytics feature page](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). +- [Value stream analytics feature preview](https://about.gitlab.com/blog/2016/09/16/feature-preview-introducing-cycle-analytics/). +- [Value stream analytics feature highlight](https://about.gitlab.com/blog/2016/09/21/cycle-analytics-feature-highlight/). diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md b/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md index b5959624954..5d704a2c6df 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md @@ -37,7 +37,7 @@ You can check the recommended variables for each cluster type in the official do - [Google GKE](https://docs.cilium.io/en/v1.8/gettingstarted/k8s-install-gke/#deploy-cilium) - [AWS EKS](https://docs.cilium.io/en/v1.8/gettingstarted/k8s-install-eks/#deploy-cilium) -Do not use `clusterType` for sandbox environments like [Minikube](https://minikube.sigs.k8s.io/docs/). +Do not use `clusterType` for sandbox environments like [minikube](https://minikube.sigs.k8s.io/docs/). You can customize Cilium's Helm variables by defining the `applications/cilium/values.yaml` file in your cluster diff --git a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md new file mode 100644 index 00000000000..1dd1c760bcc --- /dev/null +++ b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md @@ -0,0 +1,88 @@ +--- +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 +--- + +# Migrate to the GitLab Agent for Kubernetes **(FREE)** + +The first integration between GitLab and Kubernetes used cluster certificates +to connect the cluster to GitLab. +This method was [deprecated](https://about.gitlab.com/blog/2021/11/15/deprecating-the-cert-based-kubernetes-integration/) +in GitLab 14.5 in favor of the [GitLab Agent for Kubernetes](../../clusters/agent/index.md). + +To make sure your clusters connected to GitLab do not break in the future, +we recommend you migrate to the GitLab Agent as soon as possible by following +the processes described in this document. + +The certificate-based integration was used for some popular GitLab features such as, +GitLab Managed Apps, GitLab-managed clusters, and Auto DevOps. + +As a general rule, migrating clusters that rely on GitLab CI/CD can be +achieved using the [CI/CD Tunnel](../../clusters/agent/ci_cd_tunnel.md) +provided by the Agent. + +NOTE: +The GitLab Agent for Kubernetes does not intend to provide feature parity with the +certificate-based cluster integrations. As a result, the Agent doesn't support +all the features available to clusters connected through certificates. + +## Migrate cluster application deployments + +### Migrate from GitLab-managed clusters + +With GitLab-managed clusters, GitLab creates separate service accounts and namespaces +for every branch and deploys using these resources. + +To achieve a similar result with the GitLab Agent, you can use [impersonation](../../clusters/agent/repository.md#use-impersonation-to-restrict-project-and-group-access) +strategies to deploy to your cluster with restricted account access. To do so: + +1. Choose the impersonation strategy that suits your needs. +1. Use Kubernetes RBAC rules to manage impersonated account permissions in Kubernetes. +1. Use the `access_as` attribute in your Agent’s configuration file to define the impersonation. + +### Migrate from Auto DevOps + +To configure your Auto DevOps project to use the GitLab Agent: + +1. Follow the steps to [install an agent](../../clusters/agent/install/index.md) on your cluster. +1. Go to the project in which you use Auto DevOps. +1. From the sidebar, select **Settings > CI/CD** and expand **Variables**. +1. Select **Add new variable**. +1. Add `KUBE_CONTEXT` as the key, `path/to/agent/project:agent-name` as the value, and select the environment scope of your choice. +1. Select **Add variable**. +1. Repeat the process to add another variable, `KUBE_NAMESPACE`, setting the value for the Kubernetes namespace you want your deployments to target, and set the same environment scope from the previous step. +1. From the sidebar, select **Infrastructure > Kubernetes clusters**. +1. From the certificate-based clusters section, open the cluster that serves the same environment scope. +1. Select the **Details** tab and disable the cluster. +1. To activate the changes, from the project's sidebar, select **CI/CD > Variables > Run pipeline**. + +### Migrate generic deployments + +When you use Kubernetes contexts to reach the cluster from GitLab, you can use the [CI/CD Tunnel](../../clusters/agent/ci_cd_tunnel.md) +directly. It injects the available contexts into your CI environment automatically: + +1. Follow the steps to [install an agent](../../clusters/agent/install/index.md) on your cluster. +1. Go to the project in which you use Auto DevOps. +1. From the sidebar, select **Settings > CI/CD** and expand **Variables**. +1. Select **Add new variable**. +1. Add `KUBE_CONTEXT` as the key, `path/to/agent-configuration-project:your-agent-name` as the value, and select the environment scope of your choice. +1. Edit your `.gitlab-ci.yml` file and set the Kubernetes context to the `KUBE_CONTEXT` you defined in the previous step: + + ```yaml + <your job name>: + script: + - kubectl config use-context $KUBE_CONTEXT + ``` + +## Migrate from GitLab Managed Applications + +Follow the process to [migrate from GitLab Managed Apps to the Cluster Management Project](../../clusters/migrating_from_gma_to_project_template.md). + +## Migrating a Cluster Management project + +See [how to use a cluster management project with the GitLab Agent](../../clusters/management_project_template.md#use-the-agent-with-the-cluster-management-project-template). + +## Migrate cluster monitoring features + +Cluster monitoring features are not supported by the GitLab Agent for Kubernetes yet. diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index 15a680e2193..ceb6101688b 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -15,12 +15,14 @@ GitLab, and support Terraform best practices. ## Quick Start +> 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: ```yaml include: - - template: Terraform.gitlab-ci.yml + - template: Terraform.latest.gitlab-ci.yml variables: # If not using GitLab's HTTP backend, remove this line and specify TF_HTTP_* variables @@ -30,15 +32,23 @@ variables: # TF_ROOT: terraform/production ``` -This template includes some opinionated decisions, which you can override: +This template includes the following parameters that you can override: -- Including the latest [GitLab Terraform Image](https://gitlab.com/gitlab-org/terraform-images). -- Using the [GitLab managed Terraform State](#gitlab-managed-terraform-state) as +- Uses the latest [GitLab Terraform image](https://gitlab.com/gitlab-org/terraform-images). +- Uses the [GitLab-managed Terraform State](#gitlab-managed-terraform-state) as the Terraform state storage backend. -- Creating [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml): - `init`, `validate`, `build`, and `deploy`. These stages - [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml) - `init`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on the default branch. +- 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 + [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.latest.gitlab-ci.yml) + `test`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on the default branch. +- 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: + +- [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: diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 1b3cd5d4478..3d640185a55 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.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: reference, 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 --- # GitLab Flavored Markdown **(FREE)** @@ -1507,56 +1506,3 @@ entry and paste the spreadsheet: at Daring Fireball is an excellent resource for a detailed explanation of standard Markdown. - You can find the detailed specification for CommonMark in the [CommonMark Spec](https://spec.commonmark.org/current/). - The [CommonMark Dingus](https://spec.commonmark.org/dingus/) helps you test CommonMark syntax. - -## Transition from Redcarpet to CommonMark - -- In GitLab 11.8, the [Redcarpet Ruby library](https://github.com/vmg/redcarpet) - was removed. All issues and comments, including those in 11.1 and earlier, are now processed - by using the [CommonMark Ruby Library](https://github.com/gjtorikian/commonmarker). -- In GitLab 11.3 and later, CommonMark processes wiki pages and Markdown - files (`*.md`) in repositories. -- In GitLab 11.1 and later, the [CommonMark Ruby Library](https://github.com/gjtorikian/commonmarker) - for Markdown processes all new issues, merge requests, comments, and other Markdown - content. - -The documentation website migrated its Markdown engine -[from Redcarpet to Kramdown](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/108) -in October 2018. - -You may have older issues, merge requests, or Markdown documents in your -repository that relied upon nuances of the GitLab RedCarpet version -of Markdown. Because CommonMark uses slightly stricter syntax, these documents -may now appear differently after the transition to CommonMark. - -For example, numbered lists with nested lists may -render incorrectly: - -```markdown -1. Chocolate - - dark - - milk -``` - -To fix this issue, add a space to each nested item. The `-` must be aligned with the first -character of the top list item (`C` in this case): - -```markdown -1. Chocolate - - dark - - milk -``` - -1. Chocolate - - dark - - milk - -We flag any significant differences between Redcarpet and CommonMark Markdown in this document. - -If you have many Markdown files, it can be tedious to determine -if they display correctly or not. You can use the -[`diff_redcarpet_cmark`](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) -tool to generate a list of files and the -differences between how RedCarpet and CommonMark render the files. It indicates -if any changes are needed. - -`diff_redcarpet_cmark` is not an officially supported product. diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 47c41e85345..20284328918 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -6,9 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Operations Dashboard **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5781) in GitLab 11.5. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/9218) from GitLab Ultimate to GitLab Premium in 11.10. - The Operations Dashboard provides a summary of each project's operational health, including pipeline and alert status. diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 9497dd1625b..c77fc5a0f4b 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -6,13 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Container Registry **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4040) in GitLab 8.8. -> - Docker Registry manifest `v1` support was added in GitLab 8.9 to support Docker -> versions earlier than 1.10. -> - Starting in GitLab 8.12, if you have [two-factor authentication](../../profile/account/two_factor_authentication.md) enabled in your account, you need -> to pass a [personal access token](../../profile/personal_access_tokens.md) instead of your password to -> sign in to the Container Registry. -> - Support for multiple level image names was added in GitLab 9.1. > - The group-level Container Registry was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23315) in GitLab 12.10. > - Searching by image repository name was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31322) in GitLab 13.0. @@ -42,6 +35,21 @@ Only members of the project or group can access a private project's Container Re If a project is public, so is the Container Registry. +### View the tags of a specific image + +You can view a list of tags associated with a given container image: + +1. Go to your project or group. +1. Go to **Packages & Registries > Container Registry**. +1. Select the container image you are interested in. + +This brings up the Container Registry **Tag Details** page. You can view details about each tag, +such as when it was published, how much storage it consumes, and the manifest and configuration +digests. + +You can search, sort (by tag name), filter, and [delete](#delete-images-from-within-gitlab) +tags on this page. You can share a filtered view by copying the URL from your browser. + ## Use images from the Container Registry To download and run a container image hosted in the GitLab Container Registry: @@ -306,7 +314,7 @@ is set to `always`. To use your own Docker images for Docker-in-Docker, follow these steps in addition to the steps in the -[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker) section: +[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker) section: 1. Update the `image` and `service` to point to your registry. 1. Add a service [alias](../../../ci/services/index.md#available-settings-for-services). @@ -336,7 +344,7 @@ error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker To use your own Docker images with Dependency Proxy, follow these steps in addition to the steps in the -[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker) section: +[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker) section: 1. Update the `image` and `service` to point to your registry. 1. Add a service [alias](../../../ci/services/index.md#available-settings-for-services). @@ -475,256 +483,9 @@ defined in the `delete_image` job. ### Delete images by using a cleanup policy -You can create a per-project [cleanup policy](#cleanup-policy) to ensure older tags and images are regularly removed from the +You can create a per-project [cleanup policy](reduce_container_registry_storage.md#cleanup-policy) to ensure older tags and images are regularly removed from the Container Registry. -## Cleanup policy - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15398) in GitLab 12.8. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/218737) from "expiration policy" to "cleanup policy" in GitLab 13.2. - -The cleanup policy is a scheduled job you can use to remove tags from the Container Registry. -For the project where it's defined, tags matching the regex pattern are removed. -The underlying layers and images remain. - -To delete the underlying layers and images that aren't associated with any tags, administrators can use -[garbage collection](../../../administration/packages/container_registry.md#removing-untagged-manifests-and-unreferenced-layers) with the `-m` switch. - -### Enable the cleanup policy - -Cleanup policies can be run on all projects, with these exceptions: - -- For GitLab.com, the project must have been created after 2020-02-22. - Support for projects created earlier is tracked - [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/196124). -- For self-managed GitLab instances, the project must have been created - in GitLab 12.8 or later. However, an administrator can enable the cleanup policy - for all projects (even those created before 12.8) in - [GitLab application settings](../../../api/settings.md#change-application-settings) - by setting `container_expiration_policies_enable_historic_entries` to true. - Alternatively, you can execute the following command in the [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): - - ```ruby - ApplicationSetting.last.update(container_expiration_policies_enable_historic_entries: true) - ``` - - There are performance risks with enabling it for all projects, especially if you - are using an [external registry](index.md#use-with-external-container-registries). -- For self-managed GitLab instances, you can enable or disable the cleanup policy for a specific - project. - - To enable it: - - ```ruby - Feature.enable(:container_expiration_policies_historic_entry, Project.find(<project id>)) - ``` - - To disable it: - - ```ruby - Feature.disable(:container_expiration_policies_historic_entry, Project.find(<project id>)) - ``` - -WARNING: -For performance reasons, enabled cleanup policies are automatically disabled for projects on -GitLab.com that don't have a container image. - -### How the cleanup policy works - -The cleanup policy collects all tags in the Container Registry and excludes tags -until only the tags to be deleted remain. - -The cleanup policy searches for images based on the tag name. Support for the full path [has not yet been implemented](https://gitlab.com/gitlab-org/gitlab/-/issues/281071), but would allow you to clean up dynamically-named tags. - -The cleanup policy: - -1. Collects all tags for a given repository in a list. -1. Excludes the tag named `latest` from the list. -1. Evaluates the `name_regex` (tags to expire), excluding non-matching names from the list. -1. Excludes from the list any tags matching the `name_regex_keep` value (tags to preserve). -1. Excludes any tags that do not have a manifest (not part of the options in the UI). -1. Orders the remaining tags by `created_date`. -1. Excludes from the list the N tags based on the `keep_n` value (Number of tags to retain). -1. Excludes from the list the tags more recent than the `older_than` value (Expiration interval). -1. Finally, the remaining tags in the list are deleted from the Container Registry. - -WARNING: -On GitLab.com, the execution time for the cleanup policy is limited, and some of the tags may remain in -the Container Registry after the policy runs. The next time the policy runs, the remaining tags are included, -so it may take multiple runs for all tags to be deleted. - -WARNING: -GitLab self-managed installs support for third-party container registries that comply with the -[Docker Registry HTTP API V2](https://docs.docker.com/registry/spec/api/) -specification. However, this specification does not include a tag delete operation. Therefore, when -interacting with third-party container registries, GitLab uses a workaround to delete tags. See the -[related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/15737) -for more information. Due to possible implementation variations, this workaround is not guaranteed -to work with all third-party registries in the same predictable way. If you use the GitLab Container -Registry, this workaround is not required because we implemented a special tag delete operation. In -this case, you can expect cleanup policies to be consistent and predictable. - -### Create a cleanup policy - -You can create a cleanup policy in [the API](#use-the-cleanup-policy-api) or the UI. - -To create a cleanup policy in the UI: - -1. For your project, go to **Settings > Packages & Registries**. -1. Expand the **Clean up image tags** section. -1. Complete the fields. - - | Field | Description | - |---------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| - | **Toggle** | Turn the policy on or off. | - | **Run cleanup** | How often the policy should run. | - | **Keep the most recent** | How many tags to _always_ keep for each image. | - | **Keep tags matching** | The regex pattern that determines which tags to preserve. The `latest` tag is always preserved. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | - | **Remove tags older than** | Remove only tags older than X days. | - | **Remove tags matching** | The regex pattern that determines which tags to remove. This value cannot be blank. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | - -1. Click **Save**. - -Depending on the interval you chose, the policy is scheduled to run. - -NOTE: -If you edit the policy and click **Save** again, the interval is reset. - -### Regex pattern examples - -Cleanup policies use regex patterns to determine which tags should be preserved or removed, both in the UI and the API. - -Regex patterns are automatically surrounded with `\A` and `\Z` anchors. Do not include any `\A`, `\Z`, `^` or `$` token in the regex patterns as they are not necessary. - -Here are examples of regex patterns you may want to use: - -- Match all tags: - - ```plaintext - .* - ``` - - This is the default value for the expiration regex. - -- Match tags that start with `v`: - - ```plaintext - v.+ - ``` - -- Match only the tag named `main`: - - ```plaintext - main - ``` - -- Match tags that are either named or start with `release`: - - ```plaintext - release.* - ``` - -- Match tags that either start with `v`, are named `main`, or begin with `release`: - - ```plaintext - (?:v.+|main|release.*) - ``` - -### Set cleanup limits to conserve resources - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/288812) in GitLab 13.9. -> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - It's enabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-cleanup-policy-limits). - -Cleanup policies are executed as a background process. This process is complex, and depending on the number of tags to delete, -the process can take time to finish. - -To prevent server resource starvation, the following application settings are available: - -- `container_registry_expiration_policies_worker_capacity`. The maximum number of cleanup workers running concurrently. This must be greater than `1`. - We recommend starting with a low number and increasing it after monitoring the resources used by the background workers. -- `container_registry_delete_tags_service_timeout`. The maximum time, in seconds, that the cleanup process can take to delete a batch of tags. -- `container_registry_cleanup_tags_service_max_list_size`. The maximum number of tags that can be deleted in a single execution. Additional tags must be deleted in another execution. - We recommend starting with a low number, like `100`, and increasing it after monitoring that container images are properly deleted. - -For self-managed instances, those settings can be updated in the [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): - - ```ruby - ApplicationSetting.last.update(container_registry_expiration_policies_worker_capacity: 3) - ``` - -Alternatively, once the limits are [enabled](#enable-or-disable-cleanup-policy-limits), -they are available in the [administrator area](../../admin_area/index.md): - -1. On the top bar, select **Menu > Admin**. -1. Go to **Settings > CI/CD > Container Registry**. - -#### Enable or disable cleanup policy limits - -The cleanup policies limits are under development and not ready for production use. They are -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:container_registry_expiration_policies_throttling) -``` - -To disable it: - -```ruby -Feature.disable(:container_registry_expiration_policies_throttling) -``` - -### Use the cleanup policy API - -You can set, update, and disable the cleanup policies using the GitLab API. - -Examples: - -- Select all tags, keep at least 1 tag per image, clean up any tag older than 14 days, run once a month, preserve any images with the name `main` and the policy is enabled: - - ```shell - curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" \ - --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-main"}}' \ - "https://gitlab.example.com/api/v4/projects/2" - ``` - -Valid values for `cadence` when using the API are: - -- `1d` (every day) -- `7d` (every week) -- `14d` (every two weeks) -- `1month` (every month) -- `3month` (every quarter) - -See the API documentation for further details: [Edit project](../../../api/projects.md#edit-project). - -### Use with external container registries - -When using an [external container registry](../../../administration/packages/container_registry.md#use-an-external-container-registry-with-gitlab-as-an-auth-endpoint), -running a cleanup policy on a project may have some performance risks. -If a project runs a policy to remove thousands of tags -the GitLab background jobs may get backed up or fail completely. -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. - -### Troubleshooting cleanup policies - -If you see the following message: - -"Something went wrong while updating the cleanup policy." - -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). - ## Limitations - Moving or renaming existing Container Registry repositories is not supported @@ -844,7 +605,7 @@ There can be different reasons behind this: To fix this, there are two workarounds: - - If you are on GitLab 13.9 or later, you can [set limits for the cleanup policy](#set-cleanup-limits-to-conserve-resources). + - 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 @@ -869,14 +630,14 @@ these steps: If you have Rails console access, you can enter the following commands to retrieve a list of tags limited by date: - ```shell + ```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 @@ -963,3 +724,55 @@ Use your own URLs to complete the following steps: ``` Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/18383) for details. + +### Tags on S3 backend remain after successful deletion requests + +With S3 as your storage backend, tags may remain even though: + +- In the UI, you see that the tags are scheduled for deletion. +- In the API, you get an HTTP `200` response. +- The registry log shows a successful `Delete` request. + +An example `DELETE` request in the registry log: + +```shell +{"content_type":"","correlation_id":"01FQGNSKVMHQEAVE21KYTJN2P4","duration_ms":62,"host":"localhost:5000","level":"info","method":"DELETE","msg":"access","proto":"HTTP/1.1","referrer":"","remote_addr":"127.0.0.1:47498","remote_ip":"127.0.0.1","status":202,"system":"http","time":"2021-12-22T08:58:15Z","ttfb_ms":62,"uri":"/v2/<path to repo>/tags/reference/<tag_name>","user_agent":"GitLab/<version>","written_bytes":0} +``` + +There may be some errors not properly cached. Follow these steps to investigate further: + +1. In your configuration file, set the registry's log level to `debug`, and the S3 driver's log + level to `logdebugwithhttpbody`. For Omnibus, make these edits in the `gitlab.rb` file: + + ```shell + # Change the registry['log_level'] to debug + registry['log_level'] = 'debug' + + # Set log level for registry log from storage side + registry['storage'] = { + 's3' => { + 'bucket' => 'your-s3-bucket', + 'region' => 'your-s3-region' + }, + + 'loglevel' = "logdebugwithhttpbody" + } + ``` + + Then save and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Attempt to delete one or more tags using the GitLab UI or API. + +1. Inspect the registry logs and look for a response from S3. Although the response could be + `200 OK`, the body might have the error `AccessDenied`. This indicates a permission problem from + the S3 side. + +1. Ensure your S3 configuration has the `deleteObject` permisson scope. Here's an + [example role for an S3 bucket](../../../administration/object_storage.md#iam-permissions). + Once adjusted, trigger another tag deletion. You should be able to successfully delete tags. + +Follow [this issue](https://gitlab.com/gitlab-org/container-registry/-/issues/551) for details. diff --git a/doc/user/packages/container_registry/reduce_container_registry_storage.md b/doc/user/packages/container_registry/reduce_container_registry_storage.md new file mode 100644 index 00000000000..e2242a85b75 --- /dev/null +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -0,0 +1,272 @@ +--- +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 Storage **(FREE)** + +Container registries become large over time without cleanup. When a large number of images or tags are added: + +- Fetching the list of available tags or images becomes slower. +- They take up a large amount of storage space on the server. + +We recommend deleting unnecessary images and tags, and setting up a [cleanup policy](#cleanup-policy) +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. + +## Cleanup policy + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15398) in GitLab 12.8. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/218737) from "expiration policy" to "cleanup policy" in GitLab 13.2. + +The cleanup policy is a scheduled job you can use to remove tags from the Container Registry. +For the project where it's defined, tags matching the regex pattern are removed. +The underlying layers and images remain. + +To delete the underlying layers and images that aren't associated with any tags, administrators can use +[garbage collection](../../../administration/packages/container_registry.md#removing-untagged-manifests-and-unreferenced-layers) with the `-m` switch. + +### Enable the cleanup policy + +Cleanup policies can be run on all projects, with these exceptions: + +- For self-managed GitLab instances, the project must have been created + in GitLab 12.8 or later. However, an administrator can enable the cleanup policy + for all projects (even those created before 12.8) in + [GitLab application settings](../../../api/settings.md#change-application-settings) + by setting `container_expiration_policies_enable_historic_entries` to true. + Alternatively, you can execute the following command in the [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): + + ```ruby + ApplicationSetting.last.update(container_expiration_policies_enable_historic_entries: true) + ``` + + There are performance risks with enabling it for all projects, especially if you + are using an [external registry](#use-with-external-container-registries). +- For self-managed GitLab instances, you can enable or disable the cleanup policy for a specific + project. + + To enable it: + + ```ruby + Feature.enable(:container_expiration_policies_historic_entry, Project.find(<project id>)) + ``` + + To disable it: + + ```ruby + Feature.disable(:container_expiration_policies_historic_entry, Project.find(<project id>)) + ``` + +WARNING: +For performance reasons, enabled cleanup policies are automatically disabled for projects on +GitLab.com that don't have a container image. + +### How the cleanup policy works + +The cleanup policy collects all tags in the Container Registry and excludes tags +until only the tags to be deleted remain. + +The cleanup policy searches for images based on the tag name. Support for the full path [has not yet been implemented](https://gitlab.com/gitlab-org/gitlab/-/issues/281071), but would allow you to clean up dynamically-named tags. + +The cleanup policy: + +1. Collects all tags for a given repository in a list. +1. Excludes the tag named `latest` from the list. +1. Evaluates the `name_regex` (tags to expire), excluding non-matching names from the list. +1. Excludes from the list any tags matching the `name_regex_keep` value (tags to preserve). +1. Excludes any tags that do not have a manifest (not part of the options in the UI). +1. Orders the remaining tags by `created_date`. +1. Excludes from the list the N tags based on the `keep_n` value (Number of tags to retain). +1. Excludes from the list the tags more recent than the `older_than` value (Expiration interval). +1. Finally, the remaining tags in the list are deleted from the Container Registry. + +WARNING: +On GitLab.com, the execution time for the cleanup policy is limited, and some of the tags may remain in +the Container Registry after the policy runs. The next time the policy runs, the remaining tags are included, +so it may take multiple runs for all tags to be deleted. + +WARNING: +GitLab self-managed installs support for third-party container registries that comply with the +[Docker Registry HTTP API V2](https://docs.docker.com/registry/spec/api/) +specification. However, this specification does not include a tag delete operation. Therefore, when +interacting with third-party container registries, GitLab uses a workaround to delete tags. See the +[related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/15737) +for more information. Due to possible implementation variations, this workaround is not guaranteed +to work with all third-party registries in the same predictable way. If you use the GitLab Container +Registry, this workaround is not required because we implemented a special tag delete operation. In +this case, you can expect cleanup policies to be consistent and predictable. + +### Create a cleanup policy + +You can create a cleanup policy in [the API](#use-the-cleanup-policy-api) or the UI. + +To create a cleanup policy in the UI: + +1. For your project, go to **Settings > Packages & Registries**. +1. Expand the **Clean up image tags** section. +1. Complete the fields. + + | Field | Description | + |---------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| + | **Toggle** | Turn the policy on or off. | + | **Run cleanup** | How often the policy should run. | + | **Keep the most recent** | How many tags to _always_ keep for each image. | + | **Keep tags matching** | The regex pattern that determines which tags to preserve. The `latest` tag is always preserved. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | + | **Remove tags older than** | Remove only tags older than X days. | + | **Remove tags matching** | The regex pattern that determines which tags to remove. This value cannot be blank. For all tags, use `.*`. See other [regex pattern examples](#regex-pattern-examples). | + +1. Click **Save**. + +Depending on the interval you chose, the policy is scheduled to run. + +NOTE: +If you edit the policy and click **Save** again, the interval is reset. + +### Regex pattern examples + +Cleanup policies use regex patterns to determine which tags should be preserved or removed, both in the UI and the API. + +Regex patterns are automatically surrounded with `\A` and `\Z` anchors. Do not include any `\A`, `\Z`, `^` or `$` token in the regex patterns as they are not necessary. + +Here are examples of regex patterns you may want to use: + +- Match all tags: + + ```plaintext + .* + ``` + + This is the default value for the expiration regex. + +- Match tags that start with `v`: + + ```plaintext + v.+ + ``` + +- Match only the tag named `main`: + + ```plaintext + main + ``` + +- Match tags that are either named or start with `release`: + + ```plaintext + release.* + ``` + +- Match tags that either start with `v`, are named `main`, or begin with `release`: + + ```plaintext + (?:v.+|main|release.*) + ``` + +### Set cleanup limits to conserve resources + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/288812) in GitLab 13.9. +> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - It's enabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-cleanup-policy-limits). + +Cleanup policies are executed as a background process. This process is complex, and depending on the number of tags to delete, +the process can take time to finish. + +To prevent server resource starvation, the following application settings are available: + +- `container_registry_expiration_policies_worker_capacity`. The maximum number of cleanup workers running concurrently. This must be greater than `1`. + We recommend starting with a low number and increasing it after monitoring the resources used by the background workers. +- `container_registry_delete_tags_service_timeout`. The maximum time, in seconds, that the cleanup process can take to delete a batch of tags. +- `container_registry_cleanup_tags_service_max_list_size`. The maximum number of tags that can be deleted in a single execution. Additional tags must be deleted in another execution. + We recommend starting with a low number, like `100`, and increasing it after monitoring that container images are properly deleted. + +For self-managed instances, those settings can be updated in the [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): + + ```ruby + ApplicationSetting.last.update(container_registry_expiration_policies_worker_capacity: 3) + ``` + +Alternatively, once the limits are [enabled](#enable-or-disable-cleanup-policy-limits), +they are available in the [administrator area](../../admin_area/index.md): + +1. On the top bar, select **Menu > Admin**. +1. Go to **Settings > CI/CD > Container Registry**. + +#### Enable or disable cleanup policy limits + +The cleanup policies limits are under development and not ready for production use. They are +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:container_registry_expiration_policies_throttling) +``` + +To disable it: + +```ruby +Feature.disable(:container_registry_expiration_policies_throttling) +``` + +### Use the cleanup policy API + +You can set, update, and disable the cleanup policies using the GitLab API. + +Examples: + +- Select all tags, keep at least 1 tag per image, clean up any tag older than 14 days, run once a month, preserve any images with the name `main` and the policy is enabled: + + ```shell + curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: <your_access_token>" \ + --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-main"}}' \ + "https://gitlab.example.com/api/v4/projects/2" + ``` + +Valid values for `cadence` when using the API are: + +- `1d` (every day) +- `7d` (every week) +- `14d` (every two weeks) +- `1month` (every month) +- `3month` (every quarter) + +See the API documentation for further details: [Edit project](../../../api/projects.md#edit-project). + +### Use with external container registries + +When using an [external container registry](../../../administration/packages/container_registry.md#use-an-external-container-registry-with-gitlab-as-an-auth-endpoint), +running a cleanup policy on a project may have some performance risks. +If a project runs a policy to remove thousands of tags +the GitLab background jobs may get backed up or fail completely. +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 + +- [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) + +## Troubleshooting cleanup policies + +If you see the following message: + +"Something went wrong while updating the cleanup policy." + +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). diff --git a/doc/user/packages/debian_repository/index.md b/doc/user/packages/debian_repository/index.md index 89427174dcd..a8f0672e376 100644 --- a/doc/user/packages/debian_repository/index.md +++ b/doc/user/packages/debian_repository/index.md @@ -67,7 +67,7 @@ Creating a Debian package is documented [on the Debian Wiki](https://wiki.debian To create a distribution, publish a package, or install a private package, you need one of the following: -- [Personal access token](../../../api/index.md#personalproject-access-tokens) +- [Personal access token](../../../api/index.md#personalprojectgroup-access-tokens) - [CI/CD job token](../../../ci/jobs/ci_job_token.md) - [Deploy token](../../project/deploy_tokens/index.md) diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index 8b34634318c..52f5a1fcc0d 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -6,7 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency Proxy **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in GitLab 11.11. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) from GitLab Premium to GitLab Free in 13.6. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) support for private groups in GitLab 13.7. > - Anonymous access to images in public groups is no longer available starting in GitLab 13.7. @@ -20,7 +19,8 @@ upstream image from a registry, acting as a pull-through cache. ## Prerequisites -- The Dependency Proxy is enabled by default but can be [turned off by an administrator](../../../administration/packages/dependency_proxy.md). +To use the Dependency Proxy, it must be enabled for the GitLab instance. It's enabled by default, +but [administrators can turn it off](../../../administration/packages/dependency_proxy.md). ### Supported images and packages @@ -33,13 +33,17 @@ The following images and packages are supported. For a list of planned additions, view the [direction page](https://about.gitlab.com/direction/package/#dependency-proxy). -## Enable or disable the Dependency Proxy for a group +## Enable or turn off the Dependency Proxy for a group -To enable or disable the Dependency Proxy for a group: +To enable or turn off the Dependency Proxy for a group: 1. Go to your group's **Settings > Packages & Registries**. 1. Expand the **Dependency Proxy** section. -1. To enable the proxy, turn on **Enable Proxy**. To disable it, turn the toggle off. +1. To enable the proxy, turn on **Enable Proxy**. To turn it off, turn the toggle off. + +This setting only affects the Dependency Proxy for a group. Only an administrator can +[turn the Dependency Proxy on or off](../../../administration/packages/dependency_proxy.md) +for the entire GitLab instance. ## View the Dependency Proxy @@ -227,7 +231,7 @@ You can enable an automatic time-to-live (TTL) policy for the Dependency Proxy f 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 +#### Enable cleanup policies with GraphQL > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294187) in GitLab 14.4. @@ -259,7 +263,7 @@ mutation { ``` See the [Getting started with GraphQL](../../../api/graphql/getting_started.md) -guide to learn how to make GraphQL queries. +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 diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 5b7316a495e..7b44b5bcbb7 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -13,20 +13,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - It's recommended for production use. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-generic-packages-in-the-package-registry). -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - Publish generic files, like release binaries, in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. ## Authenticate to the Package Registry -To authenticate to the Package Registry, you need either a [personal access token](../../../api/index.md#personalproject-access-tokens), +To authenticate to the Package Registry, you need either a [personal access token](../../../api/index.md#personalprojectgroup-access-tokens), [CI/CD job token](../../../ci/jobs/ci_job_token.md), or [deploy token](../../project/deploy_tokens/index.md). In addition to the standard API authentication mechanisms, the generic package API allows authentication with HTTP Basic authentication for use with tools that do not support the other available mechanisms. The `user-id` is not checked and -may be any value, and the `password` must be either a [personal access token](../../../api/index.md#personalproject-access-tokens), +may be any value, and the `password` must be either a [personal access token](../../../api/index.md#personalprojectgroup-access-tokens), a [CI/CD job token](../../../ci/jobs/ci_job_token.md), or a [deploy token](../../project/deploy_tokens/index.md). ## Publish a package file diff --git a/doc/user/packages/helm_repository/index.md b/doc/user/packages/helm_repository/index.md index 488345965f9..73298afc9cd 100644 --- a/doc/user/packages/helm_repository/index.md +++ b/doc/user/packages/helm_repository/index.md @@ -30,7 +30,7 @@ Read more in the Helm documentation about these topics: To authenticate to the Helm repository, you need either: -- A [personal access token](../../../api/index.md#personalproject-access-tokens) with the scope set to `api`. +- A [personal access token](../../../api/index.md#personalprojectgroup-access-tokens) with the scope set to `api`. - A [deploy token](../../project/deploy_tokens/index.md) with the scope set to `read_package_registry`, `write_package_registry`, or both. - A [CI/CD job token](../../../ci/jobs/ci_job_token.md). diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 6646f18e6fe..21fecc16602 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -6,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Maven packages in the Package Repository **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5811) in GitLab 11.3. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. Publish [Maven](https://maven.apache.org) artifacts in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. @@ -418,8 +417,7 @@ repositories { ### Group-level Maven endpoint -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8798) in GitLab 11.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. If you rely on many packages, it might be inefficient to include the `repository` section with a unique URL for each package. Instead, you can use the group-level endpoint for @@ -476,8 +474,7 @@ repositories { ### Instance-level Maven endpoint -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8274) in GitLab 11.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. If you rely on many packages, it might be inefficient to include the `repository` section with a unique URL for each package. Instead, you can use the instance-level endpoint for diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 1086de1fa92..5338e546625 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -6,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # npm packages in the Package Registry **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5934) in GitLab 11.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. Publish npm packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency. @@ -579,8 +578,6 @@ If you get this error, ensure that: by default, it's possible to [disable it](../package_registry/#disable-the-package-registry). - Your token is not expired and has appropriate permissions. - A package with the same name or version doesn't already exist within the given scope. -- Your NPM package name does not contain a dot `.`. This is a [known issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/10248) - in GitLab 11.9 and earlier. - The scoped packages URL includes a trailing slash: - Correct: `//gitlab.example.com/api/v4/packages/npm/` - Incorrect: `//gitlab.example.com/api/v4/packages/npm` diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index 28e1571b4f8..3311b271126 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -32,6 +32,25 @@ When you view packages in a group: For information on how to create and upload a package, view the GitLab documentation for your package type. +## Authenticate with the registry + +Authentication depends on the package manager being used. For more information, see the docs on the +specific package format you want to use. + +For most package types, the following credential types are valid: + +- [Personal access token](../../profile/personal_access_tokens.md): + authenticates with your user permissions. Good for personal and local use of the package registry. +- [Project deploy token](../../project/deploy_tokens/index.md): + allows access to all packages in a project. Good for granting and revoking project access to many + users. +- [Group deploy token](../../project/deploy_tokens/index.md#group-deploy-token): + allows access to all packages in a group and its subgroups. Good for granting and revoking access + to a large number of packages to sets of users. +- [Job token](../../../ci/jobs/ci_job_token.md): + allows access to packages in the project running the job for the users running the pipeline. + Access to other external projects can be configured. + ## Use GitLab CI/CD to build packages You can use [GitLab CI/CD](../../../ci/index.md) to build packages. diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index b8dc071fc30..bb9f32d1144 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -15,7 +15,7 @@ as a Terraform module registry. To authenticate to the Terraform module registry, you need either: -- A [personal access token](../../../api/index.md#personalproject-access-tokens) with at least `read_api` rights. +- A [personal access token](../../../api/index.md#personalprojectgroup-access-tokens) with at least `read_api` rights. - A [CI/CD job token](../../../ci/jobs/ci_job_token.md). ## Publish a Terraform Module diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 4336c58b56c..36c49e39151 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +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 --- @@ -46,168 +46,169 @@ 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 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)** | | | | | ✓ | +| [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 | | ✓ | ✓ | ✓ | ✓ | 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) @@ -512,6 +513,7 @@ instance and project. | Change project configuration | | | ✓ | ✓ | | Add specific runners | | | ✓ | ✓ | | Add shared runners | | | | ✓ | +| Clear runner caches manually | | | ✓ | ✓ | | See events in the system | | | | ✓ | | Admin Area | | | | ✓ | diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index ab0cae976d2..32b8d2b33ee 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: Access +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 --- diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 96415279de4..365f96b48b3 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: Access +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 --- diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 343f8e328ba..3af8c1c1b5a 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -1,59 +1,51 @@ --- stage: Manage -group: Access +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 --- # Two-factor authentication **(FREE)** -Two-factor authentication (2FA) provides an additional level of security to your -GitLab account. After being enabled, in addition to supplying your username and -password to sign in, you are prompted for a code generated by your one-time -password authenticator (for example, a password manager on one of your devices). +Two-factor authentication (2FA) provides an additional level of security to your GitLab account. For others to access +your account, they would need your username and password _and_ access to your second factor of authentication. -By enabling 2FA, the only way someone other than you can sign in to your account -is to know your username and password _and_ have access to your one-time -password secret. +GitLab supports as a second factor of authentication: -## Overview +- Time-based one-time passwords ([TOTP](https://datatracker.ietf.org/doc/html/rfc6238)). When enabled, GitLab prompts + you for a code when you sign in. Codes are generated by your one-time password authenticator (for example, a password + manager on one of your devices). +- U2F or WebAuthn devices. You're prompted to activate your U2F or WebAuthn device (usually by pressing a button on it) when + you supply your username and password to sign in. This performs secure authentication on your behalf. -NOTE: -When you enable 2FA, don't forget to back up your [recovery codes](#recovery-codes)! +If you set up a device, also set up a TOTP so you can still access your account if you lose the device. -In addition to time-based one time passwords (TOTP), GitLab supports WebAuthn devices as the second factor -of authentication. After being enabled, in addition to supplying your username -and password to sign in, you're prompted to activate your U2F / WebAuthn device -(usually by pressing a button on it) which performs secure authentication on -your behalf. +## Use personal access tokens with two-factor authentication -It's highly recommended that you set up 2FA with both a [one-time password authenticator](#one-time-password) -or use [FortiAuthenticator](#one-time-password-via-fortiauthenticator) and a -[U2F device](#u2f-device) or a [WebAuthn device](#webauthn-device), so you can -still access your account if you lose your U2F / WebAuthn device. +When 2FA is enabled, you can't use your password to authenticate with Git over HTTPS or the [GitLab API](../../../api/index.md). +You must use a [personal access token](../personal_access_tokens.md) instead. -## Enabling 2FA +## Enable two-factor authentication > - Account email confirmation requirement [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35102) in GitLab 14.3. [Deployed behind the `ensure_verified_primary_email_for_2fa` flag](../../../administration/feature_flags.md), enabled by default. > - Account email confirmation requirement generally available and [feature flag `ensure_verified_primary_email_for_2fa` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/340151) in GitLab 14.4. -There are multiple ways to enable two-factor authentication (2FA): +You can enable 2FA: -- Using a one-time password authenticator. -- Using a U2F / WebAuthn device. +- Using a one-time password authenticator. After you enable 2FA, back up your [recovery codes](#recovery-codes). +- Using a U2F or WebAuthn device. -In GitLab 14.3 and later, your account email must be confirmed to enable two-factor authentication. +In GitLab 14.3 and later, your account email must be confirmed to enable 2FA. -### One-time password +### Enable one-time password -To enable 2FA: +To enable 2FA with a one-time password: 1. **In GitLab:** - 1. Sign in to your GitLab account. - 1. Go to your [**User settings**](../index.md#access-your-user-settings). - 1. Go to **Account**. + 1. Access your [**User settings**](../index.md#access-your-user-settings). + 1. Select **Account**. 1. Select **Enable Two-factor Authentication**. 1. **On your device (usually your phone):** - 1. Install a compatible application, like: + 1. Install a compatible application. For example: - [Authy](https://authy.com/) - [Duo Mobile](https://duo.com/product/multi-factor-authentication-mfa/duo-mobile-app) - [LastPass Authenticator](https://lastpass.com/auth/) @@ -63,37 +55,36 @@ To enable 2FA: - [Microsoft Authenticator](https://www.microsoft.com/en-us/security/mobile-authenticator-app) - [SailOTP](https://openrepos.net/content/seiichiro0185/sailotp) 1. In the application, add a new entry in one of two ways: - - Scan the code presented in GitLab with your device's camera to add the - entry automatically. + - Scan the code displayed by GitLab with your device's camera to add the entry automatically. - Enter the details provided to add the entry manually. 1. **In GitLab:** - 1. Enter the six-digit pin number from the entry on your device into the **Pin - code** field. + 1. Enter the six-digit pin number from the entry on your device into **Pin code**. 1. Enter your current password. 1. Select **Submit**. -If the pin you entered was correct, a message displays indicating that -two-factor authentication has been enabled, and you're shown a list -of [recovery codes](#recovery-codes). Be sure to download them and keep them +If you entered the correct pin, GitLab displays a list of [recovery codes](#recovery-codes). Download them and keep them in a safe place. -### One-time password via FortiAuthenticator +### Enable one-time password using FortiAuthenticator + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212312) in GitLab 13.5 [with a flag](../../../administration/feature_flags.md) named `forti_authenticator`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per user, ask an administrator to +[enable the feature flag](../../../administration/feature_flags.md) named `forti_authenticator`. On GitLab.com, this +feature is not available. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212312) in GitLab 13.5. -> - It's deployed behind a feature flag, disabled by default. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-fortiauthenticator-integration). +You can use FortiAuthenticator as a one-time password (OTP) provider in GitLab. Users must: -You can use FortiAuthenticator as a one-time password (OTP) provider in GitLab. Users must exist in -both FortiAuthenticator and GitLab with the exact same username, and users must -have FortiToken configured in FortiAuthenticator. +- Exist in both FortiAuthenticator and GitLab with the same username. +- Have FortiToken configured in FortiAuthenticator. -You need a username and access token for FortiAuthenticator. The -`access_token` in the code samples shown below is the FortAuthenticator access -key. To get the token, see the `REST API Solution Guide` at -[`Fortinet Document Library`](https://docs.fortinet.com/document/fortiauthenticator/6.2.0/rest-api-solution-guide/158294/the-fortiauthenticator-api). +You need a username and access token for FortiAuthenticator. The `access_token` shown below is the FortAuthenticator +access key. To get the token, see the REST API Solution Guide at +[Fortinet Document Library](https://docs.fortinet.com/document/fortiauthenticator/6.2.0/rest-api-solution-guide/158294/the-fortiauthenticator-api). GitLab 13.5 has been tested with FortAuthenticator version 6.2.0. -First configure FortiAuthenticator in GitLab. On your GitLab server: +Configure FortiAuthenticator in GitLab. On your GitLab server: 1. Open the configuration file. @@ -134,43 +125,27 @@ First configure FortiAuthenticator in GitLab. On your GitLab server: ``` 1. Save the configuration file. -1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) - or [restart GitLab](../../../administration/restart_gitlab.md#installations-from-source) - for the changes to take effect if you installed GitLab via Omnibus or from - source respectively. - -#### Enable FortiAuthenticator integration - -This feature comes with the `:forti_authenticator` feature flag disabled by -default. - -To enable this feature, ask a GitLab administrator with [Rails console access](../../../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags) -to run the following command: +1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) (Omnibus GitLab) or + [restart](../../../administration/restart_gitlab.md#installations-from-source) (GitLab installed from source). -```ruby -Feature.enable(:forti_authenticator, User.find(<user ID>)) -``` +### Enable one-time password using FortiToken Cloud -### One-time password via FortiToken Cloud +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212313) in GitLab 13.7 [with a flag](../../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212313) in GitLab 13.7. -> - It's deployed behind a feature flag, disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-fortitoken-cloud-integration). +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per user, ask an administrator to +[enable the feature flag](../../../administration/feature_flags.md) named `forti_token_cloud`. On GitLab.com, this +feature is not available. The feature is not ready for production use. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +You can use FortiToken Cloud as a one-time password (OTP) provider in GitLab. Users must: -You can use FortiToken Cloud as a one-time password (OTP) provider in GitLab. Users must exist in -both FortiToken Cloud and GitLab with the exact same username, and users must -have FortiToken configured in FortiToken Cloud. +- Exist in both FortiToken Cloud and GitLab with the same username. +- Have FortiToken configured in FortiToken Cloud. -You'll also need a `client_id` and `client_secret` to configure FortiToken Cloud. -To get these, see the `REST API Guide` at -[`Fortinet Document Library`](https://docs.fortinet.com/document/fortitoken-cloud/latest/rest-api). +You need a `client_id` and `client_secret` to configure FortiToken Cloud. To get these, see the REST API Guide at +[Fortinet Document Library](https://docs.fortinet.com/document/fortitoken-cloud/latest/rest-api/456035/overview). -First configure FortiToken Cloud in GitLab. On your GitLab server: +Configure FortiToken Cloud in GitLab. On your GitLab server: 1. Open the configuration file. @@ -207,215 +182,184 @@ First configure FortiToken Cloud in GitLab. On your GitLab server: ``` 1. Save the configuration file. -1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) - or [restart GitLab](../../../administration/restart_gitlab.md#installations-from-source) - for the changes to take effect if you installed GitLab via Omnibus or from - source respectively. - -#### Enable or disable FortiToken Cloud integration - -FortiToken Cloud integration is under development and not ready for production use. -It is deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:forti_token_cloud, User.find(<user ID>)) -``` - -To disable it: +1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) (Omnibus GitLab) or + [restart](../../../administration/restart_gitlab.md#installations-from-source) (GitLab installed from source). -```ruby -Feature.disable(:forti_token_cloud, User.find(<user ID>)) -``` +### Set up a U2F device -### U2F device +GitLab officially supports [YubiKey](https://www.yubico.com/products/) U2F devices, but users have successfully used +[SoloKeys](https://solokeys.com/) and [Google Titan Security Key](https://cloud.google.com/titan-security-key). -GitLab officially only supports [YubiKey](https://www.yubico.com/products/) -U2F devices, but users have successfully used [SoloKeys](https://solokeys.com/) -or [Google Titan Security Key](https://cloud.google.com/titan-security-key). - -NOTE: -2FA must be configured before U2F. - -The U2F workflow is [supported by](https://caniuse.com/#search=U2F) the -following desktop browsers: +U2F is [supported by](https://caniuse.com/#search=U2F) the following desktop browsers: - Chrome - Edge -- Firefox 67+ - Opera +- Firefox 67+. For Firefox 47-66: -NOTE: -For Firefox 47-66, you can enable the FIDO U2F API in -[`about:config`](https://support.mozilla.org/en-US/kb/about-config-editor-firefox). -Search for `security.webauth.u2f` and double click on it to toggle to `true`. + 1. Enable the FIDO U2F API in [`about:config`](https://support.mozilla.org/en-US/kb/about-config-editor-firefox). + 1. Search for `security.webauth.u2f` and select it to toggle to `true`. To set up 2FA with a U2F device: -1. Sign in to your GitLab account. -1. Go to your [**User settings**](../index.md#access-your-user-settings). -1. Go to **Account**. -1. Click **Enable Two-Factor Authentication**. +1. Access your [**User settings**](../index.md#access-your-user-settings). +1. Select **Account**. +1. Select **Enable Two-Factor Authentication**. 1. Connect your U2F device. -1. Click on **Set up New U2F Device**. +1. Select on **Set up New U2F Device**. 1. A light begins blinking on your device. Activate it by pressing its button. -A message displays, indicating that your device was successfully set up. -Click on **Register U2F Device** to complete the process. +A message displays indicating that your device was successfully set up. Select **Register U2F Device** to complete the +process. Recovery codes are not generated for U2F devices. -### WebAuthn device +### Set up a WebAuthn device > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22506) in GitLab 13.4 [with a flag](../../../administration/feature_flags.md) named `webauthn`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/232671) in GitLab 14.6. FLAG: -On self-managed GitLab, by default this feature is available. To disable the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `webauthn`. If you disable the WebAuthn feature flag after WebAuthn devices have been registered, these devices are not usable until you re-enable this feature. On GitLab.com, this feature is available. - -The WebAuthn workflow is [supported by](https://caniuse.com/#search=webauthn) the -following desktop browsers: - -- Chrome -- Edge -- Firefox -- Opera -- Safari - -and the following mobile browsers: - -- Chrome for Android -- Firefox for Android -- iOS Safari (since iOS 13.3) - -To set up 2FA with a WebAuthn compatible device: - -1. Sign in to your GitLab account. -1. Go to your [**User settings**](../index.md#access-your-user-settings). -1. Go to **Account**. +On self-managed GitLab, by default this feature is available. To disable the feature, ask an administrator to +[disable the feature flag](../../../administration/feature_flags.md) named `webauthn`. If you disable the WebAuthn +feature flag after WebAuthn devices have been registered, these devices are not usable until you re-enable this feature. +On GitLab.com, this feature is available. + +WebAuthn [supported by](https://caniuse.com/#search=webauthn): + +- The following desktop browsers: + - Chrome + - Edge + - Firefox + - Opera + - Safari +- The following mobile browsers: + - Chrome for Android + - Firefox for Android + - iOS Safari (since iOS 13.3) + +To set up 2FA with a WebAuthn-compatible device: + +1. Access your [**User settings**](../index.md#access-your-user-settings). +1. Select **Account**. 1. Select **Enable Two-Factor Authentication**. 1. Plug in your WebAuthn device. 1. Select **Set up New WebAuthn Device**. -1. Depending on your device, you might need to press a button or touch a sensor. +1. Depending on your device, you might have to press a button or touch a sensor. -A message displays, indicating that your device was successfully set up. -Recovery codes are not generated for WebAuthn devices. +A message displays indicating that your device was successfully set up. Recovery codes are not generated for WebAuthn +devices. ## Recovery codes -NOTE: -Recovery codes are not generated for U2F / WebAuthn devices. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267730) in GitLab 13.7, **Copy codes** and **Print codes** buttons. + +Immediately after successfully enabling 2FA with a one-time password, you're prompted to download +a set of generated recovery codes. If you ever lose access to your one-time password authenticator, you can use one of +these recovery codes to sign in to your account. WARNING: Each code can be used only once to sign in to your account. -Immediately after successfully enabling two-factor authentication, you're -prompted to download a set of generated recovery codes. Should you ever lose access -to your one-time password authenticator, you can use one of these recovery codes to sign in to -your account. We suggest copying and printing them, or downloading them using -the **Download codes** button for storage in a safe place. If you choose to -download them, the file is called `gitlab-recovery-codes.txt`. +We recommend copying and printing them, or downloading them using the **Download codes** button for storage in a safe +place. If you choose to download them, the file is called `gitlab-recovery-codes.txt`. + +NOTE: +Recovery codes are not generated for U2F or WebAuthn devices. + +If you lose the recovery codes, or want to generate new ones, you can use either: + +- The [2FA account settings](#regenerate-two-factor-authentication-recovery-codes) page. +- [SSH](#generate-new-recovery-codes-using-ssh). + +### Regenerate two-factor authentication recovery codes -The UI now includes **Copy codes** and **Print codes** buttons, for your convenience. -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267730) in GitLab 13.7. +To regenerate 2FA recovery codes, you need access to a desktop browser: -If you lose the recovery codes or just want to generate new ones, you can do so -from the [two-factor authentication account settings page](#regenerate-2fa-recovery-codes) or -[using SSH](#generate-new-recovery-codes-using-ssh). +1. Access your [**User settings**](../index.md#access-your-user-settings). +1. Select **Account > Two-Factor Authentication (2FA)**. +1. If you've already configured 2FA, select **Manage two-factor authentication**. +1. In the **Register Two-Factor Authenticator** pane, enter your current password and select **Regenerate recovery codes**. -## Signing in with 2FA Enabled +NOTE: +If you regenerate 2FA recovery codes, save them. You can't use any previously created 2FA codes. + +## Sign in with two-factor authentication enabled -Signing in with 2FA enabled is only slightly different than the normal sign-in process. -Enter your username and password credentials as you normally would, and you're -presented with a second prompt, depending on which type of 2FA you've enabled. +Signing in with 2FA enabled is only slightly different than the normal sign-in process. Enter your username and password +and you're presented with a second prompt, depending on which type of 2FA you've enabled. -### Sign in by using a one-time password +### Sign in using a one-time password -When asked, enter the pin from your one time password authenticator's application or a -recovery code to sign in. +When asked, enter the pin from your one time password authenticator's application or a recovery code to sign in. -### Sign in by using a U2F device +### Sign in using a U2F device To sign in by using a U2F device: -1. Click **Login via U2F Device**. +1. Select **Login via U2F Device**. 1. A light begins blinking on your device. Activate it by touching/pressing its button. -A message displays, indicating that your device responded to the authentication -request, and you're automatically signed in. +A message displays indicating that your device responded to the authentication request, and you're automatically signed +in. -### Sign in by using a WebAuthn device +### Sign in using a WebAuthn device -In supported browsers you should be automatically prompted to activate your WebAuthn device -(for example, by touching or pressing its button) after entering your credentials. +In supported browsers, you should be automatically prompted to activate your WebAuthn device (for example, by touching +or pressing its button) after entering your credentials. -A message displays, indicating that your device responded to the authentication -request and you're automatically signed in. +A message displays indicating that your device responded to the authentication request and you're automatically signed +in. -## Disabling 2FA +## Disable two-factor authentication -If you ever need to disable 2FA: +To disable 2FA: -1. Sign in to your GitLab account. -1. Go to your [**User settings**](../index.md#access-your-user-settings). -1. Go to **Account**. +1. Access your [**User settings**](../index.md#access-your-user-settings). +1. Select **Account**. 1. Select **Manage two-factor authentication**. -1. Under **Two-Factor Authentication**, enter your current password and select **Disable**. - -This clears all your two-factor authentication registrations, including mobile -applications and U2F / WebAuthn devices. +1. Under **Register Two-Factor Authenticator**, enter your current password and select **Disable two-factor + authentication**. -Support for disabling 2FA is limited, depending on your subscription level. For more information, see the -[Account Recovery](https://about.gitlab.com/support/#account-recovery) section of our website. +This clears all your 2FA registrations, including mobile applications and U2F or WebAuthn devices. -## Personal access tokens - -When 2FA is enabled, you can no longer use your normal account password to -authenticate with Git over HTTPS on the command line or when using -the [GitLab API](../../../api/index.md). You must use a -[personal access token](../personal_access_tokens.md) instead. +Support Team support for disabling 2FA is limited, depending on your subscription level. For more information, see the +[Account Recovery](https://about.gitlab.com/support/#account-recovery-and-2fa-resets) section of our website. ## Recovery options -To disable two-factor authentication on your account (for example, if you -have lost your code generation device) you can: +If you don't have access to your code generation device, you can recover access to your account: -- [Use a saved recovery code](#use-a-saved-recovery-code). -- [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh). -- [Regenerate 2FA recovery codes](#regenerate-2fa-recovery-codes). -- [Have 2FA disabled on your account](#have-2fa-disabled-on-your-account). +- [Use a saved recovery code](#use-a-saved-recovery-code), if you saved them when you enabled two-factor + authentication. +- [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh), if you didn't save your original + recovery codes but have an SSH key. +- [Have 2FA disabled on your account](#have-two-factor-authentication-disabled-on-your-account), if you don't have your + recovery codes or an SSH key. ### Use a saved recovery code -Enabling two-factor authentication for your account generated several recovery -codes. If you saved these codes, you can use one of them to sign in. +To use a recovery code: -To use a recovery code, enter your username/email and password on the GitLab -sign-in page. When prompted for a two-factor code, enter the recovery code. +1. Enter your username or email, and password, on the GitLab sign-in page. +1. When prompted for a two-factor code, enter the recovery code. -After you use a recovery code, you cannot re-use it. You can still use the other -recovery codes you saved. +After you use a recovery code, you cannot re-use it. You can still use the other recovery codes you saved. ### Generate new recovery codes using SSH -Users often forget to save their recovery codes when enabling two-factor -authentication. If an SSH key is added to your GitLab account, you can generate -a new set of recovery codes with SSH: +Users often forget to save their recovery codes when enabling 2FA. If you added an SSH key to your +GitLab account, you can generate a new set of recovery codes with SSH: -1. Run: +1. In a terminal, run: ```shell ssh git@gitlab.com 2fa_recovery_codes ``` - NOTE: - On self-managed instances, replace **`gitlab.com`** in the command above - with the GitLab server hostname (`gitlab.example.com`). + On self-managed instances, replace **`gitlab.com`** in the command above with the GitLab server hostname (`gitlab.example.com`). -1. You are prompted to confirm that you want to generate new codes. - Continuing this process invalidates previously saved codes: +1. You are prompted to confirm that you want to generate new codes. This process invalidates previously-saved codes. For + example: ```shell Are you sure you want to generate new two-factor recovery codes? @@ -441,49 +385,30 @@ a new set of recovery codes with SSH: so you do not lose access to your account again. ``` -1. Go to the GitLab sign-in page and enter your username/email and password. - When prompted for a two-factor code, enter one of the recovery codes obtained - from the command-line output. - -After signing in, visit your **User settings > Account** immediately to set -up two-factor authentication with a new device. - -### Regenerate 2FA recovery codes - -To regenerate 2FA recovery codes, you need access to a desktop browser: - -1. Navigate to GitLab. -1. Sign in to your GitLab account. -1. Go to your [**User settings**](../index.md#access-your-user-settings). -1. Select **Account > Two-Factor Authentication (2FA)**. -1. If you've already configured 2FA, click **Manage two-factor authentication**. -1. In the **Register Two-Factor Authenticator** pane, enter your current password and select **Regenerate recovery codes**. +1. Go to the GitLab sign-in page and enter your username or email, and password. When prompted for a two-factor code, + enter one of the recovery codes obtained from the command-line output. -NOTE: -If you regenerate 2FA recovery codes, save them. You can't use any previously created 2FA codes. +After signing in, immediately set up 2FA with a new device. -### Have 2FA disabled on your account +### Have two-factor authentication disabled on your account **(PREMIUM SAAS)** -If you can't use a saved recovery code or generate new recovery codes, submit a [support ticket](https://support.gitlab.com/hc/en-us/requests/new) to -request a GitLab global administrator disable two-factor authentication for your account. Note that: +If other methods are unavailable, submit a [support ticket](https://support.gitlab.com/hc/en-us/requests/new) to request +a GitLab global administrator disable 2FA for your account: - Only the owner of the account can make this request. - This service is only available for accounts that have a GitLab.com subscription. For more information, see our [blog post](https://about.gitlab.com/blog/2020/08/04/gitlab-support-no-longer-processing-mfa-resets-for-free-users/). -- Disabling this setting temporarily leaves your account in a less secure state. You should sign in and re-enable two-factor authentication - as soon as possible. +- Disabling this setting temporarily leaves your account in a less secure state. You should sign in and re-enable two-factor + authentication as soon as possible. -## Note to GitLab administrators +## Information for GitLab administrators **(FREE SELF)** -- You need to take special care to that 2FA keeps working after - [restoring a GitLab backup](../../../raketasks/backup_restore.md). -- To ensure 2FA authorizes correctly with time-based one time passwords (TOTP) server, you may want to ensure - your GitLab server's time is synchronized via a service like NTP. Otherwise, - you may have cases where authorization always fails because of time differences. -- The GitLab U2F implementation does _not_ work when the GitLab instance is accessed from - multiple hostnames, or FQDNs. Each U2F registration is linked to the _current hostname_ at - the time of registration, and cannot be used for other hostnames/FQDNs. The same applies to - WebAuthn registrations. +- Take care that 2FA keeps working after [restoring a GitLab backup](../../../raketasks/backup_restore.md). +- To ensure 2FA authorizes correctly with a time-based one time passwords (TOTP) server, synchronize your GitLab + server's time using a service like NTP. Otherwise, authorization can always fail because of time differences. +- The GitLab U2F and WebAuthn implementation does _not_ work when the GitLab instance is accessed from multiple hostnames + or FQDNs. Each U2F or WebAuthn registration is linked to the _current hostname_ at the time of registration, and + cannot be used for other hostnames or FQDNs. For example, if a user is trying to access a GitLab instance from `first.host.xyz` and `second.host.xyz`: @@ -492,13 +417,13 @@ request a GitLab global administrator disable two-factor authentication for your - The user signs out and attempts to sign in by using `second.host.xyz` - U2F authentication fails, because the U2F key has only been registered on `first.host.xyz`. -- To enforce 2FA at the system or group levels see [Enforce Two-factor Authentication](../../../security/two_factor_authentication.md). +- To enforce 2FA at the system or group levels see, [Enforce two-factor authentication](../../../security/two_factor_authentication.md). ## Troubleshooting -If you are receiving an `invalid pin code` error, this may indicate that there is a time sync issue between the authentication application and the GitLab instance itself. - -To avoid the time sync issue, enable time synchronization in the device that generates the codes. For example: +If you receive an `invalid pin code` error, this can indicate that there is a time sync issue between the authentication +application and the GitLab instance itself. To avoid the time sync issue, enable time synchronization in the device that +generates the codes. For example: - For Android (Google Authenticator): 1. Go to the Main Menu in Google Authenticator. @@ -510,15 +435,3 @@ To avoid the time sync issue, enable time synchronization in the device that gen 1. Select General. 1. Select Date & Time. 1. Enable Set Automatically. If it's already enabled, disable it, wait a few seconds, and re-enable. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 90cb6502bbd..89e4ea6ea5b 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -1,7 +1,7 @@ --- type: index, howto stage: Manage -group: Access +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 --- diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index ea66f3e508f..45cff326332 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: Access +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 --- @@ -14,7 +14,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Personal access tokens can be an alternative to [OAuth2](../../api/oauth2.md) and used to: -- Authenticate with the [GitLab API](../../api/index.md#personalproject-access-tokens). +- Authenticate with the [GitLab API](../../api/index.md#personalprojectgroup-access-tokens). - Authenticate with Git using HTTP Basic Authentication. In both cases, you authenticate with a personal access token in place of your password. @@ -33,7 +33,7 @@ Though required, GitLab usernames are ignored when authenticating with a persona There is an [issue for tracking](https://gitlab.com/gitlab-org/gitlab/-/issues/212953) to make GitLab use the username. -For examples of how you can use a personal access token to authenticate with the API, see the [API documentation](../../api/index.md#personalproject-access-tokens). +For examples of how you can use a personal access token to authenticate with the API, see the [API documentation](../../api/index.md#personalprojectgroup-access-tokens). Alternately, GitLab administrators can use the API to create [impersonation tokens](../../api/index.md#impersonation-tokens). Use impersonation tokens to automate authentication as a specific user. diff --git a/doc/user/profile/unknown_sign_in_notification.md b/doc/user/profile/unknown_sign_in_notification.md index be86db3daf5..0ed2a11d363 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: Access +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 --- diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 9ca11d43864..79d395d51c3 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -1,14 +1,11 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, 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 --- # Badges **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41174) in GitLab 10.7. - Badges are a unified way to present condensed pieces of information about your projects. They consist of a small image and a URL that the image points to. Examples for badges can be the [pipeline status](../../ci/pipelines/settings.md#pipeline-status-badge), @@ -87,7 +84,7 @@ Badges directly associated with a project can be configured on the ## Placeholders -The URL a badge points to, as well as the image URL, can contain placeholders +Both the URL a badge points to and the image URL can contain placeholders which are evaluated when displaying the badge. The following placeholders are available: diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index ccf90a3d3dd..cf571abbf8a 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -394,6 +394,8 @@ stages: production: stage: deploy before_script: + - apt-get update + - apt-get install -y python3-pip - pip3 install awscli --upgrade - pip3 install aws-sam-cli --upgrade script: diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index a95e4d2bc26..4068d8e056c 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -1,19 +1,12 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Code Owners **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916) in GitLab 11.3. -> - Code Owners for merge request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in GitLab Premium 11.9. -> - Moved to GitLab Premium in 13.9. - -INFO: -Get access to Code Owners and more with a -[free 30-day trial of GitLab Ultimate](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-code-owners-docs). +> Moved to GitLab Premium in 13.9. Code Owners define who owns specific files or directories in a repository. @@ -283,3 +276,26 @@ model/db @database [DOCUMENTATION] README.md @docs ``` + +## Troubleshooting + +### Approvals shown as optional + +A Code Owner approval rule is optional if these conditions are not met: + +- 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. +- The section is [marked as optional](#make-a-code-owners-section-optional). + +### Approvals do not show + +Code Owner approval rules only update when the merge request is created. +If you update the `CODEOWNERS` file, close the merge request and create a new one. + +### User not shown as possible approver + +A user might not show as an approver on the Code Owner merge request approval rules. + +This result occurs when a rule prevents the specific user from approving the merge request. +Check the project +[merge request approval setting](merge_requests/approvals/settings.md#edit-merge-request-approval-settings). diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index c5950347ae9..2e876b24b53 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto, reference --- -# Deploy keys +# Deploy keys **(FREE)** Deploy keys allow read-only or read-write access to your repositories by importing an SSH public key into your GitLab instance. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index c840f6c8698..f57fa5aa57d 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -4,12 +4,12 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Deploy tokens +# Deploy tokens **(FREE)** -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199370) from **Settings > Repository** in GitLab 12.9. -> - [Added `write_registry` scope](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) in GitLab 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI/CD** in GitLab 12.10.1. -> - [Added package registry scopes](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199370) from **Settings > Repository** to **Settings > CI/CD** in GitLab 12.9. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) `write_registry` scope in GitLab 12.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI/CD** to **Settings > Repository** in GitLab 12.10.1. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) package registry scopes in GitLab 13.0. Deploy tokens allow you to download (`git clone`) or push and pull packages and container registry images of a project without having a user and a password. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 66e5931fa4c..6c17964f3a5 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -6,73 +6,42 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Description templates **(FREE)** -We all know that a properly submitted issue is more likely to be addressed in -a timely manner by the developers of a project. +You can define templates to use as descriptions +for your [issues](issues/index.md) and [merge requests](merge_requests/index.md). -With description templates, you can define context-specific templates for issue and merge request -description fields for your project, and filter out unnecessary noise from issues. +You can define these templates in a project, group, or instance. Projects +inherit the templates defined at a higher level. -By using the description templates, users that create a new issue or merge -request can select a description template to help them communicate with other -contributors effectively. +You might want to use these templates: -Every GitLab project can define its own set of description templates as they -are added to the root directory of a GitLab project's repository. +- For different stages of your workflow, for example, feature proposal, feature improvement, or a bug report. +- For every issue or merge request for a specific project, so the layout is consistent. +- For a [Service Desk email template](service_desk.md#new-service-desk-issues). -Description templates must be written in [Markdown](../markdown.md) and stored -in your project's repository in the `.gitlab` directory. Only the -templates of the default branch are taken into account. +For description templates to work, they must be: -To learn how to create templates for various file types in groups, visit -[Group file templates](../group/index.md#group-file-templates). - -## Use cases - -These are some situations when you might find description templates useful: - -- You can create issues and merge request templates for different - stages of your workflow, for example, feature proposal, feature improvement, or a bug report. -- Add a template to be used in every issue for a specific project, - giving instructions and guidelines, requiring for information specific to that subject. - For example, if you have a project for tracking new blog posts, you can require the - title, outlines, author name, and author social media information. -- Following the previous example, you can make a template for every MR submitted - with a new blog post, requiring information about the post date, front matter data, - images guidelines, link to the related issue, reviewer name, and so on. -- You can also create issues and merge request templates for different - stages of your workflow, for example, feature proposal, feature improvement, or a bug report. -- You can use an [issue description template](#create-an-issue-template) as a - [Service Desk email template](service_desk.md#new-service-desk-issues). +- Saved with the `.md` extension. +- Stored in your project's repository in the `.gitlab/issue_templates` + or `.gitlab/merge_request_templates` directory. +- Be present on the default branch. ## Create an issue template Create a new Markdown (`.md`) file inside the `.gitlab/issue_templates/` -directory in your repository. Commit and push to your default branch. +directory in your repository. -To create a Markdown file: +To create an issue description template: -1. In a project, go to **Repository**. -1. Next to the default branch, select the **{plus}** button. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Repository**. +1. Next to the default branch, select **{plus}**. 1. Select **New file**. -1. Next to the default branch, in the **File name** field, add the name of your issue template. - Make sure that your file has the `.md` extension, for - example `feature_request.md` or `Feature Request.md`. -1. Commit and push to your default branch. - -If you don't have a `.gitlab/issue_templates` directory in your repository, you need to create it. - -To create the `.gitlab/issue_templates` directory: - -1. In a project, go to **Repository**. -1. Next to the default branch, select the **{plus}** button. -1. Select **New directory**. -1. Name this new directory `.gitlab` and commit to your default branch. -1. Next to the default branch, select the **{plus}** button. -1. Select **New directory**. -1. Name your directory `issue_templates` and commit to your default branch. +1. Next to the default branch, in the **File name** text box, enter `.gitlab/issue_templates/mytemplate.md`, + where `mytemplate` is the name of your issue template. +1. Commit to your default branch. To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-an-issue) -and see if you can choose a description template. +and see if you can find your description template in the **Choose a template** dropdown list. ## Create a merge request template @@ -80,51 +49,48 @@ Similarly to issue templates, create a new Markdown (`.md`) file inside the `.gitlab/merge_request_templates/` directory in your repository. Commit and push to your default branch. -## Use the templates - -Let's take for example that you've created the file `.gitlab/issue_templates/Bug.md`. -This enables the `Bug` dropdown option when creating or editing issues. When -`Bug` is selected, the content from the `Bug.md` template file is copied -to the issue description field. The **Reset template** button discards any -changes you made after picking the template and returns it to its initial status. +To create a merge request description template: -NOTE: -You can create shortcut links to create an issue using a designated template. -For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal`. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Repository**. +1. Next to the default branch, select **{plus}**. +1. Select **New file**. +1. Next to the default branch, in the **File name** text box, enter `.gitlab/merge_request_templates/mytemplate.md`, + where `mytemplate` is the name of your merge request template. +1. Commit to your default branch. - +To check if this has worked correctly, [create a new merge request](merge_requests/creating_merge_requests.md) +and see if you can find your description template in the **Choose a template** dropdown list. -You can set description templates at various levels: +## Use the templates -- The entire [instance](#set-instance-level-description-templates) -- A specific [group or subgroup](#set-group-level-description-templates) -- A specific [project](#set-a-default-template-for-merge-requests-and-issues) +When you create or edit an issue or a merge request, it shows in the **Choose a template** dropdown list. -The templates are inherited. For example, in a project, you can also access templates set for the -instance or the project's parent groups. +To apply a template: -### Set instance-level description templates **(PREMIUM SELF)** +1. Create or edit an issue or a merge request. +1. Select the **Choose a template** dropdown list. +1. If the **Description** text box hasn't been empty, to confirm, select **Apply template**. +1. Select **Save changes**. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321247) in GitLab 14.0. +When you select a description template, its content is copied to the description text box. -You can set a description template at the **instance level** for issues -and merge requests. -As a result, these templates are available in all projects within the instance. +To discard any changes to the description you've made after selecting the template: expand the **Choose a template** dropdown list and select **Reset template**. -Only instance administrators can set instance-level templates. + -To set the instance-level description template repository: +NOTE: +You can create shortcut links to create an issue using a designated template. +For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal`. Read more about [creating issues using a URL with prefilled values](issues/managing_issues.md#using-a-url-with-prefilled-values). -1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Settings > Templates**. -1. Expand **Templates** -1. From the dropdown, select your template project as the template repository at instance level. -1. Select **Save changes**. +### Set instance-level description templates **(PREMIUM SELF)** - +You can set a description template at the **instance level** for issues +and merge requests by using an [instance template repository](../admin_area/settings/instance_template_repository.md). +You can also use the instance template repository for file templates. -Learn more about [instance template repository](../admin_area/settings/instance_template_repository.md). +You might also be interested [project templates](../admin_area/custom_project_templates.md) +that you can use when creating a new project in the instance. ### Set group-level description templates **(PREMIUM)** @@ -137,23 +103,27 @@ As a result, you can use the same templates in issues and merge requests in all To re-use templates [you've created](../project/description_templates.md#create-an-issue-template): -1. Go to the group's **Settings > General > Templates**. -1. From the dropdown, select your template project as the template repository at group level. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand **Templates**. +1. From the dropdown list, select your template project as the template repository at group level. 1. Select **Save changes**.  +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)** 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 entered in the template. -The visibility of issues or merge requests should be set to either "Everyone -with access" or "Only Project Members" in your project's -**Settings / Visibility, project features, permissions** section. Otherwise, the -template text areas don't show. This is the default behavior, so in most cases -you should be fine. +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: @@ -170,11 +140,10 @@ To set a default description template for issues: Because GitLab merge request and issues support [Markdown](../markdown.md), you can use it to format headings, lists, and so on. -[GitLab versions 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/885) -provide `issues_template` and `merge_requests_template` attributes in the -[Projects API](../../api/projects.md) to help you keep your templates up to date. +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. -## Description template example +## Example description template We use description templates for issues and merge requests in the [`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/-/tree/master/.gitlab) of the diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 10dcbddac17..1d06b605aa9 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -2,7 +2,6 @@ stage: Create group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, howto --- # File Locking **(FREE)** @@ -43,8 +42,6 @@ locked by Administrator`. ## Exclusive file locks **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35856) in GitLab 10.5. - This process allows you to lock single files or file extensions and it is done through the command line. It doesn't require GitLab paid subscriptions. diff --git a/doc/user/project/img/description_templates.png b/doc/user/project/img/description_templates.png Binary files differdeleted file mode 100644 index e9d45029532..00000000000 --- a/doc/user/project/img/description_templates.png +++ /dev/null diff --git a/doc/user/project/img/description_templates_v14_7.png b/doc/user/project/img/description_templates_v14_7.png Binary files differnew file mode 100644 index 00000000000..acb1b9f79d9 --- /dev/null +++ b/doc/user/project/img/description_templates_v14_7.png diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 81e7d159a06..da47b673c29 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -33,6 +33,7 @@ created as private in GitLab as well. 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. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 72bf0841687..d4cca723333 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -26,6 +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. References to pull requests and issues are preserved (GitLab.com & 8.7+), and each imported repository maintains visibility level unless that [visibility @@ -164,16 +165,16 @@ your GitHub repositories are listed.  -## Mirror a repository and share pipeline status +## Mirror a repository and share pipeline status **(PREMIUM)** Depending on your GitLab tier, [repository mirroring](../repository/mirror/index.md) can be set up to keep your imported repository in sync with its GitHub copy. -Additionally, you can configure GitLab to send pipeline status updates back GitHub with the -[GitHub Project Integration](../integrations/github.md). **(PREMIUM)** +Additionally, you can configure GitLab to send pipeline status updates back to GitHub with the +[GitHub Project Integration](../integrations/github.md). If you import your project using [CI/CD for external repository](../../../ci/ci_cd_for_external_repos/index.md), then both -of the above are automatically configured. **(PREMIUM)** +of the above are automatically configured. NOTE: Mirroring does not sync any new or updated pull requests from your GitHub project. diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 9d7ed593d41..001f0d56cc5 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -28,7 +28,7 @@ See these documents to migrate to GitLab: You can also import any Git repository through HTTP from the **New Project** page. Note that if the repository is too large, the import can timeout. -You can also [connect your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)** +You can also [connect your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). ## LFS authentication @@ -42,7 +42,10 @@ However, you can't import issues and merge requests this way. To retain all meta merge requests, use the [import/export feature](../settings/import_export.md) to export projects from self-managed GitLab and import those projects into GitLab.com. All GitLab user associations (such as comment author) are changed to the user importing the project. For more -information, see [the import notes](../settings/import_export.md#important-notes). +information, see the prerequisites and important notes in these sections: + +- [Export a project and its data](../settings/import_export.md#export-a-project-and-its-data). +- [Import the project](../settings/import_export.md#import-a-project-and-its-data). NOTE: When migrating to GitLab.com, you must create users manually unless [SCIM](../../../user/group/saml_sso/scim_setup.md) @@ -56,7 +59,7 @@ Migrate the assets in this order: 1. [Projects](../../../api/projects.md) 1. [Project variables](../../../api/project_level_variables.md) -Keep in mind the limitations of the [import/export feature](../settings/import_export.md#exported-contents). +Keep in mind the limitations of the [import/export feature](../settings/import_export.md#items-that-are-exported). You must still migrate your [Container Registry](../../packages/container_registry/) over a series of Docker pulls and pushes. Re-run any CI pipelines to retrieve any build artifacts. @@ -87,7 +90,7 @@ to migrate users. ## Project aliases **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in GitLab Premium 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in GitLab 12.1. GitLab repositories are usually accessed with a namespace and a project name. When migrating frequently accessed repositories to GitLab, however, you can use project aliases to access those diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 07e8ea1dc06..bee097cdcbe 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -1,8 +1,7 @@ --- stage: Manage group: Workspace -info: "To 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Organize work with projects **(FREE)** @@ -43,9 +42,9 @@ Projects include the following [features](https://about.gitlab.com/features/): - [Issue tracker](issues/index.md): Discuss implementations with your team. - [Issue boards](issue_board.md): Organize and prioritize your workflow. - [Multiple issue boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (issue boards) for a project. -- [Merge Requests](merge_requests/index.md): Apply a branching +- [Merge requests](merge_requests/index.md): Apply a branching strategy and get reviewed by your team. - - [Merge Request Approvals](merge_requests/approvals/index.md): Ask for approval before + - [Merge request approvals](merge_requests/approvals/index.md): Ask for approval before implementing a change. - [Fix merge conflicts from the UI](merge_requests/conflicts.md): View Git diffs from the GitLab UI. - [Review Apps](../../ci/review_apps/index.md): By branch, preview the results @@ -144,7 +143,7 @@ There are numerous [APIs](../../api/index.md) to use with your projects: - [Issue board](../../api/boards.md) - [Labels](../../api/labels.md) - [Markdown](../../api/markdown.md) -- [Merge Requests](../../api/merge_requests.md) +- [Merge requests](../../api/merge_requests.md) - [Milestones](../../api/milestones.md) - [Services](../../api/integrations.md) - [Snippets](../../api/project_snippets.md) diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 957290c5f20..0609b843e86 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Insights **(ULTIMATE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in GitLab 12.0. Configure the Insights that matter for your projects to explore data such as triage hygiene, issues created/closed per a given period, average time for merge @@ -297,7 +297,7 @@ you may see `created_at` in place of `merged_at`. `created_at` is used instead. ### `projects` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10904) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10904) in GitLab 12.4. You can limit where the "issuables" can be queried from: diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index c9333b879f3..ad7719f0e5b 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Discord Notifications service **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22684) in GitLab 11.6. - The Discord Notifications service sends event notifications from GitLab to the channel for which the webhook was created. To send GitLab event notifications to a Discord channel, [create a webhook in Discord](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) @@ -17,10 +15,12 @@ and configure it in GitLab. 1. Open the Discord channel you want to receive GitLab event notifications. 1. From the channel menu, select **Edit channel**. -1. Click on **Webhooks** menu item. -1. Click the **Create Webhook** button and fill in the name of the bot to post the messages. Optionally, edit the avatar. -1. Note the URL from the **WEBHOOK URL** field. -1. Click the **Save** button. +1. Select **Integrations**. +1. If there are no existing webhooks, select **Create Webhook**. Otherwise, select **View Webhooks** then **New Webhook**. +1. Enter the name of the bot to post the message. +1. Optional. Edit the avatar. +1. Copy the URL from the **WEBHOOK URL** field. +1. Select **Save**. ## Configure created webhook in GitLab diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 9f1ea3796c6..c07142d6edf 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitHub project integration **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3836) in GitLab 10.6. - You can update GitHub with pipeline status updates from GitLab. This integration can help you if you use GitLab for CI/CD. @@ -46,8 +44,7 @@ to configure pipelines to run for open pull requests. ### Static or dynamic status check names -> - Introduced in GitLab 11.5 with static status check names as an opt-in option. -> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/9931) in GitLab 12.4 to make static status check names the default behavior for new projects. +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/9931) in GitLab 12.4 to make static status check names the default behavior for new projects. A status check name can be static or dynamic: diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 0d8ea636eba..0a685ad0efb 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -6,9 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Slack application **(FREE SAAS)** -> - Introduced in GitLab 9.4. -> - Distributed to Slack App Directory in GitLab 10.2. - NOTE: The GitLab Slack application is only configurable for GitLab.com. It will **not** work for on-premises installations where you can configure the diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index 7a96bb74e3f..fbfa7d914a5 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Google Chat integration **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/43756) in GitLab 11.2. - Integrate your project to send notifications from GitLab to a room of your choice in [Google Chat](https://chat.google.com/) (former Google Hangouts). diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 819c17c12fd..5b83df9b22e 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -51,7 +51,7 @@ Click on the service links to see further configuration instructions and details | [Mattermost slash commands](mattermost_slash_commands.md) | Perform common tasks with slash commands. | **{dotted-circle}** No | | [Microsoft Teams notifications](microsoft_teams.md) | Receive event notifications. | **{dotted-circle}** No | | Packagist | Keep your PHP dependencies updated on Packagist. | **{check-circle}** Yes | -| Pipelines emails | Send the pipeline status to a list of recipients by email. | **{dotted-circle}** No | +| [Pipelines emails](pipeline_status_emails.md) | Send the pipeline status to a list of recipients by email. | **{dotted-circle}** No | | [Pivotal Tracker](pivotal_tracker.md) | Add commit messages as comments to Pivotal Tracker stories. | **{dotted-circle}** No | | [Prometheus](prometheus.md) | Monitor application metrics. | **{dotted-circle}** No | | Pushover | Get real-time notifications on your device. | **{dotted-circle}** No | diff --git a/doc/user/project/integrations/pipeline_status_emails.md b/doc/user/project/integrations/pipeline_status_emails.md new file mode 100644 index 00000000000..742ab977090 --- /dev/null +++ b/doc/user/project/integrations/pipeline_status_emails.md @@ -0,0 +1,23 @@ +--- +stage: Ecosystem +group: Integrations +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Pipeline status emails **(FREE)** + +You can send notifications about pipeline status changes in a group or +project to a list of email addresses. + +## Enable pipeline status email notifications + +To enable pipeline status emails: + +1. In your project or group, on the left sidebar, select **Settings > Integrations**. +1. Select **Pipeline status emails**. +1. Ensure the **Active** checkbox is selected. +1. In **Recipients**, enter a comma-separated list of email addresses. +1. Optional. To receive notifications for broken pipelines only, select + **Notify only broken pipelines**. +1. Select the branches to send notifications for. +1. Select **Save changes**. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 680f787c83c..de7ac6782d6 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Prometheus integration **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8935) in GitLab 9.0. - GitLab offers powerful integration with [Prometheus](https://prometheus.io) for monitoring key metrics of your apps, directly in GitLab. Metrics for each environment are retrieved from Prometheus, and then displayed @@ -41,10 +39,9 @@ See [Prometheus cluster integration](../../clusters/integrations.md#prometheus-c Integration with Prometheus requires the following: -1. GitLab 9.0 or higher -1. Prometheus must be configured to collect one of the [supported metrics](prometheus_library/index.md) -1. Each metric must be have a label to indicate the environment -1. GitLab must have network connectivity to the Prometheus server +- Prometheus must be configured to collect one of the [supported metrics](prometheus_library/index.md) +- Each metric must have a label to indicate the environment +- GitLab must have network connectivity to the Prometheus server #### Getting started @@ -113,9 +110,6 @@ can use only one: ## Determining the performance impact of a merge -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10408) in GitLab 9.2. -> - GitLab 9.3 added the [numeric comparison](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/27439) of the 30 minute averages. - Developers can view the performance impact of their changes in the merge request workflow. This feature requires [Kubernetes](prometheus_library/kubernetes.md) metrics. diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index b35ebacbd31..a07abf26fba 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -4,7 +4,13 @@ group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Monitoring AWS resources **(FREE)** +# Monitoring AWS resources (DEPRECATED) **(FREE)** + +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. GitLab supports automatically detecting and monitoring AWS resources, starting with the [Elastic Load Balancer](https://aws.amazon.com/elasticloadbalancing/) (ELB). diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index 11b74c35a74..97f69d65412 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -4,9 +4,13 @@ group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Monitoring HAProxy **(FREE)** +# Monitoring HAProxy (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12621) in GitLab 9.4 +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. GitLab has support for automatically detecting and monitoring HAProxy. This is provided by leveraging the [HAProxy Exporter](https://github.com/prometheus/haproxy_exporter), which translates HAProxy statistics into a Prometheus readable form. diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index fe74ea6834b..a5fc398e558 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -4,9 +4,13 @@ group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Prometheus Metrics library **(FREE)** +# Prometheus Metrics library (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8935) in GitLab 9.0. +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. GitLab offers automatic detection of select [Prometheus exporters](https://prometheus.io/docs/instrumenting/exporters/). diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 429df7f7e27..26d006adeb9 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -4,9 +4,13 @@ group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Monitoring Kubernetes **(FREE)** +# Monitoring Kubernetes (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8935) in GitLab 9.0. +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. GitLab has support for automatically detecting and monitoring Kubernetes metrics. @@ -44,8 +48,6 @@ Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controll ## Displaying Canary metrics **(PREMIUM)** -> Introduced in [GitLab 10.2](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15201). - GitLab also gathers Kubernetes metrics for [canary deployments](../../canary_deployments.md), allowing easy comparison between the current deployed version and the canary. These metrics expect the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name to begin with `$CI_ENVIRONMENT_SLUG-canary`, to isolate the canary metrics. diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index 3f888a89b1b..ad89543e9a6 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -4,9 +4,13 @@ group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Monitoring NGINX **(FREE)** +# Monitoring NGINX (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12621) in GitLab 9.4 +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. GitLab has support for automatically detecting and monitoring NGINX. This is provided by leveraging the [NGINX VTS exporter](https://github.com/hnlq715/nginx-vts-exporter), which translates [VTS statistics](https://github.com/vozlt/nginx-module-vts) into a Prometheus readable form. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index 6478011b730..03bf9258659 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -4,9 +4,13 @@ group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Monitoring NGINX Ingress Controller **(FREE)** +# Monitoring NGINX Ingress Controller (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22133) in GitLab 11.7. +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. GitLab has support for automatically detecting and monitoring the Kubernetes NGINX Ingress controller. This is provided by leveraging the built-in Prometheus metrics included with Kubernetes NGINX Ingress controller [version 0.16.0](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0160) onward. 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 6bdd2c64dcf..89c174f8fb9 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -4,9 +4,13 @@ group: Monitor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Monitoring NGINX Ingress Controller with VTS metrics **(FREE)** +# Monitoring NGINX Ingress Controller with VTS metrics (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13438) in GitLab 9.5. +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. NOTE: [NGINX Ingress version 0.16](nginx_ingress.md) and above have built-in Prometheus metrics, which are different than the VTS based metrics. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 87f38c3482b..870554100b7 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -59,20 +59,20 @@ Your Slack team now starts receiving GitLab event notifications as configured. The following triggers are available for Slack notifications: -| Trigger name | Trigger event | -| ------------------------ | ------------------------------------------------------ | -| **Push** | A push to the repository. | -| **Issue** | An issue is created, updated, or closed. | -| **Confidential issue** | A confidential issue is created, updated, or closed. | -| **Merge request** | A merge request is created, updated, or merged. | -| **Note** | A comment is added. | -| **Confidential note** | A confidential note is added. | -| **Tag push** | A new tag is pushed to the repository. | -| **Pipeline** | A pipeline status changed. | -| **Wiki page** | A wiki page is created or updated. | -| **Deployment** | A deployment starts or finishes. | -| **Alert** | A new, unique alert is recorded. | -| **Vulnerability** | **(ULTIMATE)** A new, unique vulnerability is recorded. | +| Trigger name | Trigger event | +|--------------------------------------------------------------------------|------------------------------------------------------| +| **Push** | A push to the repository. | +| **Issue** | An issue is created, updated, or closed. | +| **Confidential issue** | A confidential issue is created, updated, or closed. | +| **Merge request** | A merge request is created, updated, or merged. | +| **Note** | A comment is added. | +| **Confidential note** | A confidential note is added. | +| **Tag push** | A new tag is pushed to the repository. | +| **Pipeline** | A pipeline status changed. | +| **Wiki page** | A wiki page is created or updated. | +| **Deployment** | A deployment starts or finishes. | +| **Alert** | A new, unique alert is recorded. | +| [**Vulnerability**](../../application_security/vulnerabilities/index.md) | A new, unique vulnerability is recorded. | ## Troubleshooting diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index e0405955d3d..8bc2b51276a 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -21,11 +21,10 @@ you can use webhooks to: every time an issue is created for a specific project or group in GitLab. - [Automatically assign labels to merge requests](https://about.gitlab.com/blog/2016/08/19/applying-gitlab-labels-automatically/). -You can configure your GitLab project or [group](#group-webhooks) to trigger -a percent-encoded webhook URL when an event occurs. For example, when new code -is pushed or a new issue is created. -The webhook listens for specific [events](#events) and -GitLab sends a POST request with data to the webhook URL. +You can configure your GitLab project or [group](#group-webhooks) to trigger a +[percent-encoded](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding) webhook URL +when an event occurs. For example, when new code is pushed or a new issue is created. The webhook +listens for specific [events](#events) and GitLab sends a POST request with data to the webhook URL. Usually, you set up your own [webhook receiver](#create-an-example-webhook-receiver) to receive information from GitLab and send it to another app, according to your requirements. @@ -55,7 +54,7 @@ You can configure a webhook for a group or a project. 1. In your project or group, on the left sidebar, select **Settings > Webhooks**. 1. In **URL**, enter the URL of the webhook endpoint. - The URL must be percentage-encoded, if necessary. + 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). @@ -135,8 +134,6 @@ in your GitLab projects. ## Filter push events by branch -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/20338) in GitLab 11.3. - Push events can be filtered by branch using a branch name or wildcard pattern to limit which push events are sent to your webhook endpoint. By default, all push events are sent to your webhook endpoint. You can configure branch filtering @@ -159,8 +156,6 @@ GitLab webhooks, keep in mind the following: ## How image URLs are displayed in the webhook body -> Introduced in GitLab 11.2. - Relative image references are rewritten to use an absolute URL in the body of a webhook. For example, if an image, merge request, comment, or wiki page includes the diff --git a/doc/user/project/issues/img/issue_board.png b/doc/user/project/issues/img/issue_board.png Binary files differdeleted file mode 100644 index dd40740aec5..00000000000 --- a/doc/user/project/issues/img/issue_board.png +++ /dev/null diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 1a23902514a..d120df82dbf 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -22,7 +22,7 @@ You can create an issue in many ways in GitLab: - [From another issue](#from-another-issue) - [From an issue board](#from-an-issue-board) - [By sending an email](#by-sending-an-email) -- Using a URL with prefilled fields +- [Using a URL with prefilled values](#using-a-url-with-prefilled-values) - [Using Service Desk](#using-service-desk) ### From a project @@ -639,6 +639,9 @@ You can then see the issue's status in the issues list and the epic tree. After an issue is closed, its health status can't be edited and the **Edit** button becomes disabled until the issue is reopened. +You can also set and clear health statuses using the `/health_status` and `/clear_health_status` +[quick actions](../quick_actions.md#issues-merge-requests-and-epics). + ## Publish an issue **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in GitLab 13.1. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 8874512f9c3..7ccc39eeb8b 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -90,9 +90,10 @@ label section of the right sidebar of an issue or a merge request: color value for a specific color. 1. Click **Create**. -Once created, you can edit a label by clicking the pencil (**{pencil}**), or delete -a label by clicking the three dots (**{ellipsis_v}**) next to the **Subscribe** button -and selecting **Delete**. +To edit a label after you create it, select (**{pencil}**). + +To delete a project label, select (**{ellipsis_v}**) next to the **Subscribe** button +and select **Delete** or select **Delete** when you edit a label. WARNING: If you delete a label, it is permanently deleted. All references to the label are removed from the system and you cannot undo the deletion. diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 283576fb4e9..2dc29f5d725 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +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 --- @@ -211,7 +211,7 @@ Instead of adding users one by one, you can [share a project with an entire grou > - 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). **(FREE SELF)** +> - 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. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 4c96c4d9f56..4e3bae2dc30 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -52,7 +52,7 @@ Administrators can share projects with any group in the system. > - 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). **(FREE SELF)** +> - 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. diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index 8f803f9207c..e67af8dc936 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -9,71 +9,69 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25144) in GitLab 12.8. -If your application offers a web interface and you are using -[GitLab CI/CD](../../../ci/index.md), you can quickly determine the accessibility +If your application offers a web interface, you can use +[GitLab CI/CD](../../../ci/index.md) to determine the accessibility impact of pending code changes. -## Overview - -GitLab uses [pa11y](https://pa11y.org/), a free and open source tool for -measuring the accessibility of web sites, and has built a simple +[Pa11y](https://pa11y.org/) is a free and open source tool for +measuring the accessibility of web sites. GitLab integrates Pa11y into a [CI job template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml). -This job outputs accessibility violations, warnings, and notices for each page -analyzed to a file called `accessibility`. +The `a11y` job analyzes a defined set of web pages and reports +accessibility violations, warnings, and notices in a file named +`accessibility`. -From [GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73309), the version of `pa11y` uses -[WCAG 2.1 rules](https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1), which may report more issues. +As of [GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73309), Pa11y uses +[WCAG 2.1 rules](https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1). ## Accessibility merge request widget > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39425) in GitLab 13.0 behind the disabled [feature flag](../../../administration/feature_flags.md) `:accessibility_report_view`. > - [Feature Flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/217372) in GitLab 13.1. -In addition to the report artifact that is created, GitLab will also show the -Accessibility Report in the merge request widget area: +GitLab displays an **Accessibility Report** in the merge request widget area:  -## Configure Accessibility Testing - -This example shows how to run [pa11y](https://pa11y.org/) -on your code with GitLab CI/CD using the [GitLab Accessibility Docker image](https://gitlab.com/gitlab-org/ci-cd/accessibility). +## Configure accessibility testing -For GitLab 12.9 and later, to define the `a11y` job, you must -[include](../../../ci/yaml/index.md#includetemplate) the -[`Accessibility.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) -included with your GitLab installation, as shown below. +You can run Pa11y with GitLab CI/CD using the +[GitLab Accessibility Docker image](https://gitlab.com/gitlab-org/ci-cd/accessibility). -Add the following to your `.gitlab-ci.yml` file: +To define the `a11y` job for GitLab 12.9 and later: -```yaml -stages: - - accessibility +1. [Include](../../../ci/yaml/index.md#includetemplate) the + [`Accessibility.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) + from your GitLab installation. +1. Add the following configuration to your `.gitlab-ci.yml` file. -variables: - a11y_urls: "https://about.gitlab.com https://gitlab.com/users/sign_in" + ```yaml + stages: + - accessibility + + variables: + a11y_urls: "https://about.gitlab.com https://gitlab.com/users/sign_in" + + include: + - template: "Verify/Accessibility.gitlab-ci.yml" + ``` -include: - - template: "Verify/Accessibility.gitlab-ci.yml" -``` +1. Customize the `a11y_urls` variable to list the URLs of the web pages to test with Pa11y. -creates an `a11y` job in your CI/CD pipeline, runs -Pa11y against the web pages defined in `a11y_urls`, and builds an HTML report for each. +The `a11y` job in your CI/CD pipeline generates these files: -The report for each URL is saved as an artifact that can be [viewed directly in your browser](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). +- One HTML report per URL listed in the `a11y_urls` variable. +- One file containing the collected report data. In GitLab versions 12.11 and later, this + file is named `gl-accessibility.json`. In GitLab versions 12.10 and earlier, this file + is named [`accessibility.json`](https://gitlab.com/gitlab-org/ci-cd/accessibility/-/merge_requests/9). -A single `gl-accessibility.json` artifact is created and saved along with the individual HTML reports. -It includes report data for all URLs scanned. - -NOTE: -For GitLab 12.10 and earlier, the [artifact generated is named `accessibility.json`](https://gitlab.com/gitlab-org/ci-cd/accessibility/-/merge_requests/9). +You can [view job artifacts in your browser](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). NOTE: -For GitLab versions earlier than 12.9, you can use `include:remote` and use a +For GitLab versions earlier than 12.9, use `include:remote` and link to the [current template in the default branch](https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) NOTE: -The job definition provided by the template does not support Kubernetes yet. +The job definition provided by the template does not support Kubernetes. -It is not yet possible to pass configurations into Pa11y via CI configuration. To change anything, -copy the template to your CI file and make the desired edits. +You cannot pass configurations into Pa11y via CI configuration. +To change the configuration, edit a copy of the template in your CI file. diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 5d1a04e1fe0..b10d6597c1e 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -2,77 +2,99 @@ stage: Create group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, howto --- -# Allow collaboration on merge requests across forks **(FREE)** +# Collaborate on merge requests across forks **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17395) in GitLab 10.6. +When you open a merge request from your fork, you can allow upstream +members to collaborate with you on your branch. +When you enable this option, members who have permission to merge to the target branch get +permission to write to the merge request's source branch. -When a user opens a merge request from a fork, they are given the option to allow -upstream members to collaborate with them on the source branch. This allows -the members of the upstream project to make small fixes or rebase branches -before merging, reducing the back and forth of accepting external contributions. +The members of the upstream project can then make small fixes or rebase branches +before merging. This feature is available for merge requests across forked projects that are publicly accessible. -When enabled for a merge request, members with merge access to the target -branch of the project is granted write permissions to the source branch -of the merge request. +## Allow commits from upstream members -## Enabling commit edits from upstream members +> Enabled by default in [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/23308). -In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/23308), -this setting is enabled by default. It can be changed by users with the -Developer [role](../../permissions.md) for the source project. After it's enabled, -upstream members can retry the pipelines and jobs of the merge request: +As the author of a merge request, you can allow commit edits from +upstream members of the project you're contributing to: 1. While creating or editing a merge request, scroll to **Contribution** and - then select the **Allow commits from members who can merge to the target branch**. + select the **Allow commits from members who can merge to the target branch** checkbox. 1. Finish creating your merge request. -After you create the merge request, the merge request widget displays a message: -**Members who can merge are allowed to add commits.** +After you create the merge request, the merge request widget displays the message +**Members who can merge are allowed to add commits**. Upstream members can then +commit directly to your branch, as well as retry the pipelines and jobs of the +merge request. -## Pushing to the fork as the upstream member +## Prevent commits from upstream members -If the creator of the merge request has enabled contributions from upstream -members, you can push directly to the branch of the forked repository. +As the author of a merge request, you can prevent commit edits from +upstream members of the project you're contributing to: -Assuming that: +1. While creating or editing a merge request, scroll to **Contribution** and + clear the **Allow commits from members who can merge to the target branch** + checkbox. +1. Finish creating your merge request. + +## Push to the fork as the upstream member -- The forked project URL is `git@gitlab.com:thedude/awesome-project.git`. -- The branch of the merge request is `update-docs`. +You can push directly to the branch of the forked repository if: -To find and work with the changes from the fork: +- The author of the merge request has enabled contributions from upstream + members. +- You have at least the [Developer role](../../permissions.md) in the + upstream project. + +In the following example: + +- The forked repository URL is `git@gitlab.com:contributor/forked-project.git`. +- The branch of the merge request is `fork-branch`. + +To change or add a commit to the contributor's merge request: 1. Open the merge request page, and select the **Overview** tab. -1. Scroll to the merge request widget, and select **Check out branch**: -  -1. In the modal window, select **{copy-to-clipboard}** (**Copy**) for step 1 - to copy the `git fetch` and `git checkout` instructions to your clipboard. - Paste the commands (which look like this example) into your terminal: +1. Scroll to the merge request widget, and select **Check out branch**. +1. In the modal window, select **Copy** (**{copy-to-clipboard}**). +1. In your terminal, navigate to your cloned version of the repository, and + paste the commands. For example: ```shell - git fetch git@gitlab.com:thedude/awesome-project.git update-docs - git checkout -b thedude-awesome-project-update-docs FETCH_HEAD + git fetch "git@gitlab.com:contributor/forked-project.git" 'fork-branch' + git checkout -b contributor/fork-branch' FETCH_HEAD ``` - These commands fetch the branch from the forked project, and create a local branch - based off the fetched branch. + Those commands fetch the branch from the forked project, and create a local branch + for you to work on. + +1. Make your changes to your local copy of the branch, and then commit them. +1. Push your local changes to the forked project. The following command pushes + the local branch `contributor/fork-branch` to the `fork-branch` branch of + the `git@gitlab.com:contributor/forked-project.git` repository: -1. Make your changes to the local copy of the branch, and then commit them. -1. In your terminal, push your local changes back up to the forked project. This - command pushes the local branch `thedude-awesome-project-update-docs` to the - `update-docs` branch of the `git@gitlab.com:thedude/awesome-project.git` repository: + ```shell + git push git@gitlab.com:contributor/forked-project.git contributor/fork-branch:fork-branch + ``` + + If you have amended or squashed any commits, you must force push. Proceed + with caution as this command rewrites the commit history: ```shell - git push git@gitlab.com:thedude/awesome-project.git thedude-awesome-project-update-docs:update-docs + git push --force git@gitlab.com:contributor/forked-project.git contributor/fork-branch:fork-branch ``` - Note the colon (`:`) between the two branches. + Note the colon (`:`) between the two branches. The general scheme is: + + ```shell + git push <forked_repository_git_url> <local_branch>:<fork_branch> + ``` ## Troubleshooting @@ -89,14 +111,3 @@ going back to the original project: 1. Create a group containing all the upstream members. 1. Go to the **Project information > Members** page in the forked project and invite the newly-created group to the forked project. - -<!-- ## Troubleshooting -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -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/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index f4393b2b76d..129010010e7 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.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: reference, concepts +info: To 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 approval rules **(PREMIUM)** @@ -146,8 +145,7 @@ approve in these ways: ### Code owners as eligible approvers **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in GitLab 11.5. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. If you add [code owners](../../code_owners.md) to your repository, the owners of files become eligible approvers in the project. To enable this merge request approval rule: diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index a6ca9423df0..1e1c8ccb241 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.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: reference, concepts +info: To 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 approval settings **(PREMIUM)** @@ -32,8 +31,7 @@ In this section of general settings, you can configure the following settings: ## Prevent approval by author -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in GitLab 11.3. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. By default, the author of a merge request cannot approve it. To change this setting: @@ -54,8 +52,7 @@ this setting, unless you configure one of these options: ## Prevent approvals by users who add commits -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in GitLab 11.10. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. By default, users who commit to a merge request can still approve it. At both the project level or [instance level](../../../admin_area/merge_requests_approvals.md) diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index e59456e5b34..6668e1736cf 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -63,7 +63,7 @@ on your code by using GitLab CI/CD and [sitespeed.io](https://www.sitespeed.io) using Docker-in-Docker. 1. First, set up GitLab Runner with a - [Docker-in-Docker build](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). + [Docker-in-Docker build](../../../ci/docker/using_docker_build.md#use-docker-in-docker). 1. Configure the default Browser Performance Testing CI/CD job as follows in your `.gitlab-ci.yml` file: ```yaml diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index b791bce5749..30d463efa69 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -2,13 +2,11 @@ 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 --- # Code Quality **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in GitLab 9.3. -> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in 13.2. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) to GitLab Free in 13.2. To ensure your project's code stays simple, readable, and easy to contribute to, you can use [GitLab CI/CD](../../../ci/index.md) to analyze your source code quality. @@ -32,8 +30,7 @@ Code Quality: ## Code Quality Widget -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in GitLab 9.3. -> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in 13.2. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) to GitLab Free in 13.2. Going a step further, GitLab can show the Code Quality report right in the merge request widget area if a report from the target branch is available to compare to: @@ -69,11 +66,8 @@ the merge request's diff view displays an indicator next to lines with new Code ## Example configuration This example shows how to run Code Quality on your code by using GitLab CI/CD and Docker. -It requires GitLab 11.11 or later, and GitLab Runner 11.5 or later. If you are using -GitLab 11.4 or earlier, you can view the deprecated job definitions in the -[documentation archive](https://docs.gitlab.com/12.10/ee/user/project/merge_requests/code_quality.html#previous-job-definitions). -- Using shared runners, the job should be configured For the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). +- Using shared runners, the job should be configured For the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-docker-in-docker). - Using private runners, there is an [alternative configuration](#set-up-a-private-runner-for-code-quality-without-docker-in-docker) recommended for running Code Quality analysis more efficiently. In either configuration, the runner must have enough disk space to handle generated Code Quality files. For example on the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB. @@ -232,7 +226,7 @@ are configured with `privileged=true`, and they do not expose `docker.sock` into the job container. As a result, socket binding cannot be used to make `docker` available in the context of the job script. -[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker) +[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker) was chosen as an operational decision by the runner team, instead of exposing `docker.sock`. ### Disabling the code quality job diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index bffb66755e0..0cc18d2117b 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -67,6 +67,8 @@ GitLab creates a squash commit message with this template: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/346805) `first_commit` and `first_multiline_commit` variables in GitLab 14.6. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75639) `url`, `approved_by`, and `merged_by` variables in GitLab 14.7. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/20421) `co_authored_by` variable in GitLab 14.7. Commit message templates support these variables: @@ -80,8 +82,13 @@ Commit message templates support these variables: | `%{reference}` | Reference to the merge request. | `group-name/project-name!72359` | | `%{first_commit}` | Full message of the first commit in merge request diff. | `Update README.md` | | `%{first_multiline_commit}` | Full message of the first commit that's not a merge commit and has more than one line in message body. Merge Request title if all commits aren't multiline. | `Update README.md`<br><br>`Improved project description in readme file.` | +| `%{url}` | Full URL to the merge request. | `https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1` | +| `%{approved_by}` | Line-separated list of the merge request approvers. This value is not updated until the first page refresh after an approval. | `Approved-by: Sidney Jones <sjones@example.com>` <br> `Approved-by: Zhang Wei <zwei@example.com>` | +| `%{merged_by}` | User who merged the merge request. | `Alex Garcia <agarcia@example.com>` | +| `%{co_authored_by}` | Names and emails of commit authors in a `Co-authored-by` Git commit trailer format. Limited to authors of 100 most recent commits in merge request. | `Co-authored-by: Zane Doe <zdoe@example.com>` <br> `Co-authored-by: Blake Smith <bsmith@example.com>` | -Empty variables that are the only word in a line are removed, along with all newline characters preceding it. +Any line containing only an empty variable is removed. If the line to be removed is both +preceded and followed by an empty line, the preceding empty line is also removed. ## Related topics diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 220049d9a88..6ee02238a22 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -2,7 +2,6 @@ stage: Create group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: howto description: "How to create merge requests in GitLab." disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html' --- @@ -78,7 +77,7 @@ You can create a merge request by running Git commands on your local machine. ```plaintext ... - remote: To create a merge request for docs-new-merge-request, visit: + remote: To create a merge request for my-new-branch, visit: remote: https://gitlab.example.com/my-group/my-project/merge_requests/new?merge_request%5Bsource_branch%5D=my-new-branch ``` @@ -111,10 +110,6 @@ For more information, [see the forking workflow documentation](../repository/for ## By sending an email -> The format of the generated email address changed in GitLab 11.7. - The earlier format is still supported so existing aliases - or contacts still work. - You can create a merge request by sending an email message to GitLab. The merge request target branch is the project's default branch. @@ -142,8 +137,6 @@ A merge request is created. ### Add attachments when creating a merge request by email -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22723) in GitLab 11.5. - You can add commits to a merge request by adding patches as attachments to the email. All attachments with a filename ending in `.patch` are considered patches and are processed diff --git a/doc/user/project/merge_requests/fail_fast_testing.md b/doc/user/project/merge_requests/fail_fast_testing.md index 0d87a04461b..3cb50195f5a 100644 --- a/doc/user/project/merge_requests/fail_fast_testing.md +++ b/doc/user/project/merge_requests/fail_fast_testing.md @@ -42,7 +42,7 @@ 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#configure-pipelines-for-merge-requests) + - 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) 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/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index 078f8048900..cd65fe20e66 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -38,9 +38,12 @@ Now, when you visit the merge request page, you can accept it If a fast-forward merge is not possible but a conflict free rebase is possible, a rebase button is offered. +You can also rebase without running a CI/CD pipeline. +[Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/118825) GitLab 14.7. + The rebase action is also available as a [quick action command: `/rebase`](../../../topics/git/git_rebase.md#rebase-from-the-gitlab-ui). - + If the target branch is ahead of the source branch and a conflict free rebase is not possible, you need to rebase the @@ -48,6 +51,13 @@ source branch locally before you can do a fast-forward merge.  +## Fast-forward merges prevent squashing commits + +If your project has enabled fast-forward merges, to merge cleanly, the code in a +merge request cannot use [squashing during merge](squash_and_merge.md). Squashing +is available only when accepting a merge request. Rebasing may be required before +squashing, even though squashing can itself be considered equivalent to rebasing. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 323b7505190..ec509f58723 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -2,7 +2,6 @@ stage: Create group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: index, reference description: "Getting started with merge requests." --- @@ -92,8 +91,7 @@ and the merge request is added to their #### Multiple assignees **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2004) in GitLab 11.11. -> - Moved to GitLab Premium in 13.9 +> Moved to GitLab Premium in 13.9 Multiple people often review merge requests at the same time. GitLab allows you to have multiple assignees for merge requests @@ -207,7 +205,7 @@ This improvement is [tracked as a follow-up](https://gitlab.com/gitlab-org/gitla - When working locally in your branch, add multiple commits and only push when you're done, so GitLab runs only one pipeline for all the commits pushed - at once. By doing so, you save pipeline minutes. + at once. By doing so, you save CI/CD minutes. - Delete feature branches on merge or after merging them to keep your repository clean. - Take one thing at a time and ship the smallest changes possible. By doing so, reviews are faster and your changes are less prone to errors. diff --git a/doc/user/project/merge_requests/img/commit-button_v13_12.png b/doc/user/project/merge_requests/img/commit-button_v13_12.png Binary files differdeleted file mode 100644 index be154b9e60b..00000000000 --- a/doc/user/project/merge_requests/img/commit-button_v13_12.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/ff_merge_rebase.png b/doc/user/project/merge_requests/img/ff_merge_rebase.png Binary files differdeleted file mode 100644 index f6139f189ce..00000000000 --- a/doc/user/project/merge_requests/img/ff_merge_rebase.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/ff_merge_rebase_v14_7.png b/doc/user/project/merge_requests/img/ff_merge_rebase_v14_7.png Binary files differnew file mode 100644 index 00000000000..3c845d277e4 --- /dev/null +++ b/doc/user/project/merge_requests/img/ff_merge_rebase_v14_7.png diff --git a/doc/user/project/merge_requests/img/squash_edit_form.png b/doc/user/project/merge_requests/img/squash_edit_form.png Binary files differdeleted file mode 100644 index 326d74b68cb..00000000000 --- a/doc/user/project/merge_requests/img/squash_edit_form.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/squash_mr_commits.png b/doc/user/project/merge_requests/img/squash_mr_commits.png Binary files differdeleted file mode 100644 index dfc1ee38435..00000000000 --- a/doc/user/project/merge_requests/img/squash_mr_commits.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/squash_mr_message.png b/doc/user/project/merge_requests/img/squash_mr_message.png Binary files differdeleted file mode 100644 index 8c7dc7886f7..00000000000 --- a/doc/user/project/merge_requests/img/squash_mr_message.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/squash_mr_widget.png b/doc/user/project/merge_requests/img/squash_mr_widget.png Binary files differdeleted file mode 100644 index 81334ca9758..00000000000 --- a/doc/user/project/merge_requests/img/squash_mr_widget.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/squash_squashed_commit.png b/doc/user/project/merge_requests/img/squash_squashed_commit.png Binary files differdeleted file mode 100644 index 7def5339d8a..00000000000 --- a/doc/user/project/merge_requests/img/squash_squashed_commit.png +++ /dev/null diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 7b157aa94d8..40859c6b572 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -103,7 +103,7 @@ job. An example configuration workflow: 1. Set up GitLab Runner to run Docker containers, like the - [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). + [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-docker-in-docker). 1. Configure the default Load Performance Testing CI/CD job in your `.gitlab-ci.yml` file. You need to include the template and configure it with CI/CD variables: diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index e6fb619d365..6441ccb73fe 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -2,7 +2,6 @@ stage: Create group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, concepts --- # Revert changes **(FREE)** @@ -13,11 +12,6 @@ by clicking the **Revert** button in merge requests and commit details. ## Revert a merge request NOTE: -The **Revert** button is available only for merge requests -created in GitLab 8.5 and later. However, you can still revert a merge request -by reverting the merge commit from the list of Commits page. - -NOTE: The **Revert** button is shown only for projects that use the merge method "Merge Commit", which can be set under the project's **Settings > General > Merge request**. [Fast-forward commits](fast_forward_merge.md) diff --git a/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v13_1.jpg Binary files differdeleted file mode 100644 index a4c9df0ebb9..00000000000 --- a/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v13_1.jpg +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v14_7.png b/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v14_7.png Binary files differnew file mode 100644 index 00000000000..2805ef19f2d --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v14_7.png diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index c25b9e15974..1b2a35ba139 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -89,7 +89,7 @@ These commit messages can be customized to follow any guidelines you might have. To do so, expand the **Merge requests** tab within your project's **General** settings and change the **Merge suggestions** text: - + You can also use following variables besides static text: diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 3fe82fb8ef3..f90296e9626 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -2,131 +2,79 @@ stage: Create group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, concepts --- # Squash and merge **(FREE)** -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) from GitLab Premium to GitLab Free in 11.0. +As you work on a feature branch, you often create small, self-contained commits. These small commits +help describe the process of building a feature, but can clutter your Git history after the feature +is finished. As you finish features, you can combine these commits and ensure a cleaner merge history +in your Git repository by using the _squash and merge_ strategy. -With squash and merge you can combine all your merge request's commits into one -and retain a clean history. +- Small commits are joined together, making it simpler to [revert all parts of a change](revert_changes.md). +- When the single commit merges into the target branch, it retains the full commit history. +- Your base branch remains clean, and contains meaningful commit messages. -Squashing lets you tidy up the commit history of a branch when accepting a merge -request. It applies all of the changes in the merge request as a single commit, -and then merges that commit using the merge method set for the project. +Each time a branch merges into your base branch, up to two commits are added: -In other words, squashing a merge request turns a long list of commits: +- The single commit created by squashing the commits from the branch. +- A merge commit, unless you have [enabled fast-forward merges](fast_forward_merge.md#enabling-fast-forward-merges) + in your project. Fast-forward merges disable both merge commits and squashing. - +By default, squashed commits contain the following metadata: -Into a single commit on merge: +- Message: Description of the squash commit, or a customized message +- Author: User that created the merge request +- Committer: User who initiated the squash - +Project owners can [create new default messages](commit_templates.md) for all +squash commits and merge commits. -NOTE: -The squashed commit in this example is followed by a merge commit, because the merge method for this repository uses a merge commit. You can disable merge commits in -**Project Settings > General > Merge requests > Merge method > Fast-forward merge**. +## Set default squash options for a merge request -The squashed commit's default commit message is taken from the merge request title. -You can [edit the default message for squash commits](commit_templates.md). +Users with permission to create or edit a merge request can set the default squash options +for a merge request. To do this: -It can also be customized before merging a merge request. +1. Go to the merge request and select **Edit**. +1. Select or clear the **Squash commits when merge request is accepted** checkbox. +1. Select **Save changes**. - +## Squash commits in a merge request -Squashing also works with the fast-forward merge strategy, see [squashing and fast-forward merge](#squash-and-fast-forward-merge) for more details. +If your project allows you to select squashing options for merge requests, to +squash the commits as part of the merge process: -## Use cases +1. Go to the merge request, and scroll to the merge request reports section that + contains the **Merge** button. +1. Ensure the **Squash commits** checkbox is selected. This checkbox doesn't display + if the project's squashing option is set to either **Do not allow** or **Require**. +1. Optional. To modify either the squash commit message or the merge commit message + (depending on your project configuration), select **Modify commit messages**. +1. When the merge request is ready to merge, select **Merge**. -When working on a feature branch, you sometimes want to commit your current -progress, but don't really care about the commit messages. Those 'work in -progress commits' don't necessarily contain important information and as such -you'd rather not include them in your target branch. +## Configure squash options for a project -With squash and merge, when the merge request is ready to be merged, -all you have to do is enable squashing before you press merge to join -the commits in the merge request into a single commit. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17613) in GitLab 13.2 [with a flag](../../../administration/feature_flags.md) named `squash_options`, disabled by default. +> - [Enabled on GitLab.com and self-managed by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39382) in GitLab 13.3. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/232536) in GitLab 13.8. Feature flag `squash_options` removed. -This way, the history of your base branch remains clean with -meaningful commit messages and: +To configure the default squashing behavior for all merge requests in your project: -- It's simpler to [revert](revert_changes.md) if necessary. -- The merged branch retains the full commit history. - -## Enable squash for a merge request - -Anyone who can create or edit a merge request can choose for it to be squashed -on the merge request form. Users can select or clear the checkbox when they -create the merge request: - - - -After the merge request is submitted, Squash and Merge can still be enabled or disabled -by editing the merge request description: - -1. Scroll to the top of the merge request page and click **Edit**. -1. Scroll down to the end of the merge request form and select the checkbox -**Squash commits when merge request is accepted**. - -This setting can then be overridden at the time of accepting the merge request. -At the end of the merge request widget, next to the **Merge** button, the **Squash commits** checkbox -can be either selected or unselected: - - - -Note that Squash and Merge might not be available depending on the project's configuration -for [Squash Commit Options](#squash-commits-options). - -## Commit metadata for squashed commits - -The squashed commit has the following metadata: - -- Message: the message of the squash commit, or a customized message. -- Author: the author of the merge request. -- Committer: the user who initiated the squash. - -## Squash and fast-forward merge - -When a project has the [fast-forward merge setting enabled](fast_forward_merge.md#enabling-fast-forward-merges), the merge -request must be able to be fast-forwarded without squashing in order to squash -it. This is because squashing is only available when accepting a merge request, -so a merge request may need to be rebased before squashing, even though -squashing can itself be considered equivalent to rebasing. - -## Squash commits options - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17613) in GitLab 13.2. -> - Deployed behind a feature flag, disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39382) in GitLab 13.3. -> - Enabled on GitLab.com. -> - Can be enabled per project. -> - Recommended for production use. - -With Squash Commits Options you can configure the behavior of Squash and Merge for your project. -To set it up, navigate to your project's **Settings > General** and expand **Merge requests**. -You can choose from these options, which affect existing and new merge requests -submitted to your project: - -- **Do not allow**: users cannot use Squash and Merge to squash all the commits immediately before - merging. The checkbox to enable or disable it is unchecked and hidden from the users. -- **Allow**: users can enable Squash and Merge on a merge request basis. - The checkbox is unchecked (disabled) by default, but and the user is allowed to enable it. -- **Encourage**: users can enable Squash and Merge on a merge request basis. - The checkbox is checked (enabled) by default to encourage its use, but the user is allowed to - disable it. -- **Require**: Squash and Merge is enabled for all merge requests, so it is always performed. - The checkbox to enable or disable it is checked and hidden from the users. - -The Squash and Merge checkbox is displayed when you create a merge request and when you edit the description of an existing one, except when Squash Commit Options is set to **Do not allow** or **Require**. - -NOTE: -If your project is set to **Do not allow** Squash and Merge, the users still have the option to -squash commits locally through the command line and force-push to their remote branch before merging. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Merge requests**. +1. In the **Squash commits when merging** section, select your desired behavior: + - **Do not allow**: Squashing is never performed, and the option is not displayed. + - **Allow**: Squashing is allowed, but deselected by default. + - **Encourage**: Squashing is allowed and selected by default, but can be disabled. + - **Require**: Squashing is always performed. While merge requests display the option + to squash, users cannot change it. +1. Select **Save changes**. ## Related topics -- [Commit message templates](commit_templates.md). +- [Commit message templates](commit_templates.md) +- [Fast-forward merges](fast_forward_merge.md) <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 796ffc7866c..236ec64a4dc 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -39,8 +39,6 @@ changes appears as a system note. ## Find the merge request that introduced a change -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2383) in GitLab 10.5. - When viewing the commit details page, GitLab links to the merge request (or merge requests, if it's in more than one) containing that commit. diff --git a/doc/user/project/pages/getting_started/pages_new_project_template.md b/doc/user/project/pages/getting_started/pages_new_project_template.md index f52f64626ac..cee10675a62 100644 --- a/doc/user/project/pages/getting_started/pages_new_project_template.md +++ b/doc/user/project/pages/getting_started/pages_new_project_template.md @@ -1,5 +1,4 @@ --- -type: reference, howto stage: Release group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments @@ -7,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Create a Pages website from a template **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47857) in GitLab 11.8. - GitLab provides templates for the most popular Static Site Generators (SSGs). You can create a new project from a template and run the CI/CD pipeline to generate a Pages website. diff --git a/doc/user/project/pages/img/icons/lock.png b/doc/user/project/pages/img/icons/lock.png Binary files differdeleted file mode 100644 index f7f32fded45..00000000000 --- a/doc/user/project/pages/img/icons/lock.png +++ /dev/null diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 59a2f0c2eba..10fbc57fa0b 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -214,8 +214,6 @@ needing to compress files on-demand. ### Resolving ambiguous URLs -> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/95) in GitLab 11.8 - GitLab Pages makes assumptions about which files to serve when receiving a request for a URL that does not include an extension. diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 4b4d479e3e9..002b234f561 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -1,5 +1,4 @@ --- -type: reference, howto stage: Release group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments @@ -7,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Pages access control **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33422) in GitLab 11.5. -> - Available on GitLab.com in GitLab 12.4. +> Available on GitLab.com in GitLab 12.4. You can enable Pages access control on your project if your administrator has [enabled the access control feature](../../../administration/pages/index.md#access-control) diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index a4e94c03e86..6c18fc158f5 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.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: reference, 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 --- # Protected branches **(FREE)** @@ -76,8 +75,6 @@ The protected branch displays in the list of protected branches. ## Create a protected branch -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) in GitLab 11.9. - Users with the Developer or higher [role](../permissions.md) can create a protected branch. Prerequisites: diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index b4e13aebdb2..e4743c82a3b 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -1,14 +1,11 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, 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 --- # Protected tags **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10356) in GitLab 9.1. - Protected tags: - Allow control over who has permission to create tags. diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 15df69ee68c..846d4732533 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -1,14 +1,11 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, 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 --- # Push Options **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) in GitLab 11.7. - 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. diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 75a5a2a6a4f..21a080de404 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -47,76 +47,78 @@ threads. Some quick actions might not be available to all subscription tiers. <!-- Keep this table sorted alphabetically --> -| 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)). | -| `/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. | -| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users as reviewers. | -| `/assign_reviewer me` or `/reviewer me` or `/request_review me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself as a reviewer. | -| `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle emoji award. | -| `/child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). | -| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | -| `/clone <path/to/project> [--with_notes]`| **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clone the issue to given project, or the current one if no arguments are given ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9421) in GitLab 13.7). Copies as much data as possible as long as the target project contains equivalent labels, milestones, and so on. Does not copy comments or system notes unless `--with_notes` is provided as an argument. | -| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | -| `/confidential` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Make confidential. | -| `/copy_metadata <!merge_request>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another merge request in the project. | -| `/copy_metadata <#issue>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another issue in the project. | -| `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. | -| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to do as done. | -| `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Toggle the draft status. | -| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | -| `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue and mark as a duplicate of another issue. **(FREE)** Also, mark both as related. | -| `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | -| `/estimate <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. Learn more about [time tracking](time_tracking.md). | -| `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants` and is not yet supported in issue templates. | -| `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). | -| `/label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | -| `/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. | -| `/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)). | -| `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906)) | -| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. | -| `/reassign_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Replace current reviewers with those specified. | -| `/rebase` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | -| `/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_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. | -| `/remove_iteration` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove iteration ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). | -| `/remove_milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove milestone. | -| `/remove_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). | -| `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. | -| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | -| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | -| `/severity <severity>` | **{check-circle}** Yes | **{check-circle}** No | **{check-circle}** No | Set the severity. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced in GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/334045). | -| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | -| `/spend <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. Learn more about [time tracking](time_tracking.md). | -| `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review ([introduced in GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/8041)). | -| `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. | -| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | -| `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. | -| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | -| `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. | -| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced in GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/8103)| -| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. | -| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. | -| `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. | -| `/unassign_reviewer` or `/remove_reviewer` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all reviewers. | -| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. | -| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. | -| `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. | -| `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. | -| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. | -| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add Zoom meeting to this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | +| 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)). | +| `/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. | +| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users as reviewers. | +| `/assign_reviewer me` or `/reviewer me` or `/request_review me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself as a reviewer. | +| `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle emoji award. | +| `/child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). | +| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear [health status](issues/managing_issues.md#health-status) ([introduced in GitLab 14.7](https://gitlab.com/gitlab-org/gitlab/-/issues/213814)). | +| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | +| `/clone <path/to/project> [--with_notes]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clone the issue to given project, or the current one if no arguments are given ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9421) in GitLab 13.7). Copies as much data as possible as long as the target project contains equivalent labels, milestones, and so on. Does not copy comments or system notes unless `--with_notes` is provided as an argument. | +| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | +| `/confidential` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Make confidential. | +| `/copy_metadata <!merge_request>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another merge request in the project. | +| `/copy_metadata <#issue>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another issue in the project. | +| `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. | +| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to do as done. | +| `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Toggle the draft status. | +| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | +| `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue and mark as a duplicate of another issue. **(FREE)** Also, mark both as related. | +| `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | +| `/estimate <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. Learn more about [time tracking](time_tracking.md). | +| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk` ([introduced in GitLab 14.7](https://gitlab.com/gitlab-org/gitlab/-/issues/213814)). | +| `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants` and is not yet supported in issue templates. | +| `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). | +| `/label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | +| `/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. | +| `/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)). | +| `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906)) | +| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. | +| `/reassign_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Replace current reviewers with those specified. | +| `/rebase` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | +| `/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_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. | +| `/remove_iteration` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove iteration ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). | +| `/remove_milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove milestone. | +| `/remove_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). | +| `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. | +| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | +| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | +| `/severity <severity>` | **{check-circle}** Yes | **{check-circle}** No | **{check-circle}** No | Set the severity. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced in GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/334045). | +| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | +| `/spend <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. Learn more about [time tracking](time_tracking.md). | +| `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review ([introduced in GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/8041)). | +| `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. | +| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | +| `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. | +| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | +| `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. | +| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced in GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/8103) | +| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. | +| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. | +| `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. | +| `/unassign_reviewer` or `/remove_reviewer` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all reviewers. | +| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. | +| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. | +| `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. | +| `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. | +| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. | +| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add Zoom meeting to this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | ## Commit messages diff --git a/doc/user/project/releases/img/feature_count_v14_6.png b/doc/user/project/releases/img/feature_count_v14_6.png Binary files differindex 0b1a0552631..f254ff4c78a 100644 --- a/doc/user/project/releases/img/feature_count_v14_6.png +++ b/doc/user/project/releases/img/feature_count_v14_6.png diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 239e6c9cea8..747b41d07f2 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Releases **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) in GitLab 11.7. - In GitLab, a release enables you to create a snapshot of your project for your users, including installation packages and release notes. You can create a GitLab release on any branch. Creating a release also creates a [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) to mark the @@ -134,6 +132,10 @@ release creation, the release job fails. To create a release when you push a Git tag, or when you add a Git tag in the UI by going to **Repository > Tags**: +NOTE: +Do not provide **Release notes** when you create the Git tag in the UI. +Providing release notes creates a release, resulting in the pipeline failing. + ```yaml release_job: stage: release @@ -829,3 +831,7 @@ Make sure that the user or a service/bot account is allowed to [create the protected tag](../protected_tags.md#configuring-protected-tags) too. See [the release permissions](#release-permissions) for more information. + +### Note about storage + +Note that the feature is built on top of Git tags, so virtually no extra data is needed besides to create the release itself. Additional assets and the release evidence that is automatically generated consume storage. diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 27767f8d325..0c5c0d5fa7c 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -1,15 +1,11 @@ --- 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 --- # Signing commits with GPG **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9546) in GitLab 9.5. -> - Subkeys support was added in GitLab 10.1. - You can use a GPG key to sign Git commits made in a GitLab repository. Signed commits are labeled **Verified** if the identity of the committer can be verified. To verify the identity of a committer, GitLab requires their public diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 54e9470892c..6ece6e3e4e0 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -2,7 +2,6 @@ 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 --- # Repository **(FREE)** @@ -66,8 +65,6 @@ Alternatively, you can clone directly into a code editor. ### Clone and open in Apple Xcode -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45820) in GitLab 11.0. - Projects that contain a `.xcodeproj` or `.xcworkspace` directory can be cloned into Xcode on macOS. @@ -98,8 +95,7 @@ Visual Studio Code: ## Download the code in a repository -> - Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/24704) in GitLab 11.11. -> - Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. +> Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. You can download the source code that's stored in a repository. diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index d040cc93876..5646f478d9f 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -25,10 +25,10 @@ GitLab. ## Cleaner diffs -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/epics/6589) in GitLab 14.5 [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. Disabled by default. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6589) in GitLab 14.5 [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. 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 `jupyter_clean_diffs`. +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 `jupyter_clean_diffs`. On GitLab.com, this feature is available. When commits include changes to Jupyter Notebook files, GitLab: diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 361c0902ebf..c8950d39f28 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -213,7 +213,7 @@ used in commits. To fix this problem, either: ### Deadline Exceeded -When upgrading to GitLab 11.11.8 or later, a change in how usernames are represented means that you +When upgrading GitLab, a change in how usernames are represented means that you must update your mirroring username and password to ensure that `%40` characters are replaced with `@`. ### Connection blocked because server only allows public key authentication diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index 498b8d063a9..221616bd41c 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -79,7 +79,7 @@ To configure a mirror from GitLab to GitHub: 1. Create a [GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `public_repo` selected. 1. Enter a **Git repository URL** with this format: - `https://<your_github_username>@github.com/<your_github_group>/<your_github_project>.git`. + `https://<your_access_token>@github.com/<github_group>/<github_project>.git`. 1. For **Password**, enter your GitHub personal access token. 1. Select **Mirror repository**. 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 0094e0b1b15..23cead7e8a7 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 @@ -127,7 +127,8 @@ To purge files from a GitLab repository: Refer to the Git [`replace`](https://git-scm.com/book/en/v2/Git-Tools-Replace) documentation for information on how this works. -1. Run a [repository cleanup](#repository-cleanup). +1. Wait at least 30 minutes, because the repository cleanup process only processes object older than 30 minutes. +1. Run [repository cleanup](#repository-cleanup). ## Repository cleanup diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index ba105a970a7..4165c1828cc 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -2,7 +2,6 @@ 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: howto --- # GitLab Web Editor **(FREE)** @@ -118,8 +117,6 @@ There are multiple ways to create a branch from the GitLab web interface. ### Create a new branch from an issue -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2808) in GitLab 8.6. - If your development workflow requires an issue for every merge request, you can create a branch directly from the issue to speed the process up. The new branch, and later its merge request, are marked as related to this issue. diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 294e493dfe9..5fe0e0ef3a2 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -17,10 +17,6 @@ In 14.4, Requirements was moved under **Issues**. With requirements, you can set criteria to check your products against. They can be based on users, stakeholders, system, software, or anything else you find important to capture. -INFO: -Meet your compliance needs with requirements in GitLab. -[Try Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-project-requirements-docs). - A requirement is an artifact in GitLab which describes the specific behavior of your product. Requirements are long-lived and don't disappear unless manually cleared. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 072d685bde4..1b30f14ac90 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -184,9 +184,10 @@ NOTE: On GitLab.com a custom mailbox is already configured with `contact-project+%{key}@incoming.gitlab.com` as the email address, you can still configure the [custom suffix](#configuring-a-custom-email-address-suffix) in project settings. -Using the `service_desk_email` configuration, you can customize the mailbox -used by Service Desk. This allows you to have a separate email address for -Service Desk by also configuring a [custom suffix](#configuring-a-custom-email-address-suffix) +Service Desk uses the [incoming email](../../administration/incoming_email.md) +configuration by default. However, by using the `service_desk_email` configuration, +you can customize the mailbox used by Service Desk. This allows you to have +a separate email address for Service Desk by also configuring a [custom suffix](#configuring-a-custom-email-address-suffix) in project settings. The `address` must include the `+%{key}` placeholder within the 'user' @@ -194,10 +195,10 @@ portion of the address, before the `@`. This is used to identify the project where the issue should be created. NOTE: -The `service_desk_email` and `incoming_email` configurations should -always use separate mailboxes. This is important, because emails picked from -`service_desk_email` mailbox are processed by a different worker and it would -not recognize `incoming_email` emails. +When configuring a custom mailbox, the `service_desk_email` and `incoming_email` +configurations must always use separate mailboxes. This is important, because +emails picked from `service_desk_email` mailbox are processed by a different +worker and it would not recognize `incoming_email` emails. To configure a custom mailbox for Service Desk with IMAP, add the following snippets to your configuration file in full: diff --git a/doc/user/project/settings/img/import_export_download_export.png b/doc/user/project/settings/img/import_export_download_export.png Binary files differdeleted file mode 100644 index 62292e99e8e..00000000000 --- a/doc/user/project/settings/img/import_export_download_export.png +++ /dev/null diff --git a/doc/user/project/settings/img/import_export_export_button.png b/doc/user/project/settings/img/import_export_export_button.png Binary files differdeleted file mode 100644 index 6f3663d64e8..00000000000 --- a/doc/user/project/settings/img/import_export_export_button.png +++ /dev/null diff --git a/doc/user/project/settings/img/import_export_mail_link.png b/doc/user/project/settings/img/import_export_mail_link.png Binary files differdeleted file mode 100644 index 1bd9a071178..00000000000 --- a/doc/user/project/settings/img/import_export_mail_link.png +++ /dev/null diff --git a/doc/user/project/settings/img/import_export_new_project.png b/doc/user/project/settings/img/import_export_new_project.png Binary files differdeleted file mode 100644 index 0e2365ecb68..00000000000 --- a/doc/user/project/settings/img/import_export_new_project.png +++ /dev/null diff --git a/doc/user/project/settings/img/import_export_select_file.png b/doc/user/project/settings/img/import_export_select_file.png Binary files differdeleted file mode 100644 index 90a3e8d5c4e..00000000000 --- a/doc/user/project/settings/img/import_export_select_file.png +++ /dev/null diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index da0336d01ff..06bdf4ca14b 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -6,129 +6,69 @@ info: "To determine the technical writer assigned to the Stage/Group associated # Project import/export **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/3050) in GitLab 8.9. -> - From GitLab 10.0, administrators can disable the project export option on the GitLab instance. +Existing projects on any self-managed GitLab instance or GitLab.com can be exported to a file and +then imported into a new GitLab instance. -Existing projects running on any GitLab instance or GitLab.com can be exported with all their related -data and be moved into a new GitLab instance. +## Set up project import/export -The **GitLab import/export** button is displayed if the project import option is enabled. +Before you can import or export a project and its data, you must set it up. -See also: +1. On the left sidebar, select **Settings > General**. +1. Expand **Visibility and access controls**. +1. Scroll to **Import sources**. +1. Enable the desired **Import sources**. -- [Project import/export API](../../../api/project_import_export.md) -- [Project import/export administration Rake tasks](../../../administration/raketasks/project_import_export.md) **(FREE SELF)** -- [Group import/export](../../group/settings/import_export.md) -- [Group import/export API](../../../api/group_import_export.md) - -To set up a project import/export: - - 1. On the top bar, go to **Menu > Admin > Settings > General > Visibility and access controls**. - 1. Scroll to **Import sources**. - 1. Enable the desired **Import sources**. - -## Important notes - -Note the following: - -- Before you can import a project, you must export the data first. - See [Export a project and its data](#export-a-project-and-its-data) - for how you can export a project through the UI. -- Imports from a newer version of GitLab are not supported. - The Importing GitLab version must be greater than or equal to the Exporting GitLab version. -- Imports fail unless the import and export GitLab instances are - compatible as described in the [Version history](#version-history). -- Exports are generated in your configured `shared_path`, a temporary shared directory, - and are moved to your configured `uploads_directory`. Every 24 hours, a specific worker deletes these export files. -- Group members are exported as project members, as long as the user has - a maintainer or administrator role in the group where the exported project lives. -- Project members with the [Owner role](../../permissions.md) are imported as Maintainers. -- Imported users can be mapped by their public email on self-managed instances, if an administrative user (not an owner) does the import. - The public email is not set by default. Users must [set it in their profiles](../../profile/index.md#set-your-public-email) - for mapping to work correctly. Additionally, the user must be an existing member of the namespace, - or the user can be added as a member of the project for contributions to be mapped. - Otherwise, a supplementary comment is left to mention that the original author and - the MRs, notes, or issues are owned by the importer. - - 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/). -- 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 could be bigger than in the original project. -- Deploy keys allowed to push to protected branches are not exported. Therefore, - you must recreate this association by first enabling these deploy keys in your - imported project and then updating your protected branches accordingly. - -## Version history - -### 14.0+ - -In GitLab 14.0, the JSON format is no longer supported for project and group exports. To allow for a -transitional period, you can still import any JSON exports. The new format for imports and exports -is NDJSON. +## Between CE and EE -### 13.0+ +You can export projects from the [Community Edition to the Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/) +and vice versa. This assumes [version history](#version-history) +requirements are met. -Starting with GitLab 13.0, GitLab can import bundles that were exported from a different GitLab deployment. -This ability is limited to two previous GitLab [minor](../../../policy/maintenance.md#versioning) -releases, which is similar to our process for [Security Releases](../../../policy/maintenance.md#security-releases). +If you're exporting a project from the Enterprise Edition to the Community Edition, you may lose +data that is retained only in the Enterprise Edition. For more information, see +[downgrading from EE to CE](../../../index.md). -For example: +## Export a project and its data -| Current version | Can import bundles exported from | -|-----------------|----------------------------------| -| 13.0 | 13.0, 12.10, 12.9 | -| 13.1 | 13.1, 13.0, 12.10 | +Before you can import a project, you must export it. -### 12.x +Prerequisites: -Prior to 13.0 this was a defined compatibility table: +- Review the list of [data that will be exported](#items-that-are-exported). + Not all data is exported. +- You must have at least the Maintainer role for the project. -| Exporting GitLab version | Importing GitLab version | -| -------------------------- | -------------------------- | -| 11.7 to 12.10 | 11.7 to 12.10 | -| 11.1 to 11.6 | 11.1 to 11.6 | -| 10.8 to 11.0 | 10.8 to 11.0 | -| 10.4 to 10.7 | 10.4 to 10.7 | -| 10.3 | 10.3 | -| 10.0 to 10.2 | 10.0 to 10.2 | -| 9.4 to 9.6 | 9.4 to 9.6 | -| 9.2 to 9.3 | 9.2 to 9.3 | -| 8.17 to 9.1 | 8.17 to 9.1 | -| 8.13 to 8.16 | 8.13 to 8.16 | -| 8.12 | 8.12 | -| 8.10.3 to 8.11 | 8.10.3 to 8.11 | -| 8.10.0 to 8.10.2 | 8.10.0 to 8.10.2 | -| 8.9.5 to 8.9.11 | 8.9.5 to 8.9.11 | -| 8.9.0 to 8.9.4 | 8.9.0 to 8.9.4 | - -Projects can be exported and imported only between versions of GitLab with matching Import/Export versions. - -For example, 8.10.3 and 8.11 have the same Import/Export version (0.1.3) -and the exports between them are compatible. - -## Between CE and EE +To export a project and its data, follow these steps: -You can export projects from the [Community Edition to the Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/) and vice versa. -This assumes [version history](#version-history) requirements are met. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings**. +1. Expand **Advanced**. +1. Select **Export project**. +1. After the export is generated, you should receive an email with a link to download the file. +1. Alternatively, you can come back to the project settings and download the file from there or + generate a new export. After the file is available, the page should show the **Download export** + button. -If you're exporting a project from the Enterprise Edition to the Community Edition, you may lose data that is retained only in the Enterprise Edition. For more information, see [downgrading from EE to CE](../../../index.md). +The export is generated in your configured `shared_path`, a temporary shared directory, and then +moved to your configured `uploads_directory`. Every 24 hours, a worker deletes these export files. -## Exported contents +### Items that are exported The following items are exported: - Project and wiki repositories - Project uploads - Project configuration, excluding integrations -- Issues with comments, merge requests with diffs and comments, labels, milestones, snippets, time tracking, - and other project entities +- Issues with comments, merge requests with diffs and comments, labels, milestones, snippets, time + tracking, and other project entities - Design Management files and data - LFS objects - Issue boards - Pipelines history - Push Rules - Awards +- Group members are exported as project members, as long as the user has the Maintainer role in the + exported project's group, or is an administrator The following items are **not** exported: @@ -140,6 +80,7 @@ The following items are **not** exported: - Any encrypted tokens - Merge Request Approvers - Repository size limits +- Deploy keys allowed to push to protected branches These content rules also apply to creating projects from templates on the [group](../../group/custom_project_templates.md) @@ -150,87 +91,146 @@ NOTE: For more details on the specific data persisted in a project export, see the [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/project/import_export.yml) file. -## Export a project and its data - -Full project export functionality is limited to project maintainers and owners. -You can configure such functionality through [project settings](index.md): - -To export a project and its data, follow these steps: +## Import a project and its data -1. Go to your project's homepage. +> Default maximum import file size [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to unlimited in GitLab 13.8. -1. Select **Settings** in the sidebar. +WARNING: +Only import projects from sources you trust. If you import a project from an untrusted source, it +may be possible for an attacker to steal your sensitive data. -1. Scroll down and expand the **Advanced** section. +Prerequisites: -1. Scroll down to find the **Export project** button: +- You must have [exported the project and its data](#export-a-project-and-its-data). +- Compare GitLab versions and ensure you are importing to a GitLab version that is the same or later + than the GitLab version you exported to. +- Review the [Version history](#version-history) + for compatibility issues. -  +To import a project: -1. After the export is generated, you should receive an email with a link to - download the file: +1. When [creating a new project](../working_with_projects.md#create-a-project), + select **Import project**. +1. In **Import project from**, select **GitLab export**. +1. Enter your project name and URL. Then select the file you exported previously. +1. Select **Import project** to begin importing. Your newly imported project page appears shortly. -  +To get the status of an import, you can query it through the [Project import/export API](../../../api/project_import_export.md#import-status). +As described in the API documentation, the query may return an import error or exceptions. -1. Alternatively, you can come back to the project settings and download the - file from there, or generate a new export. After the file is available, the page - should show the **Download export** button: +### Items that are imported -  +The following items are imported but changed slightly: -## Import the project +- Project members with the [Owner role](../../permissions.md) + 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. +- If use of the `Internal` visibility level + [is restricted](../../../public_access/public_access.md#restrict-use-of-public-or-internal-projects), + all imported projects are given `Private` visibility. -> Default maximum import file size [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to unlimited in GitLab 13.8. +Deploy keys aren't imported. To use deploy keys, you must enable them in your imported project and update protected branches. -WARNING: -Only import projects from sources you trust. If you import a project from an untrusted source, it -may be possible for an attacker to steal your sensitive data. +### Import large projects **(FREE SELF)** -1. The GitLab project import feature is the first import option when creating a - new project. Select **GitLab export**: +If you have a larger project, consider using a Rake task as described in the [developer documentation](../../../development/import_project.md#importing-via-a-rake-task). -  +## Automate group and project import **(PREMIUM)** -1. Enter your project name and URL. Then select the file you exported previously: +For information on automating user, group, and project import API calls, see +[Automate group and project import](../import/index.md#automate-group-and-project-import). -  +## Maximum import file size -1. Select **Import project** to begin importing. Your newly imported project - page appears shortly. +Administrators can set the maximum import file size one of two ways: -NOTE: -If use of the `Internal` visibility level -[is restricted](../../../public_access/public_access.md#restrict-use-of-public-or-internal-projects), -all imported projects are given the visibility of `Private`. +- With the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings). +- In the [Admin Area UI](../../admin_area/settings/account_and_limit_settings.md#max-import-size). -The maximum import file size can be set by the Administrator, and the default is `0` (unlimited). -As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin Area UI](../../admin_area/settings/account_and_limit_settings.md). +The default is `0` (unlimited). -### Project import status +## Map users for import -You can query an import through the [Project import/export API](../../../api/project_import_export.md#import-status). -As described in the API documentation, the query may return an import error or exceptions. +Imported users can be mapped by their public email addresses on self-managed instances, if an administrator (not an owner) does the import. -### Import large projects **(FREE SELF)** +- Public email addresses are not set by default. Users must +[set it in their profiles](../../profile/index.md#set-your-public-email) +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. -If you have a larger project, consider using a Rake task, as described in our [developer documentation](../../../development/import_project.md#importing-via-a-rake-task). +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/). ## Rate Limits To help avoid abuse, by default, users are rate limited to: -| Request Type | Limit | -| ---------------- | ---------------------------------------- | -| Export | 6 projects per minute | -| Download export | 1 download per group per minute | -| Import | 6 projects per minute | +| Request Type | Limit | +| ---------------- | ----- | +| Export | 6 projects per minute | +| Download export | 1 download per group per minute | +| Import | 6 projects per minute | -GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) from the defaults. +GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) +from the defaults. -## Automate group and project import **(PREMIUM)** +## Version history -For information on automating user, group, and project import API calls, see -[Automate group and project import](../import/index.md#automate-group-and-project-import). +### 14.0+ + +In GitLab 14.0, the JSON format is no longer supported for project and group exports. To allow for a +transitional period, you can still import any JSON exports. The new format for imports and exports +is NDJSON. + +### 13.0+ + +Starting with GitLab 13.0, GitLab can import bundles that were exported from a different GitLab deployment. +This ability is limited to two previous GitLab [minor](../../../policy/maintenance.md#versioning) +releases, which is similar to our process for [Security Releases](../../../policy/maintenance.md#security-releases). + +For example: + +| Current version | Can import bundles exported from | +|-----------------|----------------------------------| +| 13.0 | 13.0, 12.10, 12.9 | +| 13.1 | 13.1, 13.0, 12.10 | + +### 12.x + +Prior to 13.0 this was a defined compatibility table: + +| Exporting GitLab version | Importing GitLab version | +| -------------------------- | -------------------------- | +| 11.7 to 12.10 | 11.7 to 12.10 | +| 11.1 to 11.6 | 11.1 to 11.6 | +| 10.8 to 11.0 | 10.8 to 11.0 | +| 10.4 to 10.7 | 10.4 to 10.7 | +| 10.3 | 10.3 | +| 10.0 to 10.2 | 10.0 to 10.2 | +| 9.4 to 9.6 | 9.4 to 9.6 | +| 9.2 to 9.3 | 9.2 to 9.3 | +| 8.17 to 9.1 | 8.17 to 9.1 | +| 8.13 to 8.16 | 8.13 to 8.16 | +| 8.12 | 8.12 | +| 8.10.3 to 8.11 | 8.10.3 to 8.11 | +| 8.10.0 to 8.10.2 | 8.10.0 to 8.10.2 | +| 8.9.5 to 8.9.11 | 8.9.5 to 8.9.11 | +| 8.9.0 to 8.9.4 | 8.9.0 to 8.9.4 | + +Projects can be exported and imported only between versions of GitLab with matching Import/Export versions. + +For example, 8.10.3 and 8.11 have the same Import/Export version (0.1.3) +and the exports between them are compatible. + +## Related topics + +- [Project import/export API](../../../api/project_import_export.md) +- [Project import/export administration Rake tasks](../../../administration/raketasks/project_import_export.md) **(FREE SELF)** +- [Group import/export](../../group/settings/import_export.md) +- [Group import/export API](../../../api/group_import_export.md) ## Troubleshooting @@ -245,7 +245,7 @@ Review [issue 276930](https://gitlab.com/gitlab-org/gitlab/-/issues/276930), and ### Import workarounds for large repositories -[Maximum import size limitations](#import-the-project) +[Maximum import size limitations](#import-a-project-and-its-data) can prevent an import from being successful. If changing the import limits is not possible, you can try one of the workarounds listed here. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index c6cbd45a6ab..9df545b52ec 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -86,12 +86,17 @@ read-only view to discourage this behavior. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/300324) in GitLab 13.11. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/331231) in GitLab 14.2. -Group owners can use compliance pipeline configuration to add additional pipeline configuration to -projects to define compliance requirements such as scans or tests. - -[Compliance frameworks](#compliance-frameworks) allow group owners to specify the location of -compliance pipeline configuration stored and managed in dedicated projects, separate from regular -projects. +Compliance framework pipelines allow group owners to define +a compliance pipeline in a separate repository that gets +executed in place of the local project's `gitlab-ci.yml` file. As part of this pipeline, an +`include` statement can reference the local project's `gitlab-ci.yml` file. This way, the two CI +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), +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). When you set up the compliance framework, use the **Compliance pipeline configuration** box to link the compliance framework to specific CI/CD configuration. Use the @@ -178,8 +183,6 @@ include: # Execute individual project's configuration (if project contains .git project: '$CI_PROJECT_PATH' file: '$CI_CONFIG_PATH' ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch - rules: - - exists: '$CI_CONFIG_PATH' ``` ##### Ensure compliance jobs are always run @@ -265,7 +268,7 @@ Some features depend on others: - If you disable the **Issues** option, GitLab also removes the following features: - - **issue boards** + - **Issue Boards** - [**Service Desk**](#service-desk) NOTE: @@ -324,7 +327,7 @@ Enable [Service Desk](../service_desk.md) for your project to offer customer sup ### Export project -Learn how to [export a project](import_export.md#import-the-project) in GitLab. +Learn how to [export a project](import_export.md#import-a-project-and-its-data) in GitLab. ### Advanced settings diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 44ece6cb172..3fcfe202d38 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: Access +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" type: reference, howto --- @@ -14,18 +14,19 @@ type: reference, howto You can use a project access token to authenticate: -- With the [GitLab API](../../../api/index.md#personalproject-access-tokens). +- With the [GitLab API](../../../api/index.md#personalprojectgroup-access-tokens). - With Git, when using HTTP Basic Authentication. After you configure a project access token, you don't need a password when you authenticate. Instead, you can enter any non-blank value. -Project access tokens are similar to [personal access tokens](../../profile/personal_access_tokens.md), -except they are associated with a project rather than a user. +Project access tokens are similar to [group access tokens](../../group/settings/group_access_tokens.md) +and [personal access tokens](../../profile/personal_access_tokens.md), except they are +associated with a project rather than a group or user. You can use project access tokens: -- On GitLab SaaS if you have the Premium license tier or higher. Personal access tokens are not available with a [trial license](https://about.gitlab.com/free-trial/). +- On GitLab SaaS if you have the Premium license tier or higher. Project access tokens are not available with a [trial license](https://about.gitlab.com/free-trial/). - On self-managed instances of GitLab, with any license tier. If you have the Free tier: - Review your security and compliance policies around [user self-enrollment](../../admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups). @@ -78,83 +79,11 @@ To enable or disable project access token creation for all projects in a top-lev 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. -1. Expand **Permissions, LFS, 2FA**. -1. Under **Permissions**, turn on or off **Allow project access token creation**. +1. Expand **Permissions and group features**. +1. Under **Permissions**, turn on or off **Allow project and group access token creation**. Even when creation is disabled, you can still use and revoke existing project access tokens. -## Group access tokens **(FREE SELF)** - -With group access tokens, you can use a single token to: - -- Perform actions for groups. -- Manage the projects within the group. -- In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/330718) and later, authenticate with Git over HTTPS. - -NOTE: -You cannot use the UI to create a group access token. [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/214045) -to add this functionality. This section describes a workaround. - -If you are an administrator of a self-managed GitLab instance, you can create a group access token in the -[Rails console](../../../administration/operations/rails_console.md). - -<div class="video-fallback"> - For a demo of the group access token workaround, see <a href="https://www.youtube.com/watch?v=W2fg1P1xmU0">Demo: Group Level Access Tokens</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube.com/embed/W2fg1P1xmU0" frameborder="0" allowfullscreen="true"> </iframe> -</figure> - -### Create a group access token - -To create a group access token: - -1. Run the following commands in a [Rails console](../../../administration/operations/rails_console.md): - - ```ruby - # Set the GitLab administration user to use. If user ID 1 is not available or is not an adinistrator, use 'admin = User.admins.first' instead to select an admininistrator. - admin = User.find(1) - - # Set the group group you want to create a token for. For example, group with ID 109. - group = Group.find(109) - - # Create the group bot user. For further group access tokens, the username should be group_#{group.id}_bot#{bot_count}. For example, group_109_bot2 and email address group_109_bot2@example.com. - bot = Users::CreateService.new(admin, { name: 'group_token', username: "group_#{group.id}_bot", email: "group_#{group.id}_bot@example.com", user_type: :project_bot }).execute - - # Confirm the group bot. - bot.confirm - - # Add the bot to the group with the required role. - group.add_user(bot, :maintainer) - - # Give the bot a personal access token. - token = bot.personal_access_tokens.create(scopes:[:api, :write_repository], name: 'group_token') - - # Get the token value. - gtoken = token.token - ``` - -1. Test if the generated group access token works: - - 1. Use the group access token in the `PRIVATE-TOKEN` header with GitLab REST APIs. For example: - - - [Create an epic](../../../api/epics.md#new-epic) in the group. - - [Create a project pipeline](../../../api/pipelines.md#create-a-new-pipeline) in one of the group's projects. - - [Create an issue](../../../api/issues.md#new-issue) in one of the group's projects. - - 1. Use the group token to [clone a group's project](../../../gitlab-basics/start-using-git.md#clone-with-https) - using HTTPS. - -### Revoke a group access token - -To revoke a group access token, run the following command in a [Rails console](../../../administration/operations/rails_console.md): - -```ruby -bot = User.find_by(username: 'group_109_bot') # the owner of the token you want to revoke -token = bot.personal_access_tokens.last # the token you want to revoke -token.revoke! -``` - ## Project bot users > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210181) in GitLab 13.0. @@ -169,11 +98,11 @@ selected role and [scope](#scopes-for-a-project-access-token) of the project acc - The name is set to the name of the token. - The username is set to `project_{project_id}_bot` for the first access token. For example, `project_123_bot`. -- The email is set to `project{project_id}_bot@example.com`. For example, `project123_bot@example.com`. +- The email is set to `project{project_id}_bot@noreply.{Gitlab.config.gitlab.host}`. For example, `project123_bot@noreply.example.com`. - For additional access tokens in the same project, the username is set to `project_{project_id}_bot{bot_count}`. For example, `project_123_bot1`. -- For additional access tokens in the same project, the email is set to `project{project_id}_bot{bot_count}@example.com`. - For example, `project123_bot1@example.com`. +- For additional access tokens in the same project, the email is set to `project{project_id}_bot{bot_count}@noreply.{Gitlab.config.gitlab.host}`. + For example, `project123_bot1@noreply.example.com`. API calls made with a project access token are associated with the corresponding bot user. diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index b41ea30bfef..6ceb8c94934 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -76,6 +76,15 @@ 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. +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: + +```plaintext +Draft MR and respond to initial comments + +/spend 30m +``` + To remove all the time spent at once, use `/remove_time_spent`. ## View a time tracking report diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 40c9ae8bd59..4565b5f1c91 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -1,17 +1,14 @@ --- 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, how-to +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Web IDE **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Free in 10.7. - -The Web Integrated Development Environment (IDE) editor makes it faster and easier to contribute changes to your -projects by providing an advanced editor with commit staging. +The Web Integrated Development Environment (IDE) editor streamlines the process +to contribute changes to your projects, by providing an advanced editor with +commit staging. ## Open the Web IDE @@ -36,8 +33,6 @@ and from merge requests: ## File finder -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18323) in [GitLab Free](https://about.gitlab.com/pricing/) 10.8. - The file finder allows you to quickly open files in the current branch by searching for fragments of the file path. The file finder is launched using the keyboard shortcut <kbd>Command</kbd>+<kbd>p</kbd>, <kbd>Control</kbd>+<kbd>p</kbd>, or <kbd>t</kbd> @@ -150,7 +145,7 @@ Each schema entry supports two properties: ## Configure the Web IDE -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23352) in [GitLab Free](https://about.gitlab.com/pricing/) 13.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23352) in GitLab Free 13.1. The Web IDE supports configuration of certain editor settings by using [`.editorconfig` files](https://editorconfig.org/). When opening a file, the @@ -169,12 +164,10 @@ The Web IDE currently supports the following `.editorconfig` settings: ## Commit changes -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Free in 10.7. -> - From [GitLab 12.7 onward](https://gitlab.com/gitlab-org/gitlab/-/issues/33441), files were automatically staged. -> - From [GitLab 12.9 onward](https://gitlab.com/gitlab-org/gitlab/-/issues/196609), support for staging files was removed to prevent loss of unstaged data. All your current changes necessarily have to be committed or discarded. +> - Starting with [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/33441), files are automatically staged. +> - In [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/196609), support for staging files was removed to prevent loss of unstaged data. All of your current changes must be committed or discarded. -After making your changes, click the **Commit** button on the bottom-left to +After making your changes, select **Commit** on the bottom-left to review the list of changed files. After you have finalized your changes, you can add a commit message, commit the @@ -182,8 +175,8 @@ changes and directly create a merge request. In case you don't have write access to the selected branch, you see a warning, but can still create a new branch and start a merge request. -To discard a change in a particular file, click the **Discard changes** button on that -file in the changes tab. To discard all the changes, click the trash icon on the +To discard a change in a particular file, select **Discard changes** on that +file in the changes tab. To discard all the changes, select the trash icon on the top-right corner of the changes sidebar.  @@ -198,8 +191,6 @@ shows you a preview of the merge request diff if you commit your changes. ## View CI job logs -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19279) in [GitLab Free](https://about.gitlab.com/pricing/) 11.0. - You can use the Web IDE to quickly fix failing tests by opening the branch or merge request in the Web IDE and opening the logs of the failed job. You can access the status of all jobs for the most recent pipeline and job @@ -211,16 +202,12 @@ left. ## Switching merge requests -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19318) in [GitLab Free](https://about.gitlab.com/pricing/) 11.0. - To switch between your authored and assigned merge requests, click the dropdown in the top of the sidebar to open a list of merge requests. You must commit or discard all your changes before switching to a different merge request. ## Switching branches -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20850) in [GitLab Free](https://about.gitlab.com/pricing/) 11.2. - To switch between branches of the current project repository, click the dropdown in the top of the sidebar to open a list of branches. You must commit or discard all your changes before switching to a @@ -228,9 +215,8 @@ different branch. ## Markdown editing -> - Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18059) in [GitLab Free](https://about.gitlab.com/pricing/) 10.7. -> - Support for pasting images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22822) in [GitLab Free](https://about.gitlab.com/pricing/) 13.1. -> - Side-by-side Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68274) in [GitLab Free](https://about.gitlab.com/pricing/) 14.3 +> - Support for pasting images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22822) in GitLab Free 13.1. +> - Side-by-side Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68274) in GitLab Free 14.3. To edit Markdown files in the Web IDE: @@ -255,8 +241,7 @@ There are two ways to preview Markdown content in the Web IDE: ## Live Preview -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19764) in [GitLab Free](https://about.gitlab.com/pricing/) 11.2. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/213853) from _Client Side Evaluation_ to _Live Preview_ in GitLab 13.0. +> [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/213853) from _Client Side Evaluation_ to _Live Preview_ in GitLab 13.0. You can use the Web IDE to preview JavaScript projects right in the browser. This feature uses CodeSandbox to compile and bundle the JavaScript used to @@ -301,8 +286,7 @@ An example `package.json`: ## Interactive Web Terminals for the Web IDE -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) to GitLab Free in 13.1. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) to GitLab Free in 13.1. WARNING: Interactive Web Terminals for the Web IDE is currently in **Beta**. @@ -407,8 +391,8 @@ click **Restart Terminal** to start a new terminal session. ### File syncing to web terminal -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5276) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211686) to GitLab Free in 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5276) in GitLab Ultimate 12.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211686) from GitLab Ultimate to GitLab Free in 13.1. File changes in the Web IDE can be synced to a running web terminal. This enables users to test their code changes in a preconfigured terminal diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 9f1670d3f4c..95ea1b4d0bc 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -1,8 +1,7 @@ --- stage: Create group: Editor -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, how-to +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Wiki **(FREE)** @@ -87,11 +86,7 @@ Users with the [Developer role](../../permissions.md) can create new wiki pages: [special characters](#special-characters-in-page-titles) for subdirectories and formatting, and have [length restrictions](#length-restrictions-for-file-and-directory-names). 1. Add content to your wiki page. -1. Optional. Attach a file, and GitLab stores it according to your installed version of GitLab: - - *Files added in [GitLab 11.3 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475):* - Files are stored in the wiki's Git repository. - - *Files added GitLab 11.2 and earlier:* Files are stored in GitLab itself. To add - the file to the wiki's Git repository, you must re-upload the file. +1. Optional. Attach a file, and GitLab stores it in the wiki's Git repository. 1. Add a **Commit message**. Git requires a commit message, so GitLab creates one if you don't enter one yourself. 1. Select **Create page**. @@ -227,9 +222,9 @@ You can see the changes made in a version of a wiki page, similar to versioned d ## Track wiki events -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14902) in **GitLab 12.10.** -> - Git events were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216014) in **GitLab 13.0.** -> - [Feature flag for Git events was removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258665) in **GitLab 13.5** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14902) in GitLab 12.10. +> - Git events were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216014) in GitLab 13.0. +> - [Feature flag for Git events was removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258665) in GitLab 13.5. GitLab tracks wiki creation, deletion, and update events. These events are displayed on these pages: diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index b5b3f2d2085..61eca19a67b 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -16,7 +16,7 @@ To explore projects: 1. On the top bar, select **Menu > Projects**. 1. Select **Explore projects**. -The **Projects** page shows a list of projects, sorted by last updated date. +The **Projects** page shows a list of projects, sorted by last updated date. - To view projects with the most [stars](#star-a-project), select **Most stars**. - To view projects with the largest number of comments in the past month, select **Trending**. @@ -326,7 +326,7 @@ on the project dashboard when a project is part of a group under a Prerequisites: - Contact your administrator to enable the [GitLab Go Proxy](../packages/go_proxy/index.md). -- To use a private project in a subgroup as a Go package, you must [authenticate Go requests](#authenticate-go-requests-to-private-projects). Go requests that are not authenticated cause +- To use a private project in a subgroup as a Go package, you must [authenticate Go requests](#authenticate-go-requests-to-private-projects). Go requests that are not authenticated cause `go get` to fail. You don't need to authenticate Go requests for projects that are not in subgroups. To use a project as a Go package, use the `go get` and `godoc.org` discovery requests. You can use the meta tags: diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index b9c45bce43a..13fba126169 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -14,10 +14,6 @@ This is the user documentation. To configure the Advanced Search, visit the [administrator documentation](../../integration/elasticsearch.md). Advanced Search is enabled in GitLab.com. -INFO: -Get advanced search and more with a -[free 30-day trial of GitLab Ultimate](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-advanced-search-docs). - GitLab Advanced Search expands on the Basic Search with an additional set of features for faster, more advanced searches across the entire GitLab instance when searching in: diff --git a/doc/user/search/img/code_search.png b/doc/user/search/img/code_search.png Binary files differnew file mode 100644 index 00000000000..7c62bb6921b --- /dev/null +++ b/doc/user/search/img/code_search.png diff --git a/doc/user/search/img/project_code_search.png b/doc/user/search/img/project_code_search.png Binary files differdeleted file mode 100644 index 5412f614a74..00000000000 --- a/doc/user/search/img/project_code_search.png +++ /dev/null diff --git a/doc/user/search/index.md b/doc/user/search/index.md index aa4950cfa33..0e2be455a0c 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -1,8 +1,7 @@ --- stage: Create group: Editor -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: index, reference, 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 --- # Searching in GitLab **(FREE)** @@ -102,8 +101,7 @@ You can filter the **Issues** list to individual instances by their ID. For exam ### Filtering merge requests by approvers **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9468) in GitLab 11.9. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. To filter merge requests by an individual approver, you can type (or select from the dropdown) **Approver** and select the user. @@ -143,7 +141,7 @@ you can choose from:  -When filtering by `Deployed-before` or `Deployed-after`, the date refers to when +When filtering by `Deployed-before` or `Deployed-after`, the date refers to when the deployment to an environment (triggered by the merge commit) completed successfully. You must enter the deploy date manually. Deploy dates use the format `YYYY-MM-DD`, and must be quoted if you wish to specify @@ -272,8 +270,10 @@ 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: - + ### SHA search |
