diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-03-18 23:02:30 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-03-18 23:02:30 +0300 |
| commit | 41fe97390ceddf945f3d967b8fdb3de4c66b7dea (patch) | |
| tree | 9c8d89a8624828992f06d892cd2f43818ff5dcc8 /doc/user | |
| parent | 0804d2dc31052fb45a1efecedc8e06ce9bc32862 (diff) | |
Add latest changes from gitlab-org/gitlab@14-9-stable-eev14.9.0-rc42
Diffstat (limited to 'doc/user')
241 files changed, 4473 insertions, 3678 deletions
diff --git a/doc/user/admin_area/analytics/usage_trends.md b/doc/user/admin_area/analytics/usage_trends.md index a9c5adcf838..5f46908adb0 100644 --- a/doc/user/admin_area/analytics/usage_trends.md +++ b/doc/user/admin_area/analytics/usage_trends.md @@ -12,9 +12,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - It's enabled on GitLab.com. > - It's recommended for production use. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - Usage Trends gives you an overview of how much data your instance contains, and how quickly this volume is changing over time. Usage Trends data refreshes daily. diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index 987d7444ae0..69cb2f04c4d 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -7,7 +7,9 @@ type: reference, howto # Broadcast messages **(FREE SELF)** -GitLab can display broadcast messages to all users of a GitLab instance. There are two types of broadcast messages: +> Target roles [introduced](https://gitlab.com/gitlab-org/growth/team-tasks/-/issues/461) in GitLab 14.8 [with a flag](../../administration/feature_flags.md) named `role_targeted_broadcast_messages`. Disabled by default. + +GitLab can display broadcast messages to users of a GitLab instance. There are two types of broadcast messages: - Banners - Notifications @@ -66,6 +68,7 @@ To add a broadcast message: - `text-decoration` 1. Select one of the suggested background colors, or add the hex code of a different color. The default color is orange. 1. Select the **Dismissable** checkbox to enable users to dismiss the broadcast message. +1. Optional. Select **Target roles** to only show the broadcast message to users with the selected roles. The message displays on group, subgroup, and project pages, and does not display in Git remote responses. 1. If required, add a **Target Path** to only show the broadcast message on URLs matching that path. You can use the wildcard character `*` to match multiple URLs, for example `mygroup/myproject*`. 1. Select a date for the message to start and end. 1. Select **Add broadcast message**. diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index 437a72da767..21ac0f720ec 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -7,7 +7,8 @@ type: howto # Credentials inventory **(ULTIMATE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20912) in GitLab 12.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20912) in GitLab 12.6. +> - [Bot-created access tokens not displayed in personal access token list](https://gitlab.com/gitlab-org/gitlab/-/issues/351759) in GitLab 14.9. GitLab administrators are responsible for the overall security of their instance. To assist, GitLab provides a Credentials inventory to keep track of all the credentials that can be used to access @@ -50,6 +51,8 @@ If you see a **Revoke** button, you can revoke that user's PAT. Whether you see When a PAT is revoked from the credentials inventory, the instance notifies the user by email. + + ## Revoke a user's project access token > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/243833) in GitLab 14.8. @@ -59,6 +62,8 @@ The **Revoke** button next to a project access token can be selected to revoke t - Revoke the token project access token. - Enqueue a background worker to delete the project bot user. + + ## Delete a user's SSH key > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225248) in GitLab 13.5. @@ -66,7 +71,7 @@ The **Revoke** button next to a project access token can be selected to revoke t You can **Delete** a user's SSH key by navigating to the credentials inventory's SSH Keys tab. The instance then notifies the user. - + ## Review existing GPG keys @@ -80,4 +85,4 @@ credentials inventory GPG Keys tab, as well as the following properties: - The ID of the GPG key. - Whether the GPG key is [verified or unverified](../project/repository/gpg_signed_commits/index.md) - + diff --git a/doc/user/admin_area/img/credentials_inventory_gpg_keys_v13_10.png b/doc/user/admin_area/img/credentials_inventory_gpg_keys_v13_10.png Binary files differdeleted file mode 100644 index a88d80a72b6..00000000000 --- a/doc/user/admin_area/img/credentials_inventory_gpg_keys_v13_10.png +++ /dev/null diff --git a/doc/user/admin_area/img/credentials_inventory_gpg_keys_v14_9.png b/doc/user/admin_area/img/credentials_inventory_gpg_keys_v14_9.png Binary files differnew file mode 100644 index 00000000000..6c4c8f30df6 --- /dev/null +++ b/doc/user/admin_area/img/credentials_inventory_gpg_keys_v14_9.png diff --git a/doc/user/admin_area/img/credentials_inventory_personal_access_tokens_v14_9.png b/doc/user/admin_area/img/credentials_inventory_personal_access_tokens_v14_9.png Binary files differnew file mode 100644 index 00000000000..254d520d538 --- /dev/null +++ b/doc/user/admin_area/img/credentials_inventory_personal_access_tokens_v14_9.png diff --git a/doc/user/admin_area/img/credentials_inventory_project_access_tokens_v14_9.png b/doc/user/admin_area/img/credentials_inventory_project_access_tokens_v14_9.png Binary files differnew file mode 100644 index 00000000000..ae204ac09ef --- /dev/null +++ b/doc/user/admin_area/img/credentials_inventory_project_access_tokens_v14_9.png diff --git a/doc/user/admin_area/img/credentials_inventory_ssh_keys_v13_5.png b/doc/user/admin_area/img/credentials_inventory_ssh_keys_v13_5.png Binary files differdeleted file mode 100644 index f5edf513bbf..00000000000 --- a/doc/user/admin_area/img/credentials_inventory_ssh_keys_v13_5.png +++ /dev/null diff --git a/doc/user/admin_area/img/credentials_inventory_ssh_keys_v14_9.png b/doc/user/admin_area/img/credentials_inventory_ssh_keys_v14_9.png Binary files differnew file mode 100644 index 00000000000..8f2f11515eb --- /dev/null +++ b/doc/user/admin_area/img/credentials_inventory_ssh_keys_v14_9.png diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 57a4a746ff0..4a334c28496 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -30,7 +30,7 @@ The Admin Area is made up of the following sections: | **{hook}** System Hooks | Configure [system hooks](../../system_hooks/system_hooks.md) for many events. | | **{applications}** Applications | Create system [OAuth applications](../../integration/oauth_provider.md) for integrations with other services. | | **{slight-frown}** Abuse Reports | Manage [abuse reports](review_abuse_reports.md) submitted by your users. | -| **{license}** License | Upload, display, and remove [licenses](license.md). | +| **{license}** License | Add, display, and remove [licenses](license.md). | | **{cloud-gear}** Kubernetes | Create and manage instance-level [Kubernetes clusters](../instance/clusters/index.md). | | **{push-rules}** Push rules | Configure pre-defined Git [push rules](../project/repository/push_rules.md) for projects. Also, configure [merge requests approvers rules](merge_requests_approvals.md). | | **{location-dot}** Geo | Configure and maintain [Geo nodes](geo_nodes.md). | @@ -218,6 +218,17 @@ You must be an administrator to manually add emails to users: The [Cohorts](user_cohorts.md) tab displays the monthly cohorts of new users and their activities over time. +### Prevent a user from creating groups + +By default, users can create groups. To prevent a user from creating groups: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Users** (`/admin/users`). +1. Locate the user and select them. +1. Select **Edit**. +1. Clear the **Can create group** checkbox. +1. Select **Save changes**. + ### Administering Groups You can administer all groups in the GitLab instance from the Admin Area's Groups page. diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index 22133e30aa0..bee784e850b 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -1,183 +1,57 @@ --- -stage: Growth -group: Conversion +stage: Fulfillment +group: License info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Activate GitLab Enterprise Edition (EE) **(PREMIUM SELF)** -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. - -## Verify your GitLab edition +When you install a new GitLab instance without a license, only Free features +are enabled. To enable more features in GitLab Enterprise Edition (EE), activate +your instance with an activation code. -To activate your instance, make sure you are running GitLab Enterprise Edition (EE). +## Activate GitLab EE -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. - -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). +In GitLab Enterprise Edition 14.1 and later, you need an activation code to activate +your instance. -## Activate GitLab EE with an activation code +Prerequisite: -In GitLab Enterprise Edition 14.1 and later, you need an activation code to activate -your instance. To get an activation code you have to [purchase a license](https://about.gitlab.com/pricing/). -The activation code is a 24-character alphanumeric string you receive in a confirmation email. -You can also sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) -to copy the activation code to your clipboard. +- You must [purchase a subscription](https://about.gitlab.com/pricing/). +- You must be running GitLab Enterprise Edition (EE). +- You must have GitLab 14.1 or later. +- Your instance must be connected to the internet. To activate your instance with an activation code: +1. Copy the activation code, a 24-character alphanumeric string, from either: + - Your subscription confirmation email. + - The [Customers Portal](https://customers.gitlab.com/customers/sign_in), on the **Manage Purchases** page. 1. Sign in to your GitLab self-managed instance. 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Subscription**. -1. Enter the activation code in **Activation code**. +1. Paste 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, 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 subscription is activated. -## Upload your license - -The first time you sign in to your GitLab instance, a note with a -link to the **Upload license** page should be displayed. - -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, either: - - Select **Upload `.gitlab-license` file**, then **Choose File** and - select the license file from your local machine. - - Drag and drop the license file to the **Drag your license file here** area. - - For plain text, select **Enter license key** and paste the contents in - **License key**. -1. Select the **Terms of Service** checkbox. -1. Select **Upload License**. - -## Add your license during installation - -You can import a license file when you install GitLab. - -- **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: - - ```shell - export GITLAB_LICENSE_FILE="/path/to/license/file" - ``` - -- **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`: - - ```ruby - gitlab_rails['initial_license_file'] = "/path/to/license/file" - ``` - -WARNING: -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 - -Fifteen days before the license expires, a notification banner with the upcoming expiration -date displays to GitLab administrators. - -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](#upload-your-license). - -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. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Subscription**. -1. Select **Remove license**. - -Repeat these steps to remove all licenses, including those applied in the past. - -## View license details and history - -To view your license details: - -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 active subscriptions in the **Subscription history** table. - -You can also [export](../../subscriptions/self_managed/index.md) your license usage information to a CSV file. - -NOTE: -In GitLab 13.6 and earlier, a banner about an expiring license may continue to display -when you upload a new license. This happens when the start date of the new license -is in the future and the expiring one is still active. -The banner disappears after the new license becomes active. - -## Troubleshooting - -### No Subscription area in the Admin Area - -You cannot upload your license because there is no **Subscription** area. -This issue might occur if: - -- 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 - -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, the following -rules apply: - -- 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. +If you have an offline or airgapped environment, +[activate GitLab EE with a license file or key](license_file.md) instead. -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. +If you have questions or need assistance activating your instance, +[contact GitLab Support](https://about.gitlab.com/support/#contact-support). -### Cannot activate instance due to connectivity error +When [the license expires](license_file.md#what-happens-when-your-license-expires), +some functionality is locked. -In GitLab 14.1 and later, to activate your subscription with an activation code, -your GitLab instance must be connected to the internet. +## Verify your GitLab edition -If you have an offline or airgapped environment, -[upload a license file](license.md#activate-gitlab-ee-with-a-license-file) instead. +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. -If you have questions or need assistance activating your instance, +If you are running GitLab Community Edition (CE), you can 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). diff --git a/doc/user/admin_area/license_file.md b/doc/user/admin_area/license_file.md new file mode 100644 index 00000000000..e0332e70681 --- /dev/null +++ b/doc/user/admin_area/license_file.md @@ -0,0 +1,127 @@ +--- +stage: Fulfillment +group: License +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Activate GitLab EE with a license file or key + +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 sign in to your GitLab instance, a note with a +link to the **Add license** page should be displayed. + +Otherwise, to add 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 > General**. +1. In the **License file** area, select **Add a license**. +1. Add a license by either uploading the file or pasting the key. +1. Select the **Terms of Service** checkbox. +1. Select **Add license**. + +## Add your license during installation + +You can import a license file when you install GitLab. + +- **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: + + ```shell + export GITLAB_LICENSE_FILE="/path/to/license/file" + ``` + +- **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`: + + ```ruby + gitlab_rails['initial_license_file'] = "/path/to/license/file" + ``` + +WARNING: +These methods only add a license at the time of installation. To renew or upgrade +a license, add the license in the **Admin Area** in the web user interface. + +## What happens when your license expires + +Fifteen days before the license expires, a notification banner with the upcoming expiration +date displays to GitLab administrators. + +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, activate a new subscription. + +To go back to Free features, [delete all expired licenses](#remove-a-license). + +## Remove a license + +To remove a license from a self-managed instance: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Subscription**. +1. Select **Remove license**. + +Repeat these steps to remove all licenses, including those applied in the past. + +## View license details and history + +To view your license details: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Subscription**. + +You can add and view more than one license, but only the latest license in +the current date range is the active license. + +When you add a future-dated license, it doesn't take effect until its applicable date. +You can view all active subscriptions in the **Subscription history** table. + +You can also [export](../../subscriptions/self_managed/index.md) your license usage information to a CSV file. + +NOTE: +In GitLab 13.6 and earlier, a banner about an expiring license may continue to display +when you add 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 + +### No Subscription area in the Admin Area + +You cannot add your license because there is no **Subscription** area. +This issue might occur if: + +- You're running GitLab Community Edition. Before you add your license, you + must [upgrade to Enterprise Edition](../../update/index.md#community-to-enterprise-edition). +- You're using GitLab.com. You cannot add 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 + +GitLab displays a message prompting you to purchase +additional users. This issue occurs if you add 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, the following +rules apply: + +- 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 purchase a license for 100 users, you can have 110 users when you add +your license. However, if you have 111 users, you must purchase more users before you can add +the license. diff --git a/doc/user/admin_area/reporting/spamcheck.md b/doc/user/admin_area/reporting/spamcheck.md index 02d7cd01139..559235fe322 100644 --- a/doc/user/admin_area/reporting/spamcheck.md +++ b/doc/user/admin_area/reporting/spamcheck.md @@ -1,13 +1,16 @@ --- stage: Enablement group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Spamcheck anti-spam service **(PREMIUM SELF)** +# Spamcheck anti-spam service **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6259) in GitLab 14.8. +WARNING: +Spamcheck is available to all tiers, but only on instances using GitLab Enterprise Edition (EE). For [licensing reasons](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6259#note_726605397), it is not included in the GitLab Community Edition (CE) package. You can [migrate from CE to EE](../../../update/package/convert_to_ee.md). + [Spamcheck](https://gitlab.com/gitlab-org/spamcheck) is an anti-spam engine developed by GitLab originally to combat rising amount of spam in GitLab.com, and later made public to be used in self-managed GitLab instances. @@ -47,7 +50,7 @@ Spamcheck is only available for package-based installations: 1. Select **Save changes**. NOTE: -In single-node instances, Spamcehck runs over `localhost`, and hence is running +In single-node instances, Spamcheck runs over `localhost`, and hence is running in an unauthenticated mode. If on multi-node instances where GitLab runs on one server and Spamcheck runs on another server listening over a public endpoint, it is recommended to enforce some sort of authentication using a reverse proxy in 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 1d982196228..2f30298644a 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -178,14 +178,9 @@ nginx['client_max_body_size'] = "200m" > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296669) in GitLab 13.9. > - It's deployed behind a feature flag, disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](../../../security/two_factor_authentication.md#enable-or-disable-2fa-for-git-operations). -NOTE: -This feature is under development and not ready for production use. It is deployed -behind a feature flag that is **disabled by default**. To use it in GitLab -self-managed instances, ask a GitLab administrator to [enable it](../../../security/two_factor_authentication.md#enable-or-disable-2fa-for-git-operations). +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 `two_factor_for_cli`. On GitLab.com, this feature is not available. This feature is not ready for production use. This feature flag also affects [2FA for Git over SSH operations](../../../security/two_factor_authentication.md#2fa-for-git-over-ssh-operations). GitLab administrators can choose to customize the session duration (in minutes) for Git operations when 2FA is enabled. The default is 15 and this can be set to a value between 1 and 10080. diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 18379471bcf..0330d89aedc 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -55,31 +55,28 @@ can be set at: - The instance level. - [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/21688), the project and group level. -The value is: +For the setting on GitLab.com, see [Artifacts maximum size](../../gitlab_com/index.md#gitlab-cicd). -- In *MB* and the default is 100MB per job. -- [Set to 1G](../../gitlab_com/index.md#gitlab-cicd) on GitLab.com. - -To change it at the: +The value is in MB and the default is 100MB per job. To change it at the: - Instance level: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Change the value of maximum artifacts size (in MB). - 1. Click **Save changes** for the changes to take effect. + 1. Select **Save changes** for the changes to take effect. - Group level (this overrides the instance setting): 1. Go to the group's **Settings > CI/CD > General Pipelines**. 1. Change the value of **maximum artifacts size (in MB)**. - 1. Click **Save changes** for the changes to take effect. + 1. Select **Save changes** for the changes to take effect. - Project level (this overrides the instance and group settings): 1. Go to the project's **Settings > CI/CD > General Pipelines**. 1. Change the value of **maximum artifacts size (in MB)**. - 1. Click **Save changes** for the changes to take effect. + 1. Select **Save changes** for the changes to take effect. NOTE: The setting at all levels is only available to GitLab administrators. @@ -94,7 +91,7 @@ and the default value is `30 days`. 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD**. 1. Change the value of default expiration time. -1. Click **Save changes** for the changes to take effect. +1. Select **Save changes** for the changes to take effect. This setting is set per job and can be overridden in [`.gitlab-ci.yml`](../../../ci/yaml/index.md#artifactsexpire_in). @@ -126,7 +123,7 @@ To disable the setting: 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Continuous Integration and Deployment**. 1. Clear the **Keep the latest artifacts for all jobs in the latest successful pipelines** checkbox. -1. Click **Save changes** +1. Select **Save changes** When you disable the feature, the latest artifacts do not immediately expire. A new pipeline must run before the latest artifacts can expire and be deleted. @@ -156,7 +153,7 @@ After that time passes, the jobs are archived and no longer able to be retried. Make it empty to never expire jobs. It has to be no less than 1 day, for example: <code>15 days</code>, <code>1 month</code>, <code>2 years</code>. -As of June 22, 2020 the [value is set](../../gitlab_com/index.md#gitlab-cicd) to 3 months on GitLab.com. Jobs created before that date were archived after September 22, 2020. +For the value set for GitLab.com, see [Scheduled job archiving](../../gitlab_com/index.md#gitlab-cicd). ## Protect CI/CD variables by default @@ -233,7 +230,7 @@ To select a CI/CD template for the required pipeline configuration: 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand the **Required pipeline configuration** section. 1. Select a CI/CD template from the dropdown. -1. Click **Save changes**. +1. Select **Save changes**. ## Package Registry configuration @@ -272,7 +269,7 @@ To set the maximum file size: 1. Expand the **Package Registry** section. 1. Find the package type you would like to adjust. 1. Enter the maximum file size, in bytes. -1. Click **Save size limits**. +1. Select **Save size limits**. ## Prevent users from registering runners diff --git a/doc/user/admin_area/settings/gitaly_timeouts.md b/doc/user/admin_area/settings/gitaly_timeouts.md index fac23cb48af..42e0c9faf9f 100644 --- a/doc/user/admin_area/settings/gitaly_timeouts.md +++ b/doc/user/admin_area/settings/gitaly_timeouts.md @@ -22,6 +22,6 @@ The following timeouts are available. | Timeout | Default | Description | |:--------|:-----------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Default | 55 seconds | Timeout for most Gitaly calls (not enforced for `git` `fetch` and `push` operations, or Sidekiq jobs). For example, checking if a repository exists on disk. Makes sure that Gitaly calls made within a web request cannot exceed the entire request timeout. It should be shorter than the [worker timeout](../../../administration/operations/puma.md#worker-timeout) that can be configured for [Puma](../../../install/requirements.md#puma-settings). If a Gitaly call timeout exceeds the worker timeout, the remaining time from the worker timeout is used to avoid having to terminate the worker. | +| Default | 55 seconds | Timeout for most Gitaly calls (not enforced for `git` `fetch` and `push` operations, or Sidekiq jobs). For example, checking if a repository exists on disk. Makes sure that Gitaly calls made within a web request cannot exceed the entire request timeout. It should be shorter than the [worker timeout](../../../administration/operations/puma.md#change-the-worker-timeout) that can be configured for [Puma](../../../install/requirements.md#puma-settings). If a Gitaly call timeout exceeds the worker timeout, the remaining time from the worker timeout is used to avoid having to terminate the worker. | | Fast | 10 seconds | Timeout for fast Gitaly operations used within requests, sometimes multiple times. For example, checking if a repository exists on disk. If fast operations exceed this threshold, there may be a problem with a storage shard. Failing fast can help maintain the stability of the GitLab instance. | | Medium | 30 seconds | Timeout for Gitaly operations that should be fast (possibly within requests) but preferably not used multiple times within a request. For example, loading blobs. Timeout that should be set between Default and Fast. | diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index a581fd4aebc..052b6e26c07 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -130,6 +130,7 @@ The **Network** settings contain: Git LFS requests that supersede the user and IP rate limits. - [Files API Rate Limits](files_api_rate_limits.md) - Configure specific limits for Files API requests that supersede the user and IP rate limits. + - [Search rate limits](../../../administration/instance_limits.md#search-rate-limit) - Configure global search request rate limits for authenticated and unauthenticated users. - [Deprecated API Rate Limits](deprecated_api_rate_limits.md) - Configure specific limits for deprecated API requests that supersede the user and IP rate limits. - [Outbound requests](../../../security/webhooks.md) - Allow requests to the local network from hooks and services. @@ -170,6 +171,8 @@ The **Repository** settings contain: - [Repository's custom initial branch name](../../project/repository/branches/default.md#instance-level-custom-initial-branch-name) - Set a custom branch name for new repositories created in your instance. +- [Repository's initial default branch protection](../../project/repository/branches/default.md#instance-level-default-branch-protection) - + Configure the branch protections to apply to every repository's default branch. - [Repository mirror](visibility_and_access_controls.md#enable-project-mirroring) - Configure repository mirroring. - [Repository storage](../../../administration/repository_storage_types.md) - Configure storage path settings. diff --git a/doc/user/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md index 88be73c3215..56e240a8d39 100644 --- a/doc/user/admin_area/settings/user_and_ip_rate_limits.md +++ b/doc/user/admin_area/settings/user_and_ip_rate_limits.md @@ -107,7 +107,7 @@ attached into the response headers. | `RateLimit-Limit` | `60` | The request quota for the client **each minute**. If the rate limit period set in the admin area is different from 1 minute, the value of this header is adjusted to approximately the nearest 60-minute period. | | `RateLimit-Name` | `throttle_authenticated_web` | Name of the throttle blocking the requests. | | `RateLimit-Observed` | `67` | Number of requests associated to the client in the time window. | -| `RateLimit-Remaining` | `0` | Remaining quota in the time window. The result of `RateLimit-Limit` - `RateLimit-Remaining`. | +| `RateLimit-Remaining` | `0` | Remaining quota in the time window. The result of `RateLimit-Limit` - `RateLimit-Observed`. | | `RateLimit-Reset` | `1609844400` | [Unix time](https://en.wikipedia.org/wiki/Unix_time)-formatted time when the request quota is reset. | | `RateLimit-ResetTime` | `Tue, 05 Jan 2021 11:00:00 GMT` | [RFC2616](https://tools.ietf.org/html/rfc2616#section-3.3.1)-formatted date and time when the request quota is reset. | | `Retry-After` | `30` | Remaining duration **in seconds** until the quota is reset. This is a [standard HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After). | 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 c38b2455a8d..2165dc54899 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -17,54 +17,6 @@ To access the visibility and access control options: 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. -## Protect default branches - -With this option, you can define [branch protections](../../project/protected_branches.md) -to apply to every repository's [default branch](../../project/repository/branches/default.md). -These protections specify the user roles with permission to push to default branches. - -This setting applies only to each repository's default branch. To protect other branches, -you must configure [branch protection in the repository](../../project/protected_branches.md), -or configure [branch protection for groups](../../group/index.md#change-the-default-branch-protection-of-a-group). - -To change the default branch protection for the entire instance: - -1. Sign in to GitLab as a user with Administrator access level. -1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Visibility and access controls** section. -1. Select a **Default branch protection**: - - **Not protected** - Both developers and maintainers can push new commits - and force push. - - **Protected against pushes** - Developers cannot push new commits, but are - allowed to accept merge requests to the branch. Maintainers can push to the branch. - - **Partially protected** - Both developers and maintainers can push new commits, - but cannot force push. - - **Fully protected** - Developers cannot push new commits, but maintainers can. - No one can force push. -1. To allow group owners to override the instance's default branch protection, select - [**Allow owners to manage default branch protection per group**](#prevent-overrides-of-default-branch-protection). -1. Select **Save changes**. - -### Prevent overrides of default branch protection **(PREMIUM SELF)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211944) in GitLab 13.0. - -Instance-level protections for [default branch](../../project/repository/branches/default.md) -can be overridden on a per-group basis by the group's owner. In -[GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can -disable this privilege for group owners, enforcing the instance-level protection rule: - -1. Sign in to GitLab as a user with Administrator access level. -1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Settings > General**. -1. Expand the **Visibility and access controls** section. -1. Deselect the **Allow owners to manage default branch protection per group** checkbox. -1. Select **Save changes**. - -NOTE: -GitLab administrators can still update the default branch protection of a group. - ## Define which roles can create projects Instance-level protections for project creation define which roles can diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index 1bc0c2b8fb0..8e231d18f41 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -4,13 +4,13 @@ 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 --- -# CI/CD Analytics **(FREE)** +# CI/CD analytics **(FREE)** ## Pipeline success and duration charts > [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/38318) to CI/CD Analytics in GitLab 12.8. -CI/CD Analytics shows the history of your pipeline successes and failures, as well as how long each pipeline +CI/CD analytics shows the history of your pipeline successes and failures, as well as how long each pipeline ran. View successful pipelines: @@ -39,21 +39,14 @@ To view CI/CD analytics: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.7. > - [Added support](https://gitlab.com/gitlab-org/gitlab/-/issues/291746) for lead time for changes in GitLab 13.10. -Customer experience is a key metric. Users want to measure platform stability and other -post-deployment performance KPIs, and set targets for customer behavior, experience, and financial -impact. Tracking and measuring these indicators solves an important pain point. Similarly, creating -views that manage products, not projects or repositories, provides users with a more relevant data set. -Since GitLab is a tool for the entire DevOps life-cycle, information from different workflows is -integrated and can be used to measure the success of the teams. - The DevOps Research and Assessment ([DORA](https://cloud.google.com/blog/products/devops-sre/the-2019-accelerate-state-of-devops-elite-performance-productivity-and-scaling)) -team developed four key metrics that the industry has widely adopted. You can use these metrics as -performance indicators for software development teams: +team developed several key metrics that you can use as performance indicators for software development +teams: - Deployment frequency: How often an organization successfully releases to production. - Lead time for changes: The amount of time it takes for code to reach production. - Change failure rate: The percentage of deployments that cause a failure in production. -- Time to restore service: How long it takes an organization to recover from a failure in +- Time to restore service: How long it takes for an organization to recover from a failure in production. ### Supported metrics in GitLab @@ -62,39 +55,48 @@ The following table shows the supported metrics, at which level they are support | Metric | Level | API version | Chart (UI) version | Comments | |---------------------------|---------------------|--------------------------------------|---------------------------------------|-----------| -| `deployment_frequency` | Project-level | [13.7+](../../api/dora/metrics.md) | [13.8+](#deployment-frequency-charts) | The [old API endpoint](../../api/dora4_project_analytics.md) was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/323713) in 13.10. | -| `deployment_frequency` | Group-level | [13.10+](../../api/dora/metrics.md) | [13.12+](#deployment-frequency-charts) | | -| `lead_time_for_changes` | Project-level | [13.10+](../../api/dora/metrics.md) | [13.11+](#lead-time-charts) | Unit in seconds. Aggregation method is median. | -| `lead_time_for_changes` | Group-level | [13.10+](../../api/dora/metrics.md) | [14.0+](#lead-time-charts) | Unit in seconds. Aggregation method is median. | +| `deployment_frequency` | Project-level | [13.7+](../../api/dora/metrics.md) | [13.8+](#view-deployment-frequency-chart) | The [old API endpoint](../../api/dora4_project_analytics.md) was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/323713) in 13.10. | +| `deployment_frequency` | Group-level | [13.10+](../../api/dora/metrics.md) | [13.12+](#view-deployment-frequency-chart) | | +| `lead_time_for_changes` | Project-level | [13.10+](../../api/dora/metrics.md) | [13.11+](#view-lead-time-for-changes-chart) | Unit in seconds. Aggregation method is median. | +| `lead_time_for_changes` | Group-level | [13.10+](../../api/dora/metrics.md) | [14.0+](#view-lead-time-for-changes-chart) | Unit in seconds. Aggregation method is median. | | `change_failure_rate` | Project/Group-level | To be supported | To be supported | | | `time_to_restore_service` | Project/Group-level | To be supported | To be supported | | -### Deployment frequency charts +## View deployment frequency chart **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.8. -The **Analytics > CI/CD Analytics** page shows information about the deployment +The deployment frequency charts show information about the deployment frequency to the `production` environment. The environment must be part of the [production deployment tier](../../ci/environments/index.md#deployment-tier-of-environments) for its deployment information to appear on the graphs. - +The deployment frequency chart is available for groups and projects. + +To view the deployment frequency chart: -These charts are available for both groups and projects. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > CI/CD Analytics**. +1. Select the **Deployment frequency** tab. -### Lead time charts + + +## View lead time for changes chart **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250329) in GitLab 13.11. -The charts in the **Lead Time** tab show information about how long it takes -merge requests to be deployed to a production environment. +The lead time for changes chart shows information about how long it takes for +merge requests to be deployed to a production environment. This chart is available for groups and projects. - +- Small lead times indicate fast, efficient deployment + processes. +- For time periods in which no merge requests were deployed, the charts render a + red, dashed line. -Smaller values are better. Small lead times indicate fast, efficient deployment -processes. +To view the lead time for changes chart: -For time periods in which no merge requests were deployed, the charts render a -red, dashed line. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > CI/CD Analytics**. +1. Select the **Lead time** tab. -These charts are available for both groups and projects. + diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index 18a6ca20bc7..dc02512702a 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -40,7 +40,7 @@ To view Code Review Analytics: ## Use cases -This feature is designed for [development team leaders](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#delaney-development-team-lead) +This feature is designed for [development team leaders](https://about.gitlab.com/handbook/product/personas/#delaney-development-team-lead) and others who want to understand broad code review dynamics, and identify patterns to explain them. You can use Code Review Analytics to: diff --git a/doc/user/analytics/img/mr_throughput_chart_v13_3.png b/doc/user/analytics/img/mr_throughput_chart_v13_3.png Binary files differdeleted file mode 100644 index 100c9a8557c..00000000000 --- a/doc/user/analytics/img/mr_throughput_chart_v13_3.png +++ /dev/null diff --git a/doc/user/analytics/img/project_vsa_filter_v14_3.png b/doc/user/analytics/img/project_vsa_filter_v14_3.png Binary files differdeleted file mode 100644 index d3fcad31909..00000000000 --- a/doc/user/analytics/img/project_vsa_filter_v14_3.png +++ /dev/null diff --git a/doc/user/analytics/img/project_vsa_stage_table_v14_4.png b/doc/user/analytics/img/project_vsa_stage_table_v14_4.png Binary files differdeleted file mode 100644 index e65296062f6..00000000000 --- a/doc/user/analytics/img/project_vsa_stage_table_v14_4.png +++ /dev/null diff --git a/doc/user/analytics/merge_request_analytics.md b/doc/user/analytics/merge_request_analytics.md index f9ca06c0ef9..06774c3f16a 100644 --- a/doc/user/analytics/merge_request_analytics.md +++ b/doc/user/analytics/merge_request_analytics.md @@ -40,7 +40,7 @@ To view the number of merge requests merged per month: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Analytics > Merge request**. -1. Optional. Filter results: +1. Optional. Filter results: 1. Select the filter bar. 1. Select a parameter. 1. Select a value or enter text to refine the results. diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index 6bad374c371..92c4d447ed9 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -10,215 +10,197 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [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. -Value stream analytics measures the time spent to go from an -[idea to production](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) -(also known as cycle time) for each of your projects or groups. Value stream analytics displays the median time -spent in each stage defined in the process. +Value stream analytics provides metrics about each stage of your software development process. -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. +Use value stream analytics to identify: -For information about how to contribute to the development of value stream analytics, see our [contributor documentation](../../development/value_stream_analytics.md). +- The amount of time it takes to go from an idea to production. +- The velocity of a given project. +- Bottlenecks in the development process. +- Factors that cause your software development lifecycle to slow down. -To access value stream analytics for a project: +Value stream analytics is also available for [groups](../group/value_stream_analytics). -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > Value stream**. - -NOTE: -[Value stream analytics for groups](../group/value_stream_analytics) is also available. - -## Default stages +## View 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. +> - Filtering [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326701) in GitLab 14.3 +> - Sorting [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335974) in GitLab 14.4. -- **Issue** (Tracker) - - Time to schedule an issue (by milestone or by adding it to an issue board) -- **Plan** (Board) - - Time to first commit -- **Code** (IDE) - - Time to create a merge request -- **Test** (CI) - - Time it takes GitLab CI/CD to test your code -- **Review** (Merge request) - - Time spent on code review -- **Staging** (Continuous Deployment) - - Time between merging and deploying to production +To view value stream analytics for your project: -## Filter value stream analytics data +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Value stream**. +1. To view metrics for each stage, above the **Filter results** text box, select a stage. +1. Optional. Filter the results: + 1. Select the **Filter results** text box. + 1. Select a parameter. + 1. Select a value or enter text to refine the results. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. +1. Optional. Sort results by ascending or descending: + - To sort by most recent or oldest workflow item, select the **Merge requests** or **Issues** + header. The header name differs based on the stage you select. + - To sort by most or least amount of time spent in each stage, select the **Time** header. + +The table shows a list of related workflow items for the selected stage. Based on the stage you choose, this can be: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326701) in GitLab 14.3 +- CI/CD jobs +- Issues +- Merge requests +- Pipelines -You can filter analytics based on the following parameters: +A badge next to the workflow items table header shows the number of workflow items that completed the selected stage. -- Milestones (Group level) -- Labels (Group level) -- Author -- Assignees +## View time spent in each development stage -To filter results: +Value stream analytics shows the median time spent by issues or merge requests in each development stage. -1. Select the **Filter results** text box. -1. Select a parameter. -1. Select a value. To find a value in the list, enter the value name. +To view the median time spent in each stage: - +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Value stream**. +1. Optional. Filter the results: + 1. Select the **Filter results** text box. + 1. Select a parameter. + 1. Select a value or enter text to refine the results. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. +1. To view the median time for each stage, above the **Filter results** text box, point to a stage. -### Date ranges +## View the lead time and cycle time for issues -To filter analytics results based on a date range, -select different **From** and **To** days -from the date picker (default: last 30 days). +Value stream analytics shows the lead time and cycle time for issues in your project: -### Stage table +- Lead time: Median time from when the issue was created to when it was closed. +- Cycle time: Median time from first commit to issue closed. Commits are associated with issues when users [cross-link them in the commit message](../project/issues/crosslinking_issues.md#from-commit-messages). -> Sorting the stage table [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335974) in GitLab 14.4. +To view the lead time and cycle time for issues: - +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Value stream**. +1. Optional. Filter the results: + 1. Select the **Filter results** text box. + 1. Select a parameter. + 1. Select a value or enter text to refine the results. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. -The stage table shows a list of related workflow items for the selected stage. This can include: +The **Lead Time** and **Cycle Time** metrics display below the **Filter results** text box. -- CI/CD jobs -- Issues -- Merge requests -- Pipelines +## View lead time for changes for merge requests **(ULTIMATE)** -A little badge next to the workflow items table header shows the number of workflow items that -completed the selected stage. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340150) in GitLab 14.5. -The stage table also includes the **Time** column, which shows how long it takes each item to pass -through the selected value stream stage. +Lead time for changes is the median duration between when a merge request is merged and when it's deployed to production. -To sort the stage table by a table column, select the table header. -You can sort in ascending or descending order. To find items that spent the most time in a stage, -potentially causing bottlenecks in your value stream, sort the table by the **Time** column. -From there, select individual items to drill in and investigate how delays are happening. -To see which items most recently exited the stage, sort by the work item column on the left. +To view the lead time for changes for merge requests in your project: -The table displays 20 items per page. If there are more than 20 items, you can use the -**Prev** and **Next** buttons to navigate through the pages. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Value stream**. +1. Optional. Filter the results: + 1. Select the **Filter results** text box. + 1. Select a parameter. + 1. Select a value or enter text to refine the results. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. -## How Time metrics are measured +The **Lead Time for Changes** metrics display below the **Filter results** text box. -The **Time** metrics near the top of the page are measured as follows: +## View number of successful deployments **(PREMIUM)** -- **Lead time**: Median time from issue created to issue closed. -- **Cycle time**: Median time from first commit to issue closed. (You can associate a commit with an issue by [crosslinking in the commit message](../project/issues/crosslinking_issues.md#from-commit-messages).) -- **Lead Time for Changes**: median duration between merge request merge and deployment to a production environment for all MRs deployed in the given time period. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340150) in GitLab 14.5 (Ultimate only). +To view deployment metrics, you must have a +[production environment configured](../../ci/environments/index.md#deployment-tier-of-environments). -## Deployment metrics (**PREMIUM**) +Value stream analytics shows the following deployment metrics for your project: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) in GitLab 11.3. +- Deploys: The number of successful deployments in the date range. +- Deployment Frequency: The average number of successful deployments per day in the date range. -Value stream analytics exposes two deployment related metrics near the top of the page: +To view deployment metrics for your project: -- **Deploys:** The number of successful deployments in the date range. -- **Deployment Frequency:** The average number of successful deployments. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Value stream**. +1. Optional. Filter the results: + 1. Select the **Filter results** text box. + 1. Select a parameter. + 1. Select a value or enter text to refine the results. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. -The deployment metrics calculation uses the same method as the -[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). +The **Deploys** and **Deployment Frequency** metrics display below the **Filter results** text box. -## How the stages are measured +Deployment metrics are calculated based on data from the +[DORA API](../../api/dora/metrics.md#devops-research-and-assessment-dora-key-metrics-api). -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. +NOTE: +In GitLab 13.9 and later, metrics are calculated based on when the deployment was finished. +In GitLab 13.8 and earlier, metrics are calculated based on when the deployment was created. -| Stage | Description | -|---------|---------------| -| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whichever comes first. The label is tracked only if it already includes an [issue board list](../project/issue_board.md) created for it. | -| Plan | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. That first branch commit triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch must include the related issue number (such as `#42`). If the issue number is *not* included in a commit, that data is not included in the measurement time of the stage. | -| Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR). The process is tracked with the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) in the description of the merge request. For example, if the issue is closed with `Closes #xxx`, it's assumed that `xxx` is issue number for the merge request). If there is no closing pattern, the start time is set to the create time of the first commit. | -| Test | Essentially the start to finish time for all pipelines. Measures the median time to run the entire pipeline for that project. Related to the time required by GitLab CI/CD to run every job for the commits pushed to that merge request, as defined in the previous stage. | -| Review | Measures the median time taken to review merge requests with a closing issue pattern, from creation to merge. | -| Staging | Measures the median time between merging the merge request (with a closing issue pattern) to the first deployment to a [production environment](#how-the-production-environment-is-identified). Data not collected without a production environment. | +## Access permissions for value stream analytics -How this works: +Access permissions for value stream analytics depend on the project type. -1. Issues and merge requests are grouped in pairs, where the merge request has the - [closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) - for the corresponding issue. Issue and merge request pairs without closing patterns are - not included. -1. Issue and merge request pairs are filtered by the last XX days, specified through the UI - (default is `90` days). Pairs outside the filtered range are not included. -1. For the remaining pairs, review information needed for stages, including - issue creation date and merge request merge time. +| Project type | Permissions | +|--------------|----------------------------------------| +| Public | Anyone can access. | +| Internal | Any authenticated user can access. | +| Private | Any member Guest and above can access. | -In short, the value stream analytics dashboard tracks data related to [GitLab flow](../../topics/gitlab_flow.md). It does not include data for: +## How value stream analytics measures each stage -- Merge requests that do not close an issue. -- Issues that do not include labels present in the issue board. -- Issues without a milestone. -- Staging stages, in projects without a [production environment](#how-the-production-environment-is-identified). +Value stream analytics uses start and end events to measure the time that an issue or merge request +spends in each stage. -## How the production environment is identified +For example, a stage might start when a user adds a label to an issue, and ends when they add another label. +Items aren't included in the stage time calculation if they have not reached the end event. -Value stream analytics identifies production environments based on the -[deployment tier of environments](../../ci/environments/index.md#deployment-tier-of-environments). +| Stage | Measurement method | +|---------|----------------------| +| Issue | The median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone. The label is tracked only if it already includes an [issue board list](../project/issue_board.md) that has been created for the label. | +| Plan | The median time between the action you took for the previous stage, and when you push the first commit to the branch. The first branch commit triggers the transition from **Plan** to **Code**, and at least one of the commits in the branch must include the related issue number (such as `#42`). If the issue number is not included in a commit, that data is not included in the measurement time of the stage. | +| Code | The median time between pushing a first commit (previous stage) and creating a merge request. The process is tracked with the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) in the description of the merge request. For example, if the issue is closed with `Closes #xxx`, `xxx` is the issue number for the merge request. If there is no closing pattern, the start time is set to the create time of the first commit. | +| Test | The time from start to finish for all pipelines. Measures the median time to run the entire pipeline for that project. Related to the time required by GitLab CI/CD to run every job for the commits pushed to that merge request, as defined in the previous stage. | +| Review | The median time taken to review merge requests with a closing issue pattern, from creation to merge. | +| Staging | The median time between merging the merge request (with a closing issue pattern) to the first deployment to a [production environment](../../ci/environments/index.md#deployment-tier-of-environments). Data is not collected without a production environment. | ## Example workflow -Here's a fictional workflow of a single cycle that happens in a -single day, passing through all seven stages. If a stage doesn't have -a start and a stop mark, it isn't measured and hence isn't calculated in the median -time. It's assumed that milestones are created, and CI for testing and setting -environments is configured. - -1. Issue is created at 09:00 (start of **Issue** stage). -1. Issue is added to a milestone at 11:00 (stop of **Issue** stage and start of - **Plan** stage). -1. Start working on the issue, create a branch locally, and make one commit at - 12:00. -1. Make a second commit to the branch that mentions the issue number at 12:30 - (stop of **Plan** stage and start of **Code** stage). -1. Push branch, and create a merge request that contains the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically) - in its description at 14:00 (stop of **Code** stage and start of **Test** and - **Review** stages). -1. The CI starts running your scripts defined in [`.gitlab-ci.yml`](../../ci/yaml/index.md) and - takes 5 minutes (stop of **Test** stage). -1. Review merge request, ensure that everything is okay, and then merge the merge - request at 19:00 (stop of **Review** stage and start of **Staging** stage). -1. The merge request is merged, and a deployment to the `production` - environment starts and finishes at 19:30 (stop of **Staging** stage). - -From the previous example we see the time used for each stage: - -- **Issue**: 2 hrs (09:00 to 11:00) -- **Plan**: 1 hr (11:00 to 12:00) -- **Code**: 2 hrs (12:00 to 14:00) +This example shows a workflow through all seven stages in one day. In this +example, milestones have been created and CI for testing and setting environments is configured. + +- 09:00: Create issue. **Issue** stage starts. +- 11:00: Add issue to a milestone, start work on the issue, and create a branch locally. +**Issue** stage stops and **Plan** stage starts. +- 12:00: Make the first commit. +- 12:30: Make the second commit to the branch that mentions the issue number. **Plan** stage stops and **Code** stage starts. +- 14:00: Push branch and create a merge request that contains the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically). **Code** stage stops and **Test** and **Review** stages start. +- The CI takes 5 minutes to run scripts defined in [`.gitlab-ci.yml`](../../ci/yaml/index.md). +**Test** stage stops. +- Review merge request. +- 19:00: Merge the merge request. **Review** stage stops and **Staging** stage starts. +- 19:30: Deployment to the `production` environment starts and finishes. **Staging** stops. + +Value stream analytics records the following times for each stage: + +- **Issue**: 09:00 to 11:00: 2 hrs +- **Plan**: 11:00 to 12:00: 1 hr +- **Code**: 12:00 to 14:00: 2 hrs - **Test**: 5 minutes -- **Review**: 5 hrs (14:00 to 19:00) -- **Staging**: 30 minutes (19:00 to 19:30) - -More information: - -- Although the previous example specifies the issue number in a later commit, the process - still collects analytics data for the issue. -- The time required in the **Test** stage isn't included in the overall time of - 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 - for these issues. - -## Permissions - -The permissions for the value stream analytics for projects dashboard include: - -| Project type | Permissions | -|--------------|---------------------------------------| -| Public | Anyone can access | -| Internal | Any authenticated user can access | -| Private | Any member Guest and above can access | - -You can [read more about permissions](../../user/permissions.md) in general. - -## More 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/). +- **Review**: 14:00 to 19:00: 5 hrs +- **Staging**: 19:00 to 19:30: 30 minutes + +There are some additional considerations for this example: + +- Although this example specifies the issue number in a later commit, the process +still collects analytics data for the issue. +- The time required in the **Test** stage is included in the **Review** process, +as every merge request should be tested. +- This example illustrates only one cycle of multiple stages. The value +stream analytics dashboard shows the calculated median elapsed time for these issues. +- Value stream analytics identifies production environments based on the +[deployment tier of environments](../../ci/environments/index.md#deployment-tier-of-environments). diff --git a/doc/user/application_security/api_fuzzing/create_har_files.md b/doc/user/application_security/api_fuzzing/create_har_files.md index db0b2a32bcf..1ba19359fde 100644 --- a/doc/user/application_security/api_fuzzing/create_har_files.md +++ b/doc/user/application_security/api_fuzzing/create_har_files.md @@ -1,7 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 4eb721f8832..5413c28912a 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -87,9 +87,6 @@ In GitLab 14.0 and later, API fuzzing configuration files must be in your reposi > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299234) in GitLab 13.10. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - The API fuzzing configuration form helps you create or modify your project's API fuzzing configuration. The form lets you choose values for the most common API fuzzing options and builds a YAML snippet that you can paste in your GitLab CI/CD configuration. @@ -804,7 +801,7 @@ variables: If the value must be generated or regenerated on expiration, you can provide a program or script for the API fuzzer to execute on a specified interval. The provided script runs in an Alpine Linux -container that has Python 3 and Bash installed. +container that has Python 3 and Bash installed. You have to set the environment variable `FUZZAPI_OVERRIDES_CMD` to the program or script you would like to execute. The provided command creates the overrides JSON file as defined previously. @@ -813,7 +810,7 @@ You might want to install other scripting runtimes like NodeJS or Ruby, or maybe your overrides command. In this case, we recommend setting the `FUZZAPI_PRE_SCRIPT` to the file path of a script which provides those prerequisites. The script provided by `FUZZAPI_PRE_SCRIPT` is executed once, before the analyzer starts. -See the [Alpine Linux package management](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management) +See the [Alpine Linux package management](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management) page for information about installing Alpine Linux packages. You must provide three CI/CD variables, each set for correct operation: diff --git a/doc/user/application_security/cluster_image_scanning/index.md b/doc/user/application_security/cluster_image_scanning/index.md index 0db9af7a0d3..293645b8de6 100644 --- a/doc/user/application_security/cluster_image_scanning/index.md +++ b/doc/user/application_security/cluster_image_scanning/index.md @@ -29,7 +29,7 @@ To integrate GitLab with security scanners other than those listed here, see You can use cluster image scanning through the following methods: - [The cluster image scanning analyzer](#use-the-cluster-image-scanning-analyzer) -- [The GitLab Agent](#cluster-image-scanning-with-the-gitlab-agent) +- [The GitLab agent](#cluster-image-scanning-with-the-gitlab-agent) ## Use the cluster image scanning analyzer @@ -46,7 +46,7 @@ To enable cluster image scanning in your pipeline, you need the following: - [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. + executor on Linux/amd64. - Docker `18.09.03` or later installed on the same computer as the runner. If you're using the shared runners on GitLab.com, then this is already the case. - [Starboard Operator](https://aquasecurity.github.io/starboard/v0.10.3/operator/installation/kubectl/) @@ -277,22 +277,22 @@ Here's an example cluster image scanning report: } ``` -## Cluster image scanning with the GitLab Agent +## Cluster image scanning with the GitLab agent -You can use the [GitLab Agent](../../clusters/agent/index.md) to +You can use the [GitLab agent](../../clusters/agent/index.md) to scan images from within your Kubernetes cluster and record the vulnerabilities in GitLab. ### Prerequisites - [Starboard Operator](https://aquasecurity.github.io/starboard/v0.10.3/operator/installation/kubectl/) installed and configured in your cluster. -- [GitLab Agent](../../clusters/agent/install/index.md) +- [GitLab agent](../../clusters/agent/install/index.md) set up in GitLab, installed in your cluster, and configured using a configuration repository. ### Configuration -The Agent runs the cluster image scanning once the `cluster_image_scanning` -directive is added to your [Agent's configuration repository](../../clusters/agent/repository.md#scan-your-container-images-for-vulnerabilities). +The agent runs the cluster image scanning once the `cluster_image_scanning` +directive is added to your [agent's configuration repository](../../clusters/agent/vulnerabilities.md). ## Security Dashboard @@ -302,7 +302,7 @@ the security vulnerabilities in your groups, projects, and pipelines. ## Interacting with the vulnerabilities After you find a vulnerability, you can address it in the [vulnerability report](../vulnerabilities/index.md) -or the [GitLab Agent's](../../clusters/agent/install/index.md#view-vulnerabilities-in-cluster-images) +or the [GitLab agent's](../../clusters/agent/vulnerabilities.md) details section. ## Troubleshooting diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 430f8e1a2a2..61a2121b9c6 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -49,7 +49,9 @@ You can configure the following security controls: - Select **Configure with a merge request** to create a merge request with the changes required to enable Dependency Scanning. For more details, see [Enable Dependency Scanning via an automatic merge request](../dependency_scanning/index.md#enable-dependency-scanning-via-an-automatic-merge-request). - [Container Scanning](../container_scanning/index.md) - - Can be configured with `.gitlab-ci.yml`. For more details, read [Container Scanning](../../../user/application_security/container_scanning/index.md#configuration). + - Select **Configure with a merge request** to create a merge request with the changes required to + enable Container Scanning. For more details, see + [Enable Container Scanning through an automatic merge request](../container_scanning/index.md#enable-container-scanning-through-an-automatic-merge-request). - [Cluster Image Scanning](../cluster_image_scanning/index.md) - Can be configured with `.gitlab-ci.yml`. For more details, read [Cluster Image Scanning](../../../user/application_security/cluster_image_scanning/#configuration). - [Secret Detection](../secret_detection/index.md) @@ -66,3 +68,6 @@ You can configure the following security controls: - [License Compliance](../../../user/compliance/license_compliance/index.md) - Can be configured with `.gitlab-ci.yml`. For more details, read [License Compliance](../../../user/compliance/license_compliance/index.md#enable-license-compliance). + +- [Security Training](../../../user/application_security/vulnerabilities/index.md#enable-security-training-for-vulnerabilities) + - Enable **Security training** for the current project. For more details, read [security training](../../../user/application_security/vulnerabilities/index.md#enable-security-training-for-vulnerabilities). diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 08a8c46cc72..f2d6cef669d 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -50,7 +50,7 @@ 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. + or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor on Linux/amd64. - Docker `18.09.03` or higher installed on the same computer as the runner. If you're using the shared runners on GitLab.com, then this is already the case. - An image matching the [supported distributions](#supported-distributions). @@ -145,7 +145,7 @@ For example, to scan an image from AWS Elastic Container Registry: ```yaml container_scanning: before_script: - - curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" --output "awscliv2.zip" + - ruby -r open-uri -e "IO.copy_stream(URI.open('https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip'), 'awscliv2.zip')" - unzip awscliv2.zip - ./aws/install - aws --version @@ -253,6 +253,24 @@ images. To configure the images, set the `CS_ANALYZER_IMAGE` variable to the sta | Grype | `registry.gitlab.com/security-products/container-scanning/grype:4-ubi` | | Trivy | `registry.gitlab.com/security-products/container-scanning/trivy:4-ubi` | +### Enable Container Scanning through an automatic merge request + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6334) in GitLab 14.9. + +To enable Container Scanning in a project, create a merge request from the Security Configuration +page: + +1. In the project where you want to enable Container Scanning, go to + **Security & Compliance > Configuration**. +1. In the **Container Scanning** row, select **Configure with a merge request**. + +This automatically creates a merge request with the changes necessary to enable Container Scanning. +To complete the configuration, review and merge this merge request. + +The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal +configuration file. If you have a complex GitLab configuration file, it may not be parsed +successfully and an error may occur. + ### Overriding the container scanning template If you want to override the job definition (for example, to change properties like `variables`), you diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 290d4a06dcc..14e98766f0f 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -121,7 +121,7 @@ Use the following variables to configure coverage-guided fuzz testing in your CI | `COVFUZZ_URL_PREFIX` | Path to the `gitlab-cov-fuzz` repository cloned for use with an offline environment. You should only change this value when using an offline environment. Default: `https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz/-/raw`. | | `COVFUZZ_USE_REGISTRY` | Set to `true` to have the corpus stored in the GitLab corpus registry. The variables `COVFUZZ_CORPUS_NAME` and `COVFUZZ_GITLAB_TOKEN` are required if this variable is set to `true`. Default: `false`. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5017) in GitLab 14.8. | | `COVFUZZ_CORPUS_NAME` | Name of the corpus to be used in the job. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5017) in GitLab 14.8. | -| `COVFUZZ_GITLAB_TOKEN` | Environment variable configured with [Personal Access Token](../../../user/profile/personal_access_tokens.md#create-a-personal-access-token) with API read/write access. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5017) in GitLab 14.8. | +| `COVFUZZ_GITLAB_TOKEN` | Environment variable configured with [Personal Access Token](../../../user/profile/personal_access_tokens.md#create-a-personal-access-token) or [Project Access Token](../../../user/project/settings/project_access_tokens.md#create-a-project-access-token) with API read/write access. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5017) in GitLab 14.8. | #### Seed corpus @@ -144,12 +144,8 @@ You can download the JSON report file from the CI/CD pipelines page. For more in ## Corpus registry -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5017) in GitLab 14.8. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, ask an -administrator to [disable the feature flags](../../../administration/feature_flags.md) named -`corpus_management` and `corpus_management_ui`. On GitLab.com, this feature is available. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5017) in GitLab 14.8. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/347187) in GitLab 14.9. [Feature flags `corpus_management` and `corpus_management_ui`](https://gitlab.com/gitlab-org/gitlab/-/issues/328418) removed. The corpus registry is a library of corpuses. Corpuses in a project's registry are available to all jobs in that project. A project-wide registry is a more efficient way to manage corpuses than diff --git a/doc/user/application_security/dast/checks/200.1.md b/doc/user/application_security/dast/checks/200.1.md index 98a482b4a0f..9795ad11b0b 100644 --- a/doc/user/application_security/dast/checks/200.1.md +++ b/doc/user/application_security/dast/checks/200.1.md @@ -8,13 +8,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Description -A private RFC 1918 was identified in the target application. Public facing websites should not be issuing -requests to private IP Addresses. Attackers attempting to execute subsequent attacks, such as Server-Side +A private RFC 1918 was identified in the target application. Public facing websites should not be issuing +requests to private IP Addresses. Attackers attempting to execute subsequent attacks, such as Server-Side Request Forgery (SSRF), may be able to use this information to identify additional internal targets. ## Remediation -Identify the resource that is incorrectly specifying an internal IP address and replace it with it's public +Identify the resource that is incorrectly specifying an internal IP address and replace it with it's public facing version, or remove the reference from the target application. ## Details diff --git a/doc/user/application_security/dast/checks/548.1.md b/doc/user/application_security/dast/checks/548.1.md index 94f747739c5..d6371c5491d 100644 --- a/doc/user/application_security/dast/checks/548.1.md +++ b/doc/user/application_security/dast/checks/548.1.md @@ -8,8 +8,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Description -The target web server is configured to list the contents of directories that do not contain an index file -such as `index.html`. This could lead to accidental exposure of sensitive information, or give an attacker +The target web server is configured to list the contents of directories that do not contain an index file +such as `index.html`. This could lead to accidental exposure of sensitive information, or give an attacker details on how filenames and directories are structured and stored. ## Remediation @@ -17,11 +17,11 @@ details on how filenames and directories are structured and stored. Directory indexing should be disabled. Apache: -For Apache based web sites, ensure all `<Directory>` definitions have `Options -Indexes` configured in the +For Apache based web sites, ensure all `<Directory>` definitions have `Options -Indexes` configured in the `apache2.conf` or `httpd.conf` configuration file. NGINX: -For NGINX based websites, ensure all `location` definitions have the `autoindex off` directive set in the +For NGINX based websites, ensure all `location` definitions have the `autoindex off` directive set in the `nginx.conf` file. IIS: diff --git a/doc/user/application_security/dast/checks/598.1.md b/doc/user/application_security/dast/checks/598.1.md new file mode 100644 index 00000000000..817e20ec413 --- /dev/null +++ b/doc/user/application_security/dast/checks/598.1.md @@ -0,0 +1,31 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Use of GET request method with sensitive query strings (session ID) + +## Description + +A session ID was identified in the request URL as well as a cookie value. Session +IDs should not be sent in GET requests as they maybe captured by proxy systems, stored in +browser history, or stored in log files. If an attacker were to get access to the session +ID they would potentially be able to gain access to the target account. + +## Remediation + +As request headers are rarely logged or captured by third party systems, ensure session ID +values are only sent in cookies (assigned via `Set-Cookie` response headers) and never sent +in the request URL. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 598.1 | true | 598 | Passive | Medium | + +## Links + +- [OWASP](https://owasp.org/www-community/vulnerabilities/Information_exposure_through_query_strings_in_url) +- [CWE](https://cwe.mitre.org/data/definitions/598.html) diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md index 97224554723..435bc28c4aa 100644 --- a/doc/user/application_security/dast/checks/index.md +++ b/doc/user/application_security/dast/checks/index.md @@ -19,5 +19,6 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | [16.6](16.6.md) | AspNetMvc header exposes version information | Low | Passive | | [200.1](200.1.md) | Exposure of sensitive information to an unauthorized actor (private IP address) | Low | Passive | | [548.1](548.1.md) | Exposure of information through directory listing | Low | Passive | +| [598.1](598.1.md) | Use of GET request method with sensitive query strings (session ID) | Medium | Passive | | [614.1](614.1.md) | Sensitive cookie without Secure attribute | Low | Passive | | [693.1](693.1.md) | Missing X-Content-Type-Options: nosniff | Low | Passive | diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 0865cc10691..fd6c39ffbf1 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -51,7 +51,7 @@ results. On failure, the analyzer outputs an ## Prerequisites - [GitLab Runner](../../../ci/runners/index.md) available, with the -[`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). +[`docker` executor](https://docs.gitlab.com/runner/executors/docker.html) on Linux/amd64. - Target application deployed. For more details, read [Deployment options](#deployment-options). - DAST runs in the `dast` stage, which must be added manually to your `.gitlab-ci.yml`. @@ -105,7 +105,7 @@ services: # use services to link your app container to the dast job variables: DAST_FULL_SCAN_ENABLED: "true" # do a full scan - DAST_ZAP_USE_AJAX_SPIDER: "true" # use the ajax spider + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ``` Most applications depend on multiple services such as databases or caching services. By default, services defined in the services fields cannot communicate @@ -314,6 +314,7 @@ include: variables: DAST_FULL_SCAN_ENABLED: "true" + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ``` If your DAST job exceeds the job timeout and you need to reduce the scan duration, we shared some @@ -455,6 +456,7 @@ include: variables: GIT_STRATEGY: fetch DAST_PATHS_FILE: url_file.txt # url_file.txt lives in the root directory of the project + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ``` ##### Use `DAST_PATHS` CI/CD variable @@ -470,6 +472,7 @@ include: variables: DAST_PATHS: "/page1.html,/category1/page1.html,/page3.html" + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ``` When using `DAST_PATHS` and `DAST_PATHS_FILE`, note the following: @@ -547,6 +550,7 @@ include: variables: DAST_WEBSITE: https://example.com DAST_SPIDER_MINS: 120 + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ``` Because the template is [evaluated before](../../../ci/yaml/index.md#include) the pipeline @@ -628,7 +632,7 @@ These CI/CD variables are specific to DAST. They can be used to customize the be | `DAST_AUTH_VERIFICATION_SELECTOR` <sup>2</sup> | selector | Verifies successful authentication by checking for presence of a selector once the login form has been submitted. Example: `css:.user-photo`. | | `DAST_AUTH_VERIFICATION_URL` <sup>1,2</sup> | URL | A URL only accessible to logged in users that DAST can use to confirm successful authentication. If provided, DAST exits if it cannot access the URL. Example: `"http://example.com/loggedin_page"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207335) in GitLab 13.8. | | `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false`. | -| `DAST_BROWSER_PATH_TO_LOGIN_FORM` <sup>1,2</sup> | selector | Comma-separated list of selectors that will be clicked on prior to attempting to enter `DAST_USERNAME` and `DAST_PASSWORD` into the login form. Example: `"css:.navigation-menu,css:.login-menu-item"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326633) in GitLab 14.1. | +| `DAST_BROWSER_PATH_TO_LOGIN_FORM` <sup>1,2</sup> | selector | Comma-separated list of selectors that are clicked on prior to attempting to enter `DAST_USERNAME` and `DAST_PASSWORD` into the login form. Example: `"css:.navigation-menu,css:.login-menu-item"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326633) in GitLab 14.1. | | `DAST_DEBUG` <sup>1</sup> | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | | `DAST_EXCLUDE_URLS` <sup>1,2</sup> | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. Example, `http://example.com/sign-out`. | @@ -737,7 +741,7 @@ Only run an authenticated scan against a test server. ### Log in using automatic detection of the login form -By providing a `DAST_USERNAME`, `DAST_PASSWORD`, and `DAST_AUTH_URL`, DAST will attempt to authenticate to the +By providing a `DAST_USERNAME`, `DAST_PASSWORD`, and `DAST_AUTH_URL`, DAST attempts to authenticate to the target application by locating the login form based on a determination about whether or not the form contains username or password fields. Automatic detection is "best-effort", and depending on the application being scanned may provide either a resilient login experience or one that fails to authenticate the user. @@ -753,8 +757,8 @@ Login process: ### Log in using explicit selection of the login form By providing a `DAST_USERNAME_FIELD`, `DAST_PASSWORD_FIELD`, and `DAST_SUBMIT_FIELD`, in addition to the fields required for automatic login, -DAST will attempt to authenticate to the target application by locating the login form based on the selectors provided. -Most applications will benefit from this approach to authentication. +DAST attempts to authenticate to the target application by locating the login form based on the selectors provided. +Most applications benefit from this approach to authentication. Login process: @@ -790,6 +794,7 @@ include: dast: variables: DAST_WEBSITE: "https://example.com" + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ... DAST_AUTH_VERIFICATION_URL: "https://example.com/user/welcome" ``` @@ -808,6 +813,7 @@ include: dast: variables: DAST_WEBSITE: "https://example.com" + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ... DAST_AUTH_VERIFICATION_SELECTOR: "css:.welcome-user" ``` @@ -826,6 +832,7 @@ include: dast: variables: DAST_WEBSITE: "https://example.com" + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ... DAST_AUTH_VERIFICATION_LOGIN_FORM: "true" ``` @@ -847,6 +854,7 @@ include: dast: variables: DAST_WEBSITE: "https://my.site.com" + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ... DAST_AUTH_URL: "https://my.site.com/admin" DAST_BROWSER_PATH_TO_LOGIN_FORM: "css:.navigation-menu,css:.login-menu-item" @@ -875,6 +883,7 @@ An example configuration where the authentication debug report is exported may l dast: variables: DAST_WEBSITE: "https://example.com" + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ... DAST_AUTH_REPORT: "true" artifacts: @@ -885,7 +894,7 @@ dast: ### Selectors Selectors are used by CI/CD variables to specify the location of an element displayed on a page in a browser. -Selectors have the format `type`:`search string`. The crawler will search for the selector using the search string based on the type. +Selectors have the format `type`:`search string`. The crawler searches for the selector using the search string based on the type. | Selector type | Example | Description | | ------------- | ---------------------------------- | ----------- | diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index cc20b49764f..839833d9d98 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -479,8 +479,8 @@ Follow these steps to provide the bearer token with `DAST_API_OVERRIDES_ENV`: `{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}` (substitute your token). You can create CI/CD variables from the GitLab projects page at **Settings > CI/CD**, in the **Variables** section. - Due to the format of `TEST_API_BEARERAUTH` it's not possible to mask the variable. - To mask the token's value, you can create a second variable with the token value's, and define + Due to the format of `TEST_API_BEARERAUTH` it's not possible to mask the variable. + To mask the token's value, you can create a second variable with the token value's, and define `TEST_API_BEARERAUTH` with the value `{"headers":{"Authorization":"Bearer $MASKED_VARIABLE"}}`. 1. In your `.gitlab-ci.yml` file, set `DAST_API_OVERRIDES_ENV` to the variable you just created: @@ -876,7 +876,7 @@ variables: If the value must be generated or regenerated on expiration, you can provide a program or script for the DAST API scanner to execute on a specified interval. The provided command runs in an Alpine Linux -container that has Python 3 and Bash installed. +container that has Python 3 and Bash installed. You have to set the environment variable `DAST_API_OVERRIDES_CMD` to the program or script you would like to execute. The provided command creates the overrides JSON file as defined previously. @@ -885,7 +885,7 @@ You might want to install other scripting runtimes like NodeJS or Ruby, or maybe your overrides command. In this case, we recommend setting the `DAST_API_PRE_SCRIPT` to the file path of a script which provides those prerequisites. The script provided by `DAST_API_PRE_SCRIPT` is executed once, before the analyzer starts. -See the [Alpine Linux package management](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management) +See the [Alpine Linux package management](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management) page for information about installing Alpine Linux packages. You must provide three CI/CD variables, each set for correct operation: diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index baafdcda6e0..78de740c96d 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -15,7 +15,7 @@ details about those dependencies, including their known vulnerabilities. It is a To see the dependency list, go to your project and select **Security & Compliance > Dependency List**. -This information is sometimes referred to as a Software Bill of Materials or SBoM / BOM. +This information is sometimes referred to as a Software Bill of Materials, SBOM, or BOM. The dependency list only shows the results of the last successful pipeline to run on the default branch. This is why we recommend not changing the default behavior of allowing the secure jobs to fail. diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index 551488c0dc0..665d29c4017 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -50,7 +50,7 @@ Any custom change to the official analyzers can be achieved by using a You can switch to a custom Docker registry that provides the official analyzer images under a different prefix. For instance, the following instructs Dependency Scanning to pull `my-docker-registry/gl-images/gemnasium` -instead of `registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium`. +instead of `registry.gitlab.com/security-products/gemnasium`. In `.gitlab-ci.yml` define: ```yaml diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index a169b78a193..a4a7e6703ab 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -69,7 +69,8 @@ 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. -If you're using the shared runners on GitLab.com, this is enabled by default. +If you're using the shared runners on GitLab.com, this is enabled by default. The analyzer images +provided are for the Linux/amd64 architecture. WARNING: If you use your own runners, make sure your installed version of Docker @@ -181,7 +182,7 @@ table.supported-languages ul { </tr> <tr> <td rowspan="2">Java</td> - <td rowspan="2">8, 11, 13, 14, 15, or 16</td> + <td rowspan="2">8, 11, 13, 14, 15, 16, or 17</td> <td><a href="https://gradle.org/">Gradle</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-1">1</a></b></sup></td> <td> <ul> @@ -335,27 +336,61 @@ To support the following package managers, the GitLab analyzers proceed in two s 1. Execute the package manager or a specific task, to export the dependency information. 1. Parse the exported dependency information. -| Package Manager | Preinstalled Versions | Tested Versions | -| ------ | ------ | ------ | -| Bundler | [2.1.4](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit/-/blob/v2.11.3/Dockerfile#L15)<sup><b><a href="#exported-dependency-information-notes-1">1</a></b></sup> | [1.17.3](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/master/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | -| sbt | [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/config/.tool-versions#L4) | [1.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L330), [1.1.4](https://gitlab.com/gitlab-org/security-products/tests/scala-sbt-multiproject/-/blob/main/project/build.properties#L1), [1.1.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L339), [1.2.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L348), [1.3.12](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L357), [1.4.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L366), [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L384) | -| Maven | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L3) | [3.6.3](https://gitlab.com/gitlab-org/security-products/tests/java-maven/-/blob/master/pom.xml#L3) | -| Gradle | [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L5) | [5.6.4](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/master/gradle/wrapper/gradle-wrapper.properties#L3), [6.5](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14/gradle/wrapper/gradle-wrapper.properties#L3), [6.7-rc-1](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-15/gradle/wrapper/gradle-wrapper.properties#L3), [6.9](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14-gradle-6-9/gradle/wrapper/gradle-wrapper.properties#L3), [7.0-rc-2](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-16/gradle/wrapper/gradle-wrapper.properties#L3) | -| setuptools | [50.3.2](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L27) | [57.5.0](https://gitlab.com/gitlab-org/security-products/tests/python-setuptools/-/blob/main/setup.py) | -| pip | [20.2.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L26) | [20.x](https://gitlab.com/gitlab-org/security-products/tests/python-pip/-/blob/master/requirements.txt) | -| Pipenv | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.18.4/requirements.txt#L13) | [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/pipfile-lock-FREEZE/Pipfile.lock#L6)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/master/Pipfile) | +| Package Manager | Pre-installed Versions | Tested Versions | +| ------ | ------ | ------ | +| Bundler | [2.1.4](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit/-/blob/v2.11.3/Dockerfile#L15)<sup><b><a href="#exported-dependency-information-notes-1">1</a></b></sup> | [1.17.3](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/master/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | +| sbt | [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/config/.tool-versions#L4) | [1.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L330), [1.1.4](https://gitlab.com/gitlab-org/security-products/tests/scala-sbt-multiproject/-/blob/main/project/build.properties#L1), [1.1.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L339), [1.2.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L348), [1.3.12](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L357), [1.4.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L366), [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L384) | +| Maven | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L3) | [3.6.3](https://gitlab.com/gitlab-org/security-products/tests/java-maven/-/blob/master/pom.xml#L3) | +| Gradle | [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, [7.3.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.26.0/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup> | [5.6.4](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/master/gradle/wrapper/gradle-wrapper.properties#L3), [6.5](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14/gradle/wrapper/gradle-wrapper.properties#L3), [6.7-rc-1](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-15/gradle/wrapper/gradle-wrapper.properties#L3), [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.27.1/.gitlab-ci.yml#L289-297)<sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup>, [6.9](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14-gradle-6-9/gradle/wrapper/gradle-wrapper.properties#L3), [7.0-rc-2](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-16/gradle/wrapper/gradle-wrapper.properties#L3), [7.3](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14-gradle-7-3/gradle/wrapper/gradle-wrapper.properties#L3), [7.3.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.27.1/.gitlab-ci.yml#L299-317)<sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup> | +| setuptools | [50.3.2](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L27) | [57.5.0](https://gitlab.com/gitlab-org/security-products/tests/python-setuptools/-/blob/main/setup.py) | +| pip | [20.2.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L26) | [20.x](https://gitlab.com/gitlab-org/security-products/tests/python-pip/-/blob/master/requirements.txt) | +| Pipenv | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.18.4/requirements.txt#L13) | [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/pipfile-lock-FREEZE/Pipfile.lock#L6)<sup><b><a href="#exported-dependency-information-notes-4">4</a></b></sup>, [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/master/Pipfile) | <!-- markdownlint-disable MD044 --> <ol> <li> <a id="exported-dependency-information-notes-1"></a> <p> - The installed version of <code>Bundler</code> is only used for the <a href="https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit">bundler-audit</a> analyzer, and is not used for <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">gemnasium</a> + The pre-installed version of <code>Bundler</code> is only used for the <a href="https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit">bundler-audit</a> analyzer, and is not used for <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">gemnasium</a>. </p> </li> <li> <a id="exported-dependency-information-notes-2"></a> <p> + Different versions of Java require different versions of Gradle. The versions of Gradle listed in the above table are pre-installed + in the analyzer image. The version of Gradle used by the analyzer depends on whether your project uses a <code>gradlew</code> + (Gradle wrapper) file or not: + </p> + <ul> + <li> + <p> + If your project <i>does not use</i> a <code>gradlew</code> file, then the analyzer automatically switches to one of the + pre-installed Gradle versions, based on the version of Java specified by the + <a href="#configuring-specific-analyzers-used-by-dependency-scanning"><code>DS_JAVA_VERSION</code></a> variable. + </p> + <p>You can view the + <a href="https://docs.gradle.org/current/userguide/compatibility.html#java">Gradle Java compatibility matrix</a> to see which version + of Gradle is selected for each Java version. Note that we only support switching to one of these pre-installed Gradle versions + for Java versions 13 to 17. + </p> + </li> + <li> + <p> + If your project <i>does use</i> a <code>gradlew</code> file, then the version of Gradle pre-installed in the analyzer image is + ignored, and the version specified in your <code>gradlew</code> file is used instead. + </p> + </li> + </ul> + </li> + <li> + <a id="exported-dependency-information-notes-3"></a> + <p> + These tests confirm that if a <code>gradlew</code> file does not exist, the version of <code>Gradle</code> pre-installed in the analyzer image is used. + </p> + </li> + <li> + <a id="exported-dependency-information-notes-4"></a> + <p> This test confirms that if a <code>Pipfile.lock</code> file is found, it will be used by <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a> to scan the exact package versions listed in this file. </p> </li> @@ -563,7 +598,7 @@ The following variables are used for configuring specific analyzers (used for a | `GEMNASIUM_DB_REF_NAME` | `gemnasium` | `master` | Branch name for remote repository database. `GEMNASIUM_DB_REMOTE_URL` is required. | | `DS_REMEDIATE` | `gemnasium` | `"true"` | Enable automatic remediation of vulnerable dependencies. | | `GEMNASIUM_LIBRARY_SCAN_ENABLED` | `gemnasium` | `"true"` | Enable detecting vulnerabilities in vendored JavaScript libraries. For now, `gemnasium` leverages [`Retire.js`](https://github.com/RetireJS/retire.js) to do this job. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350512) in GitLab 14.8. | -| `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`, `15`, `16`. | +| `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`, `15`, `16`, `17`. | | `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that are passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repositories). | | `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that are passed to `gradle` by the analyzer. | | `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer passes to `sbt`. | @@ -767,13 +802,13 @@ Here's an example dependency scanning report: } ``` -### CycloneDX reports +### CycloneDX Software Bill of Materials > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350509) in GitLab 14.8 in [Beta](../../../policy/alpha-beta-support.md#beta-features). In addition to the [JSON report file](#reports-json-format), the [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) -Dependency Scanning tool outputs a [CycloneDX](https://cyclonedx.org/) report for -each supported lock or build file it detects. These CycloneDX reports are named +Dependency Scanning tool outputs a [CycloneDX](https://cyclonedx.org/) Software Bill of Materials (SBOM) for +each supported lock or build file it detects. These CycloneDX SBOMs are named `cyclonedx-<package-type>-<package-manager>.json`, and are saved in the same directory as the detected lock or build files. @@ -791,7 +826,7 @@ For example, if your project has the following structure: └── go.sum ``` -Then the Gemnasium scanner generates the following CycloneDX reports: +Then the Gemnasium scanner generates the following CycloneDX SBOMs: ```plaintext . @@ -809,23 +844,23 @@ Then the Gemnasium scanner generates the following CycloneDX reports: └── cyclonedx-go-go.json ``` -The CycloneDX reports can be downloaded [the same way as other job artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). +The CycloneDX SBOMs can be downloaded [the same way as other job artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). -### Merging multiple CycloneDX Reports +### Merging multiple CycloneDX SBOMs -You can use a CI/CD job to merge multiple CycloneDX Reports into a single report. +You can use a CI/CD job to merge multiple CycloneDX SBOMs into a single SBOM. For example: ```yaml stages: - test - - merge-cyclonedx-reports + - merge-cyclonedx-sboms include: - template: Security/Dependency-Scanning.gitlab-ci.yml -merge cyclonedx reports: - stage: merge-cyclonedx-reports +merge cyclonedx sboms: + stage: merge-cyclonedx-sboms image: alpine:latest script: - wget https://github.com/CycloneDX/cyclonedx-cli/releases/download/v0.22.0/cyclonedx-linux-musl-x64 -O /usr/local/bin/cyclonedx-cli @@ -838,14 +873,14 @@ merge cyclonedx reports: ``` GitLab uses [CycloneDX Properties](https://cyclonedx.org/use-cases/#properties--name-value-store) -to store implementation-specific details in the metadata of each CycloneDX report, -such as the location of build and lock files. If multiple CycloneDX reports are merged together, +to store implementation-specific details in the metadata of each CycloneDX SBOM, +such as the location of build and lock files. If multiple CycloneDX SBOMs are merged together, this information is removed from the resulting merged file. NOTE: -CycloneDX reports are a [Beta](../../../policy/alpha-beta-support.md#beta-features) feature, +CycloneDX SBOMs are a [Beta](../../../policy/alpha-beta-support.md#beta-features) feature, and the reports are subject to change during the beta period. Do not build integrations -that rely on the format of these reports staying consistent, as the format might change +that rely on the format of these SBOMs staying consistent, as the format might change before the feature is made generally available. ## Versioning and release process @@ -892,11 +927,11 @@ import the following default dependency scanning analyzer images from `registry. your [local Docker container registry](../../packages/container_registry/index.md): ```plaintext -registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/retire.js:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/bundler-audit:2 +registry.gitlab.com/security-products/gemnasium:2 +registry.gitlab.com/security-products/gemnasium-maven:2 +registry.gitlab.com/security-products/gemnasium-python:2 +registry.gitlab.com/security-products/retire.js:2 +registry.gitlab.com/security-products/bundler-audit:2 ``` The process for importing Docker images into a local offline Docker registry depends on @@ -961,7 +996,13 @@ BUNDLER_AUDIT_ADVISORY_DB_REF_NAME: "master" BUNDLER_AUDIT_ADVISORY_DB_URL: "gitlab.example.com/ruby-advisory-db.git" ``` -#### Python (setup tools) +#### Python (pip) + +If you need to install Python packages before the analyzer runs, you should use `pip install --user` in the `before_script` of the scanning job. The `--user` flag causes project dependencies to be installed in the user directory. If you do not pass the `--user` option, packages are installed globally, and they are not scanned and don't show up when listing project dependencies. + +#### Python (setuptools) + +If you need to install Python packages before the analyzer runs, you should use `python setup.py install --user` in the `before_script` of the scanning job. The `--user` flag causes project dependencies to be installed in the user directory. If you do not pass the `--user` option, packages are installed globally, and they are not scanned and don't show up when listing project dependencies. When using self-signed certificates for your private PyPi repository, no extra job configuration (aside from the template `.gitlab-ci.yml` above) is needed. However, you must update your `setup.py` to diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index 89d3531bccd..b72f54b4493 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -22,7 +22,7 @@ To run IaC scanning jobs, by default, you need GitLab Runner with the If you're using the shared runners on GitLab.com, this is enabled by default. WARNING: -Our IaC scanning jobs require a Linux container type. Windows containers are not yet supported. +Our IaC scanning jobs require a Linux/amd64 container type. Windows containers are not yet supported. WARNING: If you use your own runners, make sure the Docker version installed @@ -58,7 +58,7 @@ as shown in the following table: |:---------------------------------------------------------------------------------------|:--------------------|:-------------------| | [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}** | +| Presentation of JSON Report in merge request | **{dotted-circle}** | **{check-circle}** | | [Address vulnerabilities](../../application_security/vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | | [Access to Security Dashboard](../../application_security/security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | @@ -76,7 +76,12 @@ To configure IaC Scanning for a project you can: ### Configure IaC Scanning manually To enable IaC Scanning you must [include](../../../ci/yaml/index.md#includetemplate) the -[`SAST-IaC.latest.gitlab-ci.yml template`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST-IaC.latest.gitlab-ci.yml) provided as part of your GitLab installation. +[`SAST-IaC.latest.gitlab-ci.yml template`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST-IaC.latest.gitlab-ci.yml) provided as part of your GitLab installation. Here is an example of how to include it: + +```yaml +include: + - template: Security/SAST-IaC.latest.gitlab-ci.yml +``` The included template creates IaC scanning jobs in your CI/CD pipeline and scans your project's configuration files for possible vulnerabilities. diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 6a0b81335fd..ff548f1d29f 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -110,11 +110,9 @@ For more details about each of the security scanning tools, see their respective ### Override the default registry base address -By default, GitLab security scanners use `registry.gitlab.com/gitlab-org/security-products/analyzers` as the +By default, GitLab security scanners use `registry.gitlab.com/security-products` as the base address for Docker images. You can override this globally by setting the CI/CD variable -`SECURE_ANALYZERS_PREFIX` to another location. Note that this affects all scanners at once, except -the container-scanning analyzer which uses -`registry.gitlab.com/security-products/container-scanning` as its registry. +`SECURE_ANALYZERS_PREFIX` to another location. Note that this affects all scanners at once. ### Use security scanning tools with merge request pipelines @@ -221,7 +219,7 @@ security issues: WARNING: This feature is in its end-of-life process. It is [deprecated](../../update/deprecations.md#vulnerability-check) for use in GitLab 14.8, and is planned for removal in GitLab 15.0. Users should migrate to the new -[Security Approval Policies](policies/#scan-result-policy-editor). +[Security Approval Policies](policies/scan-result-policies.md). To prevent a merge request introducing a security vulnerability in a project, enable the Vulnerability-Check rule. While this rule is enabled, additional merge request approval by @@ -397,6 +395,8 @@ any report artifacts that failed validation. ### Enable security report validation +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/354928) in GitLab 14.9, and planned for removal in GitLab 15.0. + To enable report artifacts validation, set the `VALIDATE_SCHEMA` environment variable to `"true"` for the desired jobs in the `.gitlab-ci.yml` file. diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 915e43d0fa5..7aeb094093c 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -179,7 +179,7 @@ set -ux # Specify needed analyzer images analyzers=${SAST_ANALYZERS:-"bandit eslint gosec"} -gitlab=registry.gitlab.com/gitlab-org/security-products/analyzers/ +gitlab=registry.gitlab.com/security-products/ for i in "${analyzers[@]}" do diff --git a/doc/user/application_security/policies/img/container_policy_rule_mode_v14_3.png b/doc/user/application_security/policies/img/container_policy_rule_mode_v14_3.png Binary files differdeleted file mode 100644 index b21d0330b2f..00000000000 --- a/doc/user/application_security/policies/img/container_policy_rule_mode_v14_3.png +++ /dev/null diff --git a/doc/user/application_security/policies/img/container_policy_yaml_mode_v14_3.png b/doc/user/application_security/policies/img/container_policy_yaml_mode_v14_3.png Binary files differdeleted file mode 100644 index 31d5eb57228..00000000000 --- a/doc/user/application_security/policies/img/container_policy_yaml_mode_v14_3.png +++ /dev/null diff --git a/doc/user/application_security/policies/img/policy_rule_mode_v14_9.png b/doc/user/application_security/policies/img/policy_rule_mode_v14_9.png Binary files differnew file mode 100644 index 00000000000..8ca7547a33c --- /dev/null +++ b/doc/user/application_security/policies/img/policy_rule_mode_v14_9.png diff --git a/doc/user/application_security/policies/img/policy_yaml_mode_v14_9.png b/doc/user/application_security/policies/img/policy_yaml_mode_v14_9.png Binary files differnew file mode 100644 index 00000000000..1d71e8684e9 --- /dev/null +++ b/doc/user/application_security/policies/img/policy_yaml_mode_v14_9.png diff --git a/doc/user/application_security/policies/img/scan_result_policy_yaml_mode_v14_6.png b/doc/user/application_security/policies/img/scan_result_policy_yaml_mode_v14_6.png Binary files differdeleted file mode 100644 index 57649c58d8b..00000000000 --- a/doc/user/application_security/policies/img/scan_result_policy_yaml_mode_v14_6.png +++ /dev/null diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 803f3983b96..8a39220da35 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -64,13 +64,13 @@ The policy editor has two modes: - The visual _Rule_ mode allows you to construct and preview policy rules using rule blocks and related controls. -  +  - YAML mode allows you to enter a policy definition in `.yaml` format and is aimed at expert users and cases that the Rule mode doesn't support. -  +  You can use both modes interchangeably and switch between them at any time. If a YAML resource is incorrect or contains data not supported diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index 4e44162d5c5..c3778ac97de 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -8,14 +8,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w 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. +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). +NOTE: +Policy jobs are created in the `test` stage of the pipeline. If you modify the default pipeline +[`stages`](../../../ci/yaml/index.md#stages), +you must ensure that the `test` stage exists in the list. Otherwise, the pipeline fails to run and +an error appears that states `chosen stage does not exist`. + ## Scan execution policy editor NOTE: diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index 7857de8c780..8215316bcab 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -13,7 +13,7 @@ job is fully executed. ## Scan result policy editor -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77814) in GitLab 14.8 with a flag named `scan_result_policy`. Disabled by default. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77814) in GitLab 14.8. NOTE: Only project Owners have the [permissions](../../permissions.md#project-members-permissions) @@ -28,10 +28,7 @@ the bottom of the editor. All scan result policy changes are applied through a background job that runs once every 10 minutes. Allow up to 10 minutes for any policy changes committed to this project to take effect. -The policy editor only supports YAML mode. To follow work on Rule mode, see the epic -[Allow Users to Edit Rule-mode scan result policies in the Policy UI](https://gitlab.com/groups/gitlab-org/-/epics/5363). - - +The [policy editor](index.md#policy-editor) supports YAML mode and rule mode. ## Scan result policies schema diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 3c0a2caf114..d3a79410eea 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -57,7 +57,7 @@ To run SAST jobs, by default, you need GitLab Runner with the If you're using the shared runners on GitLab.com, this is enabled by default. WARNING: -Our SAST jobs require a Linux container type. Windows containers are not yet supported. +Our SAST jobs require a Linux/amd64 container type. Windows containers are not yet supported. WARNING: If you use your own runners, make sure the Docker version installed @@ -315,7 +315,6 @@ To disable analyzer rules: 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 `value` field, to name the rule to be disabled. ##### Example: Disable predefined rules of SAST analyzers @@ -345,6 +344,9 @@ and `sobelow` by matching the `type` and `value` of identifiers: value = "sql_injection" ``` +Those vulnerabilities containing the provided type and value are now disabled, meaning +they won't be displayed in Merge Request nor the Vulnerability Report. + #### Override predefined analyzer rules To override analyzer rules: @@ -365,30 +367,40 @@ To override analyzer rules: ##### Example: Override predefined rules of SAST analyzers -In the following example, rules from `eslint` -and `gosec` are matched by the `type` and `value` of identifiers and -then overridden: +Before adding a ruleset, we verify which vulnerability will be overwritten by viewing the [`gl-sast-report.json`](#reports-json-format): + +```json +"identifiers": [ + { + "type": "gosec_rule_id", + "name": "Gosec Rule ID G307", + "value": "G307" + }, + { + "type": "CWE", + "name": "CWE-703", + "value": "703", + "url": "https://cwe.mitre.org/data/definitions/703.html" + } + ] +``` + +In the following example, rules from `gosec` are matched by the `type` +and `value` of identifiers and then overridden: ```toml -[eslint] - [[eslint.ruleset]] - [eslint.ruleset.identifier] - type = "eslint_rule_id" - value = "security/detect-object-injection" - [eslint.ruleset.override] - description = "OVERRIDDEN description" - message = "OVERRIDDEN message" - name = "OVERRIDDEN name" - severity = "Critical" [gosec] [[gosec.ruleset]] [gosec.ruleset.identifier] type = "CWE" - value = "CWE-79" + value = "703" [gosec.ruleset.override] severity = "Critical" ``` +If a vulnerability is found with a type `CWE` with a value of `703` then +the vulnerability severity is overwritten to `Critical`. + #### Synthesize a custom configuration To create a custom configuration, you can use passthrough chains. @@ -661,6 +673,25 @@ repositories and thus require credentials like username and password to download Depending on the analyzer, such credentials can be provided to it via [custom CI/CD variables](#custom-cicd-variables). +#### Using a CI/CD variable to pass username and password to a private Go repository + +If your Go project depends on private modules, see +[Fetch modules from private projects](../../packages/go_proxy/index.md#fetch-modules-from-private-projects) +for how to provide authentication over HTTPS. + +To specify credentials via `~/.netrc` provide a `before_script` containing the following: + +```yaml +gosec-sast: + before_script: + - | + cat <<EOF > ~/.netrc + machine gitlab.com + login $CI_DEPLOY_USER + password $CI_DEPLOY_PASSWORD + EOF +``` + #### Using a CI/CD variable to pass username and password to a private Maven repository If your private Maven repository requires login credentials, @@ -878,12 +909,12 @@ variables: ## Reports JSON format -SAST outputs a report file in JSON format. The report file contains details of all found vulnerabilities. -To download the report file, you can either: +SAST outputs a report file in JSON format. The report file contains details of all found vulnerabilities. +To download the report file, you can either: - Download the file from the CI/CD pipelines page. -- In the pipelines tab on merge requests, set [`artifacts: paths`](../../../ci/yaml/index.md#artifactspaths) to `gl-sast-report.json`. - +- In the pipelines tab on merge requests, set [`artifacts: paths`](../../../ci/yaml/index.md#artifactspaths) to `gl-sast-report.json`. + For information, see [Download job artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). For details of the report file's schema, see diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 2ce2d59898f..582497eb465 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -42,7 +42,7 @@ To run Secret Detection jobs, by default, you need GitLab Runner with the If you're using the shared runners on GitLab.com, this is enabled by default. WARNING: -Our Secret Detection jobs expect a Linux container type. Windows containers are not supported. +Our Secret Detection jobs expect a Linux/amd64 container type. Windows containers are not supported. WARNING: If you use your own runners, make sure the Docker version installed @@ -328,14 +328,6 @@ as part of your normal job definition. A new configuration variable ([`SECRET_DETECTION_HISTORIC_SCAN`](#available-cicd-variables)) can be set to change the behavior of the GitLab Secret Detection scan to run on the entire Git history of a repository. -We have created a [short video walkthrough](https://youtu.be/wDtc_K00Y0A) showcasing how you can perform a full history secret detection scan. -<div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=wDtc_K00Y0A">Walkthrough of historical secret detection scan</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube.com/embed/wDtc_K00Y0A" frameborder="0" allowfullscreen="true"> </iframe> -</figure> - ## Running Secret Detection in an offline environment For self-managed GitLab instances in an environment with limited, restricted, or intermittent access @@ -450,9 +442,9 @@ secret_detection: ### `secret-detection` job fails with `ERR fatal: ambiguous argument` message -Your `secret-detection` job can fail with `ERR fatal: ambiguous argument` error if your -repository's default branch is unrelated to the branch the job was triggered for. +Your `secret-detection` job can fail with `ERR fatal: ambiguous argument` error if your +repository's default branch is unrelated to the branch the job was triggered for. See issue [!352014](https://gitlab.com/gitlab-org/gitlab/-/issues/352014) for more details. -To resolve the issue, make sure to correctly [set your default branch](../../project/repository/branches/default.md#change-the-default-branch-name-for-a-project) on your repository. You should set it to a branch -that has related history with the branch you run the `secret-detection` job on. +To resolve the issue, make sure to correctly [set your default branch](../../project/repository/branches/default.md#change-the-default-branch-name-for-a-project) on your repository. You should set it to a branch +that has related history with the branch you run the `secret-detection` job on. diff --git a/doc/user/application_security/secret_detection/post_processing.md b/doc/user/application_security/secret_detection/post_processing.md index 972558c3b95..643da47d876 100644 --- a/doc/user/application_security/secret_detection/post_processing.md +++ b/doc/user/application_security/secret_detection/post_processing.md @@ -56,7 +56,7 @@ A vendor revocation receiver service integrates with a GitLab instance to receiv a web notification and respond to leaked token requests. To implement a receiver service to revoke leaked tokens: - + 1. Create a publicly accessible HTTP service matching the corresponding API contract below. Your service should be idempotent and rate-limited. 1. When a pipeline corresponding to its revocable token type (in the example, `my_api_token`) diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 7b39002bac3..0b27760b4bb 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -27,8 +27,9 @@ On the vulnerability's page, you can: - [Change the vulnerability's status](#change-vulnerability-status). - [Create an issue](#create-an-issue-for-a-vulnerability). - [Link issues to the vulnerability](#linked-issues). -- [Resolve a vulnerability](#resolve-a-vulnerability), if a solution is - available. +- [Resolve a vulnerability](#resolve-a-vulnerability) if a solution is + available. +- [View security training specific to the detected vulnerability](#view-security-training-for-a-vulnerability). ## Vulnerability status values @@ -80,7 +81,7 @@ The issue is then opened so you can take further action. Prerequisites: - [Enable Jira integration](../../../integration/jira/index.md). - The **Enable Jira issues creation from vulnerabilities** option must be selected as part of the configuration. + The **Enable Jira issue creation from vulnerabilities** option must be selected as part of the configuration. - Each user must have a personal Jira user account with permission to create issues in the target project. To create a Jira issue for a vulnerability: @@ -159,3 +160,29 @@ To manually apply the patch that GitLab generated for a vulnerability: 1. Ensure your local project has the same commit checked out that was used to generate the patch. 1. Run `git apply remediation.patch`. 1. Verify and commit the changes to your branch. + +## Enable security training for vulnerabilities + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6176) in GitLab 14.9. + +Security training helps your developers learn how to fix vulnerabilities. Developers can view security training from selected educational providers, relevant to the detected vulnerability. + +To enable security training for vulnerabilities in your project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. +1. On the tab bar, select **Vulnerability Management**. +1. To enable a security training provider, turn on the toggle. + +## View security training for a vulnerability + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6176) in GitLab 14.9. + +If security training is enabled, the vulnerability page includes a training link relevant to the detected vulnerability. + +To view the security training for a vulnerability: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Vulnerability report**. +1. Select the vulnerability for which you want to view security training. +1. Select **View training**. diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index ba1455ab70a..eb59c289700 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Vulnerability Report **(ULTIMATE)** -The Vulnerability Report provides information about vulnerabilities from scans of the default branch. It contains cumulative results of all successful jobs, regardless of whether the pipeline was successful. +The Vulnerability Report provides information about vulnerabilities from scans of the default branch. It contains cumulative results of all successful jobs, regardless of whether the pipeline was successful. The scan results from a pipeline are only ingested after all the jobs in the pipeline complete. Partial results for a pipeline with jobs in progress can be seen in the pipeline security tab. @@ -52,6 +52,7 @@ From the Vulnerability Report you can: - [View an issue raised for a vulnerability](#view-issues-raised-for-a-vulnerability). - [Change the status of vulnerabilities](#change-status-of-vulnerabilities). - [Export details of vulnerabilities](#export-vulnerability-details). +- [Manually add a vulnerability finding](#manually-add-a-vulnerability-finding). ## Vulnerability Report filters @@ -219,6 +220,25 @@ You can dismiss a vulnerability for the entire project: To undo this action, select a different status from the same menu. +## Manually add a vulnerability finding + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301003) in GitLab 14.9. Disabled by default. + +FLAG: +This feature is not enabled by default. To make it available, ask an administrator to +[enable the feature flag](../../feature_flags.md) named `new_vulnerability_form`. +On GitLab.com, this feature is not yet available. + +To add a new vulnerability finding from your project level Vulnerability Report page: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Vulnerability Report**. +1. Click on **Submit Vulnerability**. +1. Complete the fields and submit the form. + +You will be brought to the newly created vulnerability's detail page. Manually created records appear in the +Group, Project, and Security Center Vulnerability Reports. To filter them, use the Generic Tool filter. + ## Operational vulnerabilities > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6345) in GitLab 14.6. diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md index 5fe772d9686..73a8470e025 100644 --- a/doc/user/clusters/agent/ci_cd_tunnel.md +++ b/doc/user/clusters/agent/ci_cd_tunnel.md @@ -4,60 +4,254 @@ 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 --- -# CI/CD Tunnel **(FREE)** +# Using a GitLab CI/CD workflow for Kubernetes **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327409) in GitLab 14.1. > - The pre-configured `KUBECONFIG` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2. > - The ability to authorize groups was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) to GitLab Free in 14.5. > - Support for Omnibus installations was [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5686) in GitLab 14.5. +> - The ability to switch between certificate-based clusters and agents was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335089) in GitLab 14.9. The certificate-based cluster context is always called `gitlab-deploy`. -To use GitLab CI/CD to safely deploy your application to a cluster, you can use the CI/CD Tunnel. +You can use a GitLab CI/CD workflow to safely deploy to and update your Kubernetes clusters. -You can authorize multiple projects to access the same cluster, so you -can keep your application's codebase in one repository and configure -your cluster in another. This method is scalable and can save you resources. +To do so, you must first [install an agent in your cluster](install/index.md). When done, you have a Kubernetes context and can +run Kubernetes API commands in your GitLab CI/CD pipeline. -To ensure access to your cluster is safe, only the projects you -authorize can access your Agent through the CI/CD Tunnel. +To ensure access to your cluster is safe: -## Prerequisites +- Each agent has a separate context (`kubecontext`). +- Only the project where the agent is configured, and any additional projects you authorize, can access the agent in your cluster. -To use the CI/CD Tunnel, you need an existing Kubernetes cluster connected to GitLab through the -[GitLab Agent](install/index.md#install-the-agent-onto-the-cluster). +You do not need to have a runner in the cluster with the agent. -To run your CI/CD jobs using the CI/CD Tunnel, you do not need to have a runner in the same cluster. +## GitLab CI/CD workflow steps -## How the CI/CD Tunnel works +To update a Kubernetes cluster by using GitLab CI/CD, complete the following steps. -When you authorize a project to use an Agent, the Tunnel automatically -injects a `KUBECONFIG` variable into its CI/CD jobs. This way, you can -run `kubectl` commands from GitLab CI/CD scripts that belong to the -authorized project. +1. Ensure you have a working Kubernetes cluster and the manifests are in a GitLab project. +1. In the same GitLab project, [register and install the GitLab agent](install/index.md). +1. [Update your `.gitlab-ci.yml` file](#update-your-gitlab-ciyml-file-to-run-kubectl-commands) to + select the agent's Kubernetes context and run the Kubernetes API commands. +1. Run your pipeline to deploy to or update the cluster. -When you authorize a group, all the projects that belong to that group -become authorized to access the selected Agent. +If you have multiple GitLab projects that contain Kubernetes manifests: -An Agent can only authorize projects or groups in the same group -hierarchy as the Agent's configuration project. You can authorize -up to 100 projects and 100 groups per Agent. +1. [Install the GitLab agent](install/index.md) in its own project, or in one of the + GitLab projects where you keep Kubernetes manifests. +1. [Authorize the agent](#authorize-the-agent) to access your GitLab projects. +1. Optional. For added security, [use impersonation](#use-impersonation-to-restrict-project-and-group-access). +1. [Update your `.gitlab-ci.yml` file](#update-your-gitlab-ciyml-file-to-run-kubectl-commands) to + select the agent's Kubernetes context and run the Kubernetes API commands. +1. Run your pipeline to deploy to or update the cluster. -Also, each Agent has a separate context (`kubecontext`). -The Tunnel uses this information to safely allow access to the cluster from -jobs running in the projects you authorized. +## Authorize the agent -### `~/.kube/cache` permissions - -`kubectl` and other tools based on the same libraries (such as Helm, `kpt`, and `kustomize`) cache information about +You must authorize the agent to access the project where you keep your Kubernetes manifests. +You can authorize the agent to access individual projects, or authorize a group or subgroup, +so all projects within have access. For added security, you can also +[use impersonation](#use-impersonation-to-restrict-project-and-group-access). + +### Authorize the agent to access your projects + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327850) in GitLab 14.4. + +To authorize the agent to access the GitLab project where you keep Kubernetes manifests: + +1. On the top bar, select **Menu > Projects** and find the project that contains the agent configuration file (`config.yaml`). +1. Edit the file. Under the `ci_access` keyword, add the `projects` attribute. +1. For the `id`, add the path: + + ```yaml + ci_access: + projects: + - id: path/to/project + ``` + + - The Kubernetes projects must be in the same group hierarchy as the project where the agent's configuration is. + - You can authorize up to 100 projects. + +All CI/CD jobs now include a `KUBECONFIG` with contexts for every shared agent connection. +Choose the context to run `kubectl` commands from your CI/CD scripts. + +### Authorize the agent to access projects in your groups + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. + +To authorize the agent to access all of the GitLab projects in a group or subgroup: + +1. On the top bar, select **Menu > Projects** and find the project that contains the agent configuration file (`config.yaml`). +1. Edit the file. Under the `ci_access` keyword, add the `groups` attribute. +1. For the `id`, add the path: + + ```yaml + ci_access: + groups: + - id: path/to/group/subgroup + ``` + + - The Kubernetes projects must be in the same group hierarchy as the project where the agent's configuration is. + - You can authorize up to 100 groups. + +All the projects that belong to the group are now authorized to access the agent. +All CI/CD jobs now include a `KUBECONFIG` with contexts for every shared agent connection. +Choose the context to run `kubectl` commands from your CI/CD scripts. + +## Update your `.gitlab-ci.yml` file to run `kubectl` commands + +In the project where you want to run Kubernetes commands, edit your project's `.gitlab-ci.yml` file. + +In the first command under the `script` keyword, set your agent's context. +Use the format `path/to/agent/repository:agent-name`. For example: + +```yaml + deploy: + image: + name: bitnami/kubectl:latest + entrypoint: [""] + script: + - kubectl config get-contexts + - kubectl config use-context path/to/agent/repository:agent-name + - kubectl get pods +``` + +If you are not sure what your agent's context is, open a terminal and connect to your cluster. +Run `kubectl config get-contexts`. + +### Environments with both certificate-based and agent-based connections + +When you deploy to an environment that has both a [certificate-based +cluster](../../infrastructure/clusters/index.md) (deprecated) and an agent connection: + +- The certificate-based cluster's context is called `gitlab-deploy`. This context + is always selected by default. +- In GitLab 14.9 and later, agent contexts are included in the + `KUBECONFIG`. You can select them by using `kubectl config use-context + path/to/agent/repository:agent-name`. +- In GitLab 14.8 and earlier, you can still use agent connections, but for environments that + already have a certificate-based cluster, the agent connections are not included in the `KUBECONFIG`. + +To use an agent connection when certificate-based connections are present, you can manually configure a new `kubectl` +configuration context. For example: + + ```yaml + deploy: + variables: + KUBE_CONTEXT: my-context # The name to use for the new context + AGENT_ID: 1234 # replace with your agent's numeric ID + K8S_PROXY_URL: wss://kas.gitlab.com/k8s-proxy/ # replace with your agent server (KAS) Kubernetes proxy URL + # ... any other variables you have configured + before_script: + - kubectl config set-credentials agent:$AGENT_ID --token="ci:${AGENT_ID}:${CI_JOB_TOKEN}" + - kubectl config set-cluster gitlab --server="${K8S_PROXY_URL}" + - kubectl config set-context "$KUBE_CONTEXT" --cluster=gitlab --user="agent:${AGENT_ID}" + - kubectl config use-context "$KUBE_CONTEXT" + # ... rest of your job configuration + ``` + +## Use impersonation to restrict project and group access **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345014) in GitLab 14.5. + +By default, your CI/CD job inherits all the permissions from the service account used to install the +agent in the cluster. +To restrict access to your cluster, you can use [impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation). + +To specify impersonations, use the `access_as` attribute in your agent configuration file and use Kubernetes RBAC rules to manage impersonated account permissions. + +You can impersonate: + +- The agent itself (default). +- The CI/CD job that accesses the cluster. +- A specific user or system account defined within the cluster. + +### Impersonate the agent + +The agent is impersonated by default. You don't need to do anything to impersonate it. + +### Impersonate the CI/CD job that accesses the cluster + +To impersonate the CI/CD job that accesses the cluster, under the `access_as` key, add the `ci_job: {}` key-value. + +When the agent makes the request to the actual Kubernetes API, it sets the +impersonation credentials in the following way: + +- `UserName` is set to `gitlab:ci_job:<job id>`. Example: `gitlab:ci_job:1074499489`. +- `Groups` is set to: + - `gitlab:ci_job` to identify all requests coming from CI jobs. + - The list of IDs of groups the project is in. + - The project ID. + - The slug of the environment this job belongs to. + + Example: for a CI job in `group1/group1-1/project1` where: + + - Group `group1` has ID 23. + - Group `group1/group1-1` has ID 25. + - Project `group1/group1-1/project1` has ID 150. + - Job running in a prod environment. + + Group list would be `[gitlab:ci_job, gitlab:group:23, gitlab:group:25, gitlab:project:150, gitlab:project_env:150:prod]`. + +- `Extra` carries extra information about the request. The following properties are set on the impersonated identity: + +| Property | Description | +| -------- | ----------- | +| `agent.gitlab.com/id` | Contains the agent ID. | +| `agent.gitlab.com/config_project_id` | Contains the agent's configuration project ID. | +| `agent.gitlab.com/project_id` | Contains the CI project ID. | +| `agent.gitlab.com/ci_pipeline_id` | Contains the CI pipeline ID. | +| `agent.gitlab.com/ci_job_id` | Contains the CI job ID. | +| `agent.gitlab.com/username` | Contains the username of the user the CI job is running as. | +| `agent.gitlab.com/environment_slug` | Contains the slug of the environment. Only set if running in an environment. | + +Example to restrict access by the CI/CD job's identity: + +```yaml +ci_access: + projects: + - id: path/to/project + access_as: + ci_job: {} +``` + +### Impersonate a static identity + +For a given connection, you can use a static identity for the impersonation. + +Under the `access_as` key, add the `impersonate` key to make the request using the provided identity. + +The identity can be specified with the following keys: + +- `username` (required) +- `uid` +- `groups` +- `extra` + +See the [official Kubernetes documentation for details](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation). + +## Troubleshooting + +### `kubectl` commands not supported + +The commands `kubectl exec`, `kubectl cp`, and `kubectl attach` are not supported. +Anything that uses these API endpoints does not work, because they use the deprecated +SPDY protocol. +[An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/346248) to add support for these commands. + +### Grant write permissions to `~/.kube/cache` + +Tools like `kubectl`, Helm, `kpt`, and `kustomize` cache information about the cluster in `~/.kube/cache`. If this directory is not writable, the tool fetches information on each invocation, -making interactions slower and creating unnecessary load on the cluster. Make sure that this directory in the container image -you use is writable for the best experience. +making interactions slower and creating unnecessary load on the cluster. For the best experience, in the +image you use in your .`gitlab-ci.yml` file, ensure this directory is writable. + +### Enable TLS -## Configure the CI/CD Tunnel +If you are on a self-managed GitLab instance, ensure your instance is configured with Transport Layer Security (TLS). -The CI/CD Tunnel is configured directly through the -Agent's configuration file ([`config.yaml`](repository.md)) to: +If you attempt to use `kubectl` without TLS, you might get an error like: -- Authorize [projects](repository.md#authorize-projects-to-use-an-agent) and [groups](repository.md#authorize-groups-to-use-an-agent) to use the same Agent. -- [Run `kubectl` commands using the CI/CD Tunnel](repository.md#run-kubectl-commands-using-the-cicd-tunnel). -- [Restrict access of authorized projects and groups through impersonation strategies](repository.md#use-impersonation-to-restrict-project-and-group-access). +```shell +$ kubectl get pods +error: You must be logged in to the server (the server has asked for the client to provide credentials) +``` diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md new file mode 100644 index 00000000000..8f0e2255121 --- /dev/null +++ b/doc/user/clusters/agent/gitops.md @@ -0,0 +1,140 @@ +--- +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 +--- + +# Using a GitOps workflow for Kubernetes **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7. + +With GitOps, you can manage containerized clusters and applications from a Git repository that: + +- Is the single source of truth of your system. +- Is the single place where you operate your system. + +By combining GitLab, Kubernetes, and GitOps, you can have: + +- GitLab as the GitOps operator. +- Kubernetes as the automation and convergence system. +- GitLab CI/CD for Continuous Integration and the agent for Continuous Deployment. + +This diagram shows the repositories and main actors in a GitOps deployment: + +```mermaid +sequenceDiagram + participant D as Developer + participant A as Application code repository + participant M as Manifest repository + participant K as GitLab agent + participant C as Agent configuration repository + loop Regularly + K-->>C: Grab the configuration + end + D->>+A: Pushing code changes + A->>M: Updating manifest + loop Regularly + K-->>M: Watching changes + M-->>K: Pulling and applying changes + end +``` + +For details, view the [architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture). + +## GitOps workflow steps + +To update a Kubernetes cluster by using GitOps, complete the following steps. + +1. Ensure you have a working Kubernetes cluster, and that the manifests are in a GitLab project. +1. In the same project, [register and install the GitLab agent](install/index.md). +1. Configure the agent configuration file so that the agent monitors the project for changes to the Kubernetes manifests. + Use the [GitOps configuration reference](#gitops-configuration-reference) for guidance. + +Any time you commit updates to your Kubernetes manifests, the agent updates the cluster. + +## GitOps configuration reference + +The following snippet shows an example of the possible keys and values for the GitOps section of an agent configuration file. + +```yaml +gitops: + manifest_projects: + - id: gitlab-org/cluster-integration/gitlab-agent + default_namespace: my-ns + paths: + # Read all YAML files from this directory. + - glob: '/team1/app1/*.yaml' + # Read all .yaml files from team2/apps and all subdirectories. + - glob: '/team2/apps/**/*.yaml' + # If 'paths' is not specified or is an empty list, the configuration below is used. + - glob: '/**/*.{yaml,yml,json}' + reconcile_timeout: 3600s + dry_run_strategy: none + prune: true + prune_timeout: 3600s + prune_propagation_policy: foreground + inventory_policy: must_match +``` + +| Keyword | Description | +|--|--| +| `manifest_projects` | Projects where your Kubernetes manifests are stored. The agent monitors the files in the repositories in these projects. When manifest files change, the agent deploys the changes to the cluster. | +| `id` | Required. Path to a Git repository that has Kubernetes manifests in YAML or JSON format. No authentication mechanisms are currently supported. | +| `default_namespace` | Namespace to use if not set explicitly in object manifest. Also used for inventory `ConfigMap` objects. | +| `paths` | Repository paths to scan for manifest files. Directories with names that start with a dot `(.)` are ignored. | +| `paths[].glob` | Required. See [doublestar](https://github.com/bmatcuk/doublestar#about) and [the match function](https://pkg.go.dev/github.com/bmatcuk/doublestar/v2#Match) for globbing rules. | +| `reconcile_timeout` | Determines whether the applier should wait until all applied resources have been reconciled, and if so, how long to wait. Default is 3600 seconds (1 hour). | +| `dry_run_strategy` | Determines whether changes [should be performed](https://github.com/kubernetes-sigs/cli-utils/blob/d6968048dcd80b1c7b55d9e4f31fc25f71c9b490/pkg/common/common.go#L68-L89). Can be: `none`, `client`, or `server`. Default is `none`.| +| `prune` | Determines whether pruning of previously applied objects should happen after apply. Default is `true`. | +| `prune_timeout` | Determines whether to wait for all resources to be fully deleted after pruning, and if so, how long to wait. Default is 3600 seconds (1 hour). | +| `prune_propagation_policy` | The deletion propagation policy that [should be used for pruning](https://github.com/kubernetes/apimachinery/blob/44113beed5d39f1b261a12ec398a356e02358307/pkg/apis/meta/v1/types.go#L456-L470). Can be: `orphan`, `background`, or `foreground`. Default is `foreground`. | +| `inventory_policy` | Determines whether an inventory object can take over objects that belong to another inventory object or don't belong to any inventory object. This is done by determining if the apply/prune operation can go through for a resource based on comparison of the `inventory-id` value in the package and the `owning-inventory` annotation (`config.k8s.io/owning-inventory`) [in the live object](https://github.com/kubernetes-sigs/cli-utils/blob/d6968048dcd80b1c7b55d9e4f31fc25f71c9b490/pkg/inventory/policy.go#L12-L66). Can be: `must_match`, `adopt_if_no_inventory`, or `adopt_all`. Default is `must_match`. | + +## Additional resources + +The following documentation and examples can help you get started with a GitOps workflow. + +- [Managing Kubernetes secrets in a GitOps workflow](gitops/secrets_management.md) +- [Application and manifest repository example](https://gitlab.com/gitlab-examples/ops/gitops-demo/hello-world-service-gitops) + +## Troubleshooting + +### Avoiding conflicts when you have multiple projects + +The agent watches each glob pattern set under a project's `paths` section independently, and makes updates to the cluster concurrently. +If changes are found at multiple paths, when the agent attempts to update the cluster, +a conflict can occur. + +To prevent this from happening, consider storing a logical group of manifests in a single place and reference them only once to avoid overlapping globs. + +For example, both of these globs match `*.yaml` files in the root directory +and could cause conflicts: + +```yaml +gitops: + manifest_projects: + - id: project1 + paths: + - glob: '/**/*.yaml' + - glob: '/*.yaml' +``` + +Instead, specify a single glob that matches all `*.yaml` files recursively: + +```yaml +gitops: + manifest_projects: + - id: project1 + paths: + - glob: '/**/*.yaml' +``` + +### Use multiple agents or projects + +If you store your Kubernetes manifests in separate GitLab projects, +update your agent configuration file with the location of these projects. + +WARNING: +The project with the agent's +configuration file can be private or public. Other projects with Kubernetes manifests must be public. Support for private manifest projects is tracked +in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/283885). diff --git a/doc/user/clusters/agent/gitops/secrets_management.md b/doc/user/clusters/agent/gitops/secrets_management.md new file mode 100644 index 00000000000..cf520c881bf --- /dev/null +++ b/doc/user/clusters/agent/gitops/secrets_management.md @@ -0,0 +1,61 @@ +--- +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 +--- + +# Managing Kubernetes secrets in a GitOps workflow + +You should never store Kubernetes secrets in unencrypted form in a `git` repository. If you use a GitOps workflow, you can follow these steps to securely manage your secrets. + +1. Set up the Sealed Secrets controller to manage secrets. +1. Deploy Docker credentials so the cluster can pull images from the GitLab Container Registry. + +## Prerequisites + +This setup requires: + +- A [GitLab agent for Kubernetes configured for the GitOps workflow](../gitops.md). +- Access to the cluster to finish the setup. + +## Set up the Sealed Secrets controller to manage secrets + +You can use the [Sealed Secrets controller](https://github.com/bitnami-labs/sealed-secrets) to store encrypted secrets securely in a `git` repository. The controller decrypts the secret into a standard Kubernetes `Secret` kind resource. + +1. Go to [the Sealed Secrets release page](https://github.com/bitnami-labs/sealed-secrets/releases) and download the most recent `controller.yaml` file. +1. In GitLab, go to the project that contains your Kubernetes manifests and upload the `controller.yaml` file. +1. Open the agent configuration file (`config.yaml`) and if needed, update the `paths.glob` pattern to match the Sealed Secrets manifest. +1. Commit and push the changes to GitLab. +1. Confirm that the Sealed Secrets controller was installed successfully: + + ```shell + kubectl get pods -lname=sealed-secrets-controller -n kube-system + ``` + +1. Install the `kubeseal` command line utility by following [the Sealed Secrets instructions](https://github.com/bitnami-labs/sealed-secrets#homebrew). +1. Get the public key you need to encrypt secrets without direct access to the cluster: + + ```shell + kubeseal --fetch-cert > public.pem + ``` + +1. Commit the public key to the repository. + +For more details on how the Sealed Secrets controller works, view [the usage instructions](https://github.com/bitnami-labs/sealed-secrets/blob/main/README.md#usage). + +## Deploy Docker credentials + +To deploy containers from the GitLab Container Registry, you must configure the cluster with the proper Docker registry credentials. You can achieve this by deploying a `docker-registry` type secret. + +1. Generate a GitLab token with at least `read-registry` rights. The token can be either a Personal or a Project Access Token. +1. Create a Kubernetes secret manifest YAML file. Update the values as needed: + + ```shell + kubectl create secret docker-registry gitlab-credentials --docker-server=registry.gitlab.example.com --docker-username=<gitlab-username> --docker-password=<gitlab-token> --docker-email=<gitlab-user-email> -n <namespace> --dry-run=client -o yaml > gitlab-credentials.yaml + ``` + +1. Encrypt the secret into a `SealedSecret` manifest: + + ```shell + kubeseal --format=yaml --cert=public.pem < gitlab-credentials.yaml > gitlab-credentials.sealed.yaml + ``` diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 3fb141e402f..a8ad19df2e1 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -8,23 +8,36 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in GitLab 13.4. > - Support for `grpcs` [introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) in GitLab 13.6. -> - Agent Server [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300960) on GitLab.com under `wss://kas.gitlab.com` through an Early Adopter Program in GitLab 13.10. +> - Agent server [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300960) on GitLab.com under `wss://kas.gitlab.com` through an Early Adopter Program in GitLab 13.10. > - The agent became available to every project on GitLab.com in GitLab 13.11. > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5. > - [Renamed](https://gitlab.com/groups/gitlab-org/-/epics/7167) from "GitLab Kubernetes Agent" to "GitLab agent for Kubernetes" in GitLab 14.6. You can connect your Kubernetes cluster with GitLab to deploy, manage, -and monitor your cloud-native solutions. You can choose from two primary workflows. +and monitor your cloud-native solutions. -In a **GitOps workflow**, you keep your Kubernetes manifests in GitLab. You install a GitLab agent in your cluster, and +To connect a Kubernetes cluster to GitLab, you must first [install an agent in your cluster](install/index.md). + +The agent runs in the cluster, and you can use it to: + +- Communicate with a cluster, which is behind a firewall or NAT. +- Access API endpoints in a cluster in real time. +- Push information about events happening in the cluster. +- Enable a cache of Kubernetes objects, which are kept up-to-date with very low latency. + +For more details about the agent's purpose and architecture, see the [architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md). + +## Workflows + +You can choose from two primary workflows. + +In a [**GitOps** workflow](gitops.md), you keep your Kubernetes manifests in GitLab. You install a GitLab agent in your cluster, and any time you update your manifests, the agent updates the cluster. This workflow is fully driven with Git and is considered pull-based, because the cluster is pulling updates from your GitLab repository. -In a **CI/CD** workflow, you use GitLab CI/CD to query and update your cluster by using the Kubernetes API. +In a [**CI/CD** workflow](ci_cd_tunnel.md), you use GitLab CI/CD to query and update your cluster by using the Kubernetes API. This workflow is considered push-based, because GitLab is pushing requests from GitLab CI/CD to your cluster. -Both of these workflows require you to [install an agent in your cluster](install/index.md). - ## Supported cluster versions GitLab supports the following Kubernetes versions. You can upgrade your @@ -32,8 +45,6 @@ Kubernetes version to a supported version at any time: - 1.20 (support ends on July 22, 2022) - 1.19 (support ends on February 22, 2022) -- 1.18 (support ends on November 22, 2021) -- 1.17 (support ends on September 22, 2021) GitLab supports at least two production-ready Kubernetes minor versions at any given time. GitLab regularly reviews the supported versions and @@ -47,174 +58,15 @@ version. The list of supported versions is based on: Some GitLab features might work on versions not listed here. -## Using Kubernetes with GitOps **(PREMIUM)** - -With GitOps, you can manage containerized clusters and applications from a Git repository that: - -- Is the single source of truth of your system. -- Is the single place where you operate your system. - -By combining GitLab, Kubernetes, and GitOps, you can have: - -- GitLab as the GitOps operator. -- Kubernetes as the automation and convergence system. -- GitLab CI/CD for Continuous Integration and the agent for Continuous Deployment. - -Beyond that, you can use all the features offered by GitLab as -the all-in-one DevOps platform for your product and your team. - -### GitOps workflow **(PREMIUM)** - -The agent uses multiple GitLab projects to provide a flexible workflow -that can suit various needs. This diagram shows these repositories and the main -The agent uses multiple GitLab projects to provide a flexible workflow. -This diagram shows these repositories and the main -actors involved in a deployment: - -```mermaid -sequenceDiagram - participant D as Developer - participant A as Application code repository - participant M as Manifest repository - participant K as GitLab agent - participant C as Agent configuration repository - loop Regularly - K-->>C: Grab the configuration - end - D->>+A: Pushing code changes - A->>M: Updating manifest - loop Regularly - K-->>M: Watching changes - M-->>K: Pulling and applying changes - end -``` - -For details, view the [architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture). - -To perform GitOps deployments, you need: - -- A properly-configured Kubernetes cluster where the GitLab agent is running. -- A project that contains the agent's configuration file (`config.yaml`) in the repository. - This file tells the agent which repositories to synchronize with the cluster. -- A project that contains Kubernetes manifests. Any changes to manifests are applied to the cluster. - -You can keep the agent's configuration file and Kubernetes manifests in one project, or you can use multiple. - -- One GitLab project (recommended): When you use one project for both the Kubernetes manifests - and the agent's configuration file, the projects can be either private or public. -- Two GitLab projects: When you use two different GitLab projects (one for Kubernetes - manifests and another for the agent's configuration file), the project with Kubernetes manifests must - be public. The project with the agent's configuration file can be either private or public. - -Support for separate private projects is tracked in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/283885). - -## Remove an agent - -You can remove an agent by using the [GitLab UI](#remove-an-agent-through-the-gitlab-ui) or the [GraphQL API](#remove-an-agent-with-the-gitlab-graphql-api). - -### Remove an agent through the GitLab UI - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323055) in GitLab 14.7. - -To remove an agent from the UI: - -1. On the top bar, select **Menu > Projects** and find the project that contains the agent's configuration file. -1. From the left sidebar, select **Infrastructure > Kubernetes clusters**. -1. In the table, in the row for your agent, in the **Options** column, select the vertical ellipsis (**{ellipsis_v}**). -1. Select **Delete agent**. - -### Remove an agent with the GitLab GraphQL API - -1. Get the `<cluster-agent-token-id>` from a query in the interactive GraphQL explorer. - - For GitLab.com, go to <https://gitlab.com/-/graphql-explorer> to open GraphQL Explorer. - - For self-managed GitLab, go to `https://gitlab.example.com/-/graphql-explorer`, replacing `gitlab.example.com` with your instance's URL. - - ```graphql - query{ - project(fullPath: "<full-path-to-agent-configuration-project>") { - clusterAgent(name: "<agent-name>") { - id - tokens { - edges { - node { - id - } - } - } - } - } - } - ``` - -1. Remove an agent record with GraphQL by deleting the `clusterAgentToken`. - - ```graphql - mutation deleteAgent { - clusterAgentDelete(input: { id: "<cluster-agent-id>" } ) { - errors - } - } - - mutation deleteToken { - clusterAgentTokenDelete(input: { id: "<cluster-agent-token-id>" }) { - errors - } - } - ``` - -1. Verify whether the removal occurred successfully. If the output in the Pod logs includes `unauthenticated`, it means that the agent was successfully removed: - - ```json - { - "level": "warn", - "time": "2021-04-29T23:44:07.598Z", - "msg": "GetConfiguration.Recv failed", - "error": "rpc error: code = Unauthenticated desc = unauthenticated" - } - ``` - -1. Delete the agent in your cluster: - - ```shell - kubectl delete -n gitlab-kubernetes-agent -f ./resources.yml - ``` - -## Migrating to the agent from the legacy certificate-based integration - -Find out how to [migrate to the agent for Kubernetes](../../infrastructure/clusters/migrate_to_gitlab_agent.md) from the certificate-based integration. - -## Kubernetes network security alerts **(ULTIMATE)** - -> [Deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. - -WARNING: -Cilium integration is in its end-of-life process. It's [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/7476) -for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) -in GitLab 15.0. - -The agent for Kubernetes also provides an integration with Cilium. This integration provides a simple way to -generate network policy-related alerts and to surface those alerts in GitLab. - -Several components work in concert for the agent to generate the alerts: - -- A working Kubernetes cluster. -- Cilium integration through either of these options: - - Installation through [cluster management template](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium). - - Enablement of [hubble-relay](https://docs.cilium.io/en/v1.8/concepts/overview/#hubble) on an - existing installation. -- One or more network policies through any of these options: - - Use the [Container Network Policy editor](../../application_security/policies/index.md#container-network-policy-editor) to create and manage policies. - - Use an [AutoDevOps](../../application_security/policies/index.md#container-network-policy) configuration. - - Add the required labels and annotations to existing network policies. -- A configuration repository with [Cilium configured in `config.yaml`](repository.md#surface-network-security-alerts-from-cluster-to-gitlab) +## Migrate to the agent from the legacy certificate-based integration -The setup process follows the same [agent's installation steps](install/index.md), -with the following differences: - -- When you define a configuration repository, you must do so with [Cilium settings](repository.md#surface-network-security-alerts-from-cluster-to-gitlab). -- You do not need to specify the `gitops` configuration section. +Read about how to [migrate to the agent for Kubernetes](../../infrastructure/clusters/migrate_to_gitlab_agent.md) from the certificate-based integration. ## Related topics +- [GitOps workflow](gitops.md) +- [GitLab CI/CD workflow](ci_cd_tunnel.md) +- [Install the agent](install/index.md) +- [Work with the agent](repository.md) - [Troubleshooting](troubleshooting.md) -- [Contribute to the GitLab agent's development](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/doc) +- [Contribute to the agent's development](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/doc) diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index 4d196e57f8f..fca80a4a291 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -4,92 +4,94 @@ 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 --- -# Install the GitLab Agent **(FREE)** +# Installing the agent for Kubernetes **(FREE)** > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5. > - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/594) multi-arch images in GitLab 14.8. The first multi-arch release is `v14.8.1`. It supports AMD64 and ARM64 architectures. +> - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/603) ARM architecture support in GitLab 14.9. -To connect a cluster to GitLab, you need to install the GitLab Agent -onto your cluster. +To connect a Kubernetes cluster to GitLab, you must install an agent in your cluster. ## Prerequisites -- An existing Kubernetes cluster. If you don't have a cluster yet, you can create a new cluster on cloud providers, such as: +Before you can install the agent in your cluster, you need: + +- An existing Kubernetes cluster. If you don't have a cluster, you can create one on a cloud provider, like: - [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine/docs/quickstart) - [Amazon Elastic Kubernetes Service (EKS)](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html) - [Digital Ocean](https://docs.digitalocean.com/products/kubernetes/quickstart/) -- On self-managed GitLab instances, a GitLab administrator needs to set up the [GitLab Agent Server (KAS)](../../../../administration/clusters/kas.md). +- On self-managed GitLab instances, a GitLab administrator must set up the [agent server](../../../../administration/clusters/kas.md). + On GitLab.com, the agent server is available at `wss://kas.gitlab.com`. ## Installation steps -To install the GitLab Agent on your cluster: +To install the agent in your cluster: -1. [Define a configuration repository](#define-a-configuration-repository). -1. [Register the Agent with GitLab](#register-the-agent-with-gitlab). -1. [Install the Agent onto the cluster](#install-the-agent-onto-the-cluster). +1. [Register the agent with GitLab](#register-the-agent-with-gitlab). +1. [Install the agent in your cluster](#install-the-agent-in-the-cluster). -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a GitLab 14.2 [walking-through video](https://www.youtube.com/watch?v=XuBpKtsgGkE) with this process. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a GitLab 14.2 [walk-through of this process](https://www.youtube.com/watch?v=XuBpKtsgGkE). -When you complete the installation process, you can -[view your Agent's status and activity information](#view-your-agents). -You can also [configure](#configure-the-agent) it to your needs. +### Register the agent with GitLab -### Define a configuration repository +> - [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. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347240) in GitLab 14.9, the agent can be registered without creating an agent configuration file. -> - [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. +You must register an agent with GitLab. -To create an Agent, you need a GitLab repository to hold its -configuration file. If you already have a repository holding your -cluster's manifest files, you can use it to store your -Agent's configuration file and sync them with no further steps. +Prerequisites: -#### Create the Agent's configuration file +- For a [GitLab CI/CD workflow](../ci_cd_tunnel.md), ensure that + [GitLab CI/CD is enabled](../../../../ci/enable_or_disable_ci.md#enable-cicd-in-a-project). -To create an Agent, go to the repository where you want to store -it and add the Agent's configuration file under: +To register an agent with GitLab: -```plaintext -.gitlab/agents/<agent-name>/config.yaml -``` +1. On the top bar, select **Menu > Projects** and find your project. +1. From the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. Select **Actions**. +1. From the **Select an agent** dropdown list: + - If you want to create a configuration with CI/CD defaults, type a name for the agent. + - If you already have an [agent configuration file](#create-an-agent-configuration-file), select it from the list. +1. Select **Register an agent**. +1. GitLab generates an access token for the agent. Securely store this token. You need it to install the agent in your cluster and to [update the agent](#update-the-agent-version) to another version. +1. Copy the command under **Recommended installation method**. You need it when you use the one-liner installation method to install the agent in your cluster. -You **don't have to add any content** to this file at the moment you -create it. The fact that the file exists tells GitLab that this is -an Agent. You can edit it later to [configure the Agent](#configure-the-agent). +### Create an agent configuration file -When creating this file, pay special attention to: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the agent configuration file can be added to multiple directories (or subdirectories) of the repository. +> - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. -- The [Agent's naming format](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md#agent-identity-and-name). -- The file extension: use the `.yaml` extension (`config.yaml`). The `.yml` extension is **not** recognized. +You can use an agent configuration file to specify details about your implementation. +Creating a file is optional but is needed if: -### Register the Agent with GitLab +- You use [a GitOps workflow](../gitops.md#gitops-configuration-reference) and you want a more advanced configuration. +- You use a GitLab CI/CD workflow. In that workflow, you must [authorize the agent](../ci_cd_tunnel.md#authorize-the-agent). -> [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. +To create an agent configuration file, go to the GitLab project. In the repository, create a file called `config.yaml` at this path: -Now that you've created your Agent's configuration file, register it -with GitLab. -When you register the Agent, GitLab generates a token that you need for -installing the Agent onto your cluster. +```plaintext +.gitlab/agents/<agent-name>/config.yaml +``` -In GitLab, go to the project where you added your Agent's configuration -file and: +- Ensure the agent name follows the [naming convention](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md#agent-identity-and-name). +- Ensure the filename has the `.yaml` file extension (`config.yaml`). The `.yml` extension is not accepted. +- Add content to the `config.yaml` file: + - For a GitOps workflow, view [the configuration reference](../gitops.md#gitops-configuration-reference) for details. + - For a GitLab CI/CD workflow, you can leave the file blank for now. -1. Ensure that [GitLab CI/CD is enabled in your project](../../../../ci/enable_or_disable_ci.md#enable-cicd-in-a-project). -1. From your project's sidebar, select **Infrastructure > Kubernetes clusters**. -1. Select **Actions**. -1. From the **Select an Agent** dropdown list, select the Agent you want to register and select **Register an Agent**. -1. GitLab generates a registration token for this Agent. Securely store this secret token, as you need it to install the Agent onto your cluster and to [update the Agent](#update-the-agent-version) to another version. -1. Copy the command under **Recommended installation method**. You need it to install the Agent onto your cluster through the one-liner installation method. +The agent bootstraps with the GitLab installation URL and an access token, +and you provide the rest of the configuration in your repository, following +Infrastructure as Code (IaaC) best practices. -### Install the Agent onto the cluster +### Install the agent in the cluster -To connect your cluster to GitLab, install the registered Agent -onto your cluster. To install it, you can use either: +To connect your cluster to GitLab, install the registered agent +in your cluster. To install it, you can use either: - [The one-liner installation method](#one-liner-installation). - [The advanced installation method](#advanced-installation). -You can use the one-liner installation for trying to use the Agent for the first time, to do internal setups with +You can use the one-liner installation for trying to use the agent for the first time, to do internal setups with high trust, and to quickly get started. For long-term production usage, you may want to use the advanced installation method to benefit from more configuration options. @@ -99,35 +101,45 @@ The one-liner installation is the simplest process, but you need Docker installed locally. If you don't have it, you can either install it or opt to the [advanced installation method](#advanced-installation). -To install the Agent on your cluster using the one-liner installation: +To install the agent on your cluster using the one-liner installation: -1. In your computer, open the terminal and connect to your cluster. +1. In your computer, open a terminal and [connect to your cluster](https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster/). 1. Run the command you copied when registering your cluster in the previous step. Optionally, you can [customize the one-liner installation command](#customize-the-one-liner-installation). ##### Customize the one-liner installation -The one-liner command generated by GitLab: +By default, the one-liner command generated by GitLab: -- Creates a namespace for the deployment (`gitlab-kubernetes-agent`). +- Creates a namespace for the deployment (`gitlab-agent`). - Sets up a service account with `cluster-admin` rights (see [how to restrict this service account](#customize-the-permissions-for-the-agentk-service-account)). -- Creates a `Secret` resource for the Agent's registration token. +- Creates a `Secret` resource for the agent's access token. - Creates a `Deployment` resource for the `agentk` pod. -You can edit these parameters according to your needs to customize the -one-liner installation command at the command line. To find all available -options, run in your terminal: +You can edit these parameters to customize the one-liner installation command. +To view all available options, open a terminal and run this command: ```shell docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help + +Usage: + cli generate [flags] + +Flags: + --agent-token string Access token registered for agent + --agent-version string Version of the agentk image to use (default "v14.8.1") + -h, --help help for generate + --kas-address string GitLab agent server for Kubernetes address + --name-prefix string The prefix to use for names of Kubernetes objects + --namespace string Kubernetes namespace to create resources in (default "gitlab-agent") + --no-rbac Do not include corresponding Roles and RoleBindings for the agent service account ``` 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. +Use `--agent-version stable` to refer to the latest stable +release at the time when the command runs. For production, however, +you should explicitly specify a matching version. #### Advanced installation @@ -135,105 +147,76 @@ For advanced installation options, use [the `kpt` installation method](https://g ##### Customize the permissions for the `agentk` service account -The GitLab Agent allows you to fully own your cluster and grant GitLab -the permissions you want. Still, to facilitate the process, by default the -generated manifests provide `cluster-admin` rights to the Agent. +You own your cluster and can grant GitLab the permissions you want. +By default, however, the generated manifests provide `cluster-admin` rights to the agent. -You can restrict the Agent's access rights using Kustomize overlays. [An example is commented out](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/build/deployment/gitlab-agent/cluster/kustomization.yaml) in the `kpt` package you retrieved as part of the installation. +You can restrict the agent's access rights by using Kustomize overlays. [An example is commented out](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/build/deployment/gitlab-agent/cluster/kustomization.yaml) in the `kpt` package you retrieved as part of the installation. -To create restricted permissions: +To restrict permissions: 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. -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. +#### Update the advanced installation base layer -## Configure the Agent +Now you can update from the upstream package by using `kpt pkg update gitlab-agent --strategy resource-merge`. +When the advanced installation setup changes, you will not need to change your custom overlays. -When successfully installed, you can [configure the Agent](../repository.md) -by editing its configuration file. -When you update the configuration file, GitLab transmits the -information to the cluster automatically without downtime. +## Install multiple agents in your cluster -## View your Agents +For total separation between teams, you might need to run multiple `agentk` instances in your cluster. +You might want multiple agents so you can restrict RBAC for every `agentk` deployment. -> The version of installed `agentk` shown on the Agent tab [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340882) in GitLab 14.8. -If you have at least the Developer role, you can access the Agent's -configuration repository and view the Agent's list: +To install multiple agents, follow the +[advanced installation steps](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent) +a second time and: -1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. -1. Select **Agent** tab to view clusters connected to GitLab through the Agent. +1. Change the agent name and create a new configuration file. +1. Register the new agent. You receive a new access token. Each token should be used only with one agent. +1. Change the namespace or prefix you use for the installation. -On this page, you can view: +You should also change the RBAC for the installed `agentk`. -- All the registered Agents for the current project. -- The connection status. -- The version of `agentk` installed on your cluster. -- The path to each Agent's configuration file. - -Furthermore, if you select one of the Agents on your list, you can view its -[activity information](#view-the-agents-activity-information). - -### View the Agent's activity information - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/277323) in GitLab 14.6. - -The activity logs help you to identify problems and get the information -you need for troubleshooting. You can see events from a week before the -current date. To access an Agent's activity: - -1. In your Agent's repository, go to the Agents list as described [above](#view-your-agents). -1. Select the Agent you want to see the activity. - -The activity list includes: - -- Agent registration events: when a new token is **created**. -- Connection events: when an Agent is successfully **connected** to a cluster. - -Note that the connection status is logged when you connect an Agent for -the first time or after more than an hour of inactivity. - -To check what else is planned for the Agent's UI and provide feedback, -see the [related epic](https://gitlab.com/groups/gitlab-org/-/epics/4739). +## Example projects -### View vulnerabilities in cluster images **(ULTIMATE)** +The following example projects can help you get started with the agent. -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6346) in GitLab 14.8 [with a flag](../../../../administration/feature_flags.md) named `cluster_vulnerabilities`. Enabled by default. +- [Configuration repository with minimal manifests](https://gitlab.com/gitlab-examples/ops/gitops-demo/k8s-agents) +- [Distinct application and manifest repository example](https://gitlab.com/gitlab-examples/ops/gitops-demo/hello-world-service-gitops) +- [Auto DevOps setup that uses the CI/CD workflow](https://gitlab.com/gitlab-examples/ops/gitops-demo/hello-world-service) +- [Cluster management project template example that uses the CI/CD workflow](https://gitlab.com/gitlab-examples/ops/gitops-demo/cluster-management) -Users with at least the [Developer role](../../../permissions.md) -can view cluster vulnerabilities. You can access them through the [vulnerability report](../../../application_security/vulnerabilities/index.md) -or in your cluster's image through the following process: +## Upgrades and version compatibility -1. Configure [cluster image scanning](../../../application_security/cluster_image_scanning/index.md) - to your build process. -1. Go to your Agent's configuration repository. -1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. -1. Select the **Agent** tab. -1. Select the Agent you want to see the vulnerabilities for. +The agent has two major components: `agentk` and `kas`. +GitLab provides `kas` installers built into the various GitLab installation methods. +The required `kas` version corresponds to the GitLab `major.minor` (X.Y) versions. - +At the same time, `agentk` and `kas` can differ by 1 minor version in either direction. For example, +`agentk` 14.4 supports `kas` 14.3, 14.4, and 14.5 (regardless of the patch). -## Create multiple Agents +A feature introduced in a given GitLab minor version might work with other `agentk` or `kas` versions. +To ensure it works, use at least the same `agentk` and `kas` minor version. For example, +if your GitLab version is 14.2, use at least `agentk` 14.2 and `kas` 14.2. -You can create and install multiple Agents using the same process -documented above. Give each Agent's configuration file a unique name -and you're good to go. You can create multiple Agents, for example: +We recommend upgrading your `kas` installations together with GitLab instances' upgrades, and to +[upgrade the `agentk` installations](#update-the-agent-version) after upgrading GitLab. -- To reach your cluster from different projects. -- To connect multiple clusters to GitLab. +The available `agentk` and `kas` versions are available in +[the Container Registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/). -## Update the Agent version +### Update the agent version -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340882) in GitLab 14.8, GitLab warns you on the Agent's list page to update the Agent version installed on your cluster. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340882) in GitLab 14.8, GitLab warns you on the agent's list page to update the agent version installed on your cluster. -To update the Agent's version on your cluster, you need to re-run the [installation command](#install-the-agent-onto-the-cluster) +To update the agent's version, re-run the [installation command](#install-the-agent-in-the-cluster) with a newer `--agent-version`. Make sure to specify the other required parameters: `--kas-address`, `--namespace`, and `--agent-token`. -You can find the available `agentk` versions in [the container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/1223205?sort=desc). +The available `agentk` versions are in [the Container Registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/1223205?sort=desc). -If you don't have access to your Agent's token, you can retrieve it from your cluster: +If you don't have access to your agent's access token, you can retrieve it from your cluster: -1. On your computer, open the terminal and connect to your cluster. +1. Open a terminal and connect to your cluster. 1. To retrieve the namespace, run: ```shell @@ -246,33 +229,8 @@ If you don't have access to your Agent's token, you can retrieve it from your cl kubectl -n <namespace> get secrets ``` -1. To retrieve the token, run: +1. To retrieve the access token, run: ```shell kubectl -n <namespace> get secret <secret-name> --template={{.data.token}} | base64 --decode ``` - -## Example projects - -The following example projects can help you get started with the Agent. - -- [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent) -- This basic GitOps example deploys NGINX: [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) - -## Upgrades and version compatibility - -The Agent is comprised of two major components: `agentk` and `kas`. -As we provide `kas` installers built into the various GitLab installation methods, the required `kas` version corresponds to the GitLab `major.minor` (X.Y) versions. - -At the same time, `agentk` and `kas` can differ by 1 minor version in either direction. For example, -`agentk` 14.4 supports `kas` 14.3, 14.4, and 14.5 (regardless of the patch). - -A feature introduced in a given GitLab minor version might work with other `agentk` or `kas` versions. -To make sure that it works, use at least the same `agentk` and `kas` minor version. For example, -if your GitLab version is 14.2, use at least `agentk` 14.2 and `kas` 14.2. - -We recommend upgrading your `kas` installations together with GitLab instances' upgrades, and to -[upgrade the `agentk` installations](#update-the-agent-version) after upgrading GitLab. - -The available `agentk` and `kas` versions can be found in -[the container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/). diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index a9d9fd1c13d..3f743d34e0a 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -1,335 +1,169 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Agent configuration repository **(FREE)** +# Working with the agent for Kubernetes **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7. -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the GitLab Agent became available on GitLab.com. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the GitLab agent became available on GitLab.com. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) the `ci_access` attribute in GitLab 14.3. > - [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. -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. +## View your agents -The Agent bootstraps with the GitLab installation URL and an authentication token, -and you provide the rest of the configuration in your repository, following -Infrastructure as Code (IaaC) best practices. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340882) in GitLab 14.8, the installed `agentk` version is displayed on the **Agent** tab. -A minimal repository layout looks like this, with `my-agent-1` as the name -of your Agent: +Prerequisite: -```plaintext -|- .gitlab - |- agents - |- my-agent-1 - |- config.yaml -``` - -Make sure that `<agent-name>` conforms to the [Agent's naming format](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md#agent-identity-and-name). +- You must have at least the Developer role. -## Synchronize manifest projects **(PREMIUM)** +To view the list of agents: -Your `config.yaml` file contains a `gitops` section, which contains a `manifest_projects` -section. Each `id` in the `manifest_projects` section is the path to a Git repository -with Kubernetes resource definitions in YAML or JSON format. The Agent monitors -each project you declare, and when the project changes, GitLab deploys the changes -using the Agent. +1. On the top bar, select **Menu > Projects** and find the project that contains your agent configuration file. +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. Select **Agent** tab to view clusters connected to GitLab through the agent. -WARNING: -When using separate GitLab projects for manifest files and configuration repository, the manifests project must be public. +On this page, you can view: -To use multiple YAML files, specify a `paths` attribute in the `gitops.manifest_projects` section. +- All the registered agents for the current project. +- The connection status. +- The version of `agentk` installed on your cluster. +- The path to each agent configuration file. -```yaml -gitops: - # Manifest projects are watched by the agent. Whenever a project changes, - # GitLab deploys the changes using the agent. - manifest_projects: - # No authentication mechanisms are currently supported. - # The `id` is a path to a Git repository with Kubernetes resource definitions - # in YAML or JSON format. - - id: gitlab-org/cluster-integration/gitlab-agent - # Namespace to use if not set explicitly in object manifest. - # Also used for inventory ConfigMap objects. - default_namespace: my-ns - # Paths inside of the repository to scan for manifest files. - # Directories with names starting with a dot are ignored. - paths: - # Read all .yaml files from team1/app1 directory. - # See https://github.com/bmatcuk/doublestar#about and - # https://pkg.go.dev/github.com/bmatcuk/doublestar/v2#Match for globbing rules. - - glob: '/team1/app1/*.yaml' - # Read all .yaml files from team2/apps and all subdirectories - - glob: '/team2/apps/**/*.yaml' - # If 'paths' is not specified or is an empty list, the configuration below is used - - glob: '/**/*.{yaml,yml,json}' - # Reconcile timeout defines whether the applier should wait - # until all applied resources have been reconciled, and if so, - # how long to wait. - reconcile_timeout: 3600s # 1 hour by default - # Dry run strategy defines whether changes should actually be performed, - # or if it is just talk and no action. - # https://github.com/kubernetes-sigs/cli-utils/blob/d6968048dcd80b1c7b55d9e4f31fc25f71c9b490/pkg/common/common.go#L68-L89 - # Can be: none, client, server - dry_run_strategy: none # 'none' by default - # Prune defines whether pruning of previously applied - # objects should happen after apply. - prune: true # enabled by default - # Prune timeout defines whether we should wait for all resources - # to be fully deleted after pruning, and if so, how long we should - # wait. - prune_timeout: 3600s # 1 hour by default - # Prune propagation policy defines the deletion propagation policy - # that should be used for pruning. - # https://github.com/kubernetes/apimachinery/blob/44113beed5d39f1b261a12ec398a356e02358307/pkg/apis/meta/v1/types.go#L456-L470 - # Can be: orphan, background, foreground - prune_propagation_policy: foreground # 'foreground' by default - # Inventory policy defines if an inventory object can take over - # objects that belong to another inventory object or don't - # belong to any inventory object. - # This is done by determining if the apply/prune operation - # can go through for a resource based on the comparison - # the inventory-id value in the package and the owning-inventory - # annotation (config.k8s.io/owning-inventory) in the live object. - # https://github.com/kubernetes-sigs/cli-utils/blob/d6968048dcd80b1c7b55d9e4f31fc25f71c9b490/pkg/inventory/policy.go#L12-L66 - # Can be: must_match, adopt_if_no_inventory, adopt_all - inventory_policy: must_match # 'must_match' by default -``` +## View an agent's activity information -### Using multiple manifest projects +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/277323) in GitLab 14.6. -Storing Kubernetes manifests in more than one repository can be handy, for example: +The activity logs help you to identify problems and get the information +you need for troubleshooting. You can see events from a week before the +current date. To view an agent's activity: -- You may store manifests for different applications in separate repositories. -- Different teams can work on manifests of independent projects in separate repositories. +1. On the top bar, select **Menu > Projects** and find the project that contains your agent configuration file. +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. Select the agent you want to see activity for. -To use multiple repositories as the source of Kubernetes manifests, specify them in the list of -`manifest_projects` in your `config.yaml`: +The activity list includes: -```yaml -gitops: - manifest_projects: - - id: group1/project1 - - id: group2/project2 -``` +- Agent registration events: When a new token is **created**. +- Connection events: When an agent is successfully **connected** to a cluster. -Note that repositories are synchronized **concurrently** and **independently** from each other, -which means that, ideally, there should **not** be any dependencies shared by these repositories. -Storing a logical group of manifests in a single repository may work better than distributing it across several -repositories. +The connection status is logged when you connect an agent for +the first time or after more than an hour of inactivity. -You cannot use a single repository as a source for multiple concurrent synchronization -operations. If such functionality is needed, you may use multiple agents reading -manifests from the same repository. +View and provide feedback about the UI in [this epic](https://gitlab.com/groups/gitlab-org/-/epics/4739). -Ensure not to specify "overlapping" globs to avoid synchronizing the same files more than once. -This is detected by the Agent and leads to an error. +## Debug the agent -INCORRECT - both globs match `*.yaml` files in the root directory: +To debug the cluster-side component (`agentk`) of the agent, set the log +level according to the available options: -```yaml -gitops: - manifest_projects: - - id: project1 - paths: - - glob: '/**/*.yaml' - - glob: '/*.yaml' -``` +- `off` +- `warning` +- `error` +- `info` +- `debug` -CORRECT - single globs matches all `*.yaml` files recursively: +The log level defaults to `info`. You can change it by using a top-level `observability` +section in the configuration file, for example: ```yaml -gitops: - manifest_projects: - - id: project1 - paths: - - glob: '/**/*.yaml' +observability: + logging: + level: debug ``` -## Authorize projects and groups to use an Agent - -With the [CI/CD Tunnel](ci_cd_tunnel.md), you can authorize [projects](#authorize-projects-to-use-an-agent) -and [groups](#authorize-groups-to-use-an-agent) to use an Agent. - -Then, you can reach your cluster from authorized projects and [run Kubernetes commands from GitLab CI/CD scripts](#run-kubectl-commands-using-the-cicd-tunnel) -in these projects. - -### Authorize projects to use an Agent - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327850) in GitLab 14.4. - -To grant projects access to the Agent through the CI/CD Tunnel: - -1. Go to your Agent's configuration repository. -1. Edit the Agent's configuration file (`config.yaml`). -1. Add the `projects` attribute into `ci_access`. -1. Identify the project through its path: - - ```yaml - ci_access: - projects: - - id: path/to/project +## Reset the agent token + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327152) in GitLab 14.9. + +To reset the agent token without downtime: + +1. Create a new token: + 1. On the top bar, select **Menu > Projects** and find your project. + 1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. + 1. Select the agent you want to create a token for. + 1. On the **Tokens** tab, select **Create token**. + 1. Enter token's name and description (optional) and select **Create token**. +1. Securely store the generated token. +1. Use the token to [install the agent in your cluster](install/index.md#install-the-agent-in-the-cluster) and to [update the agent](install/index.md#update-the-agent-version) to another version. +1. Delete the token you're no longer using. + +## Remove an agent + +You can remove an agent by using the [GitLab UI](#remove-an-agent-through-the-gitlab-ui) or the +[GraphQL API](#remove-an-agent-with-the-gitlab-graphql-api). The agent and any associated tokens +are removed from GitLab, but no changes are made in your Kubernetes cluster. You must +clean up those resources manually. + +### 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. On the top bar, select **Menu > Projects** and find the project that contains the agent configuration file. +1. From the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. In the table, in the row for your agent, in the **Options** column, select the vertical ellipsis (**{ellipsis_v}**). +1. Select **Delete agent**. + +### Remove an agent with the GitLab GraphQL API + +1. Get the `<cluster-agent-token-id>` from a query in the interactive GraphQL explorer. + - For GitLab.com, go to <https://gitlab.com/-/graphql-explorer> to open GraphQL Explorer. + - For self-managed GitLab, go to `https://gitlab.example.com/-/graphql-explorer`, replacing `gitlab.example.com` with your instance's URL. + + ```graphql + query{ + project(fullPath: "<full-path-to-agent-configuration-project>") { + clusterAgent(name: "<agent-name>") { + id + tokens { + edges { + node { + id + } + } + } + } + } + } ``` -### Authorize groups to use an Agent +1. Remove an agent record with GraphQL by deleting the `clusterAgentToken`. -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. + ```graphql + mutation deleteAgent { + clusterAgentDelete(input: { id: "<cluster-agent-id>" } ) { + errors + } + } -To grant access to all projects within a group: - -1. Go to your Agent's configuration repository. -1. Edit the Agent's configuration file (`config.yaml`). -1. Add the `groups` attribute into `ci_access`. -1. Identify the group or subgroup through its path: - - ```yaml - ci_access: - groups: - - id: path/to/group/subgroup + mutation deleteToken { + clusterAgentTokenDelete(input: { id: "<cluster-agent-token-id>" }) { + errors + } + } ``` -## Run `kubectl` commands using the CI/CD Tunnel - -After you authorize your project or group to use the Agent, you need to -configure the project's `.gitlab-ci.yaml` file to access the Agent. -This makes it possible to deploy applications to your cluster and run -any Kubernetes-specific commands from the authorized project. - -First, configure your Agent: - -1. Go to your Agent's configuration repository. -1. Edit your Agent's `config.yaml` file authorizing the [project](#authorize-projects-to-use-an-agent) or [group](#authorize-groups-to-use-an-agent) you want to run Kubernetes commands from. - -Then, configure the other project: - -1. Go to the project where you want to run Kubernetes commands from. -1. Edit your project's `.gitlab-ci.yml` file. -1. Set your Agent's context in the first command of the script with the format `path/to/agent/repository:agent-name`. -1. Run Kubernetes commands. - -For example: - -```yaml - deploy: - image: - name: bitnami/kubectl:latest - entrypoint: [""] - script: - - kubectl config use-context path/to/agent/repository:agent-name - - kubectl get pods -``` - -When you use the Agent, KubeContexts are named as `path/to/agent/repository:agent-name`. - -To get the list of available contexts: - -1. Open your terminal and connect to your cluster. -1. Run `kubectl config get-contexts`. - -### `kubectl` commands not supported - -The commands `kubectl exec`, `kubectl cp`, and `kubectl attach` are not supported by the CI/CD tunnel. -Anything else that uses the same API endpoints does not work either as they use the deprecated -SPDY protocol. -We [plan to add support for these features](https://gitlab.com/gitlab-org/gitlab/-/issues/346248) -in a future version of GitLab. - -### `kubectl` requires TLS - -`kubectl` would never send credentials over an unencrypted connection. Self-managed users should ensure that their -GitLab instance is configured with TLS for the CI/CD tunnel feature to work. Trying to use it without TLS -would produce errors: - -```shell -$ kubectl get pods -error: You must be logged in to the server (the server has asked for the client to provide credentials) -``` - -## Use impersonation to restrict project and group access **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345014) in GitLab 14.5. - -By default, the [CI/CD Tunnel](ci_cd_tunnel.md) inherits all the permissions from the service account used to install the -Agent in the cluster. -To restrict access to your cluster, you can use [impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation). - -To specify impersonations, use the `access_as` attribute in your Agent's configuration file and use Kubernetes RBAC rules to manage impersonated account permissions. - -You can impersonate: - -- The Agent itself (default). -- The CI job that accesses the cluster. -- A specific user or system account defined within the cluster. - -### Impersonate the Agent - -The Agent is impersonated by default. You don't need to do anything to impersonate it. - -### Impersonate the CI job that accesses the cluster - -To impersonate the CI job that accesses the cluster, add the `ci_job: {}` key-value -under the `access_as` key. - -When the agent makes the request to the actual Kubernetes API, it sets the -impersonation credentials in the following way: - -- `UserName` is set to `gitlab:ci_job:<job id>`. Example: `gitlab:ci_job:1074499489`. -- `Groups` is set to: - - `gitlab:ci_job` to identify all requests coming from CI jobs. - - The list of IDs of groups the project is in. - - The project ID. - - The slug of the environment this job belongs to. +1. Verify whether the removal occurred successfully. If the output in the Pod logs includes `unauthenticated`, it means that the agent was successfully removed: - Example: for a CI job in `group1/group1-1/project1` where: - - - Group `group1` has ID 23. - - Group `group1/group1-1` has ID 25. - - Project `group1/group1-1/project1` has ID 150. - - Job running in a prod environment. - - Group list would be `[gitlab:ci_job, gitlab:group:23, gitlab:group:25, gitlab:project:150, gitlab:project_env:150:prod]`. - -- `Extra` carries extra information about the request. The following properties are set on the impersonated identity: - -| Property | Description | -| -------- | ----------- | -| `agent.gitlab.com/id` | Contains the agent ID. | -| `agent.gitlab.com/config_project_id` | Contains the agent's configuration project ID. | -| `agent.gitlab.com/project_id` | Contains the CI project ID. | -| `agent.gitlab.com/ci_pipeline_id` | Contains the CI pipeline ID. | -| `agent.gitlab.com/ci_job_id` | Contains the CI job ID. | -| `agent.gitlab.com/username` | Contains the username of the user the CI job is running as. | -| `agent.gitlab.com/environment_slug` | Contains the slug of the environment. Only set if running in an environment. | - -Example to restrict access by the CI job's identity: - -```yaml -ci_access: - projects: - - id: path/to/project - access_as: - ci_job: {} -``` - -### Impersonate a static identity - -For the given CI/CD Tunnel connection, you can use a static identity for the impersonation. - -Add the `impersonate` key under the `access_as` key to make the request using the provided identity. - -The identity can be specified with the following keys: + ```json + { + "level": "warn", + "time": "2021-04-29T23:44:07.598Z", + "msg": "GetConfiguration.Recv failed", + "error": "rpc error: code = Unauthenticated desc = unauthenticated" + } + ``` -- `username` (required) -- `uid` -- `groups` -- `extra` +1. Delete the agent in your cluster: -See the [official Kubernetes documentation for more details](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation) on the usage of these keys. + ```shell + kubectl delete -n gitlab-kubernetes-agent -f ./resources.yml + ``` ## Surface network security alerts from cluster to GitLab **(ULTIMATE)** @@ -340,7 +174,28 @@ Cilium integration is in its end-of-life process. It's [deprecated](https://gitl for use in GitLab 14.8, and planned for [removal](https://gitlab.com/groups/gitlab-org/-/epics/7477) in GitLab 15.0. -The GitLab Agent provides an [integration with Cilium](index.md#kubernetes-network-security-alerts). +The agent for Kubernetes also provides an integration with Cilium. This integration provides a simple way to +generate network policy-related alerts and to surface those alerts in GitLab. + +Several components work in concert for the agent to generate the alerts: + +- A working Kubernetes cluster. +- Cilium integration through either of these options: + - Installation through [cluster management template](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium). + - Enablement of [hubble-relay](https://docs.cilium.io/en/v1.8/concepts/overview/#hubble) on an + existing installation. +- One or more network policies through any of these options: + - Use the [Container Network Policy editor](../../application_security/policies/index.md#container-network-policy-editor) to create and manage policies. + - Use an [AutoDevOps](../../application_security/policies/index.md#container-network-policy) configuration. + - Add the required labels and annotations to existing network policies. +- A configuration repository with [Cilium configured in `config.yaml`](repository.md#surface-network-security-alerts-from-cluster-to-gitlab) + +The setup process follows the same [agent's installation steps](install/index.md), +with the following differences: + +- When you define a configuration repository, you must do so with [Cilium settings](repository.md#surface-network-security-alerts-from-cluster-to-gitlab). +- You do not need to specify the `gitops` configuration section. + To integrate, add a top-level `cilium` section to your `config.yml` file. Currently, the only configuration option is the Hubble relay address: @@ -357,107 +212,3 @@ you can use `hubble-relay.gitlab-managed-apps.svc.cluster.local:80` as the addre cilium: hubble_relay_address: "hubble-relay.gitlab-managed-apps.svc.cluster.local:80" ``` - -## Scan your container images for vulnerabilities **(ULTIMATE)** - -You can use [cluster image scanning](../../application_security/cluster_image_scanning/index.md) -to scan container images in your cluster for security vulnerabilities. - -To begin scanning all resources in your cluster, add a `starboard` -configuration block to your agent's `config.yaml` with no `filters`: - -```yaml -starboard: - vulnerability_report: - filters: [] -``` - -The namespaces that are able to be scanned depend on the [Starboard Operator install mode](https://aquasecurity.github.io/starboard/latest/operator/configuration/#install-modes). -By default, the Starboard Operator only scans resources in the `default` namespace. To change this -behavior, edit the `STARBOARD_OPERATOR` environment variable in the `starboard-operator` deployment -definition. - -By adding filters, you can limit scans by: - -- Resource name -- Kind -- Container name -- Namespace - -```yaml -starboard: - vulnerability_report: - filters: - - namespaces: - - staging - - production - kinds: - - Deployment - - DaemonSet - containers: - - ruby - - postgres - - nginx - resources: - - my-app-name - - postgres - - ingress-nginx -``` - -A resource is scanned if the resource matches any of the given names and all of the given filter -types (`namespaces`, `kinds`, `containers`, `resources`). If a filter type is omitted, then all -names are scanned. In this example, a resource isn't scanned unless it has a container named `ruby`, -`postgres`, or `nginx`, and it's a `Deployment`: - -```yaml -starboard: - vulnerability_report: - filters: - - kinds: - - Deployment - containers: - - ruby - - postgres - - nginx -``` - -There is also a global `namespaces` field that applies to all filters: - -```yaml -starboard: - vulnerability_report: - namespaces: - - production - filters: - - kinds: - - Deployment - - kinds: - - DaemonSet - resources: - - log-collector -``` - -In this example, the following resources are scanned: - -- All deployments (`Deployment`) in the `production` namespace -- All daemon sets (`DaemonSet`) named `log-collector` in the `production` namespace - -## Debugging - -To debug the cluster-side component (`agentk`) of the Agent, set the log -level according to the available options: - -- `off` -- `warning` -- `error` -- `info` -- `debug` - -The log level defaults to `info`. You can change it by using a top-level `observability` -section in the configuration file, for example: - -```yaml -observability: - logging: - level: debug -``` diff --git a/doc/user/clusters/agent/runner.md b/doc/user/clusters/agent/runner.md deleted file mode 100644 index c40733bd7a5..00000000000 --- a/doc/user/clusters/agent/runner.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'https://docs.gitlab.com/runner/install/kubernetes-agent.html' -remove_date: '2022-02-01' ---- - -This document was moved to [another location](https://docs.gitlab.com/runner/install/kubernetes-agent.html). - -<!-- This redirect file can be deleted after <2022-02-01>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
\ No newline at end of file diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md index 2c9f98b7c45..a5e568837ad 100644 --- a/doc/user/clusters/agent/troubleshooting.md +++ b/doc/user/clusters/agent/troubleshooting.md @@ -4,9 +4,9 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Troubleshooting the GitLab Agent for Kubernetes +# Troubleshooting the GitLab agent for Kubernetes -When you are using the GitLab Agent for Kubernetes, you might experience issues you need to troubleshoot. +When you are using the GitLab agent for Kubernetes, you might experience issues you need to troubleshoot. You can start by viewing the service logs: @@ -14,7 +14,7 @@ You can start by viewing the service logs: kubectl logs -f -l=app=gitlab-agent -n gitlab-kubernetes-agent ``` -If you are a GitLab administrator, you can also view the [GitLab Agent Server logs](../../../administration/clusters/kas.md#troubleshooting). +If you are a GitLab administrator, you can also view the [GitLab agent server logs](../../../administration/clusters/kas.md#troubleshooting). ## Transport: Error while dialing failed to WebSocket dial @@ -28,7 +28,7 @@ If you are a GitLab administrator, you can also view the [GitLab Agent Server lo ``` This error is shown if there are some connectivity issues between the address -specified as `kas-address`, and your Agent pod. To fix it, make sure that you +specified as `kas-address`, and your agent pod. To fix it, make sure that you specified the `kas-address` correctly. ```json @@ -188,6 +188,5 @@ Alternatively, you can mount the certificate file at a different location and in } ``` -This error is shown if the manifest project is not public. To fix it, -[make sure your manifest project is public](repository.md#synchronize-manifest-projects) or your manifest files -are stored in the Agent's configuration repository. +This error is shown if the manifest project is not public. To fix it, make sure your manifest project is public or your manifest files +are stored in the agent's configuration repository. diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md new file mode 100644 index 00000000000..480b09ff2ab --- /dev/null +++ b/doc/user/clusters/agent/vulnerabilities.md @@ -0,0 +1,113 @@ +--- +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 +--- + +# Container vulnerability scanning **(ULTIMATE)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6346) in GitLab 14.8. + +To view cluster vulnerabilities, you can view the [vulnerability report](../../application_security/vulnerabilities/index.md). +You can also configure your agent so the vulnerabilities are displayed with other agent information in GitLab. + +## View cluster vulnerabilities + +Prerequisite: + +- You must have at least the Developer role. +- [Cluster image scanning](../../application_security/cluster_image_scanning/index.md) + must be part of your build process. + +To view vulnerability information in GitLab: + +1. On the top bar, select **Menu > Projects** and find the project that contains the agent configuration file. +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. Select the **Agent** tab. +1. Select the agent you want to see the vulnerabilities for. + + + +## Enable cluster vulnerability scanning **(ULTIMATE)** + +You can use [cluster image scanning](../../application_security/cluster_image_scanning/index.md) +to scan container images in your cluster for security vulnerabilities. + +To begin scanning all resources in your cluster, add a `starboard` +configuration block to your agent configuration file with no `filters`: + +```yaml +starboard: + vulnerability_report: + filters: [] +``` + +The namespaces that are able to be scanned depend on the [Starboard Operator install mode](https://aquasecurity.github.io/starboard/latest/operator/configuration/#install-modes). +By default, the Starboard Operator only scans resources in the `default` namespace. To change this +behavior, edit the `STARBOARD_OPERATOR` environment variable in the `starboard-operator` deployment +definition. + +By adding filters, you can limit scans by: + +- Resource name +- Kind +- Container name +- Namespace + +```yaml +starboard: + vulnerability_report: + filters: + - namespaces: + - staging + - production + kinds: + - Deployment + - DaemonSet + containers: + - ruby + - postgres + - nginx + resources: + - my-app-name + - postgres + - ingress-nginx +``` + +A resource is scanned if the resource matches any of the given names and all of the given filter +types (`namespaces`, `kinds`, `containers`, `resources`). If a filter type is omitted, then all +names are scanned. In this example, a resource isn't scanned unless it has a container named `ruby`, +`postgres`, or `nginx`, and it's a `Deployment`: + +```yaml +starboard: + vulnerability_report: + filters: + - kinds: + - Deployment + containers: + - ruby + - postgres + - nginx +``` + +There is also a global `namespaces` field that applies to all filters: + +```yaml +starboard: + vulnerability_report: + namespaces: + - production + filters: + - kinds: + - Deployment + - kinds: + - DaemonSet + resources: + - log-collector +``` + +In this example, the following resources are scanned: + +- All deployments (`Deployment`) in the `production` namespace. +- All daemon sets (`DaemonSet`) named `log-collector` in the `production` namespace. diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index f880e603133..2bcfea50ee3 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -980,7 +980,7 @@ podAnnotations: The only information to be changed here is the profile name which is `profile-one` in this example. Refer to the -[AppArmor tutorial](https://kubernetes.io/docs/tutorials/clusters/apparmor/#securing-a-pod) +[AppArmor tutorial](https://kubernetes.io/docs/tutorials/security/apparmor/#securing-a-pod) for more information on how AppArmor is integrated in Kubernetes. #### Using PodSecurityPolicy in your deployments @@ -1017,7 +1017,7 @@ securityPolicies: ``` This example creates a single policy named `example` with the provided specification, -and enables [AppArmor annotations](https://kubernetes.io/docs/tutorials/clusters/apparmor/#podsecuritypolicy-annotations) on it. +and enables [AppArmor annotations](https://kubernetes.io/docs/tutorials/security/apparmor/#podsecuritypolicy-annotations) on it. Support for installing the AppArmor managed application is provided by the GitLab Container Security group. If you run into unknown issues, diff --git a/doc/user/clusters/create/index.md b/doc/user/clusters/create/index.md new file mode 100644 index 00000000000..bee622ac50a --- /dev/null +++ b/doc/user/clusters/create/index.md @@ -0,0 +1,13 @@ +--- +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 +--- + +# Create Kubernetes clusters + +You can use Infrastructure as Code (IaC) to create clusters on cloud providers. +You connect the clusters to GitLab by using the agent for Kubernetes. + +- [Create a cluster on Google GKE](../../infrastructure/clusters/connect/new_gke_cluster.md) +- [Create a cluster on Amazon EKS](../../infrastructure/clusters/connect/new_eks_cluster.md) diff --git a/doc/user/clusters/crossplane.md b/doc/user/clusters/crossplane.md index e6540e68f71..9e4c672ac45 100644 --- a/doc/user/clusters/crossplane.md +++ b/doc/user/clusters/crossplane.md @@ -80,7 +80,7 @@ provided can manage resources in the `database.crossplane.io` API group: ## Configure Crossplane with a cloud provider -See [Configure Your Cloud Provider Account](https://crossplane.github.io/docs/v0.4/cloud-providers.html) +See [Configure Your Cloud Provider Account](https://crossplane.github.io/docs/v1.6/) to configure the installed cloud provider stack with a user account. The Secret, and the Provider resource referencing the Secret, must be diff --git a/doc/user/clusters/img/kubernetes-agent-ui-list_v14_8.png b/doc/user/clusters/img/kubernetes-agent-ui-list_v14_8.png Binary files differdeleted file mode 100644 index 5b5ba3a9804..00000000000 --- a/doc/user/clusters/img/kubernetes-agent-ui-list_v14_8.png +++ /dev/null diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md index ee7452537fd..74f6ec283ea 100644 --- a/doc/user/clusters/integrations.md +++ b/doc/user/clusters/integrations.md @@ -32,9 +32,9 @@ to automate this step. Prometheus and Elastic Stack cluster integrations can only be enabled for clusters [connected through cluster certificates](../project/clusters/add_existing_cluster.md). -To enable Prometheus for your cluster connected through the [GitLab Agent](agent/index.md), you can [integrate it manually](../project/integrations/prometheus.md#manual-configuration-of-prometheus). +To enable Prometheus for your cluster connected through the [GitLab agent](agent/index.md), you can [integrate it manually](../project/integrations/prometheus.md#manual-configuration-of-prometheus). -There is no option to enable Elastic Stack for your cluster if it is connected with the GitLab Agent. +There is no option to enable Elastic Stack for your cluster if it is connected with the GitLab agent. Follow this [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/300230) for updates. ## Prometheus cluster integration @@ -44,7 +44,7 @@ Follow this [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/300230) for up WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. However, you can **still use** Prometheus for Kubernetes clusters connected to GitLab through the -[Agent](agent/index.md) by [enabling Prometheus manually](../project/integrations/prometheus.md#manual-configuration-of-prometheus). +[agent](agent/index.md) by [enabling Prometheus manually](../project/integrations/prometheus.md#manual-configuration-of-prometheus). You can integrate your Kubernetes cluster with [Prometheus](https://prometheus.io/) for monitoring key metrics of your @@ -113,9 +113,9 @@ To use this integration: `gitlab-managed-apps` namespace. 1. The `Service` resource must be called `elastic-stack-elasticsearch-master` and expose the Elasticsearch API on port `9200`. -1. The logs are expected to be [Filebeat container logs](https://www.elastic.co/guide/en/beats/filebeat/7.x/filebeat-input-container.html) - following the [7.x log structure](https://www.elastic.co/guide/en/beats/filebeat/7.x/exported-fields-log.html) - and include [Kubernetes metadata](https://www.elastic.co/guide/en/beats/filebeat/7.x/add-kubernetes-metadata.html). +1. The logs are expected to be [Filebeat container logs](https://www.elastic.co/guide/en/beats/filebeat/7.16/filebeat-input-container.html) + following the [7.x log structure](https://www.elastic.co/guide/en/beats/filebeat/7.16/exported-fields-log.html) + and include [Kubernetes metadata](https://www.elastic.co/guide/en/beats/filebeat/7.16/add-kubernetes-metadata.html). You can manage your Elastic Stack however you like, but as an example, you can use [this Elastic Stack chart](https://gitlab.com/gitlab-org/charts/elastic-stack) to get up and diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index e28f9275b50..7658bc41dd9 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: The cluster management project was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To manage cluster applications, use the [GitLab Agent](agent/index.md) +To manage cluster applications, use the [GitLab agent](agent/index.md) with the [Cluster Management Project Template](management_project_template.md). A project can be designated as the management project for a cluster. diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md index 2d7e89ef765..ab17e462c6a 100644 --- a/doc/user/clusters/management_project_template.md +++ b/doc/user/clusters/management_project_template.md @@ -8,89 +8,53 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25318) in GitLab 12.10 with Helmfile support via Helm v2. > - Helm v2 support was [dropped](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63577) in GitLab 14.0. Use Helm v3 instead. -> - [Migrated](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/24) to the GitLab Agent in GitLab 14.5. +> - [Migrated](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/24) to the GitLab agent in GitLab 14.5. -Use a repository to install, manage, and deploy clusters applications through code. +GitLab provides a cluster management project template, which you use +to create a project. The project includes cluster applications that integrate with GitLab +and extend GitLab functionality. You can use the pattern shown in the project to extend +your custom cluster applications. -## Cluster Management Project Template +## Use one project for the agent and your manifests -The Cluster Management Project Template provides you a baseline to get -started and flexibility to customize your project to your cluster's needs. -For instance, you can: +If you **have not yet** used the agent to connect your cluster with GitLab: -- Extend the CI/CD configuration. -- Configure the built-in cluster applications. -- Remove the built-in cluster applications you don't need. -- Add other cluster applications using the same structure as the ones already available. +1. [Create a project from the cluster management project template](#create-a-project-based-on-the-cluster-management-project-template). +1. [Configure the project for the agent](agent/install/index.md). +1. In your project's settings, create an + [environment variable](../../ci/variables/index.md#add-a-cicd-variable-to-a-project) named `$KUBE_CONTEXT` + and set the value to `path/to/agent-configuration-project:your-agent-name`. +1. [Configure the files](#configure-the-project) as needed. -The template contains the following [components](#configure-the-available-components): +## Use separate projects for the agent and your manifests -- A pre-configured GitLab CI/CD file so that you can configure CI/CD pipelines using the [CI/CD Tunnel](agent/ci_cd_tunnel.md). -- A pre-configured [Helmfile](https://github.com/roboll/helmfile) so that -you can manage cluster applications with [Helm v3](https://helm.sh/). -- An `applications` directory with a `helmfile.yaml` configured for each -application available in the template. +If you have already configured the agent and connected a cluster with GitLab: -## Use the Agent with the Cluster Management Project Template +1. [Create a project from the cluster management project template](#create-a-project-based-on-the-cluster-management-project-template). +1. In the project where you configured your agent, + [grant the agent access to the new project](agent/ci_cd_tunnel.md#authorize-the-agent). +1. In the new project, create an + [environment variable](../../ci/variables/index.md#add-a-cicd-variable-to-a-project) named `$KUBE_CONTEXT` + and set the value to `path/to/agent-configuration-project:your-agent-name`. +1. In the new project, [configure the files](#configure-the-project) as needed. -To use a new project created from the Cluster Management Project Template -with a cluster connected to GitLab through the [GitLab Agent](agent/index.md), -you have two options: +## Create a project based on the cluster management project template -- [Use one single project](#single-project) to configure the Agent and manage cluster applications. -- [Use separate projects](#separate-projects) - one to configure the Agent and another to manage cluster applications. +To create a project from the cluster management project template: -### Single project +1. On the top bar, select **Menu > Projects > Create new project**. +1. Select **Create from template**. +1. From the list of templates, next to **GitLab Cluster Management**, select **Use template**. +1. Enter the project details. +1. Select **Create project**. -This setup is particularly useful when you haven't connected your cluster -to GitLab through the Agent yet and you want to use the Cluster Management -Project Template to manage cluster applications. +If you use self-managed GitLab, your instance might not include the latest version of the template. +In that case, select **Import project**, **Repo by URL** and for the **Git repository URL**, enter +`https://gitlab.com/gitlab-org/project-templates/cluster-management.git`. -To use one single project to configure the Agent and to manage cluster applications: +## Configure the project -1. [Create a new project from the Cluster Management Project Template](#create-a-new-project-based-on-the-cluster-management-template). -1. Configure the new project as the [Agent's configuration repository](agent/repository.md) -(where the Agent is registered and its `config.yaml` is stored). -1. From your project's settings, add a [new environment variable](../../ci/variables/index.md#add-a-cicd-variable-to-a-project) `$KUBE_CONTEXT` and set it to `path/to/agent-configuration-project:your-agent-name`. -1. [Configure the components](#configure-the-available-components) inherited from the template. - -### Separate projects - -This setup is particularly useful **when you already have a cluster** connected -to GitLab through the Agent and want to use the Cluster Management -Project Template to manage cluster applications. - -To use one project to configure the Agent ("project A") and another project to -manage cluster applications ("project B"), follow the steps below. - -We assume that you already have a cluster connected through the Agent and -[configured through the Agent's configuration repository](agent/repository.md) -("project A"). - -1. [Create a new project from the Cluster Management Project Template](#create-a-new-project-based-on-the-cluster-management-template). -This new project is "project B". -1. In your "project A", [grant the Agent access to the new project (B) through the CI/CD Tunnel](agent/repository.md#authorize-projects-to-use-an-agent). -1. From the "project's B" settings, add a [new environment variable](../../ci/variables/index.md#add-a-cicd-variable-to-a-project) `$KUBE_CONTEXT` and set it to `path/to/agent-configuration-project:your-agent-name`. -1. In "project B", [configure the components](#configure-the-available-components) inherited from the template. - -## Create a new project based on the Cluster Management Template - -To get started, create a new project based on the Cluster Management -project template to use as a cluster management project. - -You can either create the new project from the template or import the -project from the URL. Importing the project is useful if you are using -a GitLab self-managed instance that may not have the latest version of -the template. - -To [create the new project](../project/working_with_projects.md#create-a-project): - -- From the template: select the **GitLab Cluster Management** project template. -- Importing from the URL: use `https://gitlab.com/gitlab-org/project-templates/cluster-management.git`. - -## Configure the available components - -Use the available components to configure your cluster applications: +After you use the cluster management template to create a project, you can configure: - [The `.gitlab-ci.yml` file](#the-gitlab-ciyml-file). - [The main `helmfile.yml` file](#the-main-helmfileyml-file). @@ -98,22 +62,22 @@ Use the available components to configure your cluster applications: ### The `.gitlab-ci.yml` file -The base image used in your pipeline is built by the [cluster-applications](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications) -project. This image consists of a set of Bash utility scripts to support [Helm v3 releases](https://helm.sh/docs/intro/using_helm/#three-big-concepts): +The `.gitlab-ci.yml` file: -- `gl-fail-if-helm2-releases-exist {namespace}`: It tries to detect whether you have apps deployed through Helm v2 - releases for a given namespace. If so, it will fail the pipeline and ask you to manually - [migrate your Helm v2 releases to Helm v3](https://helm.sh/docs/topics/v2_v3_migration/). -- `gl-ensure-namespace {namespace}`: It creates the given namespace if it does not exist and adds the necessary label - for the [Cilium](https://github.com/cilium/cilium/) app network policies to work. -- `gl-adopt-resource-with-helm-v3 {arguments}`: Used only internally in the [cert-manager's](https://cert-manager.io/) Helmfile to - facilitate the GitLab Managed Apps adoption. -- `gl-adopt-crds-with-helm-v3 {arguments}`: Used only internally in the [cert-manager's](https://cert-manager.io/) Helmfile to - facilitate the GitLab Managed Apps adoption. -- `gl-helmfile {arguments}`: A thin wrapper that triggers the [Helmfile](https://github.com/roboll/helmfile) command. +- Ensures you are on Helm version 3. +- Deploys the enabled applications from the project. + +You can edit and extend the pipeline definitions. + +The base image used in the pipeline is built by the +[cluster-applications](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications) project. +This image contains a set of Bash utility scripts to support [Helm v3 releases](https://helm.sh/docs/intro/using_helm/#three-big-concepts). ### The main `helmfile.yml` file +The template contains a [Helmfile](https://github.com/roboll/helmfile) you can use to manage +cluster applications with [Helm v3](https://helm.sh/). + This file has a list of paths to other Helmfiles for each app. They're all commented out by default, so you must uncomment the paths for the apps that you would like to use in your cluster. @@ -124,6 +88,9 @@ from your cluster. [Read more](https://github.com/roboll/helmfile) about how Hel ### Built-in applications +The template contains an `applications` directory with a `helmfile.yaml` configured for each +application in the template. + The [built-in supported applications](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/tree/master/applications) are: - [Apparmor](../infrastructure/clusters/manage/management_project_applications/apparmor.md) @@ -138,8 +105,8 @@ The [built-in supported applications](https://gitlab.com/gitlab-org/project-temp - [Sentry](../infrastructure/clusters/manage/management_project_applications/sentry.md) - [Vault](../infrastructure/clusters/manage/management_project_applications/vault.md) -#### Customize your applications +Each application has an `applications/{app}/values.yaml` file. +For GitLab Runner, the file is `applications/{app}/values.yaml.gotmpl`. -Each app has an `applications/{app}/values.yaml` file (`applications/{app}/values.yaml.gotmpl` in case of GitLab Runner). This is the -place where you can define default values for your app's Helm chart. Some apps already have defaults -pre-defined by GitLab. +In this file, you can define default values for your app's Helm chart. +Some apps already have defaults defined. diff --git a/doc/user/clusters/migrating_from_gma_to_project_template.md b/doc/user/clusters/migrating_from_gma_to_project_template.md index b2ba1bef338..09453262fbb 100644 --- a/doc/user/clusters/migrating_from_gma_to_project_template.md +++ b/doc/user/clusters/migrating_from_gma_to_project_template.md @@ -20,7 +20,7 @@ To migrate from GitLab Managed Apps to a Cluster Management Project, follow the steps below. See also [video walk-throughs](#video-walk-throughs) with examples. -1. Create a new project based on the [Cluster Management Project template](management_project_template.md#create-a-new-project-based-on-the-cluster-management-template). +1. Create a new project based on the [Cluster Management Project template](management_project_template.md#create-a-project-based-on-the-cluster-management-project-template). 1. [Associate your new Cluster Management Project with your cluster](management_project.md#associate-the-cluster-management-project-with-the-cluster). 1. Detect apps deployed through Helm v2 releases by using the pre-configured [`.gitlab-ci.yml`](management_project_template.md#the-gitlab-ciyml-file) file: - In case you had overwritten the default GitLab Managed Apps namespace, edit `.gitlab-ci.yml`, @@ -120,7 +120,7 @@ you want to manage with the Cluster Management Project. ## Backup and uninstall cert-manager v0.10 -1. Follow the [official docs](https://docs.cert-manager.io/en/release-0.10/tasks/backup-restore-crds.html) on how to +1. Follow the [official docs](https://cert-manager.io/docs/tutorials/backup/) on how to backup your cert-manager v0.10 data. 1. Uninstall cert-manager by editing the setting all the occurrences of `installed: true` to `installed: false` in the `applications/cert-manager/helmfile.yaml` file. diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md index d98a0a145f2..27783a063da 100644 --- a/doc/user/compliance/compliance_report/index.md +++ b/doc/user/compliance/compliance_report/index.md @@ -105,3 +105,64 @@ You can generate a commit-specific Chain of Custody report for a given commit SH NOTE: The Chain of Custody report download is a CSV file, with a maximum size of 15 MB. The remaining records are truncated when this limit is reached. + +## Merge request violations + +> - Introduced in GitLab 14.6. [Deployed behind the `compliance_violations_report` flag](../../../administration/feature_flags.md). Disabled by default. +> - GraphQL API [introduced](https://gitlab.com/groups/gitlab-org/-/epics/7222) in GitLab 14.9. + +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 `compliance_violations_report`. +On GitLab.com, this feature is not available. This feature is not ready for production use. + +Merge request violations provide a view of all the [separation of duties](#approval-status-and-separation-of-duties) compliance violations +that exist in projects in a specific group. For each separation of duties compliance violation, you can see: + +- A list of compliance violations. +- The severity of each compliance violation. +- Reason for the compliance violation. +- A link to the merge request that caused the compliance violation. + +Merge request violations can be accessed: + +- In the GitLab UI. +- Using the [GraphQL API](../../../api/graphql/reference/index.md#complianceviolation) (GitLab 14.9 and later). + +### View merge request violations + +To view merge request violations: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Security & Compliance > Compliance report**. + +### Severity levels scale + +The following is a list of available violation severity levels, ranked from most to least severe: + +| Icon | Severity level | +|:----------------------------------------------|:---------------| +| **{severity-critical, 18, gl-fill-red-800}** | Critical | +| **{severity-high, 18, gl-fill-red-600}** | High | +| **{severity-medium, 18, gl-fill-orange-400}** | Medium | +| **{severity-low, 18, gl-fill-orange-300}** | Low | +| **{severity-info, 18, gl-fill-blue-400}** | Info | + +### Violation types + +The following is a list of violations that are either: + +- Already available. +- Aren't available, but which we are tracking in issues. + +| Violation | Severity level | Category | Description | Availability | +|:-------------------------------------|:----------------|:----------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------| +| Author approved merge request | High | [Separation of duties](#approval-status-and-separation-of-duties) | The author of the merge request approved their own merge request. [Learn more](../../project/merge_requests/approvals/settings.md#prevent-approval-by-author). | [Unavailable](https://gitlab.com/groups/gitlab-org/-/epics/6870) | +| Committers approved merge request | High | [Separation of duties](#approval-status-and-separation-of-duties) | The committers of the merge request approved the merge request they contributed to. [Learn more](../../project/merge_requests/approvals/settings.md#prevent-approvals-by-users-who-add-commits). | [Unavailable](https://gitlab.com/groups/gitlab-org/-/epics/6870) | +| Fewer than two approvals | High | [Separation of duties](#approval-status-and-separation-of-duties) | The merge request was merged with fewer than two approvals. [Learn more](../../project/merge_requests/approvals/rules.md). | [Unavailable](https://gitlab.com/groups/gitlab-org/-/epics/6870) | +| Pipeline failed | Medium | [Pipeline results](../../../ci/pipelines/index.md) | The merge requests pipeline failed and was merged. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | +| Pipeline passed with warnings | Info | [Pipeline results](../../../ci/pipelines/index.md) | The merge request pipeline passed with warnings and was merged. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | +| Code coverage down more than 10% | High | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | The code coverage report for the merge request indicates a reduction in coverage of more than 10%. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | +| Code coverage down between 5% to 10% | Medium | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | The code coverage report for the merge request indicates a reduction in coverage of between 5% to 10%. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | +| Code coverage down between 1% to 5% | Low | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | The code coverage report for the merge request indicates a reduction in coverage of between 1% to 5%. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | +| Code coverage down less than 1% | Info | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | The code coverage report for the merge request indicates a reduction in coverage of less than 1%. | [Unavailable](https://gitlab.com/gitlab-org/gitlab/-/issues/346011) | diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 18de33ea03b..a2172b72572 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -55,7 +55,7 @@ You can view and modify existing policies from the [policies](#policies) tab. ## License expressions -GitLab has limited support for [composite licenses](https://spdx.github.io/spdx-spec/appendix-IV-SPDX-license-expressions/). +GitLab has limited support for [composite licenses](https://spdx.github.io/spdx-spec/SPDX-license-expressions/). License compliance can read multiple licenses, but always considers them combined using the `AND` operator. For example, if a dependency has two licenses, and one of them is allowed and the other is denied by the project [policy](#policies), GitLab evaluates the composite license as _denied_, as this is the safer option. @@ -90,7 +90,7 @@ 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/) | -| Rust | [Cargo](https://crates.io) | +| Rust | [Cargo](https://crates.io/) | | PHP | [Composer](https://getcomposer.org/) | ## Enable License Compliance @@ -219,7 +219,7 @@ license_scanning: MAVEN_CLI_OPTS: --debug ``` -`mvn install` runs through all of the [build life cycle](http://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html) +`mvn install` runs through all of the [build life cycle](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html) stages prior to `install`, including `test`. Running unit tests is not directly necessary for the license scanning purposes and consumes time, so it's skipped by having the default value of `MAVEN_CLI_OPTS` as `-DskipTests`. If you want @@ -249,7 +249,7 @@ license_scanning: Alternatively, you can use a Java key store to verify the TLS connection. For instructions on how to generate a key store file, see the -[Maven Guide to Remote repository access through authenticated HTTPS](http://maven.apache.org/guides/mini/guide-repository-ssl.html). +[Maven Guide to Remote repository access through authenticated HTTPS](https://maven.apache.org/guides/mini/guide-repository-ssl.html). ### Selecting the version of Java @@ -650,7 +650,7 @@ import the following default License Compliance analyzer images from `registry.g offline [local Docker container registry](../../packages/container_registry/index.md): ```plaintext -registry.gitlab.com/gitlab-org/security-products/analyzers/license-finder:latest +registry.gitlab.com/security-products/license-finder:latest ``` The process for importing Docker images into a local offline Docker registry depends on @@ -734,7 +734,7 @@ Note, the merge request is not able to be merged until the `denied` license is r You may add a [`License-Check` approval rule](#enabling-license-approvals-within-a-project), which enables a designated approver that can approve and then merge a merge request with `denied` license. - + The **Policies** tab in the project's license compliance section displays your project's license policies. Project maintainers can specify policies in this section. @@ -853,7 +853,7 @@ A full list of variables can be found in [CI/CD variables](#available-cicd-varia To find out what tools are pre-installed in the `license_scanning` Docker image use the following command: ```shell -$ docker run --entrypoint='' registry.gitlab.com/gitlab-org/security-products/analyzers/license-finder:3 /bin/bash -lc 'asdf list' +$ docker run --entrypoint='' registry.gitlab.com/security-products/license-finder:3 /bin/bash -lc 'asdf list' golang 1.14 gradle @@ -880,7 +880,7 @@ sbt To interact with the `license_scanning` runtime environment use the following command: ```shell -$ docker run -it --entrypoint='' registry.gitlab.com/gitlab-org/security-products/analyzers/license-finder:3 /bin/bash -l +$ docker run -it --entrypoint='' registry.gitlab.com/security-products/license-finder:3 /bin/bash -l root@6abb70e9f193:~# ``` diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md index 305cca33dd5..1fb628cf505 100644 --- a/doc/user/crm/index.md +++ b/doc/user/crm/index.md @@ -6,15 +6,18 @@ 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. +> - [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. +> - In GitLab 14.8 and later, you can [create contacts and organizations only in root groups](https://gitlab.com/gitlab-org/gitlab/-/issues/350634). + With customer relations management (CRM) you can create a record of contacts (individuals) and organizations (companies) and relate them to issues. +Contacts and organizations can only be created for root groups. + 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). diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 37047e9f8d0..a6343e0d1cf 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -36,10 +36,9 @@ Each object can have as many as 5,000 comments. ## Mentions -You can mention a user or a group present in your GitLab instance with `@username` or -`@groupname`. All mentioned users are notified with to-do items and emails. -Users can change this setting for themselves in the -[notification settings](../profile/notifications.md). +You can mention a user or a group (including [subgroups](../group/subgroups/index.md#mention-subgroups)) in your GitLab +instance with `@username` or `@groupname`. All mentioned users are notified with to-do items and emails. +Users can change this setting for themselves in the [notification settings](../profile/notifications.md). You can quickly see which comments involve you, because mentions for yourself (the user currently signed in) are highlighted @@ -47,6 +46,8 @@ in a different color. Avoid mentioning `@all` in issues and merge requests, because it sends an email notification to all the members of that project's group. This might be interpreted as spam. +Notifications and mentions can be disabled in +[a group's settings](../group/index.md#disable-email-notifications). ## Add a comment to a merge request diff diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 80ee8d23a35..5cf6a505bee 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -85,7 +85,10 @@ are included when cloning. Top-level groups created after August 12, 2021 have delayed project deletion enabled by default. Projects are permanently deleted after a seven-day delay. -You can disable this by changing the [group setting](../group/index.md#enable-delayed-project-deletion). +If you are on: + +- Premium tier and above, you can disable this by changing the [group setting](../group/index.md#enable-delayed-project-deletion). +- Free tier, you cannot disable this setting or restore projects. ## Alternative SSH port @@ -130,20 +133,20 @@ Below are the current settings regarding [GitLab CI/CD](../../ci/index.md). Any settings or feature limits not listed here are using the defaults listed in the related documentation. -| Setting | GitLab.com | Default | -|-------------------------------------|-------------|---------| -| Artifacts maximum size (compressed) | 1 GB | 100 MB | -| Artifacts [expiry time](../../ci/yaml/index.md#artifactsexpire_in) | From June 22, 2020, deleted after 30 days unless otherwise specified (artifacts created before that date have no expiry). | deleted after 30 days unless otherwise specified | -| Scheduled Pipeline Cron | `*/5 * * * *` | `3-59/10 * * * *` | -| [Max jobs in active pipelines](../../administration/instance_limits.md#number-of-jobs-in-active-pipelines) | `500` for Free tier, unlimited otherwise | Unlimited | -| [Max CI/CD subscriptions to a project](../../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project) | `2` | Unlimited | -| [Max number of pipeline triggers in a project](../../administration/instance_limits.md#limit-the-number-of-pipeline-triggers) | `25000` for Free tier, Unlimited for all paid tiers | Unlimited | -| [Max pipeline schedules in projects](../../administration/instance_limits.md#number-of-pipeline-schedules) | `10` for Free tier, `50` for all paid tiers | Unlimited | -| [Max pipelines per schedule](../../administration/instance_limits.md#limit-the-number-of-pipelines-created-by-a-pipeline-schedule-per-day) | `24` for Free tier, `288` for all paid tiers | Unlimited | -| [Scheduled Job Archival](../../user/admin_area/settings/continuous_integration.md#archive-jobs) | 3 months | Never | -| Max test cases per [unit test report](../../ci/unit_test_reports.md) | `500_000` | Unlimited | -| [Max registered runners](../../administration/instance_limits.md#number-of-registered-runners-per-scope) | Free tier: `50` per-group / `50` per-project <br/> All paid tiers: `1_000` per-group / `1_000` per-project | `1_000` per-group / `1_000` per-project | -| [Limit dotenv variables](../../administration/instance_limits.md#limit-dotenv-variables) | Free tier: `50` / Premium tier: `100` / Ultimate tier: `150` | 150 | +| Setting | GitLab.com | Default (self-managed) | +|:-------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Artifacts maximum size (compressed) | 1 GB | See [Maximum artifacts size](../../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size) | +| Artifacts [expiry time](../../ci/yaml/index.md#artifactsexpire_in) | From June 22, 2020, deleted after 30 days unless otherwise specified (artifacts created before that date have no expiry). | See [Default artifacts expiration](../admin_area/settings/continuous_integration.md#default-artifacts-expiration) | +| Scheduled Pipeline Cron | `*/5 * * * *` | See [Pipeline schedules advanced configuration](../../administration/cicd.md#change-maximum-scheduled-pipeline-frequency) | +| Maximum jobs in active pipelines | `500` for Free tier, unlimited otherwise | See [Number of jobs in active pipelines](../../administration/instance_limits.md#number-of-jobs-in-active-pipelines) | +| Maximum CI/CD subscriptions to a project | `2` | See [Number of CI/CD subscriptions to a project](../../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project) | +| Maximum number of pipeline triggers in a project | `25000` for Free tier, Unlimited for all paid tiers | See [Limit the number of pipeline triggers](../../administration/instance_limits.md#limit-the-number-of-pipeline-triggers) | +| Maximum pipeline schedules in projects | `10` for Free tier, `50` for all paid tiers | See [Number of pipeline schedules](../../administration/instance_limits.md#number-of-pipeline-schedules) | +| Maximum pipelines per schedule | `24` for Free tier, `288` for all paid tiers | See [Limit the number of pipelines created by a pipeline schedule per day](../../administration/instance_limits.md#limit-the-number-of-pipelines-created-by-a-pipeline-schedule-per-day) | +| Scheduled job archiving | 3 months (from June 22, 2020). Jobs created before that date were archived after September 22, 2020. | Never | +| Maximum test cases per [unit test report](../../ci/unit_test_reports.md) | `500000` | Unlimited | +| Maximum registered runners | Free tier: `50` per-group / `50` per-project<br/>All paid tiers: `1000` per-group / `1000` per-project | See [Number of registered runners per scope](../../administration/instance_limits.md#number-of-registered-runners-per-scope) | +| Limit of dotenv variables | Free tier: `50` / Premium tier: `100` / Ultimate tier: `150` | See [Limit dotenv variables](../../administration/instance_limits.md#limit-dotenv-variables) | ## Package registry limits @@ -188,7 +191,7 @@ GitLab.com uses the IP ranges `34.74.90.64/28` and `34.74.226.0/24` for traffic fleet. This whole range is solely allocated to GitLab. You can expect connections from webhooks or repository mirroring to come from those IPs and allow them. -GitLab.com is fronted by Cloudflare. For incoming connections to GitLab.com, you might need to allow CIDR blocks of Cloudflare ([IPv4](https://www.cloudflare.com/ips-v4) and [IPv6](https://www.cloudflare.com/ips-v6)). +GitLab.com is fronted by Cloudflare. For incoming connections to GitLab.com, you might need to allow CIDR blocks of Cloudflare ([IPv4](https://www.cloudflare.com/ips-v4/) and [IPv6](https://www.cloudflare.com/ips-v6/)). For outgoing connections from CI/CD runners, we are not providing static IP addresses. All GitLab.com shared runners are deployed into Google Cloud Platform (GCP). Any @@ -296,7 +299,7 @@ for `shared_buffers` is quite high, and we are ## Puma -GitLab.com uses the default of 60 seconds for [Puma request timeouts](../../administration/operations/puma.md#worker-timeout). +GitLab.com uses the default of 60 seconds for [Puma request timeouts](../../administration/operations/puma.md#change-the-worker-timeout). ## GitLab.com-specific rate limits diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index b2b16321488..0da7eaa4d55 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. To connect clusters to GitLab, -use the [GitLab Agent](../../clusters/agent/index.md). +use the [GitLab agent](../../clusters/agent/index.md). Similar to [project-level](../../project/clusters/index.md) and [instance-level](../../instance/clusters/index.md) Kubernetes clusters, diff --git a/doc/user/group/epics/img/related_epic_block_v14_9.png b/doc/user/group/epics/img/related_epic_block_v14_9.png Binary files differnew file mode 100644 index 00000000000..7b5824b84d1 --- /dev/null +++ b/doc/user/group/epics/img/related_epic_block_v14_9.png diff --git a/doc/user/group/epics/img/related_epics_add_v14_9.png b/doc/user/group/epics/img/related_epics_add_v14_9.png Binary files differnew file mode 100644 index 00000000000..3da6eeaff43 --- /dev/null +++ b/doc/user/group/epics/img/related_epics_add_v14_9.png diff --git a/doc/user/group/epics/img/related_epics_remove_v14_9.png b/doc/user/group/epics/img/related_epics_remove_v14_9.png Binary files differnew file mode 100644 index 00000000000..2cdded5965f --- /dev/null +++ b/doc/user/group/epics/img/related_epics_remove_v14_9.png diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index d6f87a026b8..149c5362ac9 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -62,6 +62,7 @@ You can also consult the [group permissions table](../../permissions.md#group-me ## Related topics - [Manage epics](manage_epics.md) and multi-level child epics. +- Link [related epics](linked_epics.md) based on a type of relationship. - Create workflows with [epic boards](epic_boards.md). - [Turn on notifications](../../profile/notifications.md) for about epic events. - [Award an emoji](../../award_emojis.md) to an epic or its comments. diff --git a/doc/user/group/epics/linked_epics.md b/doc/user/group/epics/linked_epics.md new file mode 100644 index 00000000000..b695bae39e4 --- /dev/null +++ b/doc/user/group/epics/linked_epics.md @@ -0,0 +1,79 @@ +--- +stage: Plan +group: Product Planning +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Linked epics **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/353473) in GitLab 14.9 [with a flag](../../../administration/feature_flags.md) named `related_epics_widget`. Enabled by default. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, +ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) +named `related_epics_widget`. On GitLab.com, this feature is available. + +Linked epics are a bi-directional relationship between any two epics and appear in a block below +the epic description. You can link epics in different groups. + +The relationship only shows up in the UI if the user can see both epics. When you try to close an +epic that has open blockers, a warning is displayed. + +NOTE: +To manage linked epics through our API, visit the [epic links API documentation](../../../api/linked_epics.md). + +## Add a linked epic + +Prerequisites: + +- You must have at least the Reporter role for both groups. +- For GitLab SaaS: the epic that you're editing must be in a group on GitLab Ultimate. + The epics you're linking can be in a group on a lower tier. + +To link one epic to another: + +1. In the **Linked epics** section of an epic, + select the add linked epic button (**{plus}**). +1. Select the relationship between the two epics. Either: + - **relates to** + - **[blocks](#blocking-epics)** + - **[is blocked by](#blocking-epics)** +1. Enter the epic number or paste in the full URL of the epic. + +  + + Epics of the same group can be specified just by the reference number. + Epics from a different group require additional information like the + group name. For example: + + - The same group: `&44` + - Different group: `group&44` + + Valid references are added to a temporary list that you can review. + +1. Select **Add**. + +The linked epics are then displayed on the epic grouped by relationship. + + + +## Remove a linked epic + +Prerequisites: + +- You must have at least the Reporter role for the epic's group. + +To remove a linked epic, in the **Linked epics** section of an epic, +select **Remove** (**{close}**) next to +each epic. + +The relationship is removed from both epics. + + + +## Blocking epics + +When you [add a linked epic](#add-a-linked-epic), you can show that it **blocks** or +**is blocked by** another epic. + +If you try to close a blocked epic using the "Close epic" button, a confirmation message appears. diff --git a/doc/user/group/import/img/import_panel_v14_1.png b/doc/user/group/import/img/import_panel_v14_1.png Binary files differdeleted file mode 100644 index 52791a82c3c..00000000000 --- a/doc/user/group/import/img/import_panel_v14_1.png +++ /dev/null diff --git a/doc/user/group/import/img/new_group_navigation_v13_8.png b/doc/user/group/import/img/new_group_navigation_v13_8.png Binary files differdeleted file mode 100644 index 40be3dd41d2..00000000000 --- a/doc/user/group/import/img/new_group_navigation_v13_8.png +++ /dev/null diff --git a/doc/user/group/import/index.md b/doc/user/group/import/index.md index cdc3fe02a53..0c16b535ed1 100644 --- a/doc/user/group/import/index.md +++ b/doc/user/group/import/index.md @@ -132,3 +132,25 @@ migrated: - image URL - Boards - Board Lists + +## Troubleshooting Group Migration + +In a [rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session), +you can find the failure or error messages for the group import attempt using: + +```shell +# Get relevant import records +import = BulkImports::Entity.where(namespace_id: Group.id).bulk_import + +# Alternative lookup by user +import = BulkImport.where(user_id: User.find(...)).last + +# Get list of import entities. Each entity represents either a group or a project +entities = import.entities + +# Get a list of entity failures +entities.map(&:failures).flatten + +# Alternative failure lookup by status +entities.where(status: [-1]).pluck(:destination_name, :destination_namespace, :status) +``` diff --git a/doc/user/group/index.md b/doc/user/group/index.md index ec76dc52516..4b9ff7f64e8 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -46,19 +46,16 @@ the immediate parent group. ### Namespaces -In GitLab, a namespace is a unique name and URL for a user, a group, or subgroup. - -- `http://gitlab.example.com/username` -- `http://gitlab.example.com/groupname` -- `http://gitlab.example.com/groupname/subgroup_name` +In GitLab, a namespace is a unique name for a user, a group, or subgroup under +which a project can be created. For example, consider a user named Alex: -1. Alex creates an account with the username `alex`: `https://gitlab.example.com/alex` -1. Alex creates a group for their team with the group name `alex-team`. - The group and its projects are available at: `https://gitlab.example.com/alex-team` -1. Alex creates a subgroup of `alex-team` with the subgroup name `marketing`. - The subgroup and its projects are available at: `https://gitlab.example.com/alex-team/marketing` +| GitLab URL | Namespace | +| ---------- | --------- | +| Alex creates an account with the username `alex`: `https://gitlab.example.com/alex`. | The namespace in this case is `alex`. | +| Alex creates a group for their team with the group name `alex-team`. The group and its projects are available at: `https://gitlab.example.com/alex-team`. | The namespace in this cases is `alex-team`. | +| Alex creates a subgroup of `alex-team` with the subgroup name `marketing`. The subgroup and its projects are available at: `https://gitlab.example.com/alex-team/marketing`. | The namespace in this case is `alex-team/marketing`. | ## Create a group @@ -87,6 +84,7 @@ You can give a user access to all projects in a group. 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Group information > Members**. +1. Select **Invite members**. 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. @@ -174,6 +172,7 @@ Filter a group to find members. By default, all members in the group and subgrou - To view members in the group only, select **Membership = Direct**. - To view members of the group and its subgroups, select **Membership = Inherited**. - To view members with two-factor authentication enabled or disabled, select **2FA = Enabled** or **Disabled**. + - [In GitLab 14.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/349887), to view GitLab users created by [SAML SSO](saml_sso/index.md) or [SCIM provisioning](saml_sso/scim_setup.md) select **Enterprise = true**. ### Search a group @@ -207,31 +206,24 @@ A to-do item is created for all the group and subgroup members. ## Change the default branch protection of a group -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7583) in GitLab 12.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7583) in GitLab 12.9. +> - [Settings moved and renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/340403) in GitLab 14.9. By default, every group inherits the branch protection set at the global level. -To change this setting for a specific group: - -1. On the top bar, select **Menu > Groups**. -1. Select **Your Groups**. -1. Find the group and select it. -1. From the left menu, select **Settings > General**. -1. Expand the **Permissions and group features** section. -1. Select the desired option in the **Default branch protection** dropdown list. -1. Select **Save changes**. +To change this setting for a specific group, see [group level default branch protection](../project/repository/branches/default.md#group-level-default-branch-protection). -To change this setting globally, see [Default branch protection](../admin_area/settings/visibility_and_access_controls.md#protect-default-branches). +To change this setting globally, see [initial default branch protection](../project/repository/branches/default.md#instance-level-default-branch-protection). NOTE: -In [GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can choose to [disable group owners from updating the default branch protection](../admin_area/settings/visibility_and_access_controls.md#prevent-overrides-of-default-branch-protection). +In [GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can choose to [disable group owners from updating the default branch protection](../project/repository/branches/default.md#prevent-overrides-of-default-branch-protection). ## Add projects to a group There are two different ways to add a new project to a group: -- Select a group, and then click **New project**. You can then continue [creating your project](../../user/project/working_with_projects.md#create-a-project). -- While you are creating a project, select a group from the dropdown menu. +- Select a group, and then select **New project**. You can then continue [creating your project](../../user/project/working_with_projects.md#create-a-project). +- While you are creating a project, select a group from the dropdown list.  @@ -256,7 +248,7 @@ To change this setting globally, see [Default project creation protection](../ad ## Group activity analytics **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207164) in GitLab 12.10 as a [beta feature](https://about.gitlab.com/handbook/product/#beta). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207164) in GitLab 12.10 as a [Beta feature](../../policy/alpha-beta-support.md#beta-features). For a group, you can view how many merge requests, issues, and members were created in the last 90 days. @@ -283,12 +275,8 @@ To view the activity feed in Atom format, select the > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18328) in GitLab 12.7. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal window [with a flag](../feature_flags.md). Disabled by default. > - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 14.8. - -FLAG: -On self-managed GitLab, by default the modal window feature is available. -To hide the feature, ask an administrator to [disable the feature flag](../../administration/feature_flags.md) -named `invite_members_group_modal`. -On GitLab.com, this feature is available. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. + [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. Similar to how you [share a project with a group](../project/members/share_project_with_groups.md), you can share a group with another group. Members get direct access @@ -308,7 +296,7 @@ All the members of the `Engineering` group are added to the `Frontend` group. ## Manage group memberships via LDAP **(PREMIUM SELF)** -Group syncing allows LDAP groups to be mapped to GitLab groups. This provides more control over per-group user management. To configure group syncing, edit the `group_base` **DN** (`'OU=Global Groups,OU=GitLab INT,DC=GitLab,DC=org'`). This **OU** contains all groups that will be associated with GitLab groups. +Group syncing allows LDAP groups to be mapped to GitLab groups. This provides more control over per-group user management. To configure group syncing, edit the `group_base` **DN** (`'OU=Global Groups,OU=GitLab INT,DC=GitLab,DC=org'`). This **OU** contains all groups that are associated with GitLab groups. Group links can be created by using either a CN or a filter. To create these group links, go to the group's **Settings > LDAP Synchronization** page. After configuring the link, it may take more than an hour for the users to sync with the GitLab group. @@ -325,9 +313,9 @@ To create group links via CN: 1. Select the **LDAP Server** for the link. 1. As the **Sync method**, select `LDAP Group cn`. -1. In the **LDAP Group cn** field, begin typing the CN of the group. There is a dropdown menu with matching CNs in the configured `group_base`. Select your CN from this list. +1. In the **LDAP Group cn** field, begin typing the CN of the group. There is a dropdown list with matching CNs in the configured `group_base`. Select your CN from this list. 1. In the **LDAP Access** section, select the [permission level](../permissions.md) for users synced in this group. -1. Select the **Add Synchronization** button. +1. Select **Add Synchronization**. <!-- vale gitlab.Spelling = YES --> @@ -339,7 +327,7 @@ To create group links via filter: 1. As the **Sync method**, select `LDAP user filter`. 1. Input your filter in the **LDAP User filter** box. Follow the [documentation on user filters](../../administration/auth/ldap/index.md#set-up-ldap-user-filter). 1. In the **LDAP Access** section, select the [permission level](../permissions.md) for users synced in this group. -1. Select the **Add Synchronization** button. +1. Select **Add Synchronization**. ### Override user permissions **(PREMIUM SELF)** @@ -347,7 +335,7 @@ LDAP user permissions can be manually overridden by an administrator. To overrid 1. Go to your group's **Group information > Members** page. 1. In the row for the user you are editing, select the pencil (**{pencil}**) icon. -1. Select the brown **Edit permissions** button in the modal. +1. Select **Edit permissions** in the modal. Now you can edit the user's permissions from the **Members** page. @@ -375,7 +363,7 @@ Changing a group's path (group URL) can have unintended side effects. Read before you proceed. If you are changing the path so it can be claimed by another group or user, -you may need to rename the group too. Both names and paths must +you must rename the group too. Both names and paths must be unique. To retain ownership of the original namespace and protect the URL redirects, @@ -384,7 +372,7 @@ create a new group and transfer projects to it instead. To change your group path (group URL): 1. Go to your group's **Settings > General** page. -1. Expand the **Path, transfer, remove** section. +1. Expand the **Advanced** section. 1. Under **Change group URL**, enter a new name. 1. Select **Change group URL**. @@ -467,7 +455,7 @@ To restore a group that is marked for deletion: This setting is only available on top-level groups. It affects all subgroups. -When checked, any group within the top-level group hierarchy can be shared only with other groups within the hierarchy. +When checked, any group in the top-level group hierarchy can be shared only with other groups in the hierarchy. For example, with these groups: @@ -496,7 +484,7 @@ To prevent a project from being shared with other groups: 1. Go to the group's **Settings > General** page. 1. Expand the **Permissions and group features** section. -1. Select **Prevent sharing a project within `<group_name>` with other groups**. +1. Select **Prevent sharing a project in `<group_name>` with other groups**. 1. Select **Save changes**. This setting applies to all subgroups unless overridden by a group owner. Groups already @@ -559,6 +547,8 @@ Decreasing the user cap does not approve pending members. When the number of billable users reaches the user cap, any new member is put in a pending state and must be approved. +Pending members do not count as billable. Members count as billable only after they have been approved and are no longer in a pending state. + Prerequisite: - You must be assigned the Owner role) for the group. @@ -586,7 +576,7 @@ To prevent members from being added to projects in a group: 1. Go to the group's **Settings > General** page. 1. Expand the **Permissions and group features** section. -1. Under **Member lock**, select **Prevent adding new members to project membership within this group**. +1. Under **Membership**, select **Prevent adding new members to projects within this group**. 1. Select **Save changes**. All users who previously had permissions can no longer add members to a group. @@ -601,7 +591,7 @@ You can export a list of members in a group or subgroup as a CSV. 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. +1. After the CSV file has been generated, it is emailed as an attachment to the user that requested it. ## Restrict group access by IP address **(PREMIUM)** @@ -646,7 +636,7 @@ To restrict group access by IP address: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7297) in GitLab 12.2. > - Support for specifying multiple email domains [added](https://gitlab.com/gitlab-org/gitlab/-/issues/33143) in GitLab 13.1. -> - Support for restricting access to projects within the group [added](https://gitlab.com/gitlab-org/gitlab/-/issues/14004) in GitLab 14.1.2. +> - Support for restricting access to projects in the group [added](https://gitlab.com/gitlab-org/gitlab/-/issues/14004) in GitLab 14.1.2. You can prevent users with email addresses in specific domains from being added to a group and its projects. @@ -663,7 +653,7 @@ Any time you attempt to add a new user, the user's [primary email](../profile/in 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: +The most popular public email domains cannot be restricted, such as: - `gmail.com`, `yahoo.com`, `aol.com`, `icloud.com` - `hotmail.com`, `hotmail.co.uk`, `hotmail.fr` @@ -718,9 +708,10 @@ To disable email notifications: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21301) in GitLab 12.6. You can prevent users from being added to a conversation and getting notified when -anyone mentions a group in which those users are members. +anyone [mentions a group](../discussions/index.md#mentions) +in which those users are members. -Groups with disabled mentions are visualized accordingly in the autocompletion dropdown. +Groups with disabled mentions are visualized accordingly in the autocompletion dropdown list. This is particularly helpful for groups with a large number of users. @@ -806,9 +797,7 @@ The group's new subgroups have push rules set for them based on either: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285458) in GitLab 13.9. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../administration/feature_flags.md), disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.5. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature per group, ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `group_merge_request_approval_settings_feature_flag`. On GitLab.com, this feature is available. +> - [Feature flag `group_merge_request_approval_settings_feature_flag`](https://gitlab.com/gitlab-org/gitlab/-/issues/343872) removed in GitLab 14.9. Group approval rules manage [project merge request approval rules](../project/merge_requests/approvals/index.md) at the top-level group level. These rules [cascade to all projects](../project/merge_requests/approvals/settings.md#settings-cascading) diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index c0bd6f1a672..b5912a0b40e 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -142,6 +142,7 @@ To view an iteration report, go to the iterations list page and select an iterat > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222750) in GitLab 13.6. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/269972) in GitLab 13.7. +> - Scoped burnup and burndown charts in subgroups and projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326029) in GitLab 14.9. The iteration report includes [burndown and burnup charts](../../project/milestones/burndown_and_burnup_charts.md), similar to how they appear when viewing a [milestone](../../project/milestones/index.md). @@ -149,6 +150,33 @@ similar to how they appear when viewing a [milestone](../../project/milestones/i Burndown charts help track completion progress of total scope, and burnup charts track the daily total count and weight of issues added to and completed in a given timebox. +#### Iteration charts scoped to subgroups or projects + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326029) in GitLab 14.9. + +You can view burndown and burnup charts for iterations created for a group in any of its +subgroups or projects. +When you do this, the charts only count the issues that belong to the subgroup or project. + +For example, suppose a group has two projects named `Project 1` and `Project 2`. +Each project has a single issue assigned to the same iteration from the group. + +An iteration report generated for the group shows issue counts for all the group's projects: + +- Completed: 0 of 2 +- Incomplete: 0 of 2 +- Unstarted: 2 of 2 +- Burndown chart total issues: 2 +- Burnup chart total issues: 2 + +An iteration report generated for `Project 1` shows only issues that belong to this project: + +- Completed: 0 of 1 +- Incomplete: 0 of 1 +- Unstarted: 1 of 1 +- Burndown chart total issues: 1 +- Burnup chart total issues: 1 + ### Group issues by label > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225500) in GitLab 13.8. diff --git a/doc/user/group/planning_hierarchy/img/epic-view-ancestors-in-sidebar_v14_6.png b/doc/user/group/planning_hierarchy/img/epic-view-ancestors-in-sidebar_v14_6.png Binary files differindex 373b861239b..d4ba8acf9b9 100644 --- a/doc/user/group/planning_hierarchy/img/epic-view-ancestors-in-sidebar_v14_6.png +++ b/doc/user/group/planning_hierarchy/img/epic-view-ancestors-in-sidebar_v14_6.png diff --git a/doc/user/group/planning_hierarchy/img/issue-view-parent-epic-in-sidebar_v14_6.png b/doc/user/group/planning_hierarchy/img/issue-view-parent-epic-in-sidebar_v14_6.png Binary files differindex 95a5777674a..f3b6a80ea66 100644 --- a/doc/user/group/planning_hierarchy/img/issue-view-parent-epic-in-sidebar_v14_6.png +++ b/doc/user/group/planning_hierarchy/img/issue-view-parent-epic-in-sidebar_v14_6.png diff --git a/doc/user/group/planning_hierarchy/img/view-project-work-item-hierarchy_v14_8.png b/doc/user/group/planning_hierarchy/img/view-project-work-item-hierarchy_v14_8.png Binary files differdeleted file mode 100644 index 2ddd551ee46..00000000000 --- a/doc/user/group/planning_hierarchy/img/view-project-work-item-hierarchy_v14_8.png +++ /dev/null diff --git a/doc/user/group/planning_hierarchy/index.md b/doc/user/group/planning_hierarchy/index.md index 934421e8a9a..6ffc47923f2 100644 --- a/doc/user/group/planning_hierarchy/index.md +++ b/doc/user/group/planning_hierarchy/index.md @@ -5,7 +5,7 @@ group: Product Planning info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Planning hierarchies **(FREE)** +# Planning hierarchies **(PREMIUM)** Planning hierarchies are an integral part of breaking down your work in GitLab. To understand how you can use epics and issues together in hierarchies, remember the following: @@ -20,21 +20,7 @@ To learn about hierarchies in general, common frameworks, and using GitLab for portfolio management, see [How to use GitLab for Agile portfolio planning and project management](https://about.gitlab.com/blog/2020/11/11/gitlab-for-agile-portfolio-planning-project-management/). -## View planning hierarchies - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340844/) in GitLab 14.8. - -To view the planning hierarchy in a project: - -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Project information > Planning hierarchy**. - -Under **Current structure**, you can see a hierarchy diagram that matches your current planning hierarchy. -The work items outside your subscription plan show up below **Unavailable structure**. - - - -## Hierarchies with epics **(PREMIUM)** +## Hierarchies with epics With epics, you can achieve the following hierarchy: @@ -74,7 +60,7 @@ In an issue, you can view the parented epic above the issue in the right sidebar  -## View ancestry of an epic **(PREMIUM)** +## View ancestry of an epic In an epic, you can view the ancestors as parents in the right sidebar under **Ancestors**. diff --git a/doc/user/group/roadmap/img/epics_state_dropdown_v14_3.png b/doc/user/group/roadmap/img/epics_state_dropdown_v14_3.png Binary files differdeleted file mode 100644 index 171876e34a9..00000000000 --- a/doc/user/group/roadmap/img/epics_state_dropdown_v14_3.png +++ /dev/null diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index f10dc3bc22a..89c5c6ed466 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -24,12 +24,12 @@ When you hover over an epic bar, a popover appears with the epic's title, start weight completed. You can expand epics that contain child epics to show their child epics in the roadmap. -You can click the chevron (**{chevron-down}**) next to the epic title to expand and collapse the +You can select the chevron (**{chevron-down}**) next to the epic title to expand and collapse the child epics. On top of the milestone bars, you can see their title. When you hover over a milestone bar or title, a popover appears with its title, start date, and due -date. You can also click the chevron (**{chevron-down}**) next to the **Milestones** heading to +date. You can also select the chevron (**{chevron-down}**) next to the **Milestones** heading to toggle the list of the milestone bars.  @@ -47,10 +47,6 @@ Filtering roadmaps by milestone might not be available to you. Check the **versi When you want to explore a roadmap, there are several ways to make it easier by sorting epics or filtering them by what's important for you. -A dropdown menu lets you show only open or closed epics. By default, all epics are shown. - - - You can sort epics in the Roadmap view by: - Start date @@ -74,18 +70,15 @@ Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap-in-ep ### Roadmap settings -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345158) in GitLab 14.8 [with a flag](../../../administration/feature_flags.md) named `roadmap_settings`. Enabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `roadmap_settings`. -On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345158) in GitLab 14.8 [with a flag](../../../administration/feature_flags.md) named `roadmap_settings`. Enabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/350830) in GitLab 14.9. Feature flag `roadmap_settings`removed. When you enable the roadmap settings sidebar, you can use it to refine epics shown in the roadmap. You can configure the following: - Select date range. -- Turn milestones on or off and select whether to show all, group, sub-group, or project milestones. +- Turn milestones on or off and select whether to show all, group, subgroup, or project milestones. - Show all, open, or closed epics. - Turn progress tracking for child issues on or off and select whether to use issue weights or counts. diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md index aeb7db923a9..bffaef40800 100644 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ b/doc/user/group/saml_sso/group_managed_accounts.md @@ -65,7 +65,7 @@ This restriction also applies to projects forked from or to those groups. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34648) in GitLab 12.9. -Groups with group-managed accounts can disallow forking of projects to destinations outside the group. +Groups with group-managed accounts can prevent forking of projects to destinations outside the group. To do so, enable the "Prohibit outer forks" option in **Settings > SAML SSO**. When enabled **at the parent group level**, projects within the group can be forked only to other destinations within the group (including its subgroups). diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 14c4447c5c6..8ebcd9f62d0 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -176,7 +176,7 @@ See the [troubleshooting page](../../../administration/troubleshooting/group_sam ### Okta setup notes -Please follow the Okta documentation on [setting up a SAML application in Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/overview/) with the notes below for consideration. +Please follow the Okta documentation on [setting up a SAML application in Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/) with the notes below for consideration. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For a demo of the Okta SAML setup including SCIM, see [Demo: Okta Group SAML & SCIM setup](https://youtu.be/0ES9HsZq0AQ). @@ -214,6 +214,35 @@ we recommend the ["Use the OneLogin SAML Test Connector" documentation](https:// Recommended `NameID` value: `OneLogin ID`. +### Change the SAML app + +To change the SAML app used for sign in: + +- If the NameID is not identical in both the existing and new SAML apps, users must: + 1. [Unlink the current SAML identity](#unlinking-accounts). + 1. [Link their identity](#user-access-and-management) to the new SAML app. +- If the NameID is identical, no change is required. + +### Migrate to a different SAML provider + +You can migrate to a different SAML provider. During the migration process users will not be able to access any of the SAML groups. +To mitigate this, you can disable [SSO enforcement](#sso-enforcement). + +To migrate SAML providers: + +1. [Configure](#configure-your-identity-provider) the group with the new identity provider SAML app. +1. Ask users to [unlink their account from the group](#unlinking-accounts). +1. Ask users to [link their account to the new SAML app](#linking-saml-to-your-existing-gitlabcom-account). + +### Change email domains + +To migrate users to a new email domain, users must: + +1. Add their new email as the primary email to their accounts and verify it. +1. [Unlink their account from the group](#unlinking-accounts). +1. [Link their account to the group](#linking-saml-to-your-existing-gitlabcom-account). +1. (Optional) Remove their old email from the account. + ## User access and management > [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/268142) in GitLab 13.7. @@ -610,12 +639,6 @@ Alternatively, when users need to [link SAML to their existing GitLab.com accoun | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | As mentioned in the [NameID](#nameid) section, if the NameID changes for any user, the user can be locked out. This is a common problem when an email address is used as the identifier. | Follow the steps outlined in the ["SAML authentication failed: User has already been taken"](#message-saml-authentication-failed-user-has-already-been-taken) section. | -### I need to change my SAML app - -If the NameID is identical in both SAML apps, then no change is required. - -Otherwise, to change the SAML app used for sign in, users need to [unlink the current SAML identity](#unlinking-accounts) and then [link their identity](#user-access-and-management) to the new SAML app. - ### I need additional information to configure my identity provider Many SAML terms can vary between providers. It is possible that the information you are looking for is listed under another name. diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index d1e9ba29378..331288e33a1 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -51,7 +51,7 @@ Once [Group Single Sign-On](index.md) has been configured, we can: The SAML application that was created during [Single sign-on](index.md) setup for [Azure](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/view-applications-portal) now needs to be set up for SCIM. You can refer to [Azure SCIM setup documentation](https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/use-scim-to-provision-users-and-groups#getting-started). -1. In your app, go to the Provisioning tab, and set the **Provisioning Mode** to **Automatic**. +1. In your app, go to the Provisioning tab, and set the **Provisioning Mode** to **Automatic**. Then fill in the **Admin Credentials**, and save. The **Tenant URL** and **secret token** are the items retrieved in the [previous step](#gitlab-configuration). @@ -60,7 +60,7 @@ The SAML application that was created during [Single sign-on](index.md) setup fo - **Settings**: We recommend setting a notification email and selecting the **Send an email notification when a failure occurs** checkbox. You also control what is actually synced by selecting the **Scope**. For example, **Sync only assigned users and groups** only syncs the users and groups assigned to the application. Otherwise, it syncs the whole Active Directory. - - **Mappings**: We recommend keeping **Provision Azure Active Directory Users** enabled, and disable **Provision Azure Active Directory Groups**. + - **Mappings**: We recommend keeping **Provision Azure Active Directory Users** enabled, and disable **Provision Azure Active Directory Groups**. Leaving **Provision Azure Active Directory Groups** enabled does not break the SCIM user provisioning, but it causes errors in Azure AD that may be confusing and misleading. 1. You can then test the connection by selecting **Test Connection**. If the connection is successful, save your configuration before moving on. See below for [troubleshooting](#troubleshooting). @@ -100,12 +100,14 @@ Once synchronized, changing the field mapped to `id` and `externalId` may cause ### Okta configuration steps -Before you start this section, complete the [GitLab configuration](#gitlab-configuration) process. -Make sure that you've also set up a SAML application for [Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/overview/), -as described in the [Okta setup notes](index.md#okta-setup-notes) +Before you start this section: -Make sure that the Okta setup matches our documentation exactly, especially the NameID -configuration. Otherwise, the Okta SCIM app may not work properly. +- Check that you are using Okta [Lifecycle Management](https://www.okta.com/products/lifecycle-management/) product. This product tier is required to use SCIM on Okta. To check which Okta product you are using, check your signed Okta contract, contact your Okta AE, CSM, or Okta support. +- Complete the [GitLab configuration](#gitlab-configuration) process. +- Complete the setup for SAML application for [Okta](https://developer.okta.com/docs/guides/build-sso-integration/saml2/overview/), as described in the [Okta setup notes](index.md#okta-setup-notes). +- Check that your Okta SAML setup matches our documentation exactly, especially the NameID configuration. Otherwise, the Okta SCIM app may not work properly. + +After the above steps are complete: 1. Sign in to Okta. 1. Ensure you are in the Admin section by selecting the **Admin** button located in the top right. The admin button is not visible from the admin page. @@ -169,7 +171,7 @@ We recommend users do this prior to turning on sync, because while synchronizati New users and existing users on subsequent visits can access the group through the identify provider's dashboard or by visiting links directly. -[In GitLab 14.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/325712), GitLab users created with a SCIM identity display with an **Enterprise** badge in the **Members** view. +[In GitLab 14.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/325712), GitLab users created by [SAML SSO](index.md#user-access-and-management) or SCIM provisioning display with an **Enterprise** badge in the **Members** view.  @@ -244,7 +246,7 @@ It is important not to update these to incorrect values, since this causes users ### I need to change my SCIM app -Individual users can follow the instructions in the ["SAML authentication failed: User has already been taken"](index.md#i-need-to-change-my-saml-app) section. +Individual users can follow the instructions in the ["SAML authentication failed: User has already been taken"](index.md#change-the-saml-app) section. Alternatively, users can be removed from the SCIM app which de-links all removed users. Sync can then be turned on for the new SCIM app to [link existing users](#user-access-and-linking-setup). diff --git a/doc/user/group/settings/group_access_tokens.md b/doc/user/group/settings/group_access_tokens.md index 769943cd5d8..6b20f1763d4 100644 --- a/doc/user/group/settings/group_access_tokens.md +++ b/doc/user/group/settings/group_access_tokens.md @@ -44,7 +44,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. Enter a name. The token name is visible to any user with permissions to view the group. 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). diff --git a/doc/user/group/subgroups/img/mention_subgroups.png b/doc/user/group/subgroups/img/mention_subgroups.png Binary files differdeleted file mode 100644 index ec370add4f9..00000000000 --- a/doc/user/group/subgroups/img/mention_subgroups.png +++ /dev/null diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 46dea81ae9f..a98f213bb3f 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -2,189 +2,176 @@ stage: Manage group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, howto, concepts --- # Subgroups **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2772) in GitLab 9.0. -GitLab supports up to 20 levels of subgroups, also known as nested groups or hierarchical groups. - -By using subgroups you can do the following: - -- **Separate internal / external organizations.** Since every group - can have its own visibility level ([public, internal, or private](../../../development/permissions.md#general-permissions)), - you're able to host groups for different purposes under the same umbrella. -- **Organize large projects.** For large projects, subgroups makes it - potentially easier to separate permissions on parts of the source code. -- **Make it easier to manage people and control visibility.** Give people - different [permissions](../../permissions.md#group-members-permissions) depending on their group [membership](#membership). - -For more information on allowed permissions in groups and projects, see -[visibility levels](../../../development/permissions.md#general-permissions). - -## Overview - -A group can have many subgroups inside it, and at the same time a group can have -only one immediate parent group. It resembles a directory behavior or a nested items list: - -- Group 1 - - Group 1.1 - - Group 1.2 - - Group 1.2.1 - - Group 1.2.2 - - Group 1.2.2.1 - -In a real world example, imagine maintaining a GNU/Linux distribution with the -first group being the name of the distribution, and subsequent groups split as follows: - -- Organization Group - GNU/Linux distro - - Category Subgroup - Packages - - (project) Package01 - - (project) Package02 - - Category Subgroup - Software - - (project) Core - - (project) CLI - - (project) Android app - - (project) iOS app - - Category Subgroup - Infra tools - - (project) Ansible playbooks - -Another example of GitLab as a company would be the following: - -- Organization Group - GitLab - - Category Subgroup - Marketing - - (project) Design - - (project) General - - Category Subgroup - Software - - (project) GitLab CE - - (project) GitLab EE - - (project) Omnibus GitLab - - (project) GitLab Runner - - (project) GitLab Pages daemon - - Category Subgroup - Infra tools - - (project) Chef cookbooks - - Category Subgroup - Executive team - -When performing actions such as transferring or importing a project between -subgroups, the behavior is the same as when performing these actions at the -`group/project` level. - -## Creating a subgroup - -Users can create subgroups if they are explicitly added as an Owner (or -Maintainer, if that setting is enabled) to an immediate parent group, even if group -creation is disabled by an administrator in their settings. +You can organize GitLab [groups](../index.md) into subgroups. You can use subgroups to: + +- Separate internal and external organizations. Because every subgroup can have its own + [visibility level](../../../development/permissions.md#general-permissions), you can host groups for different + purposes under the same parent group. +- Organize large projects. You can use subgroups to give different access to parts of + the source code. +- Manage people and control visibility. Give a user a different + [role](../../permissions.md#group-members-permissions) for each group they're [a member of](#subgroup-membership). + +Subgroups can: + +- Belong to one immediate parent group. +- Have many subgroups. +- Be nested up to 20 levels. +- Use [runners](../../../ci/runners/index.md) registered to parent groups: + - Secrets configured for the parent group are available to subgroup jobs. + - Users with the Maintainer role in projects that belong to subgroups can see the details of runners registered to + parent groups. + +For example: + +```mermaid +graph TD + subgraph "Parent group" + subgraph "Subgroup A" + subgraph "Subgroup A1" + G["Project E"] + end + C["Project A"] + D["Project B"] + E["Project C"] + end + subgraph "Subgroup B" + F["Project D"] + end + end +``` + +## Create a subgroup + +Users with the at least the Maintainer role on a group can create subgroups immediately below the group, unless +[configured otherwise](#change-who-can-create-subgroups). These users can create subgroups even if group creation is +[disabled by an Administrator](../../admin_area/index.md#prevent-a-user-from-creating-groups) in the user's settings. To create a subgroup: -1. On the top bar, select **Menu > Groups** and find the parent group. -1. In the top right, select **New subgroup**. +1. On the top bar, select **Menu > Groups** and find and select the parent group to add a subgroup to. +1. On the parent group's overview page, in the top right, select **New subgroup**. 1. Select **Create group**. -1. Fill in the fields. View a list of [reserved names](../../reserved_names.md) - that cannot be used as group names. +1. Fill in the fields. View a list of [reserved names](../../reserved_names.md) that cannot be used as group names. 1. Select **Create group**. ### Change who can create subgroups -To create a subgroup you must either be an Owner or a Maintainer of the -group, depending on the group's setting. +To create a subgroup, you must have at least the Maintainer role on the group, depending on the group's setting. By +default: -By default: +- In GitLab 12.2 or later, users with at least the Maintainer role can create subgroups. +- In GitLab 12.1 or earlier, only users with the Owner role can create subgroups. -- In GitLab 12.2 or later, both Owners and Maintainers can create subgroups. -- In GitLab 12.1 or earlier, only Owners can create subgroups. +To change who can create subgroups on a group: -You can change this setting: - -- As group owner: - 1. Select the group. +- As a user with the Owner role on the group: + 1. On the top bar, select **Menu > Groups** and find the group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Permissions and group features**. + 1. Select a role from the **Allowed to create subgroups** dropdown. - As an administrator: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Groups**. 1. Select the group, and select **Edit**. + 1. Select a role from the **Allowed to create subgroups** dropdown. For more information, view the [permissions table](../../permissions.md#group-members-permissions). -## Membership - -When you add a member to a group, that member is also added to all subgroups. -Permission level is inherited from the group's parent. This model allows access to -subgroups if you have membership in one of its parents. +## Subgroup membership -Jobs for pipelines in subgroups can use [runners](../../../ci/runners/index.md) registered to the parent group(s). -This means secrets configured for the parent group are available to subgroup jobs. +When you add a member to a group, that member is also added to all subgroups. The user's permissions are inherited from +the group's parent. -In addition, maintainers of projects that belong to subgroups can see the details of runners registered to parent group(s). +Subgroup members can: -The group permissions for a member can be changed only by Owners, and only on -the **Members** page of the group the member was added. +1. Be [direct members](../../project/members/index.md#add-users-to-a-project) of the subgroup. +1. [Inherit membership](../../project/members/index.md#inherited-membership) of the subgroup from the subgroup's parent group. +1. Be a member of a group that was [shared with the subgroup's top-level group](../index.md#share-a-group-with-another-group). -You can tell if a member has inherited the permissions from a parent group by -looking at the group's **Members** page. +```mermaid +flowchart RL + subgraph Group A + A(Direct member) + B{{Shared member}} + subgraph Subgroup A + H(1. Direct member) + C{{2. Inherited member}} + D{{Inherited member}} + E{{3. Shared member}} + end + A-->|Direct membership of Group A\nInherited membership of Subgroup A|C + end + subgraph Group C + G(Direct member) + end + subgraph Group B + F(Direct member) + end + F-->|Group B\nshared with\nGroup A|B + B-->|Inherited membership of Subgroup A|D + G-->|Group C shared with Subgroup A|E +``` - +Group permissions for a member can be changed only by: -From the image above, we can deduce the following things: +- Users with the Owner role on the group. +- Changing the configuration of the group the member was added to. -- There are 5 members that have access to the group `four`. -- User 0 is a Reporter and has inherited their permissions from group `one` - which is above the hierarchy of group `four`. -- User 1 is a Developer and has inherited their permissions from group - `one/two` which is above the hierarchy of group `four`. -- User 2 is a Developer and has inherited their permissions from group - `one/two/three` which is above the hierarchy of group `four`. -- For User 3 the **Source** column indicates **Direct member**, therefore they belong to - group `four`, the one we're inspecting. -- Administrator is the Owner and member of **all** subgroups and for that reason, - as with User 3, the **Source** column indicates **Direct member**. +### Determine membership inheritance -Members can be [filtered by inherited or direct membership](../index.md#filter-a-group). +To see if a member has inherited the permissions from a parent group: -### Overriding the ancestor group membership +1. On the top bar, select **Menu > Groups** and find the group. +1. Select **Group information > Members**. -NOTE: -You must be an Owner of a group to be able to add members to it. +Members list for an example subgroup _Four_: -NOTE: -A user's permissions in a subgroup cannot be lower than in any of its ancestor groups. -Therefore, you cannot reduce a user's permissions in a subgroup with respect to its ancestor groups. + -To override a user's membership of an ancestor group (the first group they were -added to), add the user to the new subgroup again with a higher set of permissions. +In the screenshot above: + +- Five members have access to group _Four_. +- User 0 has the Reporter role on group _Four_, and has inherited their permissions from group _One_: + - User 0 is a direct member of group _One_. + - Group _One_ is above group _Four_ in the hierarchy. +- User 1 has the Developer role on group _Four_ and inherited their permissions from group _Two_: + - User 0 is a direct member of group _Two_, which is a subgroup of group _One_. + - Groups _One / Two_ are above group _Four_ in the hierarchy. +- User 2 has the Developer role on group _Four_ and has inherited their permissions from group _Three_: + - User 0 is a direct member of group _Three_, which is a subgroup of group _Two_. Group _Two_ is a subgroup of group + _One_. + - Groups _One / Two / Three_ are above group _Four_ the hierarchy. +- User 3 is a direct member of group _Four_. This means they get their Maintainer role directly from group _Four_. +- Administrator has the Owner role on group _Four_ and is a member of all subgroups. For that reason, as with User 3, + the **Source** column indicates they are a direct member. -For example, if User 1 was first added to group `one/two` with Developer -permissions, then they inherit those permissions in every other subgroup -of `one/two`. To give them the Maintainer role for group `one/two/three/four`, -you would add them again in that group as Maintainer. Removing them from that group, -the permissions fall back to those of the ancestor group. +Members can be [filtered by inherited or direct membership](../index.md#filter-a-group). -## Mentioning subgroups +### Override ancestor group membership -Mentioning groups (`@group`) in issues, commits and merge requests, would -notify all members of that group. Now with subgroups, there is more granular -support if you want to split your group's structure. Mentioning works as before -and you can choose the group of people to be notified. +Users with the Owner role on a subgroup can add members to it. - +You can't give a user a role on a subgroup that's lower than the roles they have on ancestor groups. To override a user's +role on an ancestor group, add the user to the subgroup again with a higher role. For example: -## Limitations +- If User 1 is added to group _Two_ with the Developer role, they inherit that role in every subgroup of group _Two_. +- To give User 1 the Maintainer role on group _Four_ (under _One / Two / Three_), add them again to group _Four_ with + the Maintainer role. +- If User 1 is removed from group _Four_, their role falls back to their role on group _Two_. They have the Developer + role on group _Four_ again. -Here's a list of what you can't do with subgroups: +## Mention subgroups -- [GitLab Pages](../../project/pages/index.md) supports projects hosted under - a subgroup, but not subgroup websites. - That means that only the highest-level group supports - [group websites](../../project/pages/getting_started_part_one.md#gitlab-pages-default-domain-names), - although you can have project websites under a subgroup. -- It is not possible to share a project with a group that's an ancestor of - the group the project is in. That means you can only share as you walk down - the hierarchy. For example, `group/subgroup01/project` **cannot** be shared - with `group`, but can be shared with `group/subgroup02` or - `group/subgroup01/subgroup03`. +Mentioning subgroups ([`@<subgroup_name>`](../../discussions/index.md#mentions)) in issues, commits, and merge requests +notifies all members of that group. Mentioning works the same as for projects and groups, and you can choose the group +of people to be notified. <!-- ## Troubleshooting 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 differindex c9074cbb5ea..7c3305792bb 100644 --- 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 diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index ccf77f79fd9..5ea8512ed5a 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -2,84 +2,155 @@ type: reference stage: Manage group: Optimize -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To 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 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 -[idea to production](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) -(also known as cycle time) for each of your projects or groups. Value stream analytics displays the median time -spent in each stage defined in the process. +Value stream analytics provides metrics about each stage of your software development process. -Value stream analytics can help you quickly determine the velocity of a given -group. It points to bottlenecks in the development process, enabling management -to uncover, triage, and identify the root cause of slowdowns in the software development life cycle. +Use value stream analytics to identify: -For information on how to contribute to the development of value stream analytics, see our [contributor documentation](../../../development/value_stream_analytics.md). +- The amount of time it takes to go from an idea to production. +- The velocity of a given project. +- Bottlenecks in the development process. +- Factors that cause your software development lifecycle to slow down. -To view value stream analytics for groups: +Value stream analytics is also available for [projects](../../analytics/value_stream_analytics.md). + +## View value stream analytics + +> - Date range filter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 12.4 +> - Filtering [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 13.3 +> - Horizontal stage path [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12196) in 13.0 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323982) in 13.12 + +You must have at least the Reporter role to view value stream analytics for groups. + +To view value stream analytics for your group: 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value stream**. +1. To view metrics for each stage, above the **Filter results** text box, select a stage. +1. Optional. Filter the results: + 1. Select the **Filter results** text box. + 1. Select a parameter. + 1. Select a value or enter text to refine the results. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. The charts and list show workflow items created + during the date range. +1. Optional. Sort results by ascending or descending: + - To sort by most recent or oldest workflow item, select the **Merge requests** or **Issues** + header. The header name differs based on the stage you select. + - To sort by most or least amount of time spent in each stage, select the **Time** header. + +A badge next to the workflow items table header shows the number of workflow items that +completed during the selected stage. + +The table shows a list of related workflow items for the selected stage. Based on the stage you select, this can be: + +- CI/CD jobs +- Issues +- Merge requests +- Pipelines -Value stream analytics at the group level includes data for the selected group and its subgroups. +## View metrics for each development stage -NOTE: -[Value stream analytics for projects](../../analytics/value_stream_analytics.md) is also available. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210315) in GitLab 13.0. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323982) in GitLab 13.12. + +Value stream analytics shows the median time spent by issues or merge requests in each development stage. + +To view the median time spent in each stage by a group: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Value stream**. +1. Optional. Filter the results: + 1. Select the **Filter results** text box. + 1. Select a parameter. + 1. Select a value or enter text to refine the results. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. +1. To view the metrics for each stage, above the **Filter results** text box, hover over a stage. + +## View the lead time and cycle time for issues + +Value stream analytics shows the lead time and cycle time for issues in your groups: + +- Lead time: Median time from when the issue was created to when it was closed. +- Cycle time: Median time from first commit to issue closed. Commits are associated with issues when users [cross-link them in the commit message](../../project/issues/crosslinking_issues.md#from-commit-messages). + +To view the lead time and cycle time for issues: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Value stream**. +1. Optional. Filter the results: + 1. Select the **Filter results** text box. + 1. Select a parameter. + 1. Select a value or enter text to refine the results. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. + +The **Lead Time** and **Cycle Time** metrics display below the **Filter results** text box. + +## View lead time for changes for merge requests **(ULTIMATE)** -## Default stages +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340150) in GitLab 14.5. -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. +Lead time for changes is the median duration between when a merge request is merged and when it's deployed to production. -- **Issue** (Tracker) - - Time to schedule an issue (by milestone or by adding it to an issue board) -- **Plan** (Board) - - Time to first commit -- **Code** (IDE) - - Time to create a merge request -- **Test** (CI) - - Time it takes GitLab CI/CD to test your code -- **Review** (Merge Request/MR) - - Time spent on code review -- **Staging** (Continuous Deployment) - - Time between merging and deploying to production +To view the lead time for changes for merge requests in your group: -## Filter the analytics data +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Value stream**. +1. Optional. Filter the results: + 1. Select the **Filter results** text box. + 1. Select a parameter. + 1. Select a value or enter text to refine the results. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 13.3 +The **Lead Time for Changes** metrics display below the **Filter results** text box. -GitLab provides the ability to filter analytics based on the following parameters: +## View number of successful deployments **(PREMIUM)** -- Milestones (Group level) -- Labels (Group level) -- Author -- Assignees +> 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. -To filter results: +To view deployment metrics, you must have a +[production environment configured](../../../ci/environments/index.md#deployment-tier-of-environments). -1. Select a group. -1. Click on the filter bar. -1. Select a parameter to filter by. -1. Select a value from the autocompleted results, or type to refine the results. +Value stream analytics shows the following deployment metrics for your group: + +- Deploys: The number of successful deployments in the date range. +- Deployment Frequency: The average number of successful deployments per day in the date range. - +To view deployment metrics for your group: -### Date ranges +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Value stream**. +1. Optional. Filter the results: + 1. Select the **Filter results** text box. + 1. Select a parameter. + 1. Select a value or enter text to refine the results. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13216) in GitLab 12.4. +The **Deploys** and **Deployment Frequency** metrics display below the **Filter results** text box. -GitLab provides the ability to filter analytics based on a date range. -Data is shown for workflow items created during the selected date range. To filter results: +Deployment metrics are calculated based on data from the +[DORA API](../../../api/dora/metrics.md#devops-research-and-assessment-dora-key-metrics-api). -1. Select a group. -1. Optionally select a project. -1. Select a date range using the available date pickers. +NOTE: +In GitLab 13.9 and later, metrics are calculated based on when the deployment was finished. +In GitLab 13.8 and earlier, metrics are calculated based on when the deployment was created. -### Upcoming date filter change +## Upcoming date filter change In the [epics](https://gitlab.com/groups/gitlab-org/-/epics/6046), we plan to alter the date filter behavior to filter the end event time of the currently selected stage. @@ -92,82 +163,72 @@ If you were to look at the metrics for the last three months, this issue would n the stage metrics. With the new date filter, this item would be included. DISCLAIMER: -This page contains information related to upcoming products, features, and functionality. +This section contains information related to upcoming products, features, and functionality. It is important to note that the information presented is for informational purposes only. Please do not rely on this information for purchasing or planning purposes. As with all projects, the items mentioned on this page are subject to change or delay. The development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc. -## How metrics are measured - -> 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: +## How value stream analytics measures stages -- **Lead time**: median time from issue created to issue closed. -- **Cycle time**: median time from first commit to issue closed. (You can associate a commit with an - issue by [crosslinking in the commit message](../../project/issues/crosslinking_issues.md#from-commit-messages).) -- **Lead Time for Changes**: median time between when a merge request is merged and deployed to a -production environment for all merge requests deployed in the given time period. -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340150) in GitLab 14.5. - -- **Lead Time for Changes**: median duration between merge request merge and deployment to a production environment for all MRs deployed in the given time period. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340150) in GitLab 14.5. - -The "Recent Activity" metrics near the top of the page are measured as follows: - -- **New Issues:** the number of issues created in the date range. -- **Deploys:** the number of deployments to production in the date range. -- **Deployment Frequency:** the average number of deployments to production - per day in the date range. - -To see deployment metrics, you must have a [production environment configured](../../../ci/environments/index.md#deployment-tier-of-environments). +Value stream analytics measures each stage from its start event to its end event. -NOTE: -In GitLab 13.9 and later, deployment metrics are calculated based on when the deployment was finished. -In GitLab 13.8 and earlier, deployment metrics are calculated based on when the deployment was created. +For example, a stage might start when a user adds a label to an issue, and ends when they add another label. +Items aren't included in the stage time calculation if they have not reached the end event. -You can learn more about these metrics in our [analytics definitions](../../analytics/index.md). +Each stage of value stream analytics is further described in the table below. - +| Stage | Measurement method | +| ------- | -------------------- | +| Issue | The median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whichever comes first. The label is tracked only if it already has an [issue board list](../../project/issue_board.md) created for it. | +| Plan | The median time between the action you took for the previous stage, and pushing the first commit to the branch. The first commit on the branch triggers the separation between **Plan** and **Code**. At least one of the commits in the branch must contain the related issue number (for example, `#42`). If none of the commits in the branch mention the related issue number, it is not considered in the measurement time of the stage. | +| Code | The median time between pushing a first commit (previous stage) and creating a merge request (MR) related to that commit. The key to keep the process tracked is to include the [issue closing pattern](../../project/issues/managing_issues.md#default-closing-pattern) in the description of the merge request. For example, `Closes #xxx`, where `xxx` is the number of the issue related to this merge request. If the closing pattern is not present, then the calculation uses the creation time of the first commit in the merge request as the start time. | +| Test | The median time to run the entire pipeline for that project. It's related to the time GitLab CI/CD takes to run every job for the commits pushed to that merge request. It is basically the start->finish time for all pipelines. | +| Review | The median time taken to review a merge request that has a closing issue pattern, between its creation and until it's merged. | +| Staging | The median time between merging a merge request that has a closing issue pattern until the very first deployment to a [production environment](#how-value-stream-analytics-identifies-the-production-environment). If there isn't a production environment, this is not tracked. | -## How the stages are measured +## Example workflow -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. +This example shows a workflow through all seven stages in one day. -Each stage of value stream analytics is further described in the table below. +If a stage does not include a start and a stop time, its data is not included in the median time. +In this example, milestones have been created and CI/CD for testing and setting environments is configured. -| **Stage** | **Description** | -| --------- | --------------- | -| Issue | Measures the median time between creating an issue and taking action to solve it, by either labeling it or adding it to a milestone, whatever comes first. The label is tracked only if it already has an [issue board list](../../project/issue_board.md) created for it. | -| Plan | Measures the median time between the action you took for the previous stage, and pushing the first commit to the branch. The very first commit of the branch is the one that triggers the separation between **Plan** and **Code**, and at least one of the commits in the branch needs to contain the related issue number (for example, `#42`). If none of the commits in the branch mention the related issue number, it is not considered to the measurement time of the stage. | -| Code | Measures the median time between pushing a first commit (previous stage) and creating a merge request (MR) related to that commit. The key to keep the process tracked is to include the [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically) to the description of the merge request (for example, `Closes #xxx`, where `xxx` is the number of the issue related to this merge request). If the closing pattern is not present, then the calculation takes the creation time of the first commit in the merge request as the start time. | -| Test | Measures the median time to run the entire pipeline for that project. It's related to the time GitLab CI/CD takes to run every job for the commits pushed to that merge request defined in the previous stage. It is basically the start->finish time for all pipelines. | -| Review | Measures the median time taken to review the merge request that has a closing issue pattern, between its creation and until it's merged. | -| Staging | Measures the median time between merging the merge request with a closing issue pattern until the very first deployment to a [production environment](#how-the-production-environment-is-identified). If there isn't a production environment, this is not tracked. | +- 09:00: Create issue. **Issue** stage starts. +- 11:00: Add issue to a milestone, start work on the issue, and create a branch locally. + **Issue** stage stops and **Plan** stage starts. +- 12:00: Make the first commit. +- 12:30: Make the second commit to the branch that mentions the issue number. + **Plan** stage stops and **Code** stage starts. +- 14:00: Push branch and create a merge request that contains the + [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically). + **Code** stage stops and **Test** and **Review** stages start. +- GitLab CI/CD takes 5 minutes to run scripts defined in [`.gitlab-ci.yml`](../../../ci/yaml/index.md). +- 19:00: Merge the merge request. **Review** stage stops and **Staging** stage starts. +- 19:30: Deployment to the `production` environment finishes. **Staging** stops. -How this works, behind the scenes: +Value stream analytics records the following times for each stage: -1. Issues and merge requests are grouped together in pairs, such that for each - `<issue, merge request>` pair, the merge request has the [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically) - for the corresponding issue. All other issues and merge requests are **not** - considered. -1. Then the `<issue, merge request>` pairs are filtered out by last XX days (specified - by the UI - default is 90 days). So it prohibits these pairs from being considered. -1. For the remaining `<issue, merge request>` pairs, we check the information that - we need for the stages, like issue creation date, merge request merge time, - and so on. +- **Issue**: 09:00 to 11:00: 2 hrs +- **Plan**: 11:00 to 12:00: 1 hr +- **Code**: 12:00 to 14:00: 2 hrs +- **Test**: 5 minutes +- **Review**: 14:00 to 19:00: 5 hrs +- **Staging**: 19:00 to 19:30: 30 minutes -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: +There are some additional considerations for this example: -- Merge requests that do not close an issue. -- Issues not labeled with a label present in the issue board or for issues not assigned a milestone. -- Staging stage, if the project has no [production environment](#how-the-production-environment-is-identified). +- This example demonstrates that it doesn't matter if your first + commit doesn't mention the issue number, you can do this later in any commit + on the branch you are working on. +- The **Test** stage is used in the calculation for the overall time of + the cycle. It is included in the **Review** process, as every MR should be + tested. +- This example illustrates only **one cycle** of the seven stages. The value stream analytics dashboard + shows the median time for multiple cycles. -## How the production environment is identified +## How value stream analytics identifies the production environment Value stream analytics identifies production environments by looking for project [environments](../../../ci/yaml/index.md#environment) with a name matching any of these patterns: @@ -179,149 +240,22 @@ These patterns are not case-sensitive. You can change the name of a project environment in your GitLab CI/CD configuration. -## Example workflow - -Below is an example workflow of a single cycle that happens in a -single day through all noted stages. Note that if a stage does not include a start -and a stop time, its data is not included in the median time. It is assumed that -milestones are created and a CI for testing and setting environments is configured. -a start and a stop mark, it is not measured and hence not calculated in the median -time. It is assumed that milestones are created and CI for testing and setting -environments is configured. - -1. Issue is created at 09:00 (start of **Issue** stage). -1. Issue is added to a milestone at 11:00 (stop of **Issue** stage / start of - **Plan** stage). -1. Start working on the issue, create a branch locally and make one commit at - 12:00. -1. Make a second commit to the branch which mentions the issue number at 12.30 - (stop of **Plan** stage / start of **Code** stage). -1. Push branch and create a merge request that contains the - [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically) - in its description at 14:00 (stop of **Code** stage / start of **Test** and - **Review** stages). -1. The CI starts running your scripts defined in [`.gitlab-ci.yml`](../../../ci/yaml/index.md) and - takes 5min (stop of **Test** stage). -1. Review merge request, ensure that everything is OK and merge the merge - request at 19:00. (stop of **Review** stage / start of **Staging** stage). -1. Now that the merge request is merged, a deployment to the `production` - environment starts and finishes at 19:30 (stop of **Staging** stage). - -From the above example you can conclude the time it took each stage to complete -as long as their total time: - -- **Issue**: 2h (11:00 - 09:00) -- **Plan**: 1h (12:00 - 11:00) -- **Code**: 2h (14:00 - 12:00) -- **Test**: 5min -- **Review**: 5h (19:00 - 14:00) -- **Staging**: 30min (19:30 - 19:00) - -A few notes: - -- In the above example we demonstrated that it doesn't matter if your first - commit doesn't mention the issue number, you can do this later in any commit - of the branch you are working on. -- You can see that the **Test** stage is not calculated to the overall time of - the cycle, because it is included in the **Review** process (every MR should be - tested). -- The example above was just **one cycle** of the seven stages. Add multiple - cycles, calculate their median time and the result is what the dashboard of - value stream analytics is showing. - ## Custom value streams > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12196) in GitLab 12.9. -The default stages are designed to work straight out of the box, but they might not be suitable for -all teams. Different teams use different approaches to building software, so some teams might want -to customize their value stream analytics. - -GitLab allows users to create multiple value streams, hide default stages and create custom stages -that align better to their development workflow. - -### Stage path - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210315) in GitLab 13.0. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323982) in GitLab 13.12. - - - -Stages are visually depicted as a horizontal process flow. Selecting a stage updates the content -below the value stream. - -The stage time is displayed next to the name of each stage, in the following format: - -| Symbol | Description | -|--------|-------------| -| `m` | Minutes | -| `h` | Hours | -| `d` | Days | -| `w` | Weeks | -| `M` | Months | - -Hovering over a stage item displays a popover with the following information: - -- Start event description for the given stage -- End event description -- Median time items took to complete the stage -- Number of items that completed the stage - -### Stream overview - -> [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. - -Shown metrics and charts includes: - -- [Lead time](#how-metrics-are-measured) -- [Cycle time](#how-metrics-are-measured) -- [Days to completion chart](#days-to-completion-chart) -- [Tasks by type chart](#type-of-work---tasks-by-type-chart) - -### Stage table - -> Sorting the stage table [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301082) in GitLab 13.12. +Use custom value streams to create custom stages that align with your own development processes, +and hide default stages. The dashboard depicts stages as a horizontal process +flow. - - -The stage table shows a list of related workflow items for the selected stage. This can include: - -- CI/CD jobs -- Issues -- Merge requests -- Pipelines - -A little badge next to the workflow items table header shows the number of workflow items that -completed the selected stage. - -The stage table also includes the **Time** column, which shows how long it takes each item to pass -through the selected value stream stage. - -The stage table is not displayed on the stream [Overview](#stream-overview). -The workflow item column (first column) is ordered by end event. - -To sort the stage table by a table column, select the table header. -You can sort in ascending or descending order. To find items that spent the most time in a stage, -potentially causing bottlenecks in your value stream, sort the table by the **Time** column. -From there, select individual items to drill in and investigate how delays are happening. -To see which items most recently exited the stage, sort by the work item column on the left. - -The table displays 20 items per page. If there are more than 20 items, you can use the -**Prev** and **Next** buttons to navigate through the pages. - -### Creating a value stream +### Create a value stream > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221202) in GitLab 13.3 A default value stream is readily available for each group. You can create additional value streams based on the different areas of work that you would like to measure. -Once created, a new value stream includes the [seven stages](#default-stages) that follow +Once created, a new value stream includes the stages that follow [GitLab workflow](../../../topics/gitlab_flow.md) best practices. You can customize this flow by adding, hiding or re-ordering stages. @@ -331,20 +265,17 @@ To create a value stream: 1. On the left sidebar, select **Analytics > Value Stream**. 1. In the top right, select the dropdown list and then **Create new Value Stream**. 1. Enter a name for the new Value Stream. - - You can [customize the stages](#creating-a-value-stream-with-stages). + - You can [customize the stages](#create-a-value-stream-with-stages). 1. Select **Create Value Stream**.  -#### Creating a value stream with stages +### Create a value stream with stages > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50229) in GitLab 13.7. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55572) in GitLab 13.10. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/294190) in GitLab 13.11. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - You can create value streams with stages, starting with a default or a blank template. You can add stages as desired. @@ -364,7 +295,7 @@ To create a value stream with stages:  1. Select **Create Value Stream**. -#### Label-based stages +### Label-based stages The pre-defined start and end events can cover many use cases involving both issues and merge requests. @@ -379,7 +310,7 @@ In this example, we'd like to measure times for deployment from a staging enviro  -### Editing a value stream +### Edit a value stream > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267537) in GitLab 13.10. @@ -388,7 +319,7 @@ After you create a value stream, you can customize it to suit your purposes. To 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value Stream**. 1. In the top right, select the dropdown list and then select the relevant value stream. -1. Next to the value stream dropdown, select **Edit**. +1. Next to the value stream dropdown list, select **Edit**. The edit form is populated with the value stream details. 1. Optional: - Rename the value stream. @@ -399,7 +330,7 @@ After you create a value stream, you can customize it to suit your purposes. To 1. Optional. To undo any modifications, select **Restore value stream defaults**. 1. Select **Save Value Stream**. -### Deleting a value stream +### Delete a value stream > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221205) in GitLab 13.4. @@ -413,19 +344,27 @@ To delete a custom value stream:  -## Days to completion chart +## View number of days for a cycle to complete > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21631) in GitLab 12.6. > - Chart median line [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235455) in GitLab 13.4. > - Totals [replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/262070) with averages in GitLab 13.12. -This chart visually depicts the average number of days it takes for cycles to be completed. - -This chart uses the global page filters for displaying data based on the selected -group, projects, and time frame. In addition, specific stages can be selected -from the chart itself. +The **Total time chart** shows the average number of days it takes for development cycles to complete. +The chart shows data for the last 500 workflow items. -The chart data is limited to the last 500 items. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Value stream**. +1. Above the **Filter results** box, select a stage: + - To view a summary of the cycle time for all stages, select **Overview**. + - To view the cycle time for specific stage, select a stage. +1. Optional. Filter the results: + 1. Select the **Filter results** text box. + 1. Select a parameter. + 1. Select a value or enter text to refine the results. + 1. To adjust the date range: + - In the **From** field, select a start date. + - In the **To** field, select an end date. ## Type of work - Tasks by type chart @@ -439,17 +378,3 @@ toggled to show data for merge requests and further refined for specific group-l By default the top group-level labels (max. 10) are pre-selected, with the ability to select up to a total of 15 labels. - -## Permissions - -To access 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: - -- [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/index.md b/doc/user/index.md index f4a7cd6a5d9..4ce46c5b46f 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -47,6 +47,8 @@ GitLab is a Git-based platform that integrates a great number of essential tools - Reviewing code in [merge requests](project/merge_requests/index.md) with live-preview changes per branch with [Review Apps](../ci/review_apps/index.md). - Building, testing, and deploying with built-in [Continuous Integration](../ci/index.md). +- View the current health and status of each CI environment running on Kubernetes with [deploy boards](project/deploy_boards.md). +- Leverage continuous delivery method with [Canary Deployments](project/canary_deployments.md). - Deploying personal and professional static websites with [GitLab Pages](project/pages/index.md). - Integrating with Docker by using [GitLab Container Registry](packages/container_registry/index.md). - Tracking the development lifecycle by using [GitLab Value Stream Analytics](analytics/value_stream_analytics.md). @@ -66,8 +68,6 @@ With GitLab Enterprise Edition, you can also: - [Mirror a repository](project/repository/mirror/index.md) from elsewhere on your local server. - View your entire CI/CD pipeline involving more than one project with [Multiple-Project Pipelines](../ci/pipelines/multi_project_pipelines.md). - [Lock files](project/file_lock.md) to prevent conflicts. -- View the current health and status of each CI environment running on Kubernetes with [deploy boards](project/deploy_boards.md). -- Leverage continuous delivery method with [Canary Deployments](project/canary_deployments.md). - Scan your code for vulnerabilities and [display them in merge requests](application_security/sast/index.md). You can also [integrate](project/integrations/overview.md) GitLab with numerous third-party applications, such as Mattermost, Microsoft Teams, Trello, Slack, Bamboo CI, Jira, and a lot more. @@ -76,12 +76,15 @@ You can also [integrate](project/integrations/overview.md) GitLab with numerous There are several types of users in GitLab: -- Regular users and GitLab.com users. <!-- Note: further description TBA --> -- [Groups](group/index.md) of users. -- GitLab [administrator area](admin_area/index.md) user. +- Regular users. +- [Internal users](../development/internal_users.md) often referred to as bot or system users. +- [Auditor](permissions.md#auditor-users) with read access to self-managed instances. - [GitLab Administrator](../administration/index.md) with full access to - self-managed instances' features and settings. -- [Internal users](../development/internal_users.md). + self-managed instances including settings and the [Admin Area](admin_area/index.md). + +Each user can be a member in a [group](group/index.md). + +See the [permissions page](permissions.md) for details on how each user type is used. ## User activity @@ -159,8 +162,7 @@ it all at once, from one single project. ## Account -There is a lot you can customize and configure -to enjoy the best of GitLab. +There is a lot you can customize and configure to enjoy the best of GitLab. - [Settings](profile/index.md): Manage your user settings to change your personal information, personal access tokens, authorized applications, etc. @@ -209,8 +211,7 @@ requests you're assigned to. ## Snippets [Snippets](snippets.md) are code blocks that you want to store in GitLab, from which -you have quick access to. You can also gather feedback on them through -[Discussions](#discussions). +you have quick access to. You can also gather feedback on them through [Discussions](#discussions). ## GitLab CI/CD @@ -228,8 +229,7 @@ pages and accomplish tasks faster. ## Integrations -[Integrate GitLab](../integration/index.md) with your preferred tool, -such as Trello, Jira, etc. +[Integrate GitLab](../integration/index.md) with your preferred tool, such as Trello, Jira, etc. ## Webhooks @@ -251,5 +251,4 @@ See [various statistics](admin_area/analytics/index.md) of your GitLab instance. ## Operations Dashboard -See [Operations Dashboard](operations_dashboard/index.md) for a summary of each -project's operational health. +See [Operations Dashboard](operations_dashboard/index.md) for a summary of each project's operational health. diff --git a/doc/user/infrastructure/clusters/connect/index.md b/doc/user/infrastructure/clusters/connect/index.md index 06d1307984d..004f4409919 100644 --- a/doc/user/infrastructure/clusters/connect/index.md +++ b/doc/user/infrastructure/clusters/connect/index.md @@ -8,10 +8,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w The [certificate-based Kubernetes integration with GitLab](../index.md) was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) -in GitLab 14.5. To connect your clusters, use the [GitLab Agent](../../../clusters/agent/index.md). +in GitLab 14.5. To connect your clusters, use the [GitLab agent](../../../clusters/agent/index.md). <!-- TBA: (We need to resolve https://gitlab.com/gitlab-org/gitlab/-/issues/343660 before adding this line) -If you don't have a cluster yet, create one and connect it to GitLab through the Agent. +If you don't have a cluster yet, create one and connect it to GitLab through the agent. You can also create a new cluster from GitLab using [Infrastructure as Code](../../iac/index.md#create-a-new-cluster-through-iac). --> diff --git a/doc/user/infrastructure/clusters/connect/new_eks_cluster.md b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md new file mode 100644 index 00000000000..87b8f510289 --- /dev/null +++ b/doc/user/infrastructure/clusters/connect/new_eks_cluster.md @@ -0,0 +1,132 @@ +--- +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 +--- + +# Create an Amazon EKS cluster + +You can create a cluster on Amazon Elastic Kubernetes Service (EKS) through +[Infrastructure as Code (IaC)](../../index.md). This process uses the AWS and +Kubernetes Terraform providers to create EKS clusters. You connect the clusters to GitLab +by using the GitLab agent for Kubernetes. + +**Prerequisites:** + +- An Amazon Web Services (AWS) account, with a set of configured + [security credentials](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-prereqs.html). +- [A runner](https://docs.gitlab.com/runner/install/) you can use to run the GitLab CI/CD pipeline. + +**Steps:** + +1. [Import the example project](#import-the-example-project). +1. [Register the agent for Kubernetes](#register-the-agent). +1. [Configure your project](#configure-your-project). +1. [Provision your cluster](#provision-your-cluster). + +## Import the example project + +To create a cluster from GitLab using Infrastructure as Code, you must +create a project to manage the cluster from. In this tutorial, you start with +a sample project and modify it according to your needs. + +Start by [importing the example project by URL](../../../project/import/repo_by_url.md). + +To import the project: + +1. On the top bar, select **Menu > Create new project**. +1. Select **Import project**. +1. Select **Repo by URL**. +1. For the **Git repository URL**, enter `https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks.git`. +1. Complete the fields and select **Create project**. + +This project provides you with: + +- An Amazon [Virtual Private Cloud (VPC)](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks/-/blob/main/vpc.tf). +- An Amazon [Elastic Kubernetes Service (EKS)](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks/-/blob/main/eks.tf) cluster. +- The [GitLab agent for Kubernetes](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks/-/blob/main/agent.tf) installed in the cluster. + +## Register the agent + +To create a GitLab agent for Kubernetes: + +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. Select **Actions**. +1. From the **Select an agent** dropdown list, select `eks-agent` and select **Register an agent**. +1. GitLab generates a registration token for the agent. Securely store this secret token, as you will need it later. +1. GitLab provides an address for the agent server (KAS), which you will also need later. + +## Configure your project + +Use CI/CD environment variables to configure your project. + +**Required configuration:** + +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Variables**. +1. Set the variable `AWS_ACCESS_KEY_ID` to your AWS access key ID. +1. Set the variable `AWS_SECRET_ACCESS_KEY` to your AWS secret access key. +1. Set the variable `TF_VAR_agent_token` to the agent token displayed in the previous task. +1. Set the variable `TF_VAR_kas_address` to the agent server address displayed in the previous task. + +**Optional configuration:** + +The file [`variables.tf`](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-eks/-/blob/main/variables.tf) +contains other variables that you can override according to your needs: + +- `TF_VAR_region`: Set your cluster's region. +- `TF_VAR_cluster_name`: Set your cluster's name. +- `TF_VAR_cluster_version`: Set the version of Kubernetes. +- `TF_VAR_instance_type`: Set the instance type for the Kubernetes nodes. +- `TF_VAR_instance_count`: Set the number of Kubernetes nodes. +- `TF_VAR_agent_version`: Set the version of the GitLab agent. +- `TF_VAR_agent_namespace`: Set the Kubernetes namespace for the GitLab agent. + +View the [AWS Terraform provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) and the [Kubernetes Terraform provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs) documentation for further resource options. + +## Provision your cluster + +After configuring your project, manually trigger the provisioning of your cluster. In GitLab: + +1. On the left sidebar, go to **CI/CD > Pipelines**. +1. Next to **Play** (**{play}**), select the dropdown icon (**{angle-down}**). +1. Select **Deploy** to manually trigger the deployment job. + +When the pipeline finishes successfully, you can view the new cluster: + +- In AWS: From the [EKS console](https://console.aws.amazon.com/eks/home), select **Amazon EKS > Clusters**. +- In GitLab: On the left sidebar, select **Infrastructure > Kubernetes clusters**. + +## Use your cluster + +After you provision the cluster, it is connected to GitLab and is ready for deployments. To check the connection: + +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. In the list, view the **Connection status** column. + +For more information about the capabilities of the connection, see [the GitLab agent for Kubernetes documentation](../index.md). + +## Remove the cluster + +A cleanup job is not included in your pipeline by default. To remove all created resources, you +must modify your GitLab CI/CD template before running the cleanup job. + +To remove all resources: + +1. Add the following to your `.gitlab-ci.yml` file: + + ```yaml + stages: + - init + - validate + - build + - deploy + - cleanup + + destroy: + extends: .destroy + needs: [] + ``` + +1. On the left sidebar, select **CI/CD > Pipelines** and select the most recent pipeline. +1. For the `destroy` job, select **Play** (**{play}**). diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md index d1e3bd47b89..1ed8b0ef350 100644 --- a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md @@ -4,65 +4,59 @@ 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 --- -# New GKE cluster through IaC (DEPRECATED) - -> [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. - -WARNING: -The process described on this page uses cluster certificates to connect the -new cluster to GitLab, [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -You can still create a cluster and then connect it to GitLab through the [Agent](../index.md). -[An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/343660) -to migrate this functionality to the [Agent](../index.md). +# Create a Google GKE cluster Learn how to create a new cluster on Google Kubernetes Engine (GKE) through -[Infrastructure as Code (IaC)](../../index.md). - -This process combines the GitLab Terraform and Google Terraform providers -with Kubernetes to help you create GKE clusters and deploy them through -GitLab. - -This document describes how to set up a [group-level cluster](../../../group/clusters/index.md) on GKE by importing an example project to get you started. -You can then modify the project files according to your needs. +[Infrastructure as Code (IaC)](../../index.md). This process uses the Google +and Kubernetes Terraform providers create GKE clusters. You connect the clusters to GitLab +by using the GitLab agent for Kubernetes. **Prerequisites:** -- A GitLab group. -- A GitLab user with the Maintainer role in the group. -- A [GitLab personal access token](../../../profile/personal_access_tokens.md) with `api` access, created by a user with at least the Maintainer role in the group. - A [Google Cloud Platform (GCP) service account](https://cloud.google.com/docs/authentication/getting-started). +- [A runner](https://docs.gitlab.com/runner/install/) you can use to run the GitLab CI/CD pipeline. **Steps:** 1. [Import the example project](#import-the-example-project). -1. [Create your GCP and GitLab credentials](#create-your-gcp-and-gitlab-credentials). +1. [Register the agent for Kubernetes](#register-the-agent). +1. [Create your GCP credentials](#create-your-gcp-credentials). 1. [Configure your project](#configure-your-project). -1. [Deploy your cluster](#deploy-your-cluster). +1. [Provision your cluster](#provision-your-cluster). ## Import the example project -To create a new group-level cluster from GitLab using Infrastructure as Code, it is necessary -to create a project to manage the cluster from. In this tutorial, we import a pre-configured -sample project to help you get started. +To create a cluster from GitLab using Infrastructure as Code, you must +create a project to manage the cluster from. In this tutorial, you start with +a sample project and modify it according to your needs. -Start by [importing the example project by URL](../../../project/import/repo_by_url.md). Use `https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke.git` as URL. +Start by [importing the example project by URL](../../../project/import/repo_by_url.md). -This project provides you with the following resources: +To import the project: + +1. On the top bar, select **Menu > Create new project**. +1. Select **Import project**. +1. Select **Repo by URL**. +1. For the **Git repository URL**, enter `https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke.git`. +1. Complete the fields and select **Create project**. + +This project provides you with: - A [cluster on Google Cloud Platform (GCP)](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke/-/blob/master/gke.tf) with defaults for name, location, node count, and Kubernetes version. -- A [`gitlab-admin` K8s service account](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke/-/blob/master/gitlab-admin.tf) with `cluster-admin` privileges. -- The new group-level cluster connected to GitLab. -- Pre-configures Terraform files: - - ```plaintext - ├── backend.tf # State file Location Configuration - ├── gke.tf # Google GKE Configuration - ├── gitlab-admin.tf # Adding kubernetes service account - └── group_cluster.tf # Registering kubernetes cluster to GitLab `apps` Group - ``` +- The [GitLab agent for Kubernetes](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-gke/-/blob/master/agent.tf) installed in the cluster. -## Create your GCP and GitLab credentials +## Register the agent + +To create a GitLab agent for Kubernetes: + +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. Select **Actions**. +1. From the **Select an agent** dropdown list, select `gke-agent` and select **Register an agent**. +1. GitLab generates a registration token for the agent. Securely store this secret token, as you will need it later. +1. GitLab provides an address for the agent server (KAS), which you will also need later. + +## Create your GCP credentials To set up your project to communicate to GCP and the GitLab API: @@ -85,18 +79,14 @@ The Admin role creates a service account in the `kube-system` namespace. ## Configure your project -**Required configuration:** - -Use CI/CD environment variables to configure your project as detailed below. +Use CI/CD environment variables to configure your project. **Required configuration:** 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Variables**. -1. Set the variable `TF_VAR_gitlab_token` to the GitLab personal access token you just created. 1. Set the variable `BASE64_GOOGLE_CREDENTIALS` to the `base64` encoded JSON file you just created. 1. Set the variable `TF_VAR_gcp_project` to your GCP's `project` name. -1. Set the variable `TF_VAR_gitlab_group` to the name of the group you want to connect your cluster to. If your group's URL is `https://gitlab.example.com/my-example-group`, `my-example-group` is your group's name. **Optional configuration:** @@ -105,22 +95,57 @@ contains other variables that you can override according to your needs: - `TF_VAR_gcp_region`: Set your cluster's region. - `TF_VAR_cluster_name`: Set your cluster's name. -- `TF_VAR_machine_type`: Set the machine type for the Kubernetes nodes. - `TF_VAR_cluster_description`: Set a description for the cluster. We recommend setting this to `$CI_PROJECT_URL` to create a reference to your GitLab project on your GCP cluster detail page. This way you know which project was responsible for provisioning the cluster you see on the GCP dashboard. -- `TF_VAR_base_domain`: Set to the base domain to provision resources under. -- `TF_VAR_environment_scope`: Set to the environment scope for your cluster. +- `TF_VAR_machine_type`: Set the machine type for the Kubernetes nodes. +- `TF_VAR_node_count`: Set the number of Kubernetes nodes. +- `TF_VAR_agent_version`: Set the version of the GitLab agent. +- `TF_VAR_agent_namespace`: Set the Kubernetes namespace for the GitLab agent. -Refer to the [GitLab Terraform provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs) and the [Google Terraform provider](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference) documentation for further resource options. +Refer to the [Google Terraform provider](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference) and the [Kubernetes Terraform provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs) documentation for further resource options. -## Deploy your cluster +## Provision your cluster -After configuring your project, manually trigger the deployment of your cluster. In GitLab: +After configuring your project, manually trigger the provisioning of your cluster. In GitLab: -1. From your project's sidebar, go to **CI/CD > Pipelines**. -1. Select the dropdown icon (**{angle-down}**) next to the play icon (**{play}**). -1. Select **deploy** to manually trigger the deployment job. +1. On the left sidebar, go to **CI/CD > Pipelines**. +1. Next to **Play** (**{play}**), select the dropdown icon (**{angle-down}**). +1. Select **Deploy** to manually trigger the deployment job. When the pipeline finishes successfully, you can see your new cluster: - In GCP: on your [GCP console's Kubernetes list](https://console.cloud.google.com/kubernetes/list). - In GitLab: from your project's sidebar, select **Infrastructure > Kubernetes clusters**. + +## Use your cluster + +After you provision the cluster, it is connected to GitLab and is ready for deployments. To check the connection: + +1. On the left sidebar, select **Infrastructure > Kubernetes clusters**. +1. In the list, view the **Connection status** column. + +For more information about the capabilities of the connection, see [the GitLab agent for Kubernetes documentation](../index.md). + +## Remove the cluster + +A cleanup job is not included in your pipeline by default. To remove all created resources, you +must modify your GitLab CI/CD template before running the cleanup job. + +To remove all resources: + +1. Add the following to your `.gitlab-ci.yml` file: + + ```yaml + stages: + - init + - validate + - build + - deploy + - cleanup + + destroy: + extends: .destroy + needs: [] + ``` + +1. On the left sidebar, select **CI/CD > Pipelines** and select the most recent pipeline. +1. For the `destroy` job, select **Play** (**{play}**). diff --git a/doc/user/infrastructure/clusters/deploy/inventory_object.md b/doc/user/infrastructure/clusters/deploy/inventory_object.md index 47063dcae96..d76ef0b9359 100644 --- a/doc/user/infrastructure/clusters/deploy/inventory_object.md +++ b/doc/user/infrastructure/clusters/deploy/inventory_object.md @@ -4,66 +4,74 @@ 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 --- -# Inventory object **(PREMIUM)** +# Tracking cluster resources managed by GitLab **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0. -An inventory object is a `ConfigMap` object for keeping track of the set of objects applied to a cluster. -When you remove objects from a manifest repository, the Agent uses a corresponding inventory object to -prune (delete) objects from the cluster. +GitLab uses an inventory object to track the resources you deploy to your cluster. +The inventory object is a `ConfigMap` that contains a list of controlled objects. +The managed resources use the `cli-utils.sigs.k8s.io/inventory-id` annotation. -The Agent creates an inventory object for each manifest project specified in the -`gitops.manifest_projects` configuration section. The inventory object has to be stored somewhere in the cluster. -The default behavior is: +## Default location of the inventory object -- The `namespace` used comes from `gitops.manifest_projects[].default_namespace`. If you don't specify this parameter - explicitly, the inventory object is stored in the `default` namespace. -- The `name` is generated from the numeric project ID of the manifest project and the numeric agent ID. +In the agent configuration file, you specify a list of projects. For example: - This way the Agent constructs the name and local where the inventory object is - stored in the cluster. +```yaml +gitops: + manifest_projects: + - id: gitlab-org/cluster-integration/gitlab-agent + default_namespace: my-ns +``` -The Agent cannot locate the existing inventory object if you: +The agent creates an inventory object for every item in the `manifest_projects` list. +The inventory object is stored in the namespace you specify for `default_namespace`. -- Change `gitops.manifest_projects[].default_namespace` parameter. -- Move manifests into another project. +The name and location of the inventory object is based on: -## Inventory object template +- The `default_namespace`. If you don't specify this parameter, + the inventory object is stored in the `default` namespace. +- The `name`, which is the ID of the project with the manifest and the ID of the agent. -The inventory object template is a `ConfigMap` object that allows you to configure the namespace and the name of the inventory -object. Store this template with manifest files in a single group. +WARNING: +The agent cannot locate the existing inventory object if you change +the `default_namespace` parameter or move manifests to another project. -Example inventory object template: +## Change the location of the inventory object -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: unique-name-for-the-inventory - namespace: my-project-namespace - labels: - cli-utils.sigs.k8s.io/inventory-id: unique-name-for-the-inventory -``` +You can configure the namespace and the name of the inventory object. +This action changes the location of the object in the cluster. + +1. Create an inventory object template, which is a `ConfigMap` object. + For example: + + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + name: unique-name-for-the-inventory + namespace: my-project-namespace + labels: + cli-utils.sigs.k8s.io/inventory-id: unique-name-for-the-inventory + ``` + +1. Specify a `namespace` and `name`. Ensure that the `name` is unique so it doesn't conflict with other + inventory objects in the same namespace in the future. +1. Ensure the value for `cli-utils.sigs.k8s.io/inventory-id` is unique. This value is used for objects + tracked by this inventory object. Their `config.k8s.io/owning-inventory` annotation is set to this value. + + The value doesn't have to match the `name` but it's convenient to set them to the same value. + +1. Save the file with the manifest files as a single logical group. -- The `namespace` and `name` fields configure where the real inventory object is created. -- The `cli-utils.sigs.k8s.io/inventory-id` label with its corresponding value is set on the inventory object, created - from this template. Make sure that the value is unique (for example, a string of random characters) and doesn't clash - with any existing or future inventory object templates. -- Objects tracked by this inventory object have the `config.k8s.io/owning-inventory` annotation set to the value of - the `cli-utils.sigs.k8s.io/inventory-id` label. -- The label's value doesn't have to match the `name` but it's convenient to have them set to the same value. -- Make sure that the `name` is unique so that it doesn't conflict with another inventory object in the same - namespace in the future. +## `inventory_policy` options -## Using GitOps with pre-existing Kubernetes objects +Sometimes your manifest changes affect resources that aren't tracked by the GitLab inventory object. -The Agent treats manifest files in the manifest repository as the source of truth. When it applies -objects from the files to the cluster, it tracks them in an inventory object. If an object already exists, -The Agent behaves differently based on the `gitops.manifest_projects[].inventory_policy` configuration. -Check the table below with the available options and when to use them. +To change how the agent behaves when it overwrites existing and previously untracked resources, +change the `inventory_policy` value. `inventory_policy` value | Description | ------------------------ | ------------------------------------------------------------------------------------------- | -`must_match` | This is the default policy. A live object must have the `config.k8s.io/owning-inventory` annotation set to the same value as the `cli-utils.sigs.k8s.io/inventory-id` label on the corresponding inventory object to be updated. Object is not updated and an error is reported if the values don't match or the object doesn't have the annotation. | -`adopt_if_no_inventory` | This mode allows to "adopt" an object if it doesn't have the `config.k8s.io/owning-inventory` annotation. Use this mode if you want to start managing existing objects using the GitOps feature. Once all objects have been "adopted", we recommend you to put the setting back into the default `must_match` mode to avoid any unexpected adoptions. | -`adopt_all` | This mode allows to "adopt" an object even if it has the `config.k8s.io/owning-inventory` annotation set to a different value. This mode can be useful if you want to migrate a set of objects from one agent to another one or from some other tool to the Agent. Once all objects have been "adopted", we recommend you to put the setting back into the default `must_match` mode to avoid any unexpected adoptions. | +`must_match` | The default policy. To be updated, a live object must have the `config.k8s.io/owning-inventory` annotation set to the same value as the `cli-utils.sigs.k8s.io/inventory-id` label on the corresponding inventory object. If the values don't match or the object doesn't have the annotation, the object is not updated and an error is reported. | +`adopt_if_no_inventory` | Adopt an object if it doesn't have the `config.k8s.io/owning-inventory` annotation. Use this mode if you want to start managing existing objects by using the GitOps feature. To avoid unexpected adoptions, after all objects have been adopted, put the setting back to the default `must_match` mode. | +`adopt_all` | Adopt an object even if it has the `config.k8s.io/owning-inventory` annotation set to a different value. Use this mode if you want to migrate a set of objects from one agent to another, or from some other tool to the agent. To avoid unexpected adoptions, after all objects have been adopted, put the setting back to the default `must_match` mode. | diff --git a/doc/user/infrastructure/clusters/index.md b/doc/user/infrastructure/clusters/index.md index 144a8cd2d31..cd7c5feb284 100644 --- a/doc/user/infrastructure/clusters/index.md +++ b/doc/user/infrastructure/clusters/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Kubernetes clusters **(FREE)** -To connect clusters to GitLab, use the [GitLab Agent](../../clusters/agent/index.md). +To connect clusters to GitLab, use the [GitLab agent](../../clusters/agent/index.md). ## Certificate-based Kubernetes integration (DEPRECATED) @@ -24,7 +24,7 @@ It had the following issues: - Users were constantly reporting issues with features based on this model. For this reason, we started to build features based on a new model, the -[GitLab Agent](../../clusters/agent/index.md). +[GitLab agent](../../clusters/agent/index.md). Maintaining both methods in parallel caused a lot of confusion and significantly increased the complexity to use, develop, maintain, and document them. For this reason, we decided to deprecate them to focus on the @@ -38,7 +38,7 @@ Follow this [epic](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) for updates. You can find technical information about why we moved away from cluster certificates into -the GitLab Agent model on the [Agent's blueprint documentation](../../../architecture/blueprints/gitlab_to_kubernetes_communication/index.md). +the GitLab agent model on the [agent's blueprint documentation](../../../architecture/blueprints/gitlab_to_kubernetes_communication/index.md). ## Deprecated features @@ -67,6 +67,5 @@ The concept of [project-level](../../project/clusters/index.md), [instance-level](../../instance/clusters/index.md) clusters becomes extinct in the new model, although the functionality remains to some extent. -The Agent is always configured in a single GitLab project, but you can use the CI/CD Tunnel to -[authorize other projects and groups to use the same Agent](../../clusters/agent/repository.md#authorize-projects-and-groups-to-use-an-agent). +The agent is always configured in a single GitLab project and you can expose the cluster connection to other projects and groups to [access it from GitLab CI/CD](../../clusters/agent/ci_cd_tunnel.md). By doing so, you are granting these projects and groups access to the same cluster, which is similar to group-level clusters' use case. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md index 841f2af7863..4faf5f46418 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/runner.md @@ -4,7 +4,7 @@ group: Runner info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Install GitLab Runner with a cluster management project +# Install GitLab Runner with a cluster management project **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/merge_requests/5) in GitLab 14.0. diff --git a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md index 1dd1c760bcc..01530422e4a 100644 --- a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md +++ b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md @@ -4,85 +4,78 @@ 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)** +# 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 connect your Kubernetes cluster with GitLab, you can use: -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. +- [A GitOps workflow](../../clusters/agent/gitops.md). +- [A GitLab CI/CD workflow](../../clusters/agent/ci_cd_tunnel.md). +- [A certificate-based integration](index.md). -The certificate-based integration was used for some popular GitLab features such as, -GitLab Managed Apps, GitLab-managed clusters, and Auto DevOps. +The certificate-based integration is +[**deprecated**](https://about.gitlab.com/blog/2021/11/15/deprecating-the-cert-based-kubernetes-integration/) +in GitLab 14.5. It is expected to be +[turned off by default in 15.0](../../../update/deprecations.md#certificate-based-integration-with-kubernetes) +and removed in GitLab 15.6. + +If you are using the certificate-based integration, you should move to another workflow as soon as possible. -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. +As a general rule, to migrate clusters that rely on GitLab CI/CD, +you can use the [CI/CD workflow](../../clusters/agent/ci_cd_tunnel.md). +This workflow uses an agent to connect to your cluster. The agent: + +- Is not exposed to the internet. +- Does not require full cluster-admin access to GitLab. 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. +The certificate-based integration was used for popular GitLab features like +GitLab Managed Apps, GitLab-managed clusters, and Auto DevOps. +Some features are currently available only when using certificate-based integration. ## 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. +for every branch and deploys by 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) +The GitLab agent uses [impersonation](../../clusters/agent/ci_cd_tunnel.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. +1. Use the `access_as` attribute in your agent configuration file to define the impersonation. ### Migrate from Auto DevOps -To configure your Auto DevOps project to use the GitLab Agent: +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. Follow the steps to [install an agent](../../clusters/agent/install/index.md) in your cluster. +1. Go to the project where you use Auto DevOps. +1. On the left 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. On the left 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**. +1. To activate the changes, on the left 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: +For an example, [view this project](https://gitlab.com/gitlab-examples/ops/gitops-demo/hello-world-service). -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: +### Migrate generic deployments - ```yaml - <your job name>: - script: - - kubectl config use-context $KUBE_CONTEXT - ``` +Follow the process for the [CI/CD workflow](../../clusters/agent/ci_cd_tunnel.md). -## Migrate from GitLab Managed Applications +## 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). +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 +## Migrate 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). +See [how to use a cluster management project with the GitLab agent](../../clusters/management_project_template.md). ## Migrate cluster monitoring features -Cluster monitoring features are not supported by the GitLab Agent for Kubernetes yet. +Cluster monitoring features are not yet supported by the GitLab agent for Kubernetes. diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index 6fef1aa7879..3bc7495d4be 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -60,9 +60,9 @@ This video from January 2021 walks you through all the GitLab Terraform integrat ## GitLab-managed Terraform state -[Terraform remote backends](https://www.terraform.io/docs/language/settings/backends/index.html) +[Terraform remote backends](https://www.terraform.io/language/settings/backends) enable you to store the state file in a remote, shared store. GitLab uses the -[Terraform HTTP backend](https://www.terraform.io/docs/language/settings/backends/http.html) +[Terraform HTTP backend](https://www.terraform.io/language/settings/backends/http) to securely store the state files in local storage (the default) or [the remote store of your choice](../../../administration/terraform_state.md). @@ -105,16 +105,10 @@ owned by GitLab, where everyone can contribute. The [documentation of the provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs) is available as part of the official Terraform provider documentation. -## Create a new cluster through IaC (DEPRECATED) +## Create a new cluster through IaC -Learn how to [create a new cluster on Google Kubernetes Engine (GKE)](../clusters/connect/new_gke_cluster.md). - -NOTE: -The linked tutorial connects the cluster to GitLab through cluster certificates, -and this method was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) -in GitLab 14.5. You can still create a cluster through IaC and then connect it to GitLab -through the [agent](../../clusters/agent/index.md), the default and fully supported -method to connect clusters to GitLab. +- Learn how to [create a new cluster on Amazon Elastic Kubernetes Service (EKS)](../clusters/connect/new_eks_cluster.md). +- Learn how to [create a new cluster on Google Kubernetes Engine (GKE)](../clusters/connect/new_gke_cluster.md). ## Troubleshooting diff --git a/doc/user/infrastructure/iac/mr_integration.md b/doc/user/infrastructure/iac/mr_integration.md index 8c135f18bc1..bcad5c9279a 100644 --- a/doc/user/infrastructure/iac/mr_integration.md +++ b/doc/user/infrastructure/iac/mr_integration.md @@ -151,8 +151,8 @@ apply: ### Multiple Terraform Plan reports -Starting with GitLab version 13.2, you can display multiple reports on a merge request. -The reports also display the `artifacts: name:`. See example below for a suggested setup. +Starting with GitLab version 13.2, you can display multiple reports on the merge request +page. The reports also display the `artifacts: name:`. See example below for a suggested setup. ```yaml default: diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index 8fd38215b04..39a57b60787 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -8,9 +8,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. -[Terraform remote backends](https://www.terraform.io/docs/language/settings/backends/index.html) +[Terraform remote backends](https://www.terraform.io/language/settings/backends) enable you to store the state file in a remote, shared store. GitLab uses the -[Terraform HTTP backend](https://www.terraform.io/docs/language/settings/backends/http.html) +[Terraform HTTP backend](https://www.terraform.io/language/settings/backends/http) to securely store the state files in local storage (the default) or [the remote store of your choice](../../../administration/terraform_state.md). @@ -222,9 +222,9 @@ See [this reference project](https://gitlab.com/gitlab-org/configure/examples/gi ## Using a GitLab-managed Terraform state backend as a remote data source You can use a GitLab-managed Terraform state as a -[Terraform data source](https://www.terraform.io/docs/language/state/remote-state-data.html). +[Terraform data source](https://www.terraform.io/language/state/remote-state-data). To use your existing Terraform state backend as a data source, provide the following details -as [Terraform input variables](https://www.terraform.io/docs/language/values/variables.html): +as [Terraform input variables](https://www.terraform.io/language/values/variables): - **address**: The URL of the remote state backend you want to use as a data source. For example, `https://gitlab.com/api/v4/projects/<TARGET-PROJECT-ID>/terraform/state/<TARGET-STATE-NAME>`. diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md index d8e75928675..73e57ea3d59 100644 --- a/doc/user/infrastructure/index.md +++ b/doc/user/infrastructure/index.md @@ -30,11 +30,11 @@ Learn more about how GitLab can help you run [Infrastructure as Code](iac/index. ## Integrated Kubernetes management The GitLab integration with Kubernetes helps you to install, configure, manage, deploy, and troubleshoot -cluster applications. With the GitLab Agent, you can connect clusters behind a firewall, +cluster applications. With the GitLab agent, you can connect clusters behind a firewall, have real-time access to API endpoints, perform pull-based or push-based deployments for production and non-production environments, and much more. -Learn more about the [GitLab Agent](../clusters/agent/index.md). +Learn more about the [GitLab agent](../clusters/agent/index.md). ## Runbooks in GitLab diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index a184f00f6f6..a5c1402b9ec 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. To connect clusters to GitLab, -use the [GitLab Agent](../../clusters/agent/index.md). +use the [GitLab agent](../../clusters/agent/index.md). Similar to [project-level](../../project/clusters/index.md) and [group-level](../../group/clusters/index.md) Kubernetes clusters, diff --git a/doc/user/markdown.md b/doc/user/markdown.md index a16f8fd39b1..c81fdc275d9 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -30,7 +30,7 @@ and the [main GitLab website](https://about.gitlab.com) use [Kramdown](https://k You should not view this page in the documentation, but instead [view these styles as they appear on GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md). GitLab Flavored Markdown extends the [CommonMark specification](https://spec.commonmark.org/current/). -It was inspired by [GitHub Flavored Markdown](https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). +It was inspired by [GitHub Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). ## Where you can use GitLab Flavored Markdown @@ -67,15 +67,15 @@ Features not found in standard Markdown: Features [extended from standard Markdown](#features-extended-from-standard-markdown): -| Standard Markdown | Extended Markdown in GitLab | -| ------------------------------------- | ------------------------- | -| [blockquotes](#blockquotes) | [multi-line blockquotes](#multiline-blockquote) | -| [code blocks](#code-spans-and-blocks) | [colored code and syntax highlighting](#colored-code-and-syntax-highlighting) | -| [emphasis](#emphasis) | [multiple underscores in words](#multiple-underscores-in-words-and-mid-word-emphasis) -| [headers](#headers) | [linkable Header IDs](#header-ids-and-links) | -| [images](#images) | [embedded videos](#videos) and [audio](#audio) | -| [line breaks](#line-breaks) | [more line break control](#newlines) | -| [links](#links) | [automatically linking URLs](#url-auto-linking) | +| Standard Markdown | Extended Markdown in GitLab | +|---------------------------------------|---------------------------------------------------------------------------------------| +| [blockquotes](#blockquotes) | [multi-line blockquotes](#multiline-blockquote) | +| [code blocks](#code-spans-and-blocks) | [colored code and syntax highlighting](#colored-code-and-syntax-highlighting) | +| [emphasis](#emphasis) | [multiple underscores in words](#multiple-underscores-in-words-and-mid-word-emphasis) | +| [headers](#headers) | [linkable Header IDs](#header-ids-and-links) | +| [images](#images) | [embedded videos](#videos) and [audio](#audio) | +| [line breaks](#line-breaks) | [more line break control](#newlines) | +| [links](#links) | [automatically linking URLs](#url-auto-linking) | ## Features not found in standard Markdown @@ -262,7 +262,7 @@ The following delimiters are supported: --- title: About Front Matter example: - language: yaml + language: yaml --- ``` @@ -515,31 +515,31 @@ version to reference other projects from the same namespace. GitLab Flavored Markdown recognizes the following: -| references | input | cross-project reference | shortcut inside same namespace | -| :--------------------------------------------------- | :---------------------------- | :----------------------------------------- | :------------------------------- | -| specific user | `@user_name` | | | -| specific group | `@group_name` | | | -| entire team | `@all` | | | -| project | `namespace/project>` | | | -| issue | ``#123`` | `namespace/project#123` | `project#123` | -| merge request | `!123` | `namespace/project!123` | `project!123` | -| snippet | `$123` | `namespace/project$123` | `project$123` | -| [epic](group/epics/index.md) | `&123` | `group1/subgroup&123` | | -| vulnerability **(ULTIMATE)** <sup>1</sup> | `[vulnerability:123]` | `[vulnerability:namespace/project/123]` | `[vulnerability:project/123]` | -| feature flag | `[feature_flag:123]` | `[feature_flag:namespace/project/123]` | `[feature_flag:project/123]` | -| label by ID | `~123` | `namespace/project~123` | `project~123` | -| one-word label by name | `~bug` | `namespace/project~bug` | `project~bug` | -| multi-word label by name | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | -| scoped label by name | `~"priority::high"` | `namespace/project~"priority::high"` | `project~"priority::high"` | -| project milestone by ID | `%123` | `namespace/project%123` | `project%123` | -| one-word milestone by name | `%v1.23` | `namespace/project%v1.23` | `project%v1.23` | -| multi-word milestone by name | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` | -| specific commit | `9ba12248` | `namespace/project@9ba12248` | `project@9ba12248` | -| commit range comparison | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` | -| repository file references | `[README](doc/README.md)` | | | -| repository file line references | `[README](doc/README.md#L13)` | | | -| [alert](../operations/incident_management/alerts.md) | `^alert#123` | `namespace/project^alert#123` | `project^alert#123` | -| contact | `[contact:test@example.com]` | | | +| references | input | cross-project reference | shortcut inside same namespace | +|:----------------------------------------------------------------------------|:------------------------------|:----------------------------------------|:-------------------------------| +| specific user | `@user_name` | | | +| specific group | `@group_name` | | | +| entire team | `@all` | | | +| project | `namespace/project>` | | | +| issue | ``#123`` | `namespace/project#123` | `project#123` | +| merge request | `!123` | `namespace/project!123` | `project!123` | +| snippet | `$123` | `namespace/project$123` | `project$123` | +| [epic](group/epics/index.md) | `&123` | `group1/subgroup&123` | | +| [vulnerability](application_security/vulnerabilities/index.md) <sup>1</sup> | `[vulnerability:123]` | `[vulnerability:namespace/project/123]` | `[vulnerability:project/123]` | +| feature flag | `[feature_flag:123]` | `[feature_flag:namespace/project/123]` | `[feature_flag:project/123]` | +| label by ID | `~123` | `namespace/project~123` | `project~123` | +| one-word label by name | `~bug` | `namespace/project~bug` | `project~bug` | +| multi-word label by name | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | +| scoped label by name | `~"priority::high"` | `namespace/project~"priority::high"` | `project~"priority::high"` | +| project milestone by ID | `%123` | `namespace/project%123` | `project%123` | +| one-word milestone by name | `%v1.23` | `namespace/project%v1.23` | `project%v1.23` | +| multi-word milestone by name | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` | +| specific commit | `9ba12248` | `namespace/project@9ba12248` | `project@9ba12248` | +| commit range comparison | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` | +| repository file references | `[README](doc/README.md)` | | | +| repository file line references | `[README](doc/README.md#L13)` | | | +| [alert](../operations/incident_management/alerts.md) | `^alert#123` | `namespace/project^alert#123` | `project^alert#123` | +| contact | `[contact:test@example.com]` | | | 1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222483) in GitLab 13.7. @@ -1486,7 +1486,7 @@ but they do not render properly on `docs.gitlab.com`: #### Copy from spreadsheet and paste in Markdown -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27205) in GitLab 12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27205) in GitLab 12.7. If you're working in spreadsheet software (for example, Microsoft Excel, Google Sheets, or Apple Numbers), GitLab creates a Markdown table when you copy-and-paste diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index 5cfb4278a2c..ea12b225717 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -22,6 +22,9 @@ Then, install the packages whenever you need to use them as a dependency. For documentation of the specific API endpoints that the Composer client uses, see the [Composer API documentation](../../../api/packages/composer.md). +Composer v2.0 is recommended. Composer v1.0 is supported, but it has lower performance when working +in groups with very large numbers of packages. + ## Create a Composer package If you do not have a Composer package, create one and check it in to diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index b28f0cbfb35..5b6c71d4dd2 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -553,13 +553,6 @@ this setting. However, disabling the Container Registry disables all Container R | Private project with Container Registry visibility <br/> set to **Only Project Members** (UI) or `private` (API) | View Container Registry <br/> and pull images | No | No | Yes | | Any project with Container Registry `disabled` | All operations on Container Registry | No | No | No | -## Manifest lists and garbage collection - -Manifest lists are commonly used for creating multi-architecture images. If you rely on manifest -lists, you should tag all the individual manifests referenced by a list in their respective -repositories, and not just the manifest list itself. This ensures that those manifests aren't -garbage collected, as long as they have at least one tag pointing to them. - ## Troubleshooting the GitLab Container Registry ### Docker connection error @@ -702,3 +695,10 @@ There may be some errors not properly cached. Follow these steps to investigate 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. + +### Tags temporarily cannot be marked for deletion + +GitLab is [migrating to the next generation of the Container Registry](https://gitlab.com/groups/gitlab-org/-/epics/5523). +During the migration, you may encounter difficulty deleting tags. +If you encounter an error, it's likely that your image repository is in the process of being migrated. +Please wait a few minutes and try again. diff --git a/doc/user/packages/container_registry/reduce_container_registry_storage.md b/doc/user/packages/container_registry/reduce_container_registry_storage.md index a2a22f138e3..7e8b2865b6e 100644 --- a/doc/user/packages/container_registry/reduce_container_registry_storage.md +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -49,20 +49,6 @@ Cleanup policies can be run on all projects, with these exceptions: There are performance risks with enabling it for all projects, especially if you are using an [external registry](#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 @@ -171,22 +157,32 @@ Here are examples of regex patterns you may want to use: ### 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). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/288812) in GitLab 13.9 [with a flag](../../../administration/feature_flags.md) named `container_registry_expiration_policies_throttling`. Disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80815) in GitLab 14.9. + +FLAG: +By default this feature is available in GitLab 14.9. To disable the feature, an administrator can +[disable the feature flag](../../../administration/feature_flags.md) +named `container_registry_expiration_policies_throttling`. 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. +- `container_registry_expiration_policies_worker_capacity`: the maximum number of cleanup workers + running concurrently. This must be greater than or equal to `0`. We recommend starting with a low + number and increasing it after monitoring the resources used by the background workers. To remove + all workers and not execute the cleanup policies, set this to `0`. The default value is `4`. +- `container_registry_delete_tags_service_timeout`: the maximum time (in seconds) that the cleanup + process can take to delete a batch of tags. The default value is `250`. +- `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 and increasing it after monitoring that container images are properly + deleted. The default value is `200`. +- `container_registry_expiration_policies_caching`: enable or disable tag creation timestamp caching + during execution of policies. Cached timestamps are stored in [Redis](../../../development/architecture.md#redis). + Enabled by default. For self-managed instances, those settings can be updated in the [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): @@ -194,31 +190,11 @@ For self-managed instances, those settings can be updated in the [Rails console] 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): +They are also 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. diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index 925a1b3e8e6..e431d4d7de3 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -312,3 +312,14 @@ services: - name: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/docker:18.09.7-dind alias: docker ``` + +### "Not Found" error when pulling image + +Docker errors similar to the following may indicate that the user running the build job doesn't have +a minimum of the Guest role in the specified Dependency Proxy group: + +```plaintext +ERROR: gitlab.example.com:443/group1/dependency_proxy/containers/alpine:latest: not found + +failed to solve with frontend dockerfile.v0: failed to create LLB definition: gitlab.example.com:443/group1/dependency_proxy/containers/alpine:latest: not found +``` diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index ada6f033288..9dc859a37e2 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -6,12 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Generic Packages Repository **(FREE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4209) in GitLab 13.5. -> - It's [deployed behind a feature flag](../../../user/feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It's able to be enabled or disabled per-project. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-generic-packages-in-the-package-registry). +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4209) in GitLab 13.5 [with a flag](../../../administration/feature_flags.md) named `generic_packages`. Enabled by default. +> - [Feature flag `generic_packages`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80886) removed in GitLab 14.8. 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. @@ -194,31 +190,6 @@ upload: - Invoke-RestMethod -Headers @{ "JOB-TOKEN"="$CI_JOB_TOKEN" } -InFile path/to/file.txt -uri "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/0.0.1/file.txt" -Method put ``` -### Enable or disable generic packages in the Package Registry - -Support for generic packages is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -# For the instance -Feature.enable(:generic_packages) -# For a single project -Feature.enable(:generic_packages, Project.find(<project id>)) -``` - -To disable it: - -```ruby -# For the instance -Feature.disable(:generic_packages) -# For a single project -Feature.disable(:generic_packages, Project.find(<project id>)) -``` - ### Generic package sample project The [Write CI-CD Variables in Pipeline](https://gitlab.com/guided-explorations/cfg-data/write-ci-cd-variables-in-pipeline) project contains a working example you can use to create, upload, and download generic packages in GitLab CI/CD. diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index a2228148447..b980f6a5694 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -60,6 +60,12 @@ For most package types, the following credential types are valid: allows access to packages in the project running the job for the users running the pipeline. Access to other external projects can be configured. + NOTE: + There's an open issue, + [GitLab-#333444](https://gitlab.com/gitlab-org/gitlab/-/issues/333444), + which prevents you from using a job token with internal projects. This bug only impacts self-managed + GitLab instances. + ## 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/package_registry/reduce_package_registry_storage.md b/doc/user/packages/package_registry/reduce_package_registry_storage.md index c2e4cd8d889..f8a1e63a228 100644 --- a/doc/user/packages/package_registry/reduce_package_registry_storage.md +++ b/doc/user/packages/package_registry/reduce_package_registry_storage.md @@ -16,7 +16,7 @@ We recommend deleting unnecessary packages and files. This page offers examples ## Check Package Registry Storage Use -The Usage Quotas page (**Settings > Usage Quotas > Storage**) displays storage usage for Packages. +The Usage Quotas page (**Settings > Usage Quotas > Storage**) displays storage usage for Packages. ## Delete a package diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index bf007572ac7..4d46032d229 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -254,7 +254,9 @@ Prerequisites: - The maximum allowed package size is 5 GB. - You can't upload the same version of a package multiple times. If you try, you receive the error `400 Bad Request`. -- You cannot publish PyPI packages to a group, only to a project. +- PyPI packages are published using your projectID. +- If your project is in a group, PyPI packages published to your project registry are also available + at the group-level registry (see [Install from the group level](#install-from-the-group-level)). You can then [publish a package by using twine](#publish-a-pypi-package-by-using-twine). diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index 6fc47a23373..a107d06a63c 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -36,7 +36,7 @@ PUT /projects/:id/packages/terraform/modules/:module-name/:module-system/:module | -------------------| --------------- | ---------| -------------------------------------------------------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/index.md#namespaced-path-encoding). | | `module-name` | string | yes | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), or hyphens (`-`) and cannot exceed 64 characters. -| `module-system` | string | yes | The package system. It can contain only lowercase letters (`a-z`) and numbers (`0-9`), and cannot exceed 64 characters. +| `module-system` | string | yes | The package system. It can contain only lowercase letters (`a-z`) and numbers (`0-9`), and cannot exceed 64 characters. More information can be found in the [Terraform Module Registry Protocol documentation](https://www.terraform.io/internals/module-registry-protocol). | `module-version` | string | yes | The package version. It must be valid according to the [Semantic Versioning Specification](https://semver.org/). Provide the file content in the request body. @@ -93,7 +93,7 @@ credentials "gitlab.com" { Where `gitlab.com` can be replaced with the hostname of your self-managed GitLab instance. -You can then reference your Terraform Module from a downstream Terraform project: +You can then refer to your Terraform Module from a downstream Terraform project: ```plaintext module "<module>" { @@ -101,6 +101,8 @@ module "<module>" { } ``` +Where `<namespace>` is the [namespace](../../../user/group/index.md#namespaces) of the Terraform module registry. + ## Publish a Terraform module by using CI/CD To work with Terraform modules in [GitLab CI/CD](../../../ci/index.md), you can use diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 4476b0dd75b..c90f575e83a 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -4,7 +4,7 @@ group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Permissions and roles +# Permissions and roles **(FREE)** Users have different abilities depending on the role they have in a particular group or project. If a user is both in a project's group and the @@ -33,168 +33,176 @@ usernames. A GitLab administrator can configure the GitLab instance to ## Project members permissions +- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/219299) in GitLab 14.8, personal namespace owners appear with Owner role in new projects in their namespace. Introduced [with a flag](../administration/feature_flags.md) named `personal_project_owner_with_owner_access`. Disabled by default. +- [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/351919) in GitLab 14.9. Feature flag `personal_project_owner_with_owner_access` [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/219299). + A user's role determines what permissions they have on a project. The Owner role provides all permissions but is available only: - For group owners. The role is inherited for a group's projects. - For Administrators. -Personal namespace owners have the same permissions as an Owner, but are displayed with the Maintainer role on projects created in their personal namespace. -For more information, see [projects members documentation](project/members/index.md). +Personal [namespace](group/index.md#namespaces) owners: + +- Are displayed as having the Maintainer role on projects in the namespace, but have the same permissions as a user with the Owner role. +- In GitLab 14.9 and later, for new projects in the namespace, are displayed as having the Owner role. + +For more information about how to manage project members, see +[members of a project](project/members/index.md). 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)** | | | | | ✓ | -| [Clusters](infrastructure/clusters/index.md):<br>View [pod logs](project/clusters/kubernetes_pod_logs.md) | | | ✓ | ✓ | ✓ | -| [Clusters](infrastructure/clusters/index.md):<br>View clusters | | | ✓ | ✓ | ✓ | -| [Clusters](infrastructure/clusters/index.md):<br>Manage clusters | | | | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete cleanup policies | | | ✓ | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Push an image to the Container Registry | | | ✓ | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Pull an image from the Container Registry | ✓ (*20*) | ✓ (*20*) | ✓ | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Remove a Container Registry image | | | ✓ | ✓ | ✓ | -| [GitLab Pages](project/pages/index.md):<br>View Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [GitLab Pages](project/pages/index.md):<br>Manage | | | | ✓ | ✓ | -| [GitLab Pages](project/pages/index.md):<br>Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | -| [GitLab Pages](project/pages/index.md):<br>Remove GitLab Pages | | | | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>View [alerts](../operations/incident_management/alerts.md) | | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Assign an alert | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>View [incident](../operations/incident_management/incidents.md) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Create [incident](../operations/incident_management/incidents.md) | (*16*) | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>View [on-call schedules](../operations/incident_management/oncall_schedules.md) | | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Participate in on-call rotation | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>View [escalation policies](../operations/incident_management/escalation_policies.md) | | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Manage [on-call schedules](../operations/incident_management/oncall_schedules.md) | | | | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Manage [escalation policies](../operations/incident_management/escalation_policies.md) | | | | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Add Labels | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Assign | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Create (*18*) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Create [confidential issues](project/issues/confidential_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>View [Design Management](project/issues/design_management.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>View related issues | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Set weight | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>View [confidential issues](project/issues/confidential_issues.md) | (*2*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Close / reopen (*19*) | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Lock threads | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Manage related issues | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Manage tracker | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Move issues (*14*) | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Set issue [time tracking](project/time_tracking.md) estimate and time spent | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Delete | | | | | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View allowed and denied licenses **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View License Compliance reports **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View License list **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>Manage license policy **(ULTIMATE)** | | | | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Assign reviewer | | ✓ | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>See list | | ✓ | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Apply code change suggestions | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Approve (*8*) | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Assign | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Create (*17*) | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Add labels | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Lock threads | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Manage or accept | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Manage merge approval rules (project settings) | | | | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Delete | | | | | ✓ | -| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Manage user-starred metrics dashboards (*6*) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | -| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | -| [Package registry](packages/index.md):<br>Pull a package | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Package registry](packages/index.md):<br>Publish a package | | | ✓ | ✓ | ✓ | -| [Package registry](packages/index.md):<br>Delete a package | | | | ✓ | ✓ | -| [Package registry](packages/index.md):<br>Delete a file associated with a package | | | | ✓ | ✓ | -| [Project operations](../operations/index.md):<br>View [Error Tracking](../operations/error_tracking.md) list | | ✓ | ✓ | ✓ | ✓ | -| [Project operations](../operations/index.md):<br>Manage [Feature Flags](../operations/feature_flags.md) **(PREMIUM)** | | | ✓ | ✓ | ✓ | -| [Project operations](../operations/index.md):<br>Manage [Error Tracking](../operations/error_tracking.md) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Download project | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Reposition comments on images (posted by any user) | ✓ (*9*) | ✓ (*9*) | ✓ (*9*) | ✓ | ✓ | -| [Projects](project/index.md):<br>View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [releases](project/releases/index.md) | ✓ (*5*) | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View Requirements **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [time tracking](project/time_tracking.md) reports | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [wiki](project/wiki/index.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Create [snippets](snippets.md) | | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Manage labels | | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [project traffic statistics](../api/project_statistics.md) | | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Create, edit, delete [milestones](project/milestones/index.md). | | | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Create, edit, delete [releases](project/releases/index.md) | | | ✓ (*12*) | ✓ (*12*) | ✓ (*12*) | -| [Projects](project/index.md):<br>Create, edit [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Enable Review Apps | | | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View project [Audit Events](../administration/audit_events.md) | | | ✓ (*10*) | ✓ | ✓ | -| [Projects](project/index.md):<br>Add deploy keys | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Add new team members | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Change [project features visibility](../public_access/public_access.md) level | | | | ✓ (*13*) | ✓ | -| [Projects](project/index.md):<br>Configure [webhooks](project/integrations/webhooks.md) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Delete [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Edit comments (posted by any user) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Edit project badges | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Edit project settings | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Export project | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Manage [project access tokens](project/settings/project_access_tokens.md) **(FREE SELF)** **(PREMIUM SAAS)** (*11*) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Manage [Project Operations](../operations/index.md) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Rename project | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Share (invite) projects with groups | | | | ✓ (*7*) | ✓ (*7*) | -| [Projects](project/index.md):<br>View 2FA status of members | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Administer project compliance frameworks | | | | | ✓ | -| [Projects](project/index.md):<br>Archive project | | | | | ✓ | -| [Projects](project/index.md):<br>Change project visibility level | | | | | ✓ | -| [Projects](project/index.md):<br>Delete project | | | | | ✓ | -| [Projects](project/index.md):<br>Disable notification emails | | | | | ✓ | -| [Projects](project/index.md):<br>Transfer project to another namespace | | | | | ✓ | -| [Repository](project/repository/index.md):<br>Pull project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>View project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>View a commit status | | ✓ | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Add tags | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Create new branches | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Create or update commit status | | | ✓ (*4*) | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Force push to non-protected branches | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Push to non-protected branches | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Remove non-protected branches | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Rewrite or remove Git tags | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Enable or disable branch protection | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Enable or disable tag protection | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Manage [push rules](project/repository/push_rules.md) | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Push to protected branches (*4*) | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Turn on or off protected branch push for developers | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Remove fork relationship | | | | | ✓ | -| [Repository](project/repository/index.md):<br>Force push to protected branches (*3*) | | | | | | -| [Repository](project/repository/index.md):<br>Remove protected branches (*3*) | | | | | | -| [Requirements Management](project/requirements/index.md):<br>Archive / reopen **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| [Requirements Management](project/requirements/index.md):<br>Create / edit **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| [Requirements Management](project/requirements/index.md):<br>Import / export **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Create issue from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Create vulnerability from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Dismiss vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Dismiss vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Resolve vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Revert vulnerability to detected state **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability findings in [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Terraform](infrastructure/index.md):<br>Read Terraform state | | | ✓ | ✓ | ✓ | -| [Terraform](infrastructure/index.md):<br>Manage Terraform state | | | | ✓ | ✓ | -| [Test cases](../ci/test_cases/index.md):<br>Archive | | ✓ | ✓ | ✓ | ✓ | -| [Test cases](../ci/test_cases/index.md):<br>Create | | ✓ | ✓ | ✓ | ✓ | -| [Test cases](../ci/test_cases/index.md):<br>Move | | ✓ | ✓ | ✓ | ✓ | -| [Test cases](../ci/test_cases/index.md):<br>Reopen | | ✓ | ✓ | ✓ | ✓ | +| Action | Guest | Reporter | Developer | Maintainer | Owner | +|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|----------|-----------|------------|----------| +| [Analytics](analytics/index.md):<br>View issue analytics | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [merge request analytics](analytics/merge_request_analytics.md) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [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) | | ✓ | ✓ | ✓ | ✓ | +| [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) | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Create and run [on-demand DAST scans](application_security/dast/index.md#on-demand-scans) | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Manage [security policy](application_security/policies/index.md) | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>View [dependency list](application_security/dependency_list/index.md) | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>View [threats list](application_security/threat_monitoring/index.md#threat-monitoring) | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Create a [CVE ID Request](application_security/cve_id_request.md) | | | | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Create or assign [security policy project](application_security/policies/index.md) | | | | | ✓ | +| [Clusters](infrastructure/clusters/index.md):<br>View [pod logs](project/clusters/kubernetes_pod_logs.md) | | | ✓ | ✓ | ✓ | +| [Clusters](infrastructure/clusters/index.md):<br>View clusters | | | ✓ | ✓ | ✓ | +| [Clusters](infrastructure/clusters/index.md):<br>Manage clusters | | | | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete cleanup policies | | | ✓ | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Push an image to the Container Registry | | | ✓ | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Pull an image from the Container Registry | ✓ (*20*) | ✓ (*20*) | ✓ | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Remove a Container Registry image | | | ✓ | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>View Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>Manage | | | | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>Remove GitLab Pages | | | | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [alerts](../operations/incident_management/alerts.md) | | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Assign an alert | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [incident](../operations/incident_management/incidents.md) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Create [incident](../operations/incident_management/incidents.md) | (*16*) | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [on-call schedules](../operations/incident_management/oncall_schedules.md) | | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Participate in on-call rotation | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [escalation policies](../operations/incident_management/escalation_policies.md) | | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Manage [on-call schedules](../operations/incident_management/oncall_schedules.md) | | | | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Manage [escalation policies](../operations/incident_management/escalation_policies.md) | | | | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Add Labels | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Assign | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Create (*18*) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Create [confidential issues](project/issues/confidential_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>View [Design Management](project/issues/design_management.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>View related issues | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Set weight | ✓ (*15*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>View [confidential issues](project/issues/confidential_issues.md) | (*2*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Close / reopen (*19*) | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Lock threads | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Manage related issues | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Manage tracker | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Move issues (*14*) | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Set issue [time tracking](project/time_tracking.md) estimate and time spent | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Delete | | | | | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View allowed and denied licenses | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View License Compliance reports | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View License list | | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>Manage license policy | | | | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Assign reviewer | | ✓ | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>See list | | ✓ | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Apply code change suggestions | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Approve (*8*) | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Assign | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Create (*17*) | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Add labels | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Lock threads | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Manage or accept | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Manage merge approval rules (project settings) | | | | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Delete | | | | | ✓ | +| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Manage user-starred metrics dashboards (*6*) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | +| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Pull a package | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Publish a package | | | ✓ | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Delete a package | | | | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Delete a file associated with a package | | | | ✓ | ✓ | +| [Project operations](../operations/index.md):<br>View [Error Tracking](../operations/error_tracking.md) list | | ✓ | ✓ | ✓ | ✓ | +| [Project operations](../operations/index.md):<br>Manage [Feature Flags](../operations/feature_flags.md) | | | ✓ | ✓ | ✓ | +| [Project operations](../operations/index.md):<br>Manage [Error Tracking](../operations/error_tracking.md) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Download project | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Reposition comments on images (posted by any user) | ✓ (*9*) | ✓ (*9*) | ✓ (*9*) | ✓ | ✓ | +| [Projects](project/index.md):<br>View Insights | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [releases](project/releases/index.md) | ✓ (*5*) | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View Requirements | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [time tracking](project/time_tracking.md) reports | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [wiki](project/wiki/index.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Create [snippets](snippets.md) | | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Manage labels | | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [project traffic statistics](../api/project_statistics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Create, edit, delete [milestones](project/milestones/index.md). | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Create, edit, delete [releases](project/releases/index.md) | | | ✓ (*12*) | ✓ (*12*) | ✓ (*12*) | +| [Projects](project/index.md):<br>Create, edit [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Enable Review Apps | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View project [Audit Events](../administration/audit_events.md) | | | ✓ (*10*) | ✓ | ✓ | +| [Projects](project/index.md):<br>Add deploy keys | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Add new team members | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Change [project features visibility](../public_access/public_access.md) level | | | | ✓ (*13*) | ✓ | +| [Projects](project/index.md):<br>Configure [webhooks](project/integrations/webhooks.md) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Delete [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Edit comments (posted by any user) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Edit project badges | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Edit project settings | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Export project | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Manage [project access tokens](project/settings/project_access_tokens.md) (*11*) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Manage [Project Operations](../operations/index.md) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Rename project | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Share (invite) projects with groups | | | | ✓ (*7*) | ✓ (*7*) | +| [Projects](project/index.md):<br>View 2FA status of members | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Administer project compliance frameworks | | | | | ✓ | +| [Projects](project/index.md):<br>Archive project | | | | | ✓ | +| [Projects](project/index.md):<br>Change project visibility level | | | | | ✓ | +| [Projects](project/index.md):<br>Delete project | | | | | ✓ | +| [Projects](project/index.md):<br>Disable notification emails | | | | | ✓ | +| [Projects](project/index.md):<br>Transfer project to another namespace | | | | | ✓ | +| [Repository](project/repository/index.md):<br>Pull project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>View project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>View a commit status | | ✓ | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Add tags | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Create new branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Create or update commit status | | | ✓ (*4*) | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Force push to non-protected branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Push to non-protected branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Remove non-protected branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Rewrite or remove Git tags | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Enable or disable branch protection | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Enable or disable tag protection | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Manage [push rules](project/repository/push_rules.md) | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Push to protected branches (*4*) | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Turn on or off protected branch push for developers | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Remove fork relationship | | | | | ✓ | +| [Repository](project/repository/index.md):<br>Force push to protected branches (*3*) | | | | | | +| [Repository](project/repository/index.md):<br>Remove protected branches (*3*) | | | | | | +| [Requirements Management](project/requirements/index.md):<br>Archive / reopen | | ✓ | ✓ | ✓ | ✓ | +| [Requirements Management](project/requirements/index.md):<br>Create / edit | | ✓ | ✓ | ✓ | ✓ | +| [Requirements Management](project/requirements/index.md):<br>Import / export | | ✓ | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Create issue from vulnerability finding | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Create vulnerability from vulnerability finding | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Dismiss vulnerability | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Dismiss vulnerability finding | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Resolve vulnerability | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Revert vulnerability to detected state | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Use security dashboard | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability findings in [dependency list](application_security/dependency_list/index.md) | | | ✓ | ✓ | ✓ | +| [Terraform](infrastructure/index.md):<br>Read Terraform state | | | ✓ | ✓ | ✓ | +| [Terraform](infrastructure/index.md):<br>Manage Terraform state | | | | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Archive | | ✓ | ✓ | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Create | | ✓ | ✓ | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Move | | ✓ | ✓ | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Reopen | | ✓ | ✓ | ✓ | ✓ | <!-- markdownlint-disable MD029 --> @@ -243,33 +251,33 @@ More details about the permissions for some project-level features follow. - [Pipeline visibility](../ci/enable_or_disable_ci.md#enable-cicd-in-a-project): When set to **Everyone with Access**, gives access to certain CI/CD "view" features to *non-project* members. -| Action | Non-member | Guest | Reporter | Developer | Maintainer | Owner | -|-----------------------------------------------------------------------------------|------------|---------|----------|-----------|------------|-------| -| See that artifacts exist | ✓ (*3*) | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| View a list of jobs | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | -| View and download artifacts | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | -| View [environments](../ci/environments/index.md) | ✓ (*3*) | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| View job logs and job details page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | -| View pipeline details page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | -| View pipelines page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | -| View pipelines tab in MR | ✓ (*3*) | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| [View vulnerabilities in a pipeline](application_security/security_dashboard/index.md#view-vulnerabilities-in-a-pipeline) | | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | -| Cancel and retry jobs | | | | ✓ | ✓ | ✓ | -| Create new [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | -| Delete job logs or job artifacts | | | | ✓ (*4*) | ✓ | ✓ | -| Run CI/CD pipeline for a protected branch | | | | ✓ (*5*) | ✓ (*5*) | ✓ | -| Stop [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | -| View a job with [debug logging](../ci/variables/index.md#debug-logging) | | | | ✓ | ✓ | ✓ | -| Use pipeline editor | | | | ✓ | ✓ | ✓ | -| Add specific runners to project | | | | | ✓ | ✓ | -| Clear runner caches manually | | | | | ✓ | ✓ | -| Enable shared runners in project | | | | | ✓ | ✓ | -| Manage CI/CD settings | | | | | ✓ | ✓ | -| Manage job triggers | | | | | ✓ | ✓ | -| Manage project-level CI/CD variables | | | | | ✓ | ✓ | -| Run [interactive web terminals](../ci/interactive_web_terminal/index.md) | | | | | ✓ | ✓ | -| Use [environment terminals](../ci/environments/index.md#web-terminals-deprecated) | | | | | ✓ | ✓ | -| Delete pipelines | | | | | | ✓ | +| Action | Non-member | Guest | Reporter | Developer | Maintainer | Owner | +|---------------------------------------------------------------------------------------------------------------------------|------------|---------|----------|-----------|------------|-------| +| See that artifacts exist | ✓ (*3*) | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| View a list of jobs | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | +| View and download artifacts | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | +| View [environments](../ci/environments/index.md) | ✓ (*3*) | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| View job logs and job details page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | +| View pipeline details page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | +| View pipelines page | ✓ (*1*) | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | +| View pipelines tab in MR | ✓ (*3*) | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| [View vulnerabilities in a pipeline](application_security/security_dashboard/index.md#view-vulnerabilities-in-a-pipeline) | | ✓ (*2*) | ✓ | ✓ | ✓ | ✓ | +| Cancel and retry jobs | | | | ✓ | ✓ | ✓ | +| Create new [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | +| Delete job logs or job artifacts | | | | ✓ (*4*) | ✓ | ✓ | +| Run CI/CD pipeline for a protected branch | | | | ✓ (*5*) | ✓ (*5*) | ✓ | +| Stop [environments](../ci/environments/index.md) | | | | ✓ | ✓ | ✓ | +| View a job with [debug logging](../ci/variables/index.md#debug-logging) | | | | ✓ | ✓ | ✓ | +| Use pipeline editor | | | | ✓ | ✓ | ✓ | +| Run [interactive web terminals](../ci/interactive_web_terminal/index.md) | | | | ✓ | ✓ | ✓ | +| Add specific runners to project | | | | | ✓ | ✓ | +| Clear runner caches manually | | | | | ✓ | ✓ | +| Enable shared runners in project | | | | | ✓ | ✓ | +| Manage CI/CD settings | | | | | ✓ | ✓ | +| Manage job triggers | | | | | ✓ | ✓ | +| Manage project-level CI/CD variables | | | | | ✓ | ✓ | +| Use [environment terminals](../ci/environments/index.md#web-terminals-deprecated) | | | | | ✓ | ✓ | +| Delete pipelines | | | | | | ✓ | <!-- markdownlint-disable MD029 --> @@ -288,20 +296,20 @@ More details about the permissions for some project-level features follow. This table shows granted privileges for jobs triggered by specific types of users: -| Action | Guest, Reporter | Developer | Maintainer| Administrator | -|---------------------------------------------|-----------------|-----------|-----------|---------------| -| Run CI job | | ✓ | ✓ | ✓ | -| Clone source and LFS from current project | | ✓ | ✓ | ✓ | -| Clone source and LFS from public projects | | ✓ | ✓ | ✓ | -| Clone source and LFS from internal projects | | ✓ (*1*) | ✓ (*1*) | ✓ | -| Clone source and LFS from private projects | | ✓ (*2*) | ✓ (*2*) | ✓ (*2*) | -| Pull container images from current project | | ✓ | ✓ | ✓ | -| Pull container images from public projects | | ✓ | ✓ | ✓ | -| Pull container images from internal projects| | ✓ (*1*) | ✓ (*1*) | ✓ | -| Pull container images from private projects | | ✓ (*2*) | ✓ (*2*) | ✓ (*2*) | -| Push container images to current project | | ✓ | ✓ | ✓ | -| Push container images to other projects | | | | | -| Push source and LFS | | | | | +| Action | Guest, Reporter | Developer | Maintainer | Administrator | +|----------------------------------------------|-----------------|-----------|------------|---------------| +| Run CI job | | ✓ | ✓ | ✓ | +| Clone source and LFS from current project | | ✓ | ✓ | ✓ | +| Clone source and LFS from public projects | | ✓ | ✓ | ✓ | +| Clone source and LFS from internal projects | | ✓ (*1*) | ✓ (*1*) | ✓ | +| Clone source and LFS from private projects | | ✓ (*2*) | ✓ (*2*) | ✓ (*2*) | +| Pull container images from current project | | ✓ | ✓ | ✓ | +| Pull container images from public projects | | ✓ | ✓ | ✓ | +| Pull container images from internal projects | | ✓ (*1*) | ✓ (*1*) | ✓ | +| Pull container images from private projects | | ✓ (*2*) | ✓ (*2*) | ✓ (*2*) | +| Push container images to current project | | ✓ | ✓ | ✓ | +| Push container images to other projects | | | | | +| Push source and LFS | | | | | 1. Only if the triggering user is not an external one. 1. Only if the triggering user is a member of the project. @@ -327,7 +335,7 @@ to learn more. ### Value stream analytics permissions Find the current permissions on the value stream analytics dashboard, as described in -[related documentation](analytics/value_stream_analytics.md#permissions). +[related documentation](analytics/value_stream_analytics.md#access-permissions-for-value-stream-analytics). ### Issue board permissions @@ -361,64 +369,64 @@ The following table lists group permissions available for each role: <!-- Keep this table sorted: first, by minimum role, then alphabetically. --> -| Action | Guest | Reporter | Developer | Maintainer | Owner | -|--------------------------------------------------------------------------|-------|----------|-----------|------------|-------| -| Browse group | ✓ | ✓ | ✓ | ✓ | ✓ | -| Pull a container image using the dependency proxy | ✓ | ✓ | ✓ | ✓ | ✓ | -| View Contribution analytics | ✓ | ✓ | ✓ | ✓ | ✓ | -| View group epic **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View group wiki pages **(PREMIUM)** | ✓ (6) | ✓ | ✓ | ✓ | ✓ | -| View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View Insights charts **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View Issue analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View value stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | -| Create/edit group epic **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | -| Create/edit/delete epic boards **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | -| Manage group labels | | ✓ | ✓ | ✓ | ✓ | -| Publish [packages](packages/index.md) | | | ✓ | ✓ | ✓ | -| Pull [packages](packages/index.md) | | ✓ | ✓ | ✓ | ✓ | -| Delete [packages](packages/index.md | | | | ✓ | ✓ | -| Pull a Container Registry image | ✓ (7) | ✓ | ✓ | ✓ | ✓ | -| Remove a Container Registry image | | | ✓ | ✓ | ✓ | -| View Group DevOps Adoption **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | -| View Productivity analytics **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | -| Create and edit group wiki pages **(PREMIUM)** | | | ✓ | ✓ | ✓ | -| Create project in group | | | ✓ (3)(5) | ✓ (3) | ✓ (3) | -| Create/edit/delete group milestones | | | ✓ | ✓ | ✓ | -| Create/edit/delete iterations | | | ✓ | ✓ | ✓ | -| Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | -| Enable/disable a dependency proxy | | | ✓ | ✓ | ✓ | -| Purge the dependency proxy for a group | | | | | ✓ | -| Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| View group Audit Events | | | ✓ (7) | ✓ (7) | ✓ | -| Create subgroup | | | | ✓ (1) | ✓ | -| Delete group wiki pages **(PREMIUM)** | | | ✓ | ✓ | ✓ | -| Edit epic comments (posted by any user) **(ULTIMATE)** | | | | ✓ (2) | ✓ (2) | -| List group deploy tokens | | | | ✓ | ✓ | -| Manage [group push rules](group/index.md#group-push-rules) **(PREMIUM)** | | | | ✓ | ✓ | -| View/manage group-level Kubernetes cluster | | | | ✓ | ✓ | -| Administer project compliance frameworks | | | | | ✓ | -| Create/Delete group deploy tokens | | | | | ✓ | -| Change group visibility level | | | | | ✓ | -| Delete group | | | | | ✓ | -| Delete group epic **(PREMIUM)** | | | | | ✓ | -| Disable notification emails | | | | | ✓ | -| Edit group settings | | | | | ✓ | -| Edit SAML SSO **(PREMIUM SAAS)** | | | | | ✓ (4) | -| Filter members by 2FA status | | | | | ✓ | -| Manage group level CI/CD variables | | | | | ✓ | -| Manage group members | | | | | ✓ | -| Share (invite) groups with groups | | | | | ✓ | -| View 2FA status of members | | | | | ✓ | -| View Billing **(FREE SAAS)** | | | | | ✓ (4) | -| View Usage Quotas **(FREE SAAS)** | | | | | ✓ (4) | -| Manage runners | | | | | ✓ | +| Action | Guest | Reporter | Developer | Maintainer | Owner | +|-----------------------------------------------------------------------------------------|-------|----------|-----------|------------|-------| +| Browse group | ✓ | ✓ | ✓ | ✓ | ✓ | +| Pull a container image using the dependency proxy | ✓ | ✓ | ✓ | ✓ | ✓ | +| View Contribution analytics | ✓ | ✓ | ✓ | ✓ | ✓ | +| View group [epic](group/epics/index.md) | ✓ | ✓ | ✓ | ✓ | ✓ | +| View [group wiki](project/wiki/group.md) pages | ✓ (6) | ✓ | ✓ | ✓ | ✓ | +| View [Insights](project/insights/index.md) | ✓ | ✓ | ✓ | ✓ | ✓ | +| View [Insights](project/insights/index.md) charts | ✓ | ✓ | ✓ | ✓ | ✓ | +| View [Issue analytics](analytics/issue_analytics.md) | ✓ | ✓ | ✓ | ✓ | ✓ | +| View value stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | +| Create/edit group [epic](group/epics/index.md) | | ✓ | ✓ | ✓ | ✓ | +| Create/edit/delete [epic boards](group/epics/epic_boards.md) | | ✓ | ✓ | ✓ | ✓ | +| Manage group labels | | ✓ | ✓ | ✓ | ✓ | +| Publish [packages](packages/index.md) | | | ✓ | ✓ | ✓ | +| Pull [packages](packages/index.md) | | ✓ | ✓ | ✓ | ✓ | +| Delete [packages](packages/index.md) | | | | ✓ | ✓ | +| Pull a Container Registry image | ✓ (7) | ✓ | ✓ | ✓ | ✓ | +| Remove a Container Registry image | | | ✓ | ✓ | ✓ | +| View [Group DevOps Adoption](group/devops_adoption/index.md) | | ✓ | ✓ | ✓ | ✓ | +| View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | +| View [Productivity analytics](analytics/productivity_analytics.md) | | ✓ | ✓ | ✓ | ✓ | +| View Usage quota data | | ✓ | ✓ | ✓ | ✓ | +| Create and edit [group wiki](project/wiki/group.md) pages | | | ✓ | ✓ | ✓ | +| Create project in group | | | ✓ (3)(5) | ✓ (3) | ✓ (3) | +| Create/edit/delete group milestones | | | ✓ | ✓ | ✓ | +| Create/edit/delete iterations | | | ✓ | ✓ | ✓ | +| Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | +| Enable/disable a dependency proxy | | | ✓ | ✓ | ✓ | +| Purge the dependency proxy for a group | | | | | ✓ | +| Use [security dashboard](application_security/security_dashboard/index.md) | | | ✓ | ✓ | ✓ | +| View group Audit Events | | | ✓ (7) | ✓ (7) | ✓ | +| Create subgroup | | | | ✓ (1) | ✓ | +| Delete [group wiki](project/wiki/group.md) pages | | | ✓ | ✓ | ✓ | +| Edit [epic](group/epics/index.md) comments (posted by any user) | | | | ✓ (2) | ✓ (2) | +| List group deploy tokens | | | | ✓ | ✓ | +| Manage [group push rules](group/index.md#group-push-rules) | | | | ✓ | ✓ | +| View/manage group-level Kubernetes cluster | | | | ✓ | ✓ | +| Administer project compliance frameworks | | | | | ✓ | +| Create/Delete group deploy tokens | | | | | ✓ | +| Change group visibility level | | | | | ✓ | +| Delete group | | | | | ✓ | +| Delete group [epic](group/epics/index.md) | | | | | ✓ | +| Disable notification emails | | | | | ✓ | +| Edit group settings | | | | | ✓ | +| Edit [SAML SSO](group/saml_sso/index.md) | | | | | ✓ (4) | +| Filter members by 2FA status | | | | | ✓ | +| Manage group level CI/CD variables | | | | | ✓ | +| Manage group members | | | | | ✓ | +| Share (invite) groups with groups | | | | | ✓ | +| View 2FA status of members | | | | | ✓ | +| View [Billing](../subscriptions/gitlab_com/index.md#view-your-gitlab-saas-subscription) | | | | | ✓ (4) | +| View [Usage Quotas](usage_quotas.md) Page | | | | ✓ | ✓ (4) | +| Manage runners | | | | | ✓ | <!-- markdownlint-disable MD029 --> -1. Groups can be set to [allow either Owners or Owners and - Maintainers to create subgroups](group/subgroups/index.md#creating-a-subgroup) +1. Groups can be set to allow either Owners, or Owners and users with the Maintainer role, to [create subgroups](group/subgroups/index.md#create-a-subgroup). 2. Introduced in GitLab 12.2. 3. Default project creation role can be changed at: - The [instance level](admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects). @@ -437,7 +445,7 @@ permission level from the parent group(s). This model allows access to nested groups if you have membership in one of its parents. To learn more, read through the documentation on -[subgroups memberships](group/subgroups/index.md#membership). +[subgroups memberships](group/subgroups/index.md#subgroup-membership). ## External users **(FREE SELF)** @@ -478,7 +486,7 @@ An administrator can flag a user as external by either of the following methods: 1. On the left sidebar, select **Overview > Users** to create a new user or edit an existing one. There, you can find the option to flag the user as external. -Additionally users can be set as external users using: +Additionally, users can be set as external users using: - [SAML groups](../integration/saml.md#external-groups). - [LDAP groups](../administration/auth/ldap/ldap_synchronization.md#external-groups). @@ -543,7 +551,7 @@ with the permissions described on the documentation on [auditor users permission ## Users with minimal access **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40942) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40942) in GitLab 13.4. Owners can add members with a "minimal access" role to a parent group. Such users don't automatically have access to projects and subgroups underneath. Owners must explicitly add these "minimal access" users to the specific subgroups and diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index c116b1fc00d..3f5554b80ac 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -5,7 +5,7 @@ group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Deleting a User account **(FREE)** +# Deleting a user account **(FREE)** Users can be deleted from a GitLab instance, either by: @@ -15,7 +15,7 @@ Users can be deleted from a GitLab instance, either by: NOTE: Deleting a user deletes all projects in that user namespace. -## As a user +## Delete your own account As a user, to delete your own account: @@ -24,7 +24,7 @@ As a user, to delete your own account: 1. On the left sidebar, select **Account**. 1. Select **Delete account**. -## As an administrator **(FREE SELF)** +## Delete users and user contributions **(FREE SELF)** As an administrator, to delete a user account: @@ -32,55 +32,40 @@ As an administrator, to delete a user account: 1. On the left sidebar, select **Overview > Users**. 1. Select a user. 1. Under the **Account** tab, select: - - **Delete user** to delete only the user but maintain their - [associated records](#associated-records). - - **Delete user and contributions** to delete the user and - their associated records. + - **Delete user** to delete only the user but maintain their [associated records](#associated-records). You can't use this option if + the selected user is the sole owner of any groups. + - **Delete user and contributions** to delete the user and their associated records. This option also removes all groups (and + projects within these groups) where the user is the sole direct Owner of a group. Inherited ownership doesn't apply. WARNING: -Using the **Delete user and contributions** option may result -in removing more data than intended. Please see [associated records](#associated-records) -below for additional details. +Using the **Delete user and contributions** option may result in removing more data than intended. See +[associated records](#associated-records) for additional details. ### Associated records -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7393) for issues in GitLab 9.0. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10467) for merge requests, award emoji, notes, and abuse reports in GitLab 9.1. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10273) hard deletion from abuse reports and spam logs in GitLab 9.1. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11853) hard deletion from the API in GitLab 9.3. - -There are two options for deleting users: - -- **Delete user** -- **Delete user and contributions** - -When using the **Delete user** option, not all associated records are deleted with the user. -Here's a list of things created by the user that are **not** deleted: - -- Abuse reports -- Award emoji -- Epics -- Issues -- Merge requests -- Notes - -Instead of being deleted, these records are moved to a system-wide -user with the username Ghost User, whose sole purpose is to act as a container -for such records. Any commits made by a deleted user still display the -username of the original user. - -When using the **Delete user and contributions** option, **all** associated records -are removed. This includes all of the items mentioned above including issues, -merge requests, notes/comments, and more. Consider -[blocking a user](../../admin_area/moderate_users.md#block-a-user) -or using the **Delete user** option instead. - -When a user is deleted from an [abuse report](../../admin_area/review_abuse_reports.md) -or spam log, these associated -records are not ghosted and are removed, along with any groups the user -is a sole owner of. Administrators can also request this behavior when -deleting users from the [API](../../../api/users.md#user-deletion) or the -Admin Area. +When deleting users, you can either: + +- Delete just the user. Not all associated records are deleted with the user. Instead of being deleted, these records + are moved to a system-wide user with the username Ghost User. The Ghost User's purpose is to act as a container for + such records. Any commits made by a deleted user still display the username of the original user. +- Delete the user and their contributions, including: + - Abuse reports. + - Award emojis. + - Epics. + - Groups of which the user is the only user with the Owner role. + - Issues. + - Merge requests. + - Notes and comments. + - Personal access tokens. + - Snippets. + +An alternative to deleting is [blocking a user](../../admin_area/moderate_users.md#block-a-user). + +When a user is deleted from an [abuse report](../../admin_area/review_abuse_reports.md) or spam log, these associated +records are always removed. + +The deleting associated records option can be requested in the [API](../../../api/users.md#user-deletion) as well as +the Admin Area. ## Troubleshooting diff --git a/doc/user/profile/img/personal_readme_setup_v14_5.png b/doc/user/profile/img/personal_readme_setup_v14_5.png Binary files differindex 92d8e0ec936..6a776506ac6 100644 --- a/doc/user/profile/img/personal_readme_setup_v14_5.png +++ b/doc/user/profile/img/personal_readme_setup_v14_5.png diff --git a/doc/user/profile/notifications.md b/doc/user/profile/notifications.md index acbaf62579f..4c9622810b2 100644 --- a/doc/user/profile/notifications.md +++ b/doc/user/profile/notifications.md @@ -184,6 +184,7 @@ Users are notified of the following events: | Password changed | User | Security email, always sent when user changes their own password. | | Password changed by administrator | User | Security email, always sent when an administrator changes the password of another user. | | Personal access tokens expiring soon | User | Security email, always sent. | +| Personal access tokens have been created | User | Security email, always sent. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337591) in GitLab 14.9. | | Personal access tokens have expired | User | Security email, always sent. | | Project access level changed | User | Sent when user project access level is changed. | | SSH key has expired | User | Security email, always sent. _[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322637) in GitLab 13.12._ | diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 10d718fdf1a..1fbbe438370 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -25,8 +25,8 @@ Personal access tokens are: - Used with a GitLab username to authenticate with GitLab features that require usernames. For example, [GitLab managed Terraform state backend](../infrastructure/iac/terraform_state.md#using-a-gitlab-managed-terraform-state-backend-as-a-remote-data-source) and [Docker container registry](../packages/container_registry/index.md#authenticate-with-the-container-registry), -- Similar to [project access tokens](../project/settings/project_access_tokens.md), but are attached - to a user rather than a project. +- Similar to [project access tokens](../project/settings/project_access_tokens.md) and [group access tokens](../group/settings/group_access_tokens.md), but are attached + to a user rather than a project or group. NOTE: Though required, GitLab usernames are ignored when authenticating with a personal access token. diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 52baf5189e1..48160bb97ac 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -39,7 +39,7 @@ The default theme is Indigo. You can choose between 10 themes: ## Dark mode -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28252) in GitLab 13.1 as an Alpha release. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28252) in GitLab 13.1 as an [Alpha](../../policy/alpha-beta-support.md#alpha-features) release. GitLab has started work on dark mode! The dark mode Alpha release is available in the spirit of iteration and the lower expectations of diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 79d395d51c3..2f9e04fb828 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w 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), -[test coverage](../../ci/pipelines/settings.md#test-coverage-report-badge), or ways to contact the +[test coverage](../../ci/pipelines/settings.md#test-coverage-report-badge), [latest release](../../ci/pipelines/settings.md#latest-release-badge), or ways to contact the project maintainers.  diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index 77cf04cc7eb..344caed7449 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -6,8 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Canary Deployments **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1659) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.1. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to GitLab Free in 13.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1659) in GitLab 9.1. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) from GitLab Premium to GitLab Free in 13.8. A popular [Continuous Deployment](https://en.wikipedia.org/wiki/Continuous_deployment) strategy, where a small portion of the fleet is updated to the new version of @@ -35,7 +35,7 @@ your pods fleet and watch their behavior as a percentage of your user base visits the temporarily deployed feature. If all works well, you can deploy the feature to production knowing that it shouldn't cause any problems. -Canary deployments are also especially useful for backend refactors, performance +Canary deployments are also especially required for backend refactors, performance improvements, or other changes where the user interface doesn't change, but you want to make sure the performance stays the same, or improves. Developers need to be careful when using canaries with user-facing changes, because by default, @@ -50,7 +50,7 @@ this document. Canary deployments require that you properly configure deploy boards: 1. Follow the steps to [enable deploy boards](deploy_boards.md#enabling-deploy-boards). -1. To track canary deployments you need to label your Kubernetes deployments and +1. To track canary deployments you must label your Kubernetes deployments and pods with `track: canary`. To get started quickly, you can use the [Auto Deploy](../../topics/autodevops/stages.md#auto-deploy) template for canary deployments that GitLab provides. @@ -60,19 +60,19 @@ Any other track label is considered `canary` (temporary). This allows GitLab to discover whether a deployment is stable or canary (temporary). Once all of the above are set up and the pipeline has run at least once, -navigate to the environments page under **Pipelines > Environments**. +Go to the environments page under **Pipelines > Environments**. As the pipeline executes, deploy boards clearly mark canary pods, enabling -quick and easy insight into the status of each environment and deployment. +quick and clear insight into the status of each environment and deployment. Canary deployments are marked with a yellow dot in the deploy board so that you -can easily notice them. +can quickly notice them.  ### Advanced traffic control with Canary Ingress (DEPRECATED) -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215501) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to Free in GitLab 13.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215501) in GitLab 13.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) from GitLab Premium to GitLab Free in 13.8. > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. WARNING: @@ -82,7 +82,7 @@ Canary deployments can be more strategic with [Canary Ingress](https://kubernete which is an advanced traffic routing service that controls incoming HTTP requests between stable and canary deployments based on factors such as weight, sessions, cookies, and others. GitLab uses this service in its [Auto Deploy architecture](../../topics/autodevops/upgrading_auto_deploy_dependencies.md#v2-chart-resource-architecture) -to let users easily and safely roll out their new deployments. +to let users quickly and safely roll out their new deployments. #### How to set up a Canary Ingress in a canary deployment @@ -115,13 +115,13 @@ Here's an example setup flow from scratch: #### How to change the traffic weight on a Canary Ingress -You can change the traffic weight within your environment's deploy board by using [GraphiQL](../../api/graphql/getting_started.md#graphiql), +You can change the traffic weight in your environment's deploy board by using [GraphiQL](../../api/graphql/getting_started.md#graphiql), or by sending requests to the [GraphQL API](../../api/graphql/getting_started.md#command-line). To use your [deploy board](../../user/project/deploy_boards.md): -1. Navigate to **Deployments > Environments** for your project. -1. Set the new weight with the dropdown on the right side. +1. Go to **Deployments > Environments** for your project. +1. Set the new weight with the dropdown list on the right side. 1. Confirm your selection. Here's an example using [GraphiQL](../../api/graphql/getting_started.md#graphiql): diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index e14a71a7e10..82106c9d1a9 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. WARNING: -This feature was deprecated in GitLab 14.5. Use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated) +This feature was deprecated in GitLab 14.5. Use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac) to create new clusters. Through GitLab, you can create new clusters and add existing clusters hosted on Amazon Elastic @@ -19,11 +19,11 @@ Kubernetes Service (EKS). ## Connect an existing EKS cluster If you already have an EKS cluster and want to connect it to GitLab, -use the [GitLab Agent](../../clusters/agent/index.md). +use the [GitLab agent](../../clusters/agent/index.md). ## Create a new EKS cluster -To create a new cluster from GitLab, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated). +To create a new cluster from GitLab, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac). ### How to create a new cluster on EKS through cluster certificates (DEPRECATED) diff --git a/doc/user/project/clusters/add_existing_cluster.md b/doc/user/project/clusters/add_existing_cluster.md index 0c3827bcbb1..f2d537513b7 100644 --- a/doc/user/project/clusters/add_existing_cluster.md +++ b/doc/user/project/clusters/add_existing_cluster.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect your cluster to GitLab, use the [GitLab Agent](../../clusters/agent/index.md) +To connect your cluster to GitLab, use the [GitLab agent](../../clusters/agent/index.md) instead. If you have an existing Kubernetes cluster, you can add it to a project, group, @@ -69,8 +69,8 @@ To add a Kubernetes cluster to your project, group, or instance: 1. Project's **{cloud-gear}** **Infrastructure > Kubernetes clusters** page, for a project-level cluster. 1. Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. 1. **Menu > Admin > Kubernetes** page, for an instance-level cluster. -1. Click **Add Kubernetes cluster**. -1. Click the **Add existing cluster** tab and fill in the details: +1. On the **Kubernetes clusters** page, select the **Connect with a certificate** option from the **Actions** dropdown menu. +1. On the **Connect a cluster** page, fill in the details: 1. **Kubernetes cluster name** (required) - The name you wish to give the cluster. 1. **Environment scope** (required) - The [associated environment](multiple_kubernetes_clusters.md#setting-the-environment-scope) to this cluster. diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 99edddeb3e9..cb8d04e0e28 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -19,7 +19,7 @@ hosted on Google Kubernetes Engine (GKE). ## Connect an existing GKE cluster If you already have a GKE cluster and want to connect it to GitLab, -use the [GitLab Agent](../../clusters/agent/index.md). +use the [GitLab agent](../../clusters/agent/index.md). ## Create a new GKE cluster from GitLab diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index a0fca517f2e..a4f6dc325c8 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. -To create a new cluster use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated). +To create a new cluster use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac). NOTE: Every new Google Cloud Platform (GCP) account receives @@ -29,7 +29,7 @@ in a few clicks. > [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 14.0. -As of GitLab 14.0, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac-deprecated) +As of GitLab 14.0, use [Infrastructure as Code](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac) to **safely create new clusters from GitLab**. Creating clusters from GitLab using cluster certificates is still available on the @@ -49,7 +49,7 @@ supports connecting existing clusters using the certificate-based connection met ## Add existing cluster -As of GitLab 14.0, use the [GitLab Agent](../../clusters/agent/index.md) +As of GitLab 14.0, use the [GitLab agent](../../clusters/agent/index.md) to connect your cluster to GitLab. Alternatively, you can [add an existing cluster](add_existing_cluster.md) @@ -57,7 +57,7 @@ through the certificate-based method, but we don't recommend using this method f ## Configure your cluster -As of GitLab 14.0, use the [GitLab Agent](../../clusters/agent/index.md) +As of GitLab 14.0, use the [GitLab agent](../../clusters/agent/index.md) to configure your cluster. ## Disable a cluster diff --git a/doc/user/project/clusters/cluster_access.md b/doc/user/project/clusters/cluster_access.md index 4e00ae0dd07..8ff0a275649 100644 --- a/doc/user/project/clusters/cluster_access.md +++ b/doc/user/project/clusters/cluster_access.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect your cluster to GitLab, use the [GitLab Agent](../../clusters/agent/index.md) +To connect your cluster to GitLab, use the [GitLab agent](../../clusters/agent/index.md) instead. When creating a cluster in GitLab, you are asked if you would like to create either: diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md index e89ce12b35e..c1cdf754c11 100644 --- a/doc/user/project/clusters/deploy_to_cluster.md +++ b/doc/user/project/clusters/deploy_to_cluster.md @@ -10,8 +10,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect your cluster to GitLab, use the [GitLab Agent](../../clusters/agent/index.md). -To deploy with the Agent, use the [CI/CD Tunnel](../../clusters/agent/ci_cd_tunnel.md). +To connect your cluster to GitLab, use the [GitLab agent](../../clusters/agent/index.md). +To deploy with the agent, use the [CI/CD workflow](../../clusters/agent/ci_cd_tunnel.md). A Kubernetes cluster can be the destination for a deployment job. If @@ -143,6 +143,6 @@ Reasons for failure include: NOTE: Project-level clusters upgraded from GitLab 12.0 or older may be configured -in a way that causes this error. Ensure you deselect the +in a way that causes this error. Ensure you clear the [GitLab-managed cluster](gitlab_managed_clusters.md) option if you want to manage namespaces and service accounts yourself. diff --git a/doc/user/project/clusters/gitlab_managed_clusters.md b/doc/user/project/clusters/gitlab_managed_clusters.md index 686b3026b2c..9c5cc14f720 100644 --- a/doc/user/project/clusters/gitlab_managed_clusters.md +++ b/doc/user/project/clusters/gitlab_managed_clusters.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect your cluster to GitLab, use the [GitLab Agent](../../../user/clusters/agent/index.md). +To connect your cluster to GitLab, use the [GitLab agent](../../../user/clusters/agent/index.md). To manage applications, use the [Cluster Project Management Template](../../../user/clusters/management_project_template.md). You can choose to allow GitLab to manage your cluster for you. If your cluster diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index dc37060593c..f89d863e83b 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. To connect clusters to GitLab, use the -[GitLab Agent](../../clusters/agent/index.md). +[GitLab agent](../../clusters/agent/index.md). [Project-level](../../infrastructure/clusters/connect/index.md#cluster-levels-deprecated) Kubernetes clusters allow you to connect a Kubernetes cluster to a project in GitLab. diff --git a/doc/user/project/clusters/multiple_kubernetes_clusters.md b/doc/user/project/clusters/multiple_kubernetes_clusters.md index a56eaa9b953..149df5248c8 100644 --- a/doc/user/project/clusters/multiple_kubernetes_clusters.md +++ b/doc/user/project/clusters/multiple_kubernetes_clusters.md @@ -13,7 +13,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: Using multiple Kubernetes clusters for a single project **with cluster certificates** was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. -To connect clusters to GitLab, use the [GitLab Agent](../../../user/clusters/agent/index.md). +To connect clusters to GitLab, use the [GitLab agent](../../../user/clusters/agent/index.md). You can associate more than one Kubernetes cluster to your project. That way you can have different clusters for different environments, diff --git a/doc/user/project/clusters/protect/container_host_security/index.md b/doc/user/project/clusters/protect/container_host_security/index.md index a0297a7a86f..f6f31ee8f36 100644 --- a/doc/user/project/clusters/protect/container_host_security/index.md +++ b/doc/user/project/clusters/protect/container_host_security/index.md @@ -1,7 +1,7 @@ --- stage: Protect group: Container Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Container Host Security **(FREE)** diff --git a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md index 4e56b7e5140..25e2f6ddb91 100644 --- a/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_host_security/quick_start_guide.md @@ -1,7 +1,7 @@ --- stage: Protect group: Container Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Getting started with Container Host Security **(FREE)** diff --git a/doc/user/project/clusters/protect/container_network_security/index.md b/doc/user/project/clusters/protect/container_network_security/index.md index 7176a1cf1b9..eeaf7e82ef4 100644 --- a/doc/user/project/clusters/protect/container_network_security/index.md +++ b/doc/user/project/clusters/protect/container_network_security/index.md @@ -1,7 +1,7 @@ --- stage: Protect group: Container Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Container Network Security **(FREE)** diff --git a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md index e6c91302d7b..43f4ea6c326 100644 --- a/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md +++ b/doc/user/project/clusters/protect/container_network_security/quick_start_guide.md @@ -1,7 +1,7 @@ --- stage: Protect group: Container Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Getting started with Container Network Security **(FREE)** diff --git a/doc/user/project/clusters/protect/index.md b/doc/user/project/clusters/protect/index.md index 473195f4c17..3a80132fb50 100644 --- a/doc/user/project/clusters/protect/index.md +++ b/doc/user/project/clusters/protect/index.md @@ -1,7 +1,7 @@ --- stage: Protect group: Container Security -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Protecting your deployed applications **(FREE)** diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index eb18834cc6b..fefc27063a6 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -124,7 +124,7 @@ Only one CODEOWNERS pattern can match per file path. ### Organize Code Owners by putting them into sections -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab Premium 13.2 behind a feature flag, enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab 13.2 behind a feature flag, enabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. You can organize Code Owners by putting them into named sections. @@ -170,7 +170,7 @@ entries under **Database**. The entries defined under the sections **Documentati ### Make a Code Owners section optional -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab Premium 13.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab 13.8. You can designate optional sections in your Code Owners file. Prepend the section name with the caret `^` character to treat the entire section as optional. diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 15490ab0b94..567c15c7d5f 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -7,8 +7,8 @@ type: howto, reference # Deploy boards (DEPRECATED) **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) to GitLab Free in 13.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in GitLab 9.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) from GitLab Premium to GitLab Free in 13.8. > - In GitLab 13.5 and earlier, apps that consist of multiple deployments are shown as > duplicates on the deploy board. This is [fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/8463) > in GitLab 13.6. @@ -20,7 +20,7 @@ type: howto, reference WARNING: This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. [An epic exists](https://gitlab.com/groups/gitlab-org/-/epics/2493) -to add this functionality to the [Agent](../index.md). +to add this functionality to the [agent](../index.md). GitLab deploy boards offer a consolidated view of the current health and status of each CI [environment](../../ci/environments/index.md) running on [Kubernetes](https://kubernetes.io), displaying the status diff --git a/doc/user/project/deploy_keys/img/public_deploy_key_v13_0.png b/doc/user/project/deploy_keys/img/public_deploy_key_v13_0.png Binary files differdeleted file mode 100644 index 2f708555af1..00000000000 --- a/doc/user/project/deploy_keys/img/public_deploy_key_v13_0.png +++ /dev/null diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 57f6efa3092..b7674be2fa0 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -2,186 +2,145 @@ 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 -type: howto, reference --- # 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. +Use deploy keys to access repositories that are hosted in GitLab. In most cases, you use deploy keys +to access a repository from an external host, like a build server or Continuous Integration (CI) server. -Deploy keys streamline interactions between your GitLab repository and another -machine. For example, setting up a deploy key allows secure cloning of your -repositories to a Continuous Integration (CI) server without setting up a fake -user account. +Depending on your needs, you might want to use a [deploy token](../deploy_tokens/) to access a repository instead. -There are two types of deploy keys: +| Attribute | Deploy key | Deploy token | +|------------------|-------------|--------------| +| Sharing | Shareable between multiple projects, even those in different groups. | Belong to a project or group. | +| Source | Public SSH key generated on an external host. | Generated on your GitLab instance, and is provided to users only at creation time. | +| Validity | Valid as long as it's registered and enabled. | Can be given an expiration date. | +| Registry access | Cannot access a package registry. | Can read from and write to a package registry. | -- [Project deploy keys](#project-deploy-keys) -- [Public deploy keys](#public-deploy-keys) +## Scope -## Key details on deploy keys +A deploy key has a defined scope when it is created: -Deploy keys allow a remote machine (VM, physical, and so on) to access a GitLab -repository with just a few steps. If you want a remote machine to interact with a GitLab -repository in automation, it's a simple solution. +- **Project deploy key:** Access is limited to the selected project. +- **Public deploy key:** Access can be granted to _any_ project in a GitLab instance. Access to each + project must be [granted](#grant-project-access-to-a-public-deploy-key) by a user with at least + the Maintainer role. -A drawback is that your repository could become vulnerable if a remote machine is compromised -by a hacker. You should limit access to the remote machine before a deploy key is -enabled on your repository. A good rule to follow is to provide access only to trusted users, -and make sure that the allowed users have at least the Maintainer role -in the GitLab project. +You cannot change a deploy key's scope after creating it. -If this security implication is a concern for your organization, -[Deploy Tokens](../deploy_tokens/index.md) works as an alternative, but with more -security control. +## Permissions -## Deploy keys permissions +A deploy key is given a permission level when it is created: -You can choose the access level of a deploy key when you enable it on a project: +- **Read-only:** A read-only deploy key can only read from the repository. +- **Read-write:** A read-write deploy key can read from, and write to, the repository. -- `read-only`: The deploy key can read a repository. -- `read-write`: The deploy key can read a repository and write to it. +You can change a deploy key's permission level after creating it. Changing a project deploy key's +permissions only applies for the current project. -Project maintainers and owners can activate and deactivate deploy keys. -They can also add their own deploy keys and enable them for this project. +When a read-write deploy key is used to push a commit, GitLab checks if the creator of the +deploy key has permission to access the resource. -When a `write-access` deploy key is used to push a commit, GitLab checks if -the **creator** of the deploy key has permission to access the resource. For example: +For example: - When a deploy key is used to push a commit to a [protected branch](../protected_branches.md), - the **creator** of the deploy key must have access to the branch. -- When a deploy key is used to push a commit that triggers a CI/CD pipelines, the **creator** of - the deploy key must have access to the CI/CD resources (like protected environments, secret variables, and so on). -- If the **creator** of a deploy key does not have permissions to read a project's - repository, the deploy key _might_ encounter an error during the process. + the _creator_ of the deploy key must have access to the branch. +- When a deploy key is used to push a commit that triggers a CI/CD pipeline, the _creator_ of the + deploy key must have access to the CI/CD resources, including protected environments and secret + variables. -## Differences between deploy keys and deploy tokens +## View deploy keys -Both deploy keys and [deploy tokens](../deploy_tokens/index.md#deploy-tokens) can -help you access a repository, but there are some notables differences between them: - -- Deploy keys are shareable between projects that are not related or don't even - belong to the same group. Deploy tokens belong to either a project or - [a group](../deploy_tokens/index.md#group-deploy-token). -- A deploy key is an SSH key you generate on the **remote machine**. A deploy - token, on the other hand, is generated by your **GitLab instance**, and is - provided to users only once (at creation time). -- A deploy key is valid as long as it's registered and enabled. Deploy tokens - can be time-sensitive, as you can control their validity by setting an - expiration date to them. -- You can't log in to a registry with deploy keys, or perform read / write operations - on it, but this [is possible with deploy tokens](../deploy_tokens/index.md#gitlab-deploy-token). -- You need an SSH key pair to use deploy keys, but not deploy tokens. - -## How to enable deploy keys - -### Project deploy keys - -[Project maintainers and owners](../../permissions.md#project-members-permissions) -can add or enable a deploy key for a project repository: +To view the deploy keys available to a project: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Deploy keys**. -1. Specify a title for the new deploy key and paste your public SSH key. -1. Optional. To allow `read-write` access, select the **Grant write permissions to this key** checkbox. Leave it unchecked for `read-only` access. -There are three lists of project deploy keys: +The deploy keys available are listed: -- Enabled deploy keys -- Privately accessible deploy keys -- Public accessible deploy keys +- **Enabled deploy keys:** Deploy keys that have access to the project. +- **Privately accessible deploy keys:** Project deploy keys that don't have access to the project. +- **Public accessible deploy keys:** Public deploy keys that don't have access to the project. - +## Create a project deploy key -After you add a key, it's enabled for this project by default and it appears -in the **Enabled deploy keys** tab. +Prerequisites: -In the **Privately accessible deploy keys** tab, you can enable a private key which -has been already imported in a different project. If you have access to these keys, -it's because you have either: +- You must have at least the Maintainer role for the project. +- [Generate an SSH key pair](../../../ssh/index.md#generate-an-ssh-key-pair). Put the private SSH + key on the host that requires access to the repository. -- Previously uploaded the keys yourself in a different project. -- You are a maintainer or owner of the other project where the keys were imported. - -In the **Publicly accessible deploy keys** tab, you can enable -keys that were [made available to your entire GitLab instance](#public-deploy-keys). +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Deploy keys**. +1. Complete the fields. +1. Optional. To grant `read-write` permission, select the **Grant write permissions to this key** + checkbox. -After a key is added, you can edit it to update its title, or switch between `read-only` -and `read-write` access. +A project deploy key is enabled when it is created. You can modify only a project deploy key's +name and permissions. -NOTE: -If you have enabled a privately or publicly accessible or deploy key for your -project, and if you then update the access level for this key from `read-only` to -`read-write`, the change is only for the **current project**. +## Create a public deploy key -### Public deploy keys +Prerequisites: -Public deploy keys allow `read-only` or `read-write` access to any repository in -your GitLab instance. This allows for the integration of your repositories to -secure, shared services, such as CI/CD. +- You must have administrator access. +- [Generate an SSH key pair](../../../ssh/index.md#generate-an-ssh-key-pair). Put the private SSH + key on the host that requires access to the repository. -Instance administrators can add public deploy keys: +To create a public deploy key: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Deploy Keys**. 1. Select **New deploy key**. +1. Complete the fields. + - Use a meaningful description for **Name**. For example, include the name of the external host + or application that will use the public deploy key. -Make sure your new key has a meaningful title. This title is the primary -way for project maintainers and owners to identify the correct public deploy key -to add to a repository or project. For example, the key you set up might be -intended to give access to a SaaS CI/CD instance. In this case use the name of -that service in the key title if that is all the key is used for. +You can modify only a public deploy key's name. - +## Grant project access to a public deploy key -After adding a key, it's available to any shared system. Users with a maintainer role or -higher can [authorize a public deploy key](#project-deploy-keys) to start using -it with the project. +Prerequisites: -NOTE: -The **Publicly accessible deploy keys** tab in a Project's CI/CD -settings only appears if there is at least one Public deploy key configured. +- You must have at least the Maintainer role for the project. -Public deploy keys can provide greater security compared to project deploy keys. -This is because the administrator of the target integrated system is the only -entity who needs to know or configure the key value. +To grant a public deploy key access to a project: -When creating a Public deploy key, consider what scope and permissions are -required for it across the entire GitLab instance. For very narrow usage, such -as a single specific service, a `read-only` deploy key tied to this service is -best. If the service entails broader usage across the instance, a -deploy key with full `read-write` access is more appropriate. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Deploy keys**. +1. Select **Publicly accessible deploy keys**. +1. In the key's row, select **Enable**. +1. To grant read-write permission to the public deploy key: + 1. In the key's row, select **Edit** (**{pencil}**). + 1. Select the **Grant write permissions to this key** checkbox. + +## Revoke project access of a deploy key -WARNING: -Adding a public deploy key **does not** immediately expose any repository -to the remote machine. Access to a project is only given when a project -maintainer chooses to make use of a deploy key in the project's -configuration. +To revoke a deploy key's access to a project, you can disable it. Any service that relies on +a deploy key stops working when the key is disabled. -## How to disable deploy keys +Prerequisites: -[Project maintainers and owners](../../permissions.md#project-members-permissions) -can remove or disable a deploy key for a project repository: +- You must have at least the Maintainer role for the project. + +To disable a deploy key: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Deploy keys**. 1. Select **Disable** (**{cancel}**). -NOTE: -Any service that relies on a deploy key stops working after that key is removed. - -If the key is **publicly accessible**, it is removed from the project, but can -still be found under **Publicly accessible deploy keys**. - -If the key is **privately accessible** and only in use by this project, it is -deleted entirely from GitLab on removal. +What happens to the deploy key when it is disabled depends on the following: -If the key is **privately accessible** and also in use by other projects, it is -removed from the project, but still available under **Privately accessible -deploy keys**. +- If the key is publicly accessible, it is removed from the project but still available in the + **Publicly accessible deploy keys** tab. +- If the key is privately accessible and only in use by this project, it is deleted. +- If the key is privately accessible and also in use by other projects, it is removed from the + project, but still available in the **Privately accessible deploy keys** tab. ## Troubleshooting @@ -192,7 +151,7 @@ branch](../protected_branches.md). - The owner associated to a deploy key does not have access to the protected branch. - The owner associated to a deploy key does not have [membership](../members/index.md) to the project of the protected branch. -- **No one** is selected in [the "Allowed to push" section](../protected_branches.md#configure-a-protected-branch) of the protected branch. +- **No one** is selected in [the **Allowed to push** section](../protected_branches.md#configure-a-protected-branch) of the protected branch. All deploy keys are associated to an account. Since the permissions for an account can change, this might lead to scenarios where a deploy key that was working is suddenly unable to push to a protected branch. diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 9911c90863d..4810fb96ed3 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -25,10 +25,10 @@ GitLab supports two different modes of file locking: - [Exclusive file locks](#exclusive-file-locks) for binary files: done **through the command line** with Git LFS and `.gitattributes`, it prevents locked - files from being modified on any branch. **(FREE)** + files from being modified on any branch. - [Default branch locks](#default-branch-file-and-directory-locks): done **through the GitLab UI**, it prevents locked files and directories being - modified on the default branch. **(PREMIUM)** + modified on the default branch. ## Permissions @@ -40,7 +40,7 @@ users are prevented from modifying locked files by pushing, merging, or any other means, and are shown an error like: `The path '.gitignore' is locked by Administrator`. -## Exclusive file locks **(FREE)** +## Exclusive file locks 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. @@ -192,7 +192,7 @@ Suggested workflow for shared projects: ## Default branch file and directory locks **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/440) in GitLab Enterprise Edition 8.9. Available in [GitLab Premium](https://about.gitlab.com/pricing/). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/440) in GitLab 8.9. This process allows you to lock one file at a time through the GitLab UI and requires access to [GitLab Premium](https://about.gitlab.com/pricing/) diff --git a/doc/user/project/highlighting.md b/doc/user/project/highlighting.md index 728f51a8062..ef0c787b9d3 100644 --- a/doc/user/project/highlighting.md +++ b/doc/user/project/highlighting.md @@ -7,61 +7,67 @@ type: reference # Syntax Highlighting **(FREE)** -GitLab provides syntax highlighting on all files through the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It attempts to guess what language to use based on the file extension, which most of the time is sufficient. +GitLab provides syntax highlighting on all files through the +[Rouge](https://rubygems.org/gems/rouge) Ruby gem. It attempts to guess what language +to use based on the file extension, which most of the time is sufficient. + +The paths here are Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). NOTE: The [Web IDE](web_ide/index.md) and [Snippets](../snippets.md) use [Monaco Editor](https://microsoft.github.io/monaco-editor/) for text editing, which internally uses the [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) library for syntax highlighting. -<!-- vale gitlab.Spelling = NO --> - -If GitLab is guessing wrong, you can override its choice of language using the -`gitlab-language` attribute in `.gitattributes`. For example, if you are working in a Prolog -project and using the `.pl` file extension (which would normally be highlighted as Perl), -you can add the following to your `.gitattributes` file: +## Override syntax highlighting for a file type -<!-- vale gitlab.Spelling = YES --> - -``` conf -*.pl gitlab-language=prolog -``` +NOTE: +The Web IDE [does not support `.gitattribute` files](https://gitlab.com/gitlab-org/gitlab/-/issues/22014). -<!-- vale gitlab.Spelling = NO --> +To override syntax highlighting for a file type: -When you check in and push that change, all `*.pl` files in your project are highlighted as Prolog. +1. If a `.gitattributes` file does not exist in the root directory of your project, + create a blank file with this name. +1. For each file type you want to modify, add a line to the `.gitattributes` file + declaring the file extension and your desired highlighting language: -<!-- vale gitlab.Spelling = YES --> + ```conf + # This extension would normally receive Perl syntax highlighting + # but if we also use Prolog, we may want to override highlighting for + # files with this extension: + *.pl gitlab-language=prolog + ``` -The paths here are Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). So, if you were to invent a file format called a `Nicefile` at the root of your project that used Ruby syntax, all you need is: +1. Commit, push, and merge your changes into your default branch. -``` conf -/Nicefile gitlab-language=ruby -``` +After the changes merge into your [default branch](repository/branches/default.md), +all `*.pl` files in your project are highlighted in your preferred language. -To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shenanigans are available through common gateway interface (CGI) options, such as: +You can also extend the highlighting with common gateway interface (CGI) options, such as: ``` conf -# json with erb in it +# JSON file with .erb in it /my-cool-file gitlab-language=erb?parent=json -# an entire file of highlighting errors! +# An entire file of highlighting errors! /other-file gitlab-language=text?token=Error ``` -These configurations only take effect when the `.gitattributes` -file is in your [default branch](repository/branches/default.md). +## Disable syntax highlighting for a file type -NOTE: -The Web IDE does not support `.gitattribute` files, but it's [planned for a future release](https://gitlab.com/gitlab-org/gitlab/-/issues/22014). +To disable highlighting entirely for a file type, follow the instructions for overriding +the highlighting for a file type, and use `gitlab-language=text`: -## Configure maximum file size for highlighting +```conf +# Disable syntax highlighting for this file type +*.module gitlab-language=text +``` -You can configure the maximum size of the file to be highlighted. +## Configure maximum file size for highlighting -The file size is measured in kilobytes, and is set to a default of `512 KB`. Any file _over_ the file size is rendered in plain text. +By default, GitLab renders any file larger than 512 KB in plain text. To change this value: -1. Open the [`gitlab.yml`](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/config/gitlab.yml.example) configuration file. +1. Open the [`gitlab.yml`](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/config/gitlab.yml.example) + configuration file for your project. 1. Add this section, replacing `maximum_text_highlight_size_kilobytes` with the value you want. @@ -72,3 +78,5 @@ The file size is measured in kilobytes, and is set to a default of `512 KB`. Any ## https://docs.gitlab.com/ee/user/project/highlighting.html maximum_text_highlight_size_kilobytes: 512 ``` + +1. Commit, push, and merge your changes into your default branch. diff --git a/doc/user/project/img/labels_sort_label_priority.png b/doc/user/project/img/labels_sort_label_priority.png Binary files differdeleted file mode 100644 index faf629ac61d..00000000000 --- a/doc/user/project/img/labels_sort_label_priority.png +++ /dev/null diff --git a/doc/user/project/img/labels_sort_priority.png b/doc/user/project/img/labels_sort_priority.png Binary files differdeleted file mode 100644 index a6b5fca26f4..00000000000 --- a/doc/user/project/img/labels_sort_priority.png +++ /dev/null diff --git a/doc/user/project/img/labels_subscriptions_v13_5.png b/doc/user/project/img/labels_subscriptions_v13_5.png Binary files differdeleted file mode 100644 index a2a4e9e50cc..00000000000 --- a/doc/user/project/img/labels_subscriptions_v13_5.png +++ /dev/null diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 62495872659..8c0d9fc422b 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import your project from Bitbucket Cloud to GitLab **(FREE)** NOTE: -The Bitbucket Cloud importer works only with Bitbucket.org, not with Bitbucket +The Bitbucket Cloud importer works only with [Bitbucket.org](https://bitbucket.org/), not with Bitbucket Server (aka Stash). If you are trying to import projects from Bitbucket Server, use [the Bitbucket Server importer](bitbucket_server.md). @@ -31,25 +31,37 @@ When importing: - Repository public access is retained. If a repository is private in Bitbucket, it's created as private in GitLab as well. -## Requirements +## Prerequisite for GitLab self-managed To import your projects from Bitbucket Cloud, the [Bitbucket Cloud integration](../../../integration/bitbucket.md) -must be enabled. Ask your GitLab administrator to enable this if it isn't already enabled. +must be enabled. If it isn't enabled, ask your GitLab administrator to enable it. By default it's +enabled on GitLab.com. ## How it works -When issues/pull requests are being imported, the Bitbucket importer tries to find -the Bitbucket author/assignee in the GitLab database using the Bitbucket `nickname`. -For this to work, the Bitbucket author/assignee should have signed in beforehand in GitLab -and **associated their Bitbucket account**. Their `nickname` must also match their Bitbucket -`username`. If the user is not found in the GitLab database, the project creator -(most of the times the current user that started the import process) is set as the author, -but a reference on the issue about the original Bitbucket author is kept. +When issues/pull requests are being imported, the Bitbucket importer uses the Bitbucket nickname of +the author/assignee and tries to find the same Bitbucket identity in GitLab. If they don't match or +the user is not found in the GitLab database, the project creator (most of the times the current +user that started the import process) is set as the author, but a reference on the issue about the +original Bitbucket author is kept. The importer will create any new namespaces (groups) if they don't exist or in the case the namespace is taken, the repository will be imported under the user's namespace that started the import process. +## Requirements for user-mapped contributions + +For user contributions to be mapped, each user must complete the following before the project import: + +1. Verify that the username in the [Bitbucket account settings](https://bitbucket.org/account/settings/) + matches the public name in the [Atlassian account settings](https://id.atlassian.com/manage-profile/profile-and-visibility). + If they don't match, modify the public name in the Atlassian account settings to match the + username in the Bitbucket account settings. + +1. Connect your Bitbucket account in [GitLab profile social sign-in](https://gitlab.com/-/profile/account). + +1. [Set your public email](../../profile/index.md#set-your-public-email). + ## Import your Bitbucket repositories 1. Sign in to GitLab. @@ -69,9 +81,35 @@ namespace that started the import process. ## Troubleshooting -If you have more than one Bitbucket account, be sure to sign in to the correct account. +### If you have more than one Bitbucket account + +Be sure to sign in to the correct account. + If you've accidentally started the import process with the wrong account, follow these steps: 1. Revoke GitLab access to your Bitbucket account, essentially reversing the process in the following procedure: [Import your Bitbucket repositories](#import-your-bitbucket-repositories). 1. Sign out of the Bitbucket account. Follow the procedure linked from the previous step. + +### User mapping fails despite matching names + +[For user mapping to work](#requirements-for-user-mapped-contributions), +the username in the Bitbucket account settings must match the public name in the Atlassian account +settings. If these names match but user mapping still fails, the user may have modified their +Bitbucket username after connecting their Bitbucket account in the +[GitLab profile social sign-in](https://gitlab.com/-/profile/account). + +To fix this, the user must verify that their Bitbucket external UID in the GitLab database matches their +current Bitbucket public name, and reconnect if there's a mismatch: + +1. [Use the API to get the currently authenticated user](../../../api/users.md#list-current-user-for-normal-users). + +1. In the API's response, the `identities` attribute contains the Bitbucket account that exists in + the GitLab database. If the `extern_uid` doesn't match the current Bitbucket public name, the + user should reconnect their Bitbucket account in the [GitLab profile social sign-in](https://gitlab.com/-/profile/account). + +1. Following reconnection, the user should use the API again to verify that their `extern_uid` in + the GitLab database now matches their current Bitbucket public name. + +The importer must then [delete the imported project](../../project/working_with_projects.md#delete-a-project) +and import again. diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index 120c64e00f2..867477c83b2 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -51,4 +51,4 @@ are some useful links to get you started: - [ClearCase to Git](https://therub.org/2013/07/19/clearcase-to-git/) - [Dual syncing ClearCase to Git](https://therub.org/2013/10/22/dual-syncing-clearcase-and-git/) - [Moving to Git from ClearCase](https://sateeshkumarb.wordpress.com/2011/01/15/moving-to-git-from-clearcase/) -- [ClearCase to Git webinar](https://www.brighttalk.com/webcast/11817/162473/clearcase-to-git) +- [ClearCase to Git webinar](https://www.brighttalk.com/webcast/11817/162473) diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md index 55c5feff1f0..8bb716d8122 100644 --- a/doc/user/project/import/cvs.md +++ b/doc/user/project/import/cvs.md @@ -71,6 +71,6 @@ Here's a few links to get you started with the migration: - [Migrate using the `cvs-fast-export` tool](https://gitlab.com/esr/cvs-fast-export) - [Stack Overflow post on importing the CVS repository](https://stackoverflow.com/a/11490134/974710) -- [Convert a CVS repository to Git](https://www.techrepublic.com/blog/linux-and-open-source/convert-cvs-repositories-to-git/) +- [Convert a CVS repository to Git](http://www.techrepublic.com/article/convert-cvs-repositories-to-git/) - [Man page of the `git-cvsimport` tool](https://mirrors.edge.kernel.org/pub/software/scm/git/docs/git-cvsimport.html) - [Migrate using `reposurgeon`](http://www.catb.org/~esr/reposurgeon/repository-editing.html#conversion) diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index bcbc6e09f1b..6913cda0cd5 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -14,7 +14,7 @@ mind that it is possible only if GitLab.com integration is enabled on your GitLa To get to the importer page you need to go to "New project" page. NOTE: -If you are interested in importing Wiki and Merge Request data to your new instance, +If you are interested in importing Wiki and merge request data to your new instance, you'll need to follow the instructions for [exporting a project](../settings/import_export.md#export-a-project-and-its-data)  diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index 5f7475eac36..a44669e738e 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -32,8 +32,7 @@ imported into the GitLab issue's description as plain text. Our parser for converting text in Jira issues to GitLab Flavored Markdown is only compatible with Jira V3 REST API. -There is an [epic](https://gitlab.com/groups/gitlab-org/-/epics/2738) tracking the addition of -items, such as issue assignees, comments, and much more. These are included in the future +There is an [epic](https://gitlab.com/groups/gitlab-org/-/epics/2738) tracking the addition of issue assignees, comments, and much more in the future iterations of the GitLab Jira importer. ## Prerequisites @@ -60,7 +59,7 @@ Importing large projects may take several minutes depending on the size of the i To import Jira issues to a GitLab project: -1. On the **{issues}** **Issues** page, click **Import Issues** (**{import}**) **> Import from Jira**. +1. On the **{issues}** **Issues** page, select **Import Issues** (**{import}**) **> Import from Jira**.  @@ -68,20 +67,20 @@ To import Jira issues to a GitLab project: The following form appears. If you've previously set up the [Jira integration](../../../integration/jira/index.md), you can now see - the Jira projects that you have access to in the dropdown. + the Jira projects that you have access to in the dropdown list.  -1. Click the **Import from** dropdown and select the Jira project that you wish to import issues from. +1. Click the **Import from** dropdown list and select the Jira project that you wish to import issues from. In the **Jira-GitLab user mapping template** section, the table shows to which GitLab users your Jira users are mapped. - When the form appears, the dropdown defaults to the user conducting the import. + When the form appears, the dropdown list defaults to the user conducting the import. -1. To change any of the mappings, click the dropdown in the **GitLab username** column and +1. To change any of the mappings, click the dropdown list in the **GitLab username** column and select the user you want to map to each Jira user. - The dropdown may not show all the users, so use the search bar to find a specific + The dropdown list may not show all the users, so use the search bar to find a specific user in this GitLab project. 1. Click **Continue**. You're presented with a confirmation that import has started. diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index d155f91e40b..71ca9f4f640 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can integrate an [external issue tracker](../../../integration/external-issue-tracker.md) with GitLab. If your preferred issue tracker is not listed in the -[integrations list](../../../integration/external-issue-tracker.md#integration), +[integrations list](../../../integration/external-issue-tracker.md#configure-an-external-issue-tracker), you can enable a custom issue tracker. After you enable the custom issue tracker, a link to the issue tracker displays diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 0a685ad0efb..7e8de776619 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -32,15 +32,15 @@ where you can select a project to enable the GitLab Slack application for. Alternatively, you can configure the Slack application with a project's integration settings. -Keep in mind that you need to have the appropriate permissions for your Slack -team in order to be able to install a new application, read more in Slack's -docs on [Adding an app to your workspace](https://slack.com/help/articles/202035138-Add-apps-to-your-Slack-workspace). +Keep in mind that you must have the appropriate permissions for your Slack +team to be able to install a new application, read more in Slack's +documentation on [Adding an app to your workspace](https://slack.com/help/articles/202035138-Add-apps-to-your-Slack-workspace). To enable the GitLab service for your Slack team: 1. Go to your project's **Settings > Integration > Slack application** (only visible on GitLab.com). -1. Click **Add to Slack**. +1. Select **Add to Slack**. That's all! You can now start using the Slack slash commands. @@ -49,11 +49,11 @@ That's all! You can now start using the Slack slash commands. To create a project alias on GitLab.com for Slack integration: 1. Go to your project's home page. -1. Navigate to **Settings > Integrations** (only visible on GitLab.com) -1. On the **Integrations** page, click **Slack application**. +1. Go to **Settings > Integrations** (only visible on GitLab.com) +1. On the **Integrations** page, select **Slack application**. 1. The current **Project Alias**, if any, is displayed. To edit this value, - click **Edit**. -1. Enter your desired alias, and click **Save changes**. + select **Edit**. +1. Enter your desired alias, and select **Save changes**. Some Slack commands require a project alias, and fail with the following error if the project alias is incorrect or missing from the command: diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md new file mode 100644 index 00000000000..d66e2222538 --- /dev/null +++ b/doc/user/project/integrations/harbor.md @@ -0,0 +1,50 @@ +--- +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 +--- + +# Harbor container registry integration **(FREE)** + +Use Harbor as the container registry for your GitLab project. + +[Harbor](https://goharbor.io/) is an open source registry that can help you manage artifacts across cloud native compute platforms, like Kubernetes and Docker. + +This integration can help you if you need GitLab CI/CD and a container image repository. + +## Prerequisites + +In the Harbor instance, ensure that: + +- The project to be integrated has been created. +- The signed-in user has permission to pull, push, and edit images in the Harbor project. + +## Configure GitLab + +GitLab supports integrating Harbor projects at the group or project level. Complete these steps in GitLab: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Harbor**. +1. Turn on the **Active** toggle under **Enable Integration**. +1. Provide the Harbor configuration information: + - **Harbor URL**: The base URL of Harbor instance which is being linked to this GitLab project. For example, `https://harbor.example.net`. + - **Harbor project name**: The project name in the Harbor instance. For example, `testproject`. + - **Username**: Your username in the Harbor instance, which should meet the requirements in [prerequisites](#prerequisites). + - **Password**: Password of your username. + +1. Select **Save changes**. + +After the Harbor integration is activated: + +- The global variables `$HARBOR_USER`, `$HARBOR_PASSWORD`, `$HARBOR_URL`, and `$HARBOR_PROJECT` are created for CI/CD use. +- The project-level integration settings override the group-level integration settings. + +## Secure your requests to the Harbor APIs + +For each API request through the Harbor integration, the credentials for your connection to the Harbor API use +the `username:password` combination. The following are suggestions for safe use: + +- Use TLS on the Harbor APIs you connect to. +- Follow the principle of least privilege (for access on Harbor) with your credentials. +- Have a rotation policy on your credentials. diff --git a/doc/user/project/integrations/img/failed_badges.png b/doc/user/project/integrations/img/failed_badges.png Binary files differnew file mode 100644 index 00000000000..d44415a8687 --- /dev/null +++ b/doc/user/project/integrations/img/failed_badges.png diff --git a/doc/user/project/integrations/img/failed_banner.png b/doc/user/project/integrations/img/failed_banner.png Binary files differnew file mode 100644 index 00000000000..ba40c1301d6 --- /dev/null +++ b/doc/user/project/integrations/img/failed_banner.png diff --git a/doc/user/project/integrations/img/failed_banner_error.png b/doc/user/project/integrations/img/failed_banner_error.png Binary files differnew file mode 100644 index 00000000000..8f4dabbf8c2 --- /dev/null +++ b/doc/user/project/integrations/img/failed_banner_error.png diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index b317e65bdf2..768acb02ee6 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -32,7 +32,7 @@ on your configuration: If Mattermost is installed on the same server as GitLab, the configuration process can be done for you by GitLab. -Go to the Mattermost Slash Command service on your project and click **Add to Mattermost** button. +Go to the Mattermost Slash Command service on your project and select **Add to Mattermost**. ## Manual configuration @@ -52,13 +52,13 @@ installations from source. To enable custom slash commands from the Mattermost administrator console: 1. Sign in to Mattermost as a user with administrator privileges. -1. Next to your username, click the **{ellipsis_v}** **Settings** icon, and +1. Next to your username, select the **{ellipsis_v}** **Settings** icon, and select **System Console**. 1. Select **Integration Management**, and set these values to `TRUE`: - **Enable Custom Slash Commands** - **Enable integrations to override usernames** - **Enable integrations to override profile picture icons** -1. Click **Save**, but do not close this browser tab, because you need it in +1. Select **Save**, but do not close this browser tab, because you need it in a later step. ### Get configuration values from GitLab @@ -85,9 +85,9 @@ the previous step: 1. In the Mattermost tab you left open when you [enabled custom slash commands](#enable-custom-slash-commands), go to your team page. -1. Click the **{ellipsis_v}** **Settings** icon, and select **Integrations**. +1. Select the **{ellipsis_v}** **Settings** icon, and select **Integrations**. 1. In the left menu, select **Slash commands**. -1. Click **Add Slash Command**: +1. Select **Add Slash Command**:  1. Provide a **Display Name** and **Description** for your new command. @@ -101,7 +101,7 @@ the previous step: [viewed configuration values](#get-configuration-values-from-gitlab). 1. For all other values, you may use the suggestions from GitLab or use your preferred values. -1. Copy the **Token** value, as you need it in a later step, and click **Done**. +1. Copy the **Token** value, as you need it in a later step, and select **Done**. ### Provide the Mattermost token to GitLab @@ -116,7 +116,7 @@ provide to GitLab:  -1. Click **Save changes** for the changes to take effect. +1. Select **Save changes** for the changes to take effect. Your slash command can now communicate with your GitLab project. @@ -165,4 +165,4 @@ different types of notifications. All events are sent to the specified channel. ## Further reading - [Mattermost slash commands documentation](https://docs.mattermost.com/developer/slash-commands.html) -- [Omnibus GitLab Mattermost](https://docs.gitlab.com/omnibus/gitlab-mattermost/) +- [Omnibus GitLab Mattermost](../../../integration/mattermost/) diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 8ecc16050be..2cb62b8924e 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -43,6 +43,7 @@ Click on the service links to see further configuration instructions and details | [Flowdock](../../../api/integrations.md#flowdock) | Send notifications from GitLab to Flowdock flows. | **{dotted-circle}** No | | [GitHub](github.md) | Obtain statuses for commits and pull requests. | **{dotted-circle}** No | | [Google Chat](hangouts_chat.md) | Send notifications from your GitLab project to a room in Google Chat.| **{dotted-circle}** No | +| [Harbor](harbor.md) | Use Harbor as the container registry. | **{dotted-circle}** No | | [irker (IRC gateway)](irker.md) | Send IRC messages. | **{dotted-circle}** No | | [Jenkins](../../../integration/jenkins.md) | Run CI/CD pipelines with Jenkins. | **{check-circle}** Yes | | JetBrains TeamCity CI | Run CI/CD pipelines with TeamCity. | **{check-circle}** Yes | diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 9d8b98edba1..d37196ec114 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -202,6 +202,10 @@ The available values for `object_attributes.action` in the payload are: The `assignee` and `assignee_id` keys are deprecated and contain the first assignee only. +The `escalation_status` and `escalation_policy` fields are +only available for issue types which support escalations, +such as incidents. + Request header: ```plaintext @@ -271,6 +275,12 @@ Payload example: "url": "http://example.com/diaspora/issues/23", "state": "opened", "action": "open", + "severity": "high", + "escalation_status": "triggered", + "escalation_policy": { + "id": 18, + "name": "Engineering On-call" + }, "labels": [{ "id": 206, "title": "API", @@ -771,7 +781,8 @@ Payload example: Merge request events are triggered when: - A new merge request is created. -- An existing merge request is updated, approved, unapproved, merged, or closed. +- An existing merge request is updated, approved (by all required approvers), unapproved, merged, or closed. +- An individual user adds or removes their approval to an existing merge request. - A commit is added in the source branch. - All threads are resolved on the merge request. @@ -783,6 +794,8 @@ The available values for `object_attributes.action` in the payload are: - `update` - `approved` - `unapproved` +- `approval` +- `unapproval` - `merge` Request header: @@ -1294,7 +1307,7 @@ Payload example: "id": 3, "name": "User", "email": "user@gitlab.com", - "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", + "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon" }, "commit": { "id": 2366, diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index ace5783c852..e823391401d 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -62,7 +62,8 @@ You can configure a webhook for a group or a project. ## Test a webhook -You can trigger a webhook manually, to ensure it's working properly. +You can trigger a webhook manually, to ensure it's working properly. You can also send +a test request to re-enable a [disabled webhook](#re-enable-disabled-webhooks). For example, to test `push events`, your project should have at least one commit. The webhook uses this commit in the webhook. @@ -72,6 +73,8 @@ To test a webhook: 1. Scroll down to the list of configured webhooks. 1. From the **Test** dropdown list, select the type of event to test. +You can also test a webhook from its edit page. +  ## Create an example webhook receiver @@ -143,7 +146,32 @@ GitLab webhooks, keep in mind the following: GitLab assumes the hook failed and retries it. Most HTTP libraries take care of the response for you automatically but if you are writing a low-level hook, this is important to remember. -- GitLab ignores the HTTP status code returned by your endpoint. +- GitLab usually ignores the HTTP status code returned by your endpoint, + unless the [`web_hooks_disable_failed` feature flag is set](#failing-webhooks). + +### Failing webhooks + +> - Introduced in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) in GitLab 14.9. + +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 `web_hooks_disable_failed`. +The feature is not ready for production use. + +If a webhook fails repeatedly, it may be disabled automatically. + +Webhooks that return response codes in the `5xx` range are understood to be failing +intermittently, and are temporarily disabled. This lasts initially +for 10 minutes. If the hook continues to fail, the back-off period is +extended on each retry, up to a maximum disabled period of 24 hours. + +Webhooks that return failure codes in the `4xx` range are understood to be +misconfigured, and these are disabled until you manually re-enable +them. These webhooks are not automatically retried. + +See [troubleshooting](#troubleshoot-webhooks) for information on +how to see if a webhook is disabled, and how to re-enable it. ## How image URLs are displayed in the webhook body @@ -186,6 +214,13 @@ To view the table: 1. In your project, on the left sidebar, select **Settings > Webhooks**. 1. Scroll down to the webhooks. +1. Each [failing webhook](#failing-webhooks) has a badge listing it as: + + - **Failed to connect** if it is misconfigured, and needs manual intervention to re-enable it. + - **Fails to connect** if it is temporarily disabled and will retry later. + +  + 1. Select **Edit** for the webhook you want to view. The table includes the following details about each request: @@ -216,8 +251,8 @@ If the endpoint doesn't send an HTTP response in those 10 seconds, GitLab may assume the webhook failed and retry it. If your webhooks are failing or you are receiving multiple requests, -you can try changing the default timeout value. -In your `/etc/gitlab/gitlab.rb` file, uncomment or add the following setting: +an administrator can try changing the default timeout value +by uncommenting or adding the following setting in `/etc/gitlab/gitlab.rb`: ```ruby gitlab_rails['webhook_timeout'] = 10 @@ -233,3 +268,17 @@ determined by [CAcert.org](http://www.cacert.org/). If that is not the case, consider using [SSL Checker](https://www.sslshopper.com/ssl-checker.html) to identify faults. Missing intermediate certificates are common causes of verification failure. + +### Re-enable disabled webhooks + +If a webhook is failing, a banner displays at the top of the edit page explaining +why it is disabled, and when it will be automatically re-enabled. For example: + + + +In the case of a failed webhook, an error banner is displayed: + + + +To re-enable a failing or failed webhook, [send a test request](#test-a-webhook). If the test +request succeeds, the webhook is re-enabled. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 71440298d85..d731ceb5aca 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -53,7 +53,7 @@ the issue board feature. > - Multiple issue boards per project [moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53811) to GitLab Free in 12.1. > - Multiple issue boards per group are available in GitLab Premium. -Multiple issue boards allow for more than one issue board for a given project **(FREE)** or group **(PREMIUM)**. +Multiple issue boards allow for more than one issue board for a given project in GitLab Free or group in GitLab Premium and higher tiers. This is great for large projects with more than one team or when a repository hosts the code of multiple products. Using the search box at the top of the menu, you can filter the listed boards. @@ -275,7 +275,7 @@ Users on GitLab Free can use a single group issue board. ### Assignee lists **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5784) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5784) in GitLab 11.0. As in a regular list showing all issues with a chosen label, you can add an assignee list that shows all issues assigned to a user. @@ -295,7 +295,7 @@ To remove an assignee list, just as with a label list, click the trash icon. ### Milestone lists **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6469) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6469) in GitLab 11.2. You're also able to create lists of a milestone. These are lists that filter issues by the assigned milestone, giving you more freedom and visibility on the issue board. To add a milestone list: @@ -333,7 +333,7 @@ to and from a iteration list to manipulate the iteration of the dragged issues. ### Group issues in swimlanes **(PREMIUM)** -> - Grouping by epic [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3352) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. +> - Grouping by epic [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3352) in GitLab 13.6. > - Editing issue titles in the issue sidebar [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232745) in GitLab 13.8. > - Editing iteration in the issue sidebar [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290232) in GitLab 13.9. @@ -356,7 +356,7 @@ appears on the right. There you can see and edit the issue's: - Title - Assignees -- Epic **(PREMIUM)** +- [Epic](../group/epics/index.md) - Milestone - Time tracking value (view only) - Due date @@ -506,14 +506,14 @@ You can filter by the following: - Assignee - Author -- Epic -- Iteration +- [Epic](../group/epics/index.md) +- [Iteration](../group/iterations/index.md) - Label - Milestone - My Reaction - Release - Type (issue/incident) -- Weight +- [Weight](issues/issue_weight.md) #### Filtering issues in a group board @@ -536,7 +536,7 @@ changing a label. A typical workflow of using an issue board would be: -1. You have [created](labels.md#label-management) and [prioritized](labels.md#label-priority) +1. You [create](labels.md#create-a-label) and [prioritize](labels.md#set-label-priority) labels to categorize your issues. 1. You have a bunch of issues (ideally labeled). 1. You visit the issue board and start [creating lists](#create-a-new-list) to diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 947fbdcc2d1..e5d698fa97a 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -52,7 +52,7 @@ export, after which the email is prepared. ## Sorting -Exported issues are always sorted by `Issue ID`. +Exported issues are always sorted by `Title`. ## Format @@ -63,11 +63,11 @@ the values: | Column | Description | |------------------------------------------|-----------------------------------------------------------| +| Title | Issue `title` | +| Description | Issue `description` | | Issue ID | Issue `iid` | | URL | A link to the issue on GitLab | -| Title | Issue `title` | | State | `Open` or `Closed` | -| Description | Issue `description` | | Author | Full name of the issue author | | Author Username | Username of the author, with the `@` symbol omitted | | Assignee | Full name of the issue assignee | @@ -85,6 +85,10 @@ the values: | [Epic](../../group/epics/index.md) ID | ID of the parent epic, introduced in 12.7 | | [Epic](../../group/epics/index.md) Title | Title of the parent epic, introduced in 12.7 | +In GitLab 14.7 and earlier, the first two columns were `Issue ID` and `URL`, +which [caused an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/34769) +when importing back into GitLab. + ## Limitations - Export Issues to CSV is not available at the Group's Issues List. diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 66ca29c094e..e9f3f4be1c3 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -6,4 +6,6 @@ remove_date: '2022-02-24' This file was moved to [another location](index.md). <!-- This redirect file can be deleted after <2022-02-24>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 155d6260a5c..58591129d97 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -19,7 +19,7 @@ You can create an issue in many ways in GitLab: - [From a project](#from-a-project) - [From a group](#from-a-group) -- [From another issue](#from-another-issue) +- [From another issue or incident](#from-another-issue-or-incident) - [From an issue board](#from-an-issue-board) - [By sending an email](#by-sending-an-email) - [Using a URL with prefilled values](#using-a-url-with-prefilled-values) @@ -70,9 +70,10 @@ The newly created issue opens. The project you selected most recently becomes the default for your next visit. This can save you a lot of time and clicks, if you mostly create issues for the same project. -### From another issue +### From another issue or incident -> New issue becoming linked to the issue of origin [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68226) in GitLab 14.3. +> - New issue becoming linked to the issue of origin [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68226) in GitLab 14.3. +> - **Relate to…** checkbox [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198494) in GitLab 14.9. You can create a new issue from an existing one. The two issues can then be marked as related. @@ -83,10 +84,10 @@ Prerequisites: To create an issue from another issue: 1. In an existing issue, select the vertical ellipsis (**{ellipsis_v}**). -1. Select **New issue**. +1. Select **New related issue**. 1. Complete the [fields](#fields-in-the-new-issue-form). - The new issue's description is prefilled with `Related to #123`, where `123` is the ID of the - issue of origin. If you keep this mention in the description, the two issues become + The new issue form has a **Relate to issue #123** checkbox, where `123` is the ID of the + issue of origin. If you keep this checkbox checked, the two issues become [linked](related_issues.md). 1. Select **Create issue**. @@ -160,6 +161,9 @@ To regenerate the email address: ### Using a URL with prefilled values +> - Ability to use both `issuable_template` and `issue[description]` in the same URL [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80554) in GitLab 14.9. +> - Ability to specify `add_related_issue` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198494) in GitLab 14.9. + To link directly to the new issue page with prefilled fields, use query string parameters in a URL. You can embed a URL in an external HTML page to create issues with certain fields prefilled. @@ -168,9 +172,10 @@ HTML page to create issues with certain fields prefilled. | -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | Title | `issue[title]` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | | Issue type | `issue[issue_type]` | Either `incident` or `issue`. | -| Description template | `issuable_template` | Cannot be used at the same time as `issue[description]`. Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | -| Description | `issue[description]` | Cannot be used at the same time as `issuable_template`. Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | +| Description template | `issuable_template` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). | +| Description | `issue[description]` | Must be [URL-encoded](../../../api/index.md#namespaced-path-encoding). If used in combination with `issuable_template` or a [default issue template](../description_templates.md#set-a-default-template-for-merge-requests-and-issues), the `issue[description]` value is appended to the template. | | Confidential | `issue[confidential]` | If `true`, the issue is marked as confidential. | +| Relate to… | `add_related_issue` | A numeric issue ID. If present, the issue form shows a [**Relate to…** checkbox](#from-another-issue-or-incident) to optionally link the new issue to the specified existing issue. | Adapt these examples to form your new issue URL with prefilled fields. To create an issue in the GitLab project: @@ -264,7 +269,7 @@ When bulk editing issues in a project, you can edit the following attributes: - [Notification](../../profile/notifications.md) subscription - [Iteration](../../group/iterations/index.md) -### Bulk edit issues from a group +### Bulk edit issues from a group **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7249) in GitLab 12.1. > - Assigning epic [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210470) in GitLab 13.2. @@ -573,13 +578,11 @@ To copy the issue's email address: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 13.3. Disabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/3413) in GitLab 13.9. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 14.5. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, ask an administrator to -[disable the feature flags](../../../administration/feature_flags.md) named `real_time_issue_sidebar` and `broadcast_issue_updates`. -On GitLab.com, this feature is available. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/17589) in GitLab 14.9. Feature flags `real_time_issue_sidebar` and `broadcast_issue_updates` removed. Assignees in the sidebar are updated in real time. +When you're viewing an issue and somebody changes its assignee, +you can see the change without having to refresh the page. ## Assignee diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index f957d701a3b..279f297d016 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -39,4 +39,4 @@ to assign the issue to.  -To remove an assignee, deselect them from the same dropdown menu. +To remove an assignee, clear them from the same dropdown menu. diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index f83ebc5e8a8..b8151ac873a 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -75,4 +75,9 @@ Access our [permissions](../../permissions.md) page for more information. When you [add a linked issue](#add-a-linked-issue), you can show that it **blocks** or **is blocked by** another issue. -Issues that block other issues have an icon (**{issue-block}**) shown in the issue lists and [boards](../issue_board.md). +Issues that block other issues have an icon (**{issue-block}**) next to their title, shown in the +issue lists and [boards](../issue_board.md). +The icon disappears when the blocking issue is closed or their relationship is changed or +[removed](#remove-a-linked-issue). + +If you try to close a blocked issue using the "Close issue" button, a confirmation message appears. diff --git a/doc/user/project/issues/sorting_issue_lists.md b/doc/user/project/issues/sorting_issue_lists.md index 329f65bfacd..9311ef590df 100644 --- a/doc/user/project/issues/sorting_issue_lists.md +++ b/doc/user/project/issues/sorting_issue_lists.md @@ -49,7 +49,7 @@ Ties are broken arbitrarily. Only the highest prioritized label is checked, and labels with a lower priority are ignored. For more information, see [issue 14523](https://gitlab.com/gitlab-org/gitlab/-/issues/14523). -To learn more about priority labels, read the [Labels](../labels.md#label-priority) documentation. +To learn how to change label priority, see [Label priority](../labels.md#set-label-priority). ## Sorting by last updated @@ -98,7 +98,9 @@ When you sort by **Priority**, the issue order changes to sort in this order: 1. Issues with a higher priority label. 1. Issues without a prioritized label. -To learn more about priority, read the [Labels](../labels.md#label-priority) documentation. +Ties are broken arbitrarily. + +To learn how to change label priority, see [Label priority](../labels.md#set-label-priority). ## Sorting by title diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 7ccc39eeb8b..18197cd860f 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -6,145 +6,270 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Labels **(FREE)** -As your count of issues, merge requests, and epics grows in GitLab, it's more and more challenging +As your count of issues, merge requests, and epics grows in GitLab, it gets more challenging to keep track of those items. Especially as your organization grows from just a few people to -hundreds or thousands. This is where labels come in. They help you organize and tag your work -so you can track and find the work items you're interested in. +hundreds or thousands. With labels, you can organize and tag your work, and track the work items +you're interested in. Labels are a key part of [issue boards](issue_board.md). With labels you can: -- Categorize epics, issues, and merge requests using colors and descriptive titles like +- Categorize [epics](../group/epics/index.md), issues, and merge requests using colors and descriptive titles like `bug`, `feature request`, or `docs`. -- Dynamically filter and manage epics, issues, and merge requests. +- Dynamically filter and manage [epics](../group/epics/index.md), issues, and merge requests. - [Search lists of issues, merge requests, and epics](../search/index.md#search-issues-and-merge-requests), as well as [issue boards](../search/index.md#issue-boards). -## Project labels and group labels +## Types of labels -There are two types of labels in GitLab: +You can use two types of labels in GitLab: - **Project labels** can be assigned to issues and merge requests in that project only. -- **Group labels** can be assigned to issues and merge requests in any project in - the selected group or its subgroups. - - They can also be assigned to epics in the selected group or its subgroups.**(ULTIMATE)** +- **Group labels** can be assigned to issues, merge requests, and [epics](../group/epics/index.md) + in any project in the selected group or its subgroups. ## Assign and unassign labels > Unassigning labels with the **X** button [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216881) in GitLab 13.5. -Every issue, merge request, and epic can be assigned any number of labels. The labels are -managed in the right sidebar, where you can assign or unassign labels as needed. +You can assign labels to any issue, merge request, or epic. To assign or unassign a label: -1. In the **Labels** section of the sidebar, click **Edit**. +1. In the **Labels** section of the sidebar, select **Edit**. 1. In the **Assign labels** list, search for labels by typing their names. You can search repeatedly to add more labels. The selected labels are marked with a checkmark. -1. Click the labels you want to assign or unassign. +1. Select the labels you want to assign or unassign. 1. To apply your changes to labels, select **X** next to **Assign labels** or select any area outside the label section. -Alternatively, to unassign a label, click the **X** on the label you want to unassign. +Alternatively, to unassign a label, select the **X** on the label you want to unassign. -You can also assign a label with the `/label` [quick action](quick_actions.md), -remove labels with `/unlabel`, and reassign labels (remove all and assign new ones) with `/relabel`. +You can also assign and unassign labels with [quick actions](quick_actions.md): -## Label management +- Assign labels with `/label`. +- Remove labels with `/unlabel`. +- Remove all labels and assign new ones with `/relabel`. -Users with a [permission level](../permissions.md) of Reporter or higher are able to create -and edit labels. +## View available labels -### Project labels +### View project labels -> Showing all inherited labels [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241990) in GitLab 13.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241990) in GitLab 13.5: the label list in a project also shows all inherited labels. -To view a project's available labels, in the project, go to **Project information > Labels**. -Its list of labels includes both the labels defined at the project level, and -all labels defined by its ancestor groups. For each label, you can see the -project or group path from where it was created. You can filter the list by -entering a search query in the **Filter** field, and then clicking its search -icon (**{search}**). +To view the **project's labels**: -To create a new project label: +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Labels**. -1. In your project, go to **Project information > Labels**. -1. Select the **New label** button. +Or: + +1. View an issue or merge request. +1. On the right sidebar, in the **Labels** section, select **Edit**. +1. Select **Manage project labels**. + +The list of labels includes both the labels created in the project and +all labels created in the project's ancestor groups. For each label, you can see the +project or group path where it was created. + +### View group labels + +To view the **group's labels**: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Group information > Labels**. + +Or: + +1. View an epic. +1. On the right sidebar, in the **Labels** section, select **Edit**. +1. Select **Manage group labels**. + +The list includes all labels created only in the group. It does not list any labels created in +the group's projects. + +## Create a label + +Prerequisites: + +- You must have at least the Reporter role for the project or group. + +### Create a project label + +To create a project label: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Labels**. +1. Select **New label**. +1. In the **Title** field, enter a short, descriptive name for the label. You + can also use this field to create [scoped, mutually exclusive labels](#scoped-labels). +1. Optional. In the **Description** field, enter additional + information about how and when to use this label. +1. Optional. Select a color by selecting from the available colors, or enter a hex color value for + a specific color in the **Background color** field. +1. Select **Create label**. + +### Create a project label from an issue or merge request + +You can also create a new project label from an issue or merge request. +Labels you create this way belong to the same project as the issue or merge request. + +Prerequisites: + +- You must have at least the Reporter role for the project. + +To do so: + +1. View an issue or merge request. +1. On the right sidebar, in the **Labels** section, select **Edit**. +1. Select **Create project label**. +1. Fill in the name field. You can't specify a description if creating a label this way. + You can add a description later by [editing the label](#edit-a-label). +1. Optional. Select a color by selecting from the available colors, or enter a hex color value for + a specific color. +1. Select **Create**. + +### Create a group label + +To create a group label: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Group information > Labels**. +1. Select **New label**. 1. In the **Title** field, enter a short, descriptive name for the label. You can also use this field to create [scoped, mutually exclusive labels](#scoped-labels). -1. Optional. In the **Description** field, you can enter additional +1. Optional. In the **Description** field, enter additional information about how and when to use this label. -1. Optional. Select a background color for the label by selecting one of the - available colors, or by entering a hex color value in the **Background color** - field. +1. Optional. Select a color by selecting from the available colors, or enter a hex color value for + a specific color in the **Background color** field. 1. Select **Create label**. -You can also create a new project label from within an issue or merge request. In the -label section of the right sidebar of an issue or a merge request: +### Create a group label from an epic **(PREMIUM)** + +You can also create a new group label from an epic. +Labels you create this way belong to the same group as the epic. + +Prerequisites: + +- You must have at least the Reporter role for the group. -1. Click **Edit**. -1. Click **Create project label**. - - Fill in the name field. Note that you can't specify a description if creating a label - this way. You can add a description later by editing the label (see below). - - Optional. Select a color by clicking on the available colors, or input a hex - color value for a specific color. -1. Click **Create**. +To do so: -To edit a label after you create it, select (**{pencil}**). +1. View an epic. +1. On the right sidebar, in the **Labels** section, select **Edit**. +1. Select **Create group label**. +1. Fill in the name field. You can't specify a description if creating a label this way. + You can add a description later by [editing the label](#edit-a-label). +1. Optional. Select a color by selecting from the available colors,enter input a hex color value + for a specific color. +1. Select **Create**. -To delete a project label, select (**{ellipsis_v}**) next to the **Subscribe** button -and select **Delete** or select **Delete** when you edit a label. +## Edit a label + +Prerequisites: + +- You must have at least the Reporter role for the project or group. + +### Edit a project label + +To edit a **project** label: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Labels**. +1. Next to the label you want to edit, select **Edit** (**{pencil}**). + +### Edit a group label + +To edit a **group** label: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Group information > Labels**. +1. Next to the label you want to edit, select **Edit** (**{pencil}**). + +## Delete 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. +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. + +Prerequisites: -#### Promote a project label to a group label +- You must have at least the Reporter role for the project. + +### Delete a project label + +To delete a **project** label: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Labels**. +1. Either: + + - Next to the **Subscribe** button, select (**{ellipsis_v}**). + - Next to the label you want to edit, select **Edit** (**{pencil}**). + +1. Select **Delete**. + +### Delete a group label + +To delete a **group** label: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Group information > Labels**. +1. Either: + + - Next to the **Subscribe** button, select (**{ellipsis_v}**). + - Next to the label you want to edit, select **Edit** (**{pencil}**). + +1. Select **Delete**. + +## Promote a project label to a group label > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231472) in GitLab 13.6: promoting a project label keeps that label's ID and changes it into a group label. Previously, promoting a project label created a new group label with a new ID and deleted the old label. -If you previously created a project label and now want to make it available for other -projects within the same group, you can promote it to a group label. +You might want to make a project label available for other +projects in the same group. Then, you can promote the label to a group label. If other projects in the same group have a label with the same title, they are all merged with the new group label. If a group label with the same title exists, it is also merged. -All issues, merge requests, issue board lists, issue board filters, and label subscriptions -with the old labels are assigned to the new group label. +WARNING: +Promoting a label is a permanent action and cannot be reversed. -The new group label has the same ID as the previous project label. +Prerequisites: -WARNING: -Promoting a label is a permanent action, and cannot be reversed. +- You must have at least the Reporter role for the project. +- You must have at least the Reporter role for the project's parent group. To promote a project label to a group label: -1. Navigate to **Project information > Labels** in the project. -1. Click on the three dots (**{ellipsis_v}**) next to the **Subscribe** button and +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Labels**. +1. Next to the **Subscribe** button, select the three dots (**{ellipsis_v}**) and select **Promote to group label**. -### Group labels +All issues, merge requests, issue board lists, issue board filters, and label subscriptions +with the old labels are assigned to the new group label. + +The new group label has the same ID as the previous project label. -To view the group labels list, navigate to the group and click **Group information > Labels**. -The list includes all labels that are defined at the group level only. It does not -list any labels that are defined in projects. You can filter the list by entering -a search query at the top and clicking search (**{search}**). +## Generate default project labels -To create a **group label**, navigate to **Group information > Labels** in the group and -follow the same process as [creating a project label](#project-labels). +If a project or its parent group has no labels, you can generate a default set of project +labels from the label list page. -#### Create group labels from epics **(ULTIMATE)** +Prerequisites: -You can create group labels from the epic sidebar. The labels you create -belong to the immediate group to which the epic belongs. The process is the same as -creating a [project label from an issue or merge request](#project-labels). +- You must have at least the Reporter role for the project. +- The project must have no labels present. -### Generate default labels +To add the default labels to the project: -If a project or group has no labels, you can generate a default set of project or group -labels from the label list page. The page shows a **Generate a default set of labels** -button if the list is empty. Select the button to add the following default labels -to the project: +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Labels**. +1. Select **Generate a default set of labels**. + +The following labels are created: - `bug` - `confirmed` @@ -157,131 +282,143 @@ to the project: ## Scoped labels **(PREMIUM)** -Scoped labels allow teams to use the label feature to annotate issues, merge requests -and epics with mutually exclusive labels. This can enable more complicated workflows -by preventing certain labels from being used together. - -A label is scoped when it uses a special double-colon (`::`) syntax in the label's -title, for example: +Teams can use scoped labels to annotate issues, merge requests, and epics with mutually exclusive +labels. By preventing certain labels from being used together, you can create more complex workflows.  -An issue, merge request or epic cannot have two scoped labels, of the form `key::value`, -with the same `key`. Adding a new label with the same `key`, but a different `value` -causes the previous `key` label to be replaced with the new label. +A scoped label uses a double-colon (`::`) syntax in its title, for example: `workflow::in-review`. -For example: +An issue, merge request, or epic cannot have two scoped labels, of the form `key::value`, +with the same `key`. If you add a new label with the same `key` but a different `value`, +the previous `key` label is replaced with the new label. -1. An issue is identified as being low priority, and a `priority::low` project - label is added to it. -1. After more review the issue priority is increased, and a `priority::high` label is - added. -1. GitLab automatically removes the `priority::low` label, as an issue should not - have two priority labels at the same time. +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For a video overview, see [Scoped Labels Speed Run](https://www.youtube.com/watch?v=ebyCiKMFODg). ### Filter by scoped labels > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12285) in GitLab 14.4. -To filter issue, merge request, or epic lists for ones with labels that belong to a given scope, enter +To filter issue, merge request, or epic lists by a given scope, enter `<scope>::*` in the searched label name. For example, filtering by the `platform::*` label returns issues that have `platform::iOS`, `platform::Android`, or `platform::Linux` labels. NOTE: -This is not available on the [issues or merge requests dashboard pages](../search/index.md#search-issues-and-merge-requests). +Filtering by scoped labels not available on the [issues or merge requests dashboard pages](../search/index.md#search-issues-and-merge-requests). + +### Scoped labels examples + +**Example 1.** Updating issue priority: + +1. You decide that an issue is of low priority, and assign it the `priority::low` label. +1. After more review, you realize the issue's priority is higher increased, and you assign it the + `priority::high` label. +1. Because an issue shouldn't have two priority labels at the same time, GitLab removes the + `priority::low` label. + +**Example 2.** You want a custom field in issues to track the operating system platform +that your features target, where each issue should only target one platform. + +You create three labels: + +- `platform::iOS` +- `platform::Android` +- `platform::Linux` + +If you assign any of these labels to an issue automatically removes any other existing label that +starts with `platform::`. + +**Example 3.** You can use scoped labels to represent the workflow states of your teams. -### Workflows with scoped labels +Suppose you have the following labels: -Suppose you wanted a custom field in issues to track the operating system platform -that your features target, where each issue should only target one platform. You -would then create three labels `platform::iOS`, `platform::Android`, `platform::Linux`. -Applying any one of these labels on a given issue would automatically remove any other -existing label that starts with `platform::`. +- `workflow::development` +- `workflow::review` +- `workflow::deployed` -The same pattern could be applied to represent the workflow states of your teams. -Suppose you have the labels `workflow::development`, `workflow::review`, and -`workflow::deployed`. If an issue already has the label `workflow::development` -applied, and a developer wanted to advance the issue to `workflow::review`, they -would simply apply that label, and the `workflow::development` label would -automatically be removed. This behavior already exists when you move issues -across label lists in an [issue board](issue_board.md#create-workflows), but -now, team members who may not be working in an issue board directly would still -be able to advance workflow states consistently in issues themselves. +If an issue already has the label `workflow::development` and a developer wants to show that the +issue is now under review, they assign the `workflow::review`, and the `workflow::development` label +is removed. -This functionality is demonstrated in a video regarding -[using scoped labels for custom fields and workflows](https://www.youtube.com/watch?v=4BCBby6du3c). +The same happens when you move issues across label lists in an +[issue board](issue_board.md#create-workflows). With scoped labels, team members not working in an +issue board can also advance workflow states consistently in issues themselves. -### Scoped labels with nested scopes +For a video explanation, see: + +<div class="video-fallback"> + See the video: <a href="https://www.youtube.com/watch?v=4BCBby6du3c">Use scoped labels for custom fields and custom workflows</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube.com/embed/4BCBby6du3c" frameborder="0" allowfullscreen="true"> </iframe> +</figure> + +### Nested scopes You can create a label with a nested scope by using multiple double colons `::` when creating it. In this case, everything before the last `::` is the scope. -For example, `workflow::backend::review` and `workflow::backend::development` are valid -scoped labels, but they **can't** exist on the same issue at the same time, as they -both share the same scope, `workflow::backend`. +For example, if your project has these labels: -Additionally, `workflow::backend::review` and `workflow::frontend::review` are valid -scoped labels, and they **can** exist on the same issue at the same time, as they -both have different scopes, `workflow::frontend` and `workflow::backend`. +- `workflow::backend::review` +- `workflow::backend::development` +- `workflow::frontend::review` -## Subscribing to labels +An issue **can't** have both `workflow::backend::review` and `workflow::backend::development` +labels at the same time, because they both share the same scope: `workflow::backend`. -From the project label list page and the group label list page, you can click **Subscribe** -to the right of any label to enable [notifications](../profile/notifications.md) for that -label. You are notified whenever the label is assigned to an epic, -issue, or merge request. +On the other hand, an issue **can** have both `workflow::backend::review` and `workflow::frontend::review` +labels at the same time, because they both have different scopes: `workflow::frontend` and `workflow::backend`. -If you are subscribing to a group label from within a project, you can select to subscribe -to label notifications for the project only, or the whole group. +## Receive notifications when a label is used - +You can subscribe to a label to [receive notifications](../profile/notifications.md) whenever the +label is assigned to an issue, merge request, or epic. -## Label priority +To subscribe to a label: -Labels can have relative priorities, which are used in the **Label priority** and -**Priority** sort orders of issues and merge request list pages. Prioritization -for both group and project labels happens at the project level, and cannot be done -from the group label list. +1. [View the label list page.](#view-available-labels) +1. To the right of any label, select **Subscribe**. +1. Optional. If you are subscribing to a group label from a project, select either: + - **Subscribe at project level** to be notified about events in this project. + - **Subscribe at group level**: to be notified about events in the whole group. -NOTE: -Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/14523) considers changing this. +## Set label priority -From the project label list page, star a label to indicate that it has a priority. - - +Labels can have relative priorities, which are used when you sort issue and merge request lists +by [label priority](issues/sorting_issue_lists.md#sorting-by-label-priority) and [priority](issues/sorting_issue_lists.md#sorting-by-priority). -Drag starred labels up and down the list to change their priority, where higher in the list -means higher priority. +When prioritizing labels, you must do it from a project. +It's not possible to do it from the group label list. - +NOTE: +Priority sorting is based on the highest priority label only. +[This discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/14523) considers changing this. -On the merge request and issue list pages (for both groups and projects) you -can sort by `Label priority` or `Priority`. +Prerequisites: -If you sort by `Label priority`, GitLab uses this sort comparison order: +- You must have at least the Reporter role for the project. -1. Items with a higher priority label. -1. Items without a prioritized label. +To prioritize a label: -Ties are broken arbitrarily. Note that only the highest prioritized label is checked, -and labels with a lower priority are ignored. See this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/14523) -for more information. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Project information > Labels**. +1. Next to a label you want to prioritize, select the star (**{star-o}**). - + -If you sort by `Priority`, GitLab uses this sort comparison order: +This label now appears at the top of the label list, under **Prioritized Labels**. -1. Items with milestones that have due dates, where the soonest assigned [milestone](milestones/index.md) - is listed first. -1. Items with milestones with no due dates. -1. Items with a higher priority label. -1. Items without a prioritized label. +To change the relative priority of these labels, drag them up and down the list. +The labels higher in the list get higher priority. -Ties are broken arbitrarily. + - +To learn what happens when you sort by priority or label priority, see +[Sorting and ordering issue lists](issues/sorting_issue_lists.md). ## Troubleshooting diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 8be2ade3f2f..c3d5dca0675 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -10,16 +10,43 @@ Members are the users and groups who have access to your project. Each member gets a role, which determines what they can do in the project. +Project members can: + +1. Be [direct members](#add-users-to-a-project) of the project. +1. [Inherit membership](#inherited-membership) of the project from the project's group. +1. Be a member of a group that was [shared](share_project_with_groups.md) with the project. +1. Be a member of a group that was [shared with the project's group](../../group/index.md#share-a-group-with-another-group). + +```mermaid +flowchart RL + subgraph Group A + A(Direct member) + B{{Shared member}} + subgraph Project A + H(1. Direct member) + C{{2. Inherited member}} + D{{4. Inherited member}} + E{{3. Shared member}} + end + A-->|Direct membership of Group A\nInherited membership of Project A|C + end + subgraph Group C + G(Direct member) + end + subgraph Group B + F(Direct member) + end + F-->|Group B\nshared with\nGroup A|B + B-->|Inherited membership of Project A|D + G-->|Group C shared with Project A|E +``` + ## Add users to a project > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal window [with a flag](../../feature_flags.md). Disabled by default. > - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 14.8. - -FLAG: -On self-managed GitLab, by default the modal window feature is available. -To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) -named `invite_members_group_modal`. -On GitLab.com, this feature is available. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. + [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. Add users to a project so they become members and have permission to perform actions. @@ -52,12 +79,8 @@ using the email address the invitation was sent to. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal window [with a flag](../../feature_flags.md). Disabled by default. > - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 14.8. - -FLAG: -On self-managed GitLab, by default the modal window feature is available. -To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) -named `invite_members_group_modal`. -On GitLab.com, this feature is available. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. + [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. When you add a group to a project, each user in the group gets access to the project. Each user's access is based on: @@ -68,6 +91,7 @@ Each user's access is based on: Prerequisite: - You must have the Maintainer or Owner role. +- Sharing the project with other groups must not be [prevented](../../group/index.md#prevent-a-project-from-being-shared-with-groups). To add groups to a project: @@ -98,11 +122,11 @@ To import users: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Members**. -1. On the **Invite member** tab, at the bottom of the panel, select **Import**. +1. Select **Import from a project**. 1. Select the project. You can view only the projects for which you're a maintainer. 1. Select **Import project members**. -A success message is displayed and the new members are now displayed in the list. +After the success message displays, refresh the page to view the new members. ## Inherited membership @@ -139,7 +163,7 @@ To remove a member from a project: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Project information > Members**. -1. Next to the project member you want to remove, select **Remove member** **{remove}**. +1. Next to the project member you want to remove, select **Remove member**. 1. Optional. In the confirmation box, select the **Also unassign this user from related issues and merge requests** checkbox. 1. To prevent leaks of sensitive information from private projects, verify the diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 4e3bae2dc30..02a9b76ce38 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -15,10 +15,14 @@ Groups are used primarily to [create collections of projects](../../group/index. take advantage of the fact that groups define collections of _users_, namely the group members. -## Sharing a project with a group of users +## Share a project with a group of users -NOTE: -In GitLab 13.11, you can [replace this form with a modal window](#share-a-project-modal-window). +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11 from a form to a modal + window [with a flag](../../feature_flags.md). Disabled by default. +> - Modal window [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) + in GitLab 14.8. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) in GitLab 14.9. + [Feature flag `invite_members_group_modal`](https://gitlab.com/gitlab-org/gitlab/-/issues/352526) removed. The primary mechanism to give a group of users, say 'Engineering', access to a project, say 'Project Acme', in GitLab is to make the 'Engineering' group the owner of 'Project @@ -28,9 +32,9 @@ This is where the group sharing feature can be of use. To share 'Project Acme' with the 'Engineering' group: 1. For 'Project Acme' use the left navigation menu to go to **Project information > Members**. -1. Select the **Invite group** tab. +1. Select **Invite a group**. 1. Add the 'Engineering' group with the maximum access level of your choice. -1. Optional. Select an expiration date. +1. Optional. Select an **Access expiration date**. 1. Select **Invite**. After sharing 'Project Acme' with 'Engineering': @@ -45,51 +49,19 @@ You can share a project only with: Administrators can share projects with any group in the system. -### Share a project modal window - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247208) in GitLab 13.11. -> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - Enabled on GitLab.com. -> - Recommended for production use. -> - Replaces the existing form with buttons to open a modal window. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-modal-window). - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -In GitLab 13.11, you can optionally replace the sharing form with a modal window. -To share a project after enabling this feature: - -1. Go to your project's page. -1. On the left sidebar, go to **Project information > Members**, and then select **Invite a group**. -1. Select a group, and select a **Max role**. -1. Optional. Select an **Access expiration date**. -1. Select **Invite**. - -### Enable or disable modal window **(FREE SELF)** - -The modal window for sharing a project is under development and is ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:invite_members_group_modal) -``` +## Maximum access level -To disable it: +In the example above, the maximum access level of 'Developer' for members from 'Engineering' means that users with higher access levels in 'Engineering' ('Maintainer' or 'Owner') only have 'Developer' access to 'Project Acme'. -```ruby -Feature.disable(:invite_members_group_modal) -``` +### Share a project with a subgroup -## Maximum access level +You can't share a project with a group that's an ancestor of a [subgroup](../../group/subgroups/index.md) the project is +in. That means you can only share down the hierarchy. For example, `group/subgroup01/project`: -In the example above, the maximum access level of 'Developer' for members from 'Engineering' means that users with higher access levels in 'Engineering' ('Maintainer' or 'Owner') only have 'Developer' access to 'Project Acme'. +- Can not be shared with `group`. +- Can be shared with `group/subgroup02` or `group/subgroup01/subgroup03`. -## Sharing public project with private group +## Share public project with private group When sharing a public project with a private group, owners and maintainers of the project see the name of the group in the `members` page. Owners also have the possibility to see members of the private group they don't have access to when mentioning them in the issue or merge request. diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index fa447ea35af..01772e59127 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -175,7 +175,7 @@ granting them push access: 1. [Create a new group](../../../group/index.md#create-a-group). 1. [Add the user to the group](../../../group/index.md#add-users-to-a-group), and select the Reporter role for the user. -1. [Share the project with your group](../../members/share_project_with_groups.md#sharing-a-project-with-a-group-of-users), +1. [Share the project with your group](../../members/share_project_with_groups.md#share-a-project-with-a-group-of-users), based on the Reporter role. 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 1e1c8ccb241..0a7fbc9ee95 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -140,9 +140,7 @@ To learn more, see [Coverage check approval rule](../../../../ci/pipelines/setti > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.4. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../../../administration/feature_flags.md), disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.5. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature per group, ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) named `group_merge_request_approval_settings_feature_flag`. On GitLab.com, this feature is available. +> - [Feature flag `group_merge_request_approval_settings_feature_flag`](https://gitlab.com/gitlab-org/gitlab/-/issues/343872) removed in GitLab 14.9. You can also enforce merge request approval settings: diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 15ba6e9de98..fb41ec3eff6 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -66,11 +66,8 @@ git cherry-pick -m 2 7a39eb0 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21268) in GitLab 13.11 behind a [feature flag](../../feature_flags.md), disabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/324154) in GitLab 14.0. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -You can use the GitLab UI to cherry-pick merge requests into a project, even if the -merge request is from a fork: +You can cherry-pick merge requests from the same project, or forks of the same +project, from the GitLab user interface: 1. In the merge request's secondary menu, click **Commits** to display the commit details page. 1. Click on the **Options** dropdown and select **Cherry-pick** to show the cherry-pick modal. diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index d735ce0ef91..10fc778d5ae 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -592,17 +592,17 @@ plugins: If your merge requests do not show any code quality changes when using a custom tool, ensure that the line property is an `integer`. -### Code Quality CI job with Code Climate plugins enabled fails with error "engine <plugin_name> ran for 900 seconds and was killed" +### Code Quality CI job with Code Climate plugins enabled fails with error -If you enabled any of the Code Climate plugins, and the Code Quality CI job fails with the error below, -it's likely the job takes longer than the default timeout of 900 seconds. +If you enabled any of the Code Climate plugins, and the Code Quality CI job fails with the error +below, it's likely the job takes longer than the default timeout of 900 seconds: ```shell error: (CC::CLI::Analyze::EngineFailure) engine pmd ran for 900 seconds and was killed Could not analyze code quality for the repository at /code ``` -To work around this problem, set `TIMEOUT_SECONDS` to a higher value in your `.gitlab.-ci.yml` file. +To work around this problem, set `TIMEOUT_SECONDS` to a higher value in your `.gitlab.-ci.yml` file. For example: diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index 0cc18d2117b..b9b65d759dc 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -69,6 +69,7 @@ GitLab creates a squash commit message with this template: > - [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. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/26303) `all_commits` variable in GitLab 14.9. Commit message templates support these variables: @@ -81,15 +82,20 @@ Commit message templates support these variables: | `%{description}` | Description of the merge request. | `Merge request description.`<br>`Can be multiline.` | | `%{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.` | +| `%{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>` | +| `%{approved_by}` | Line-separated list of the merge request approvers. | `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>` | +| `%{all_commits}` | Messages from all commits in the merge request. Limited to 100 most recent commits. Skips commit bodies exceeding 100KiB and merge commit messages. | `* Feature introduced` <br><br> `This commit implements feature` <br> `Changelog:added` <br><br> `* Bug fixed` <br><br> `* Documentation improved` <br><br>`This commit introduced better docs.`| 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. +After you edit a commit message on an open merge request, GitLab will +not automatically update the commit message again. +To restore the commit message to the project template, reload the page. + ## Related topics - [Squash and merge](squash_and_merge.md). diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md index 0014c1ba994..20e0d3a1f5b 100644 --- a/doc/user/project/merge_requests/commits.md +++ b/doc/user/project/merge_requests/commits.md @@ -31,15 +31,7 @@ To seamlessly navigate among commits in a merge request: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29274) in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `context_commits`. Enabled by default. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) in GitLab 14.8. - -WARNING: -This feature is in [beta](../../../policy/alpha-beta-support.md#beta-features) -and is [incomplete](https://gitlab.com/groups/gitlab-org/-/epics/1192). - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, -ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `context_commits`. -On GitLab.com, this feature is available. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) in GitLab 14.9. [Feature flag `context_commits`](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) removed. When reviewing a merge request, it helps to have more context about the changes made. That includes unchanged lines in unchanged files, and previous commits diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index 6dbbab316a0..df527ec6ebf 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -18,11 +18,11 @@ The following table shows what attributes will be present in the CSV. | Column | Description | |--------------------|--------------------------------------------------------------| +| Title | Merge request title | +| Description | Merge request description | | MR ID | MR `iid` | | URL | A link to the merge request on GitLab | -| Title | Merge request title | | State | Opened, Closed, Locked, or Merged | -| Description | Merge request description | | Source Branch | Source branch | | Target Branch | Target branch | | Source Project ID | ID of the source project | @@ -39,6 +39,10 @@ The following table shows what attributes will be present in the CSV. | Created At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | | Updated At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | +In GitLab 14.7 and earlier, the first two columns were `MR ID` and `URL`, +which [caused an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/34769) +when importing back into GitLab. + ## Limitations - Export merge requests to CSV is not available at the Group's merge request list. diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index cd65fe20e66..dc13b270f17 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -43,7 +43,7 @@ You can also rebase without running a CI/CD pipeline. 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 diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 8699a42dd5d..fd1751585d5 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -7,7 +7,7 @@ description: "Getting started with merge requests." # Getting started with merge requests **(FREE)** -A merge request (**MR**) is the basis of GitLab as a code +A merge request (**MR**) is the basis of GitLab as a tool for code collaboration and version control. When working in a Git-based platform, you can use branching @@ -161,7 +161,7 @@ enabled by default for all new merge requests, enable it in the [project's settings](../settings/index.md#merge-request-settings). This option is also visible in an existing merge request next to -the merge request button and can be selected or deselected before merging. +the merge request button and can be selected or cleared before merging. It is only visible to users with the Maintainer role in the source project. 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 differdeleted file mode 100644 index 3c845d277e4..00000000000 --- a/doc/user/project/merge_requests/img/ff_merge_rebase_v14_7.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/ff_merge_rebase_v14_9.png b/doc/user/project/merge_requests/img/ff_merge_rebase_v14_9.png Binary files differnew file mode 100644 index 00000000000..f4330549a57 --- /dev/null +++ b/doc/user/project/merge_requests/img/ff_merge_rebase_v14_9.png diff --git a/doc/user/project/merge_requests/img/merge_request_diff_v12_2.png b/doc/user/project/merge_requests/img/merge_request_diff_v12_2.png Binary files differdeleted file mode 100644 index 7e23b7db309..00000000000 --- a/doc/user/project/merge_requests/img/merge_request_diff_v12_2.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 cc4ad186771..7861e1e28fc 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -92,7 +92,7 @@ template that is included with GitLab. NOTE: For large scale k6 tests you need to ensure the GitLab Runner instance performing the actual test is able to handle running the test. Refer to [k6's guidance](https://k6.io/docs/testing-guides/running-large-tests#hardware-considerations) -for spec details. The [default shared GitLab.com runners](../../../ci/runners/build_cloud/linux_build_cloud.md) +for spec details. The [default shared GitLab.com runners](../../../ci/runners/saas/linux_saas_runner.md) likely have insufficient specs to handle most large k6 tests. This template runs the diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md deleted file mode 100644 index 611f37a949b..00000000000 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'conflicts.md' -remove_date: '2022-01-26' ---- - -This document was moved to [another location](conflicts.md). - -<!-- This redirect file can be deleted after <2022-01-26>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index f90296e9626..a1d6959b75e 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -65,7 +65,7 @@ To configure the default squashing behavior for all merge requests in your proje 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. + - **Allow**: Squashing is allowed, but cleared 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. diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index bd54eda42f5..d7177208a6e 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -52,7 +52,12 @@ from any job in any stage in the pipeline. The coverage displays for each line: Hovering over the coverage bar provides further information, such as the number of times the line was checked by tests. -Uploading a test coverage report does not enable [test coverage results in Merge Requests](../../../ci/pipelines/settings.md#add-test-coverage-results-to-a-merge-request-deprecated) or [code coverage history](../../../ci/pipelines/settings.md#view-code-coverage-history). You must configure these separately. +Uploading a test coverage report does not enable: + +- [Test coverage results in merge requests](../../../ci/pipelines/settings.md#merge-request-test-coverage-results). +- [Code coverage history](../../../ci/pipelines/settings.md#view-code-coverage-history). + +You must configure these separately. ### Limits diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 165131d50a4..3491346f7d9 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -37,7 +37,7 @@ for the most popular hosting services: - [Cloudflare](https://support.cloudflare.com/hc/en-us/articles/201720164-Creating-a-Cloudflare-account-and-adding-a-website) - [cPanel](https://documentation.cpanel.net/display/84Docs/Edit+DNS+Zone) - [DigitalOcean](https://docs.digitalocean.com/products/networking/dns/how-to/manage-records/) -- [DreamHost](https://help.dreamhost.com/hc/en-us/articles/215414867-How-do-I-add-custom-DNS-records-) +- [DreamHost](https://help.dreamhost.com/hc/en-us/articles/360035516812) - [Gandi](https://docs.gandi.net/en/domain_names/faq/dns_records.html) - [Go Daddy](https://www.godaddy.com/help/add-an-a-record-19238) - [Hostgator](https://www.hostgator.com/help/article/changing-dns-records) diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index ec66dce41f9..4d8919090a2 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -315,7 +315,7 @@ To enable this setting: 1. Tick the checkbox **Force HTTPS (requires valid certificates)**. If you use Cloudflare CDN in front of GitLab Pages, make sure to set the SSL connection setting to -`full` instead of `flexible`. For more details, see the [Cloudflare CDN directions](https://support.cloudflare.com/hc/en-us/articles/200170416-End-to-end-HTTPS-with-Cloudflare-Part-3-SSL-options#h_4e0d1a7c-eb71-4204-9e22-9d3ef9ef7fef). +`full` instead of `flexible`. For more details, see the [Cloudflare CDN directions](https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes#h_4e0d1a7c-eb71-4204-9e22-9d3ef9ef7fef). <!-- ## Troubleshooting diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index 75fc407ce3f..f09aea3b02a 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -79,6 +79,8 @@ If you get an error **Something went wrong while obtaining the Let's Encrypt cer 1. Make sure [your domain is verified](index.md#1-add-a-custom-domain-to-pages). 1. Go to step 1. +Another possible cause of this error is the `_redirects` file because the current implementation relies on an HTTP ACME challenge. If you redirect the `.acme-challenge/` endpoint Let's Encrypt cannot validate the domain. Make sure you don't have a wildcard (`*`) redirect either as that too breaks validation. The problem with wildcard redirects is tracked in the [Wildcard redirects break Let's Encrypt integration](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/649) issue. + ### Message "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later." hangs for more than an hour If you've enabled Let's Encrypt integration, but a certificate is absent after an hour and you see the message, "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later.", try to remove and add the domain for GitLab Pages again by following these steps: diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 32826346eab..5773dd1f2c0 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -34,7 +34,7 @@ Pages domains are `*.gitlab.io`. | Project pages owned by a subgroup | `subgroup/projectname` | `http(s)://groupname.example.io/subgroup/projectname`| WARNING: -There are some known [limitations](introduction.md#limitations) +There are some known [limitations](introduction.md#subdomains-of-subdomains) regarding namespaces served under the general domain name and HTTPS. Make sure to read that section. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 65e1579001b..e4bc58854ef 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -76,17 +76,21 @@ website.  -## Limitations +## Subdomains of subdomains -When using Pages under the general domain of a GitLab instance (`*.example.io`), -you _cannot_ use HTTPS with sub-subdomains. That means that if your -username or group name contains a dot, for example `foo.bar`, the domain -`https://foo.bar.example.io` does _not_ work. This is a limitation of the -[HTTP Over TLS protocol](https://tools.ietf.org/html/rfc2818#section-3.1). -HTTP pages continue to work provided you don't redirect HTTP to HTTPS. +When using Pages under the top-level domain of a GitLab instance (`*.example.io`), you can't use HTTPS with subdomains +of subdomains. If your namespace or group name contains a dot (for example, `foo.bar`) the domain +`https://foo.bar.example.io` does _not_ work. -GitLab Pages [does **not** support group websites for subgroups](../../group/subgroups/index.md#limitations). -You can only create the highest-level group website. +This limitation is because of the [HTTP Over TLS protocol](https://tools.ietf.org/html/rfc2818#section-3.1). HTTP pages +work as long as you don't redirect HTTP to HTTPS. + +## GitLab Pages and subgroups + +You must host your GitLab Pages website in a project. This project can belong to a [group](../../group/index.md) or +[subgroup](../../group/subgroups/index.md). For +[group websites](../../project/pages/getting_started_part_one.md#gitlab-pages-default-domain-names), the group must be +at the top level and not a subgroup. ## Specific configuration options for Pages diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md index 1f60aafe71b..7779f87b459 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -6,4 +6,6 @@ remove_date: '2022-03-14' This file was moved to [another location](custom_domains_ssl_tls_certification/lets_encrypt_integration.md). <!-- This redirect file can be deleted after <2022-03-14>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index beafbc86cb5..cdae1d2f837 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -163,6 +163,12 @@ Splats also match empty strings, so the previous rule redirects ### Rewrite all requests to a root `index.html` +NOTE: +If you are using [GitLab Pages integration with Let’s Encrypt](custom_domains_ssl_tls_certification/lets_encrypt_integration.md), +you must enable it before adding this rule. Otherwise, the redirection breaks the Let's Encrypt +integration. For more details, see +[GitLab Pages issue 649](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/649). + Single page applications (SPAs) often perform their own routing using client-side routes. For these applications, it's important that _all_ requests are rewritten to the root `index.html` so that the routing logic can be handled @@ -180,7 +186,7 @@ rule like: Use placeholders in rules to match portions of the requested URL and use these matches when rewriting or redirecting to a new URL. -A placehold is formatted as a `:` character followed by a string of letters +A placeholder is formatted as a `:` character followed by a string of letters (`[a-zA-Z]+`) in both the `from` and `to` paths: ```plaintext diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 8bb18905222..292530e6c9c 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -29,7 +29,7 @@ When a branch is protected, the default behavior enforces these restrictions on ### Set the default branch protection level Administrators can set a default branch protection level in the -[Admin Area](../admin_area/settings/visibility_and_access_controls.md#protect-default-branches). +[Admin Area](../project/repository/branches/default.md#instance-level-default-branch-protection). ## Configure a protected branch @@ -41,7 +41,7 @@ To protect a branch: 1. Go to your project and select **Settings > Repository**. 1. Expand **Protected branches**. -1. From the **Branch** dropdown menu, select the branch you want to protect. +1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to merge** list, select a role, or group that can merge into this branch. In GitLab Premium, you can also add users. 1. From the **Allowed to push** list, select a role, group, or user that can push to this branch. In GitLab Premium, you can also add users. 1. Select **Protect**. @@ -58,7 +58,7 @@ To protect multiple branches at the same time: 1. Go to your project and select **Settings > Repository**. 1. Expand **Protected branches**. -1. From the **Branch** dropdown menu, type the branch name and a wildcard. +1. From the **Branch** dropdown list, type the branch name and a wildcard. For example: | Wildcard protected branch | Matching branches | @@ -101,7 +101,7 @@ to a protected branch. This is compatible with workflows like the [GitLab workfl 1. Go to your project and select **Settings > Repository**. 1. Expand **Protected branches**. -1. From the **Branch** dropdown menu, select the branch you want to protect. +1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to merge** list, select **Developers + Maintainers**. 1. From the **Allowed to push** list, select **No one**. 1. Select **Protect**. @@ -112,7 +112,7 @@ You can allow everyone with write access to push to the protected branch. 1. Go to your project and select **Settings > Repository**. 1. Expand **Protected branches**. -1. From the **Branch** dropdown menu, select the branch you want to protect. +1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push** list, select **Developers + Maintainers**. 1. Select **Protect**. @@ -128,27 +128,28 @@ key must have at least read access to the project. Prerequisites: -- The deploy key must be [enabled for your project](deploy_keys/index.md#how-to-enable-deploy-keys). -- The deploy key must have [write access](deploy_keys/index.md#deploy-keys-permissions) to your project repository. +- The deploy key must be enabled for your project. A project deploy key is enabled by default when + it is created. However, a public deploy key must be + [granted](deploy_keys/index.md#grant-project-access-to-a-public-deploy-key) access to the + project. +- The deploy key must have [write access](deploy_keys/index.md#permissions) to your project + repository. To allow a deploy key to push to a protected branch: 1. Go to your project and select **Settings > Repository**. 1. Expand **Protected branches**. -1. From the **Branch** dropdown menu, select the branch you want to protect. +1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push** list, select the deploy key. 1. Select **Protect**. -Deploy keys are not available in the **Allowed to merge** dropdown. +Deploy keys are not available in the **Allowed to merge** dropdown list. ## Allow force push on a protected branch > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15611) in GitLab 13.10 behind a disabled feature flag. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323431) in GitLab 14.0. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - You can allow [force pushes](../../topics/git/git_rebase.md#force-push) to protected branches. @@ -156,7 +157,7 @@ To protect a new branch and enable force push: 1. Go to your project and select **Settings > Repository**. 1. Expand **Protected branches**. -1. From the **Branch** dropdown menu, select the branch you want to protect. +1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push** and **Allowed to merge** lists, select the settings you want. 1. To allow all users with push access to force push, turn on the **Allowed to force push** toggle. 1. To reject code pushes that change files listed in the `CODEOWNERS` file, turn on the @@ -169,12 +170,12 @@ To enable force pushes on branches that are already protected: 1. Expand **Protected branches**. 1. In the list of protected branches, next to the branch, turn on the **Allowed to force push** toggle. -When enabled, members who are can push to this branch can also force push. +Members who can push to this branch can now also force push. ## Require Code Owner approval on a protected branch **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in GitLab Premium 12.4. -> - [In](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5 and later, users and groups who can push to protected branches do not have to use a merge request to merge their feature branches. This means they can skip merge request approval rules. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in GitLab 12.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in GitLab 13.5, users and groups who can push to protected branches do not have to use a merge request to merge their feature branches. This means they can skip merge request approval rules. For a protected branch, you can require at least one approval by a [Code Owner](code_owners.md). @@ -182,7 +183,7 @@ To protect a new branch and enable Code Owner's approval: 1. Go to your project and select **Settings > Repository**. 1. Expand **Protected branches**. -1. From the **Branch** dropdown menu, select the branch you want to protect. +1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to push** and **Allowed to merge** lists, select the settings you want. 1. Turn on the **Require approval from code owners** toggle. 1. Select **Protect**. @@ -221,7 +222,7 @@ Users with at least the Maintainer role can manually delete protected branches by using the GitLab web interface: 1. Go to **Repository > Branches**. -1. Next to the branch you want to delete, select the **Delete** button (**{remove}**). +1. Next to the branch you want to delete, select **Delete** (**{remove}**). 1. On the confirmation dialog, type the branch name and select **Delete protected branch**. Protected branches can only be deleted by using GitLab either from the UI or API. diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 7d071a45d63..5df34fcdcc4 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -27,18 +27,18 @@ By default: ## Configuring protected tags -To protect a tag, you need to have at least the Maintainer role. +To protect a tag, you must have at least the Maintainer role. 1. Go to the project's **Settings > Repository**. -1. From the **Tag** dropdown menu, select the tag you want to protect or type and click **Create wildcard**. In the screenshot below, we chose to protect all tags matching `v*`: +1. From the **Tag** dropdown list, select the tag you want to protect or type and click **Create wildcard**. In the screenshot below, we chose to protect all tags matching `v*`:  -1. From the **Allowed to create** dropdown, select users with permission to create - matching tags, and click **Protect**: +1. From the **Allowed to create** dropdown list, select users with permission to create + matching tags, and select **Protect**: -  +  1. After done, the protected tag displays in the **Protected tags** list: @@ -61,7 +61,7 @@ Two different wildcards can potentially match the same tag. For example, In that case, if _any_ of these protected tags have a setting like **Allowed to create**, then `production-stable` also inherit this setting. -If you click on a protected tag's name, GitLab displays a list of +If you select a protected tag's name, GitLab displays a list of all matching tags:  diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 8070c37db78..ae42d90af06 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -7,11 +7,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab quick actions **(FREE)** -> - Introduced in [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26672): +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26672) in GitLab 12.1: > once an action is executed, an alert appears when a quick action is successfully applied. -> - Introduced in [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/16877): you can use +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16877) in GitLab 13.2: you can use > quick actions when updating the description of issues, epics, and merge requests. -> - Introduced in [GitLab 13.8](https://gitlab.com/gitlab-org/gitlab/-/issues/292393): when you enter +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292393) in GitLab 13.8: when you enter > `/` into a description or comment field, all available quick actions are displayed in a scrollable list. > - The rebase quick action was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49800) in GitLab 13.8. @@ -49,15 +49,15 @@ threads. Some quick actions might not be available to all subscription tiers. | Command | Issue | Merge request | Epic | Action | |:-------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `/add_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add one or more [CRM contacts](../crm/index.md) ([introduced in GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413)). | +| `/add_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add one or more [CRM contacts](../crm/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). | | `/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)). | +| `/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](https://gitlab.com/gitlab-org/gitlab/-/issues/7330) in GitLab 12.0). | +| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear [health status](issues/managing_issues.md#health-status) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). | | `/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. | @@ -68,47 +68,48 @@ threads. Some quick actions might not be available to all subscription tiers. | `/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. | +| `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue and mark as a duplicate of another issue. 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)). | +| `/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](https://gitlab.com/gitlab-org/gitlab/-/issues/213814) in GitLab 14.7). | | `/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)). | +| `/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](https://gitlab.com/gitlab-org/gitlab/-/issues/196795) in GitLab 13.1). | | `/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. Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. | -| `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). | +| `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data. | +| `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10556) in GitLab 12.1). | | `/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)) | +| `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296787) in GitLab 14.5). | +| `/page <policy name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Start escalations for the incident ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/79977) in GitLab 14.9). | +| `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in GitLab 13.0) | | `/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 [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove one or more [CRM contacts](../crm/index.md) ([introduced in GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413)). | +| `/remove_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](https://gitlab.com/gitlab-org/gitlab/-/issues/7330) in GitLab 12.0). | +| `/remove_contacts [contact:email1@example.com] [contact:email2@example.com]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove one or more [CRM contacts](../crm/index.md) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413) in GitLab 14.6). | | `/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_iteration` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove iteration ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196795) in GitLab 13.1). | | `/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_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10556) in GitLab 12.1). | | `/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)). | +| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609) in GitLab 12.4). | | `/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). | +| `/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](https://gitlab.com/gitlab-org/gitlab/-/issues/334045) in GitLab 14.2. | | `/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)). | +| `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8041) in GitLab 12.7). | | `/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) | +| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8103) in GitLab 14.3 | | `/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. | @@ -118,7 +119,7 @@ threads. Some quick actions might not be available to all subscription tiers. | `/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)). | +| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add Zoom meeting to this issue ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609) in GitLab 12.4). | ## Commit messages diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 8049ee9726d..26b36198bde 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -42,7 +42,7 @@ To view a list of releases: - On the left sidebar, select **Deployments > Releases**, or -- On the project's overview page, if at least one release exists, click the number of releases. +- On the project's overview page, if at least one release exists, select the number of releases.  @@ -52,10 +52,10 @@ To view a list of releases: ### Sort releases -To sort releases by **Released date** or **Created date**, select from the sort order dropdown. To +To sort releases by **Released date** or **Created date**, select from the sort order dropdown list. To switch between ascending or descending order, select **Sort order**. - + ## Create a release @@ -307,9 +307,9 @@ Read more about [Release permissions](#release-permissions). To edit the details of a release: 1. On the left sidebar, select **Deployments > Releases**. -1. In the top-right corner of the release you want to modify, click **Edit this release** (the pencil icon). +1. In the top-right corner of the release you want to modify, select **Edit this release** (the pencil icon). 1. On the **Edit Release** page, change the release's details. -1. Click **Save changes**. +1. Select **Save changes**. You can edit the release title, notes, associated milestones, and asset links. To change the release date use the @@ -330,16 +330,16 @@ the [Releases API](../../../api/releases/index.md#create-a-release). In the user interface, to associate milestones to a release: 1. On the left sidebar, select **Deployments > Releases**. -1. In the top-right corner of the release you want to modify, click **Edit this release** (the pencil icon). +1. In the top-right corner of the release you want to modify, select **Edit this release** (the pencil icon). 1. From the **Milestones** list, select each milestone you want to associate. You can select multiple milestones. -1. Click **Save changes**. +1. Select **Save changes**. On the **Deployments > Releases** page, the **Milestone** is listed in the top section, along with statistics about the issues in the milestones.  -Releases are also visible on the **Issues > Milestones** page, and when you click a milestone +Releases are also visible on the **Issues > Milestones** page, and when you select a milestone on this page. Here is an example of milestones with no releases, one release, and two releases, respectively. @@ -360,8 +360,8 @@ You can be notified by email when a new release is created for your project. To subscribe to notifications for releases: 1. On the left sidebar, select **Project information**. -1. Click **Notification setting** (the bell icon). -1. In the list, click **Custom**. +1. Select **Notification setting** (the bell icon). +1. In the list, select **Custom**. 1. Select the **New release** checkbox. 1. Close the dialog box to save. @@ -395,12 +395,12 @@ To set a deploy freeze window in the UI, complete these steps: 1. Sign in to GitLab as a user with the Maintainer role. 1. On the left sidebar, select **Project information**. -1. In the left navigation menu, navigate to **Settings > CI/CD**. +1. In the left navigation menu, go to **Settings > CI/CD**. 1. Scroll to **Deploy freezes**. -1. Click **Expand** to see the deploy freeze table. -1. Click **Add deploy freeze** to open the deploy freeze modal. +1. Select **Expand** to see the deploy freeze table. +1. Select **Add deploy freeze** to open the deploy freeze modal. 1. Enter the start time, end time, and time zone of the desired deploy freeze period. -1. Click **Add deploy freeze** in the modal. +1. Select **Add deploy freeze** in the modal. 1. After the deploy freeze is saved, you can edit it by selecting the edit button (**{pencil}**) and remove it by selecting the delete button (**{remove}**).  @@ -468,6 +468,28 @@ Each link as an asset has the following attributes: | `filepath` | The redirect link to the `url`. See [this section](#permanent-links-to-release-assets) for more information. | No | | `link_type` | The content kind of what users can download via `url`. See [this section](#link-types) for more information. | No | +##### Permanent link to latest release + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16821) in GitLab 14.9. + +Latest release page is accessible through a permanent URL. +GitLab will redirect to the latest release page URL when it is visited. + +The format of the URL is: + +```plaintext +https://host/namespace/project/-/releases/permalink/latest +``` + +We also support, suffix path carry forward on the redirect to the latest release. +Example if release `v14.8.0-ee` is the latest release and has a readable link `https://host/namespace/project/-/releases/v14.8.0-ee#release` then it can be addressed as `https://host/namespace/project/-/releases/permalink/latest#release`. + +Refer [permanent links to latest release assets](#permanent-links-to-latest-release-assets) section to understand more about the suffix path carry forward usage. + +###### Sorting preferences + +By default, GitLab fetches the release using `released_at` time. The use of the query parameter `?order_by=released_at` is optional, and support for `?order_by=semver` is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352945). + ##### Permanent links to release assets > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27300) in GitLab 12.9. @@ -475,7 +497,7 @@ Each link as an asset has the following attributes: The assets associated with a release are accessible through a permanent URL. GitLab always redirects this URL to the actual asset location, so even if the assets move to a different location, you can continue -to use the same URL. This is defined during [link creation](../../../api/releases/links.md#create-a-link) or [updating](../../../api/releases/links.md#update-a-link). +to use the same URL. This is defined during [link creation](../../../api/releases/links.md#create-a-link) or [updating](../../../api/releases/links.md#update-a-link) using the `filepath` API attribute. The format of the URL is: @@ -503,6 +525,36 @@ https://gitlab.com/gitlab-org/gitlab-runner/-/releases/v11.9.0-rc2/downloads/bin The physical location of the asset can change at any time and the direct link remains unchanged. +##### Permanent links to latest release assets + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16821) in GitLab 14.9. + +The `filepath` from [permanent links to release assets](#permanent-links-to-release-assets) can be used in combination with [permanent link to the latest release](#permanent-link-to-latest-release). It is useful when we want to link a permanant URL to download an asset from the *latest release*. + +The format of the URL is: + +```plaintext +https://host/namespace/project/-/releases/permalink/latest/downloads/:filepath +``` + +If you have an asset with [`filepath`](../../../api/releases/links.md#create-a-link) for the `v11.9.0-rc2` latest release in the `gitlab-org` +namespace and `gitlab-runner` project on `gitlab.com`, for example: + +```json +{ + "name": "linux amd64", + "filepath": "/binaries/gitlab-runner-linux-amd64", + "url": "https://gitlab-runner-downloads.s3.amazonaws.com/v11.9.0-rc2/binaries/gitlab-runner-linux-amd64", + "link_type": "other" +} +``` + +This asset has a direct link of: + +```plaintext +https://gitlab.com/gitlab-org/gitlab-runner/-/releases/permalink/latest/downloads/binaries/gitlab-runner-linux-amd64 +``` + ##### Link Types > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207257) in GitLab 13.1. @@ -611,7 +663,7 @@ On [GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/releases), you can view t  The totals are displayed on [shields](https://shields.io/) and are generated per release by -[a Rake task in the `www-gitlab-com` repo](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/lib/tasks/update_gitlab_project_releases_page.rake). +[a Rake task in the `www-gitlab-com` repository](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/lib/tasks/update_gitlab_project_releases_page.rake). | Item | Formula | | ------ | ------ | @@ -634,7 +686,7 @@ This data is saved in a JSON file and called *release evidence*. The feature includes test artifacts and linked milestones to facilitate internal processes, like external audits. -To access the release evidence, on the Releases page, click the link to the JSON file that's listed +To access the release evidence, on the Releases page, select the link to the JSON file that's listed under the **Evidence collection** heading. You can also [use the API](../../../api/releases/index.md#collect-release-evidence) to @@ -720,7 +772,7 @@ When you create a release, if [job artifacts](../../../ci/yaml/index.md#artifact Although job artifacts normally expire, artifacts included in release evidence do not expire. -To enable job artifact collection you need to specify both: +To enable job artifact collection you must specify both: 1. [`artifacts:paths`](../../../ci/yaml/index.md#artifactspaths) 1. [`artifacts:reports`](../../../ci/yaml/index.md#artifactsreports) diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index d706a0e8f8a..f9fd1a48b9a 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -26,7 +26,7 @@ using the GitLab default only if no customizations are set: 1. A [project-specific](#change-the-default-branch-name-for-a-project) custom default branch name. 1. A [subgroup-level](#group-level-custom-initial-branch-name) custom default branch name. 1. A [group-level](#group-level-custom-initial-branch-name) custom default branch name. -1. An [instance-level](#instance-level-custom-initial-branch-name) custom default branch name. **(FREE SELF)** +1. An [instance-level](#instance-level-custom-initial-branch-name) custom default branch name. 1. If no custom default branch name is set at any level, GitLab defaults to: - `main`: Projects created with GitLab 14.0 or later. - `master`: Projects created before GitLab 14.0. @@ -81,13 +81,83 @@ overrides it. Users with at least the Owner role of groups and subgroups can configure the default branch name for a group: 1. Go to the group **Settings > Repository**. -1. Expand **Default initial branch name**. +1. Expand **Default branch**. 1. Change the default initial branch to a custom name of your choice. 1. Select **Save changes**. Projects created in this group after you change the setting use the custom branch name, unless a subgroup configuration overrides it. +## Protect initial default branches **(FREE SELF)** + +GitLab administrators and group owners can define [branch protections](../../../project/protected_branches.md) +to apply to every repository's [default branch](#default-branch) +at the [instance level](#instance-level-default-branch-protection) and +[group level](#group-level-default-branch-protection) with one of the following options: + +- **Not protected** - Both developers and maintainers can push new commits + and force push. +- **Protected against pushes** - Developers cannot push new commits, but are + allowed to accept merge requests to the branch. Maintainers can push to the branch. +- **Partially protected** - Both developers and maintainers can push new commits, + but cannot force push. +- **Fully protected** - Developers cannot push new commits, but maintainers can. + No one can force push. + +### Instance-level default branch protection **(FREE SELF)** + +This setting applies only to each repository's default branch. To protect other branches, +you must either: + +- Configure [branch protection in the repository](../../../project/protected_branches.md). +- Configure [branch protection for groups](../../../group/index.md#change-the-default-branch-protection-of-a-group). + +Administrators of self-managed instances can customize the initial default branch protection for projects hosted on that instance. Individual +groups and subgroups can override this instance-wide setting for their projects. + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Default branch**. +1. Select [**Initial default branch protection**](#protect-initial-default-branches). +1. To allow group owners to override the instance's default branch protection, select + [**Allow owners to manage default branch protection per group**](#prevent-overrides-of-default-branch-protection). +1. Select **Save changes**. + +#### Prevent overrides of default branch protection **(PREMIUM SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211944) in GitLab 13.0. + +Instance-level protections for default branches +can be overridden on a per-group basis by the group's owner. In +[GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can +disable this privilege for group owners, enforcing the instance-level protection rule: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Repository**. +1. Expand the **Default branch** section. +1. Clear the **Allow owners to manage default branch protection per group** checkbox. +1. Select **Save changes**. + +NOTE: +GitLab administrators can still update the default branch protection of a group. + +### Group-level default branch protection **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7583) in GitLab 12.9. +> - [Settings moved and renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/340403) in GitLab 14.9. + +Instance-level protections for [default branch](#default-branch) +can be overridden on a per-group basis by the group's owner. In +[GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can +[enforce protection of initial default branches](#prevent-overrides-of-default-branch-protection) +which locks this setting for group owners. + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Default branch**. +1. Select [**Initial default branch protection**](#protect-initial-default-branches). +1. Select **Save changes**. + ## Update the default branch name in your repository WARNING: diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index b085372c8f2..ddeef65a6b5 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -18,36 +18,24 @@ submit them through a merge request to the repository you don't have access to. ## Creating a fork -To fork an existing project in GitLab: - -1. On the project's home page, in the top right, click **{fork}** **Fork**. - -  - -1. Select the project to fork to: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15013) a new form in GitLab 13.11 [with a flag](../../../user/feature_flags.md) named `fork_project_form`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77181) in GitLab 14.8. Feature flag `fork_project_form` removed. - - Recommended method. Below **Select a namespace to fork the project**, identify - the project you want to fork to, and click **Select**. Only namespaces where you have - at least the Developer role for are shown. - -  - - - Experimental method. If your GitLab administrator has - enabled the experimental fork project form, read - [Create a fork with the fork project form](#create-a-fork-with-the-fork-project-form). - Only namespaces where you have at least the Developer role for are shown. - - NOTE: - The project path must be unique in the namespace. +To fork an existing project in GitLab: -GitLab creates your fork, and redirects you to the project page for your new fork. -The permissions you have in the namespace are your permissions in the fork. +1. On the project's home page, in the top right, select **{fork}** **Fork**: +  +1. Optional. Edit the **Project name**. +1. For **Project URL**, select the [namespace](../../group/index.md#namespaces) + your fork should belong to. +1. Add a **Project slug**. This value becomes part of the URL to your fork. + It must be unique in the namespace. +1. Optional. Add a **Project description**. +1. Select the **Visibility level** for your fork. For more information about + visibility levels, read [Project and group visibility](../../../public_access/public_access.md). +1. Select **Fork project**. -WARNING: -When a public project with the repository feature set to **Members Only** -is forked, the repository is public in the fork. The owner -of the fork must manually change the visibility. Issue -[#36662](https://gitlab.com/gitlab-org/gitlab/-/issues/36662) exists for this issue. +GitLab creates your fork, and redirects you to the new fork's page. ## Repository mirroring @@ -59,7 +47,7 @@ Without mirroring, to work locally you must use `git pull` to update your local with the upstream project, then push the changes back to your fork to update it. WARNING: -With mirroring, before approving a merge request, you are asked to sync. Because of this, automating it is recommended. +With mirroring, before approving a merge request, you are asked to sync. We recommend you automate it. Read more about [How to keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/). @@ -75,30 +63,9 @@ When creating a merge request, if the forked project's visibility is more restri  Then you can add labels, a milestone, and assign the merge request to someone who can review -your changes. Then click **Submit merge request** to conclude the process. When successfully merged, your +your changes. Then select **Submit merge request** to conclude the process. When successfully merged, your changes are added to the repository and branch you're merging into. ## Removing a fork relationship You can unlink your fork from its upstream project in the [advanced settings](../settings/index.md#removing-a-fork-relationship). - -## Create a fork with the fork project form **(FREE SELF)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15013) in GitLab 13.11 [with a flag](../../../administration/feature_flags.md) named `fork_project_form`. Disabled by default. -> - [Enabled on self-managed and GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64967) in GitLab 13.8. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `fork_project_form`. -On GitLab.com, this feature is available. - -This version of the fork project form is experimental: - - - -To use it, follow the instructions at [Creating a fork](#creating-a-fork) and provide: - -- The project name. -- The project URL. -- The project slug. -- Optional. The project description. -- The visibility level for your fork. diff --git a/doc/user/project/repository/gpg_signed_commits/img/profile_settings_gpg_keys_paste_pub.png b/doc/user/project/repository/gpg_signed_commits/img/profile_settings_gpg_keys_paste_pub.png Binary files differdeleted file mode 100644 index 6e2ff33eebb..00000000000 --- a/doc/user/project/repository/gpg_signed_commits/img/profile_settings_gpg_keys_paste_pub.png +++ /dev/null diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index f5cea8a8075..00998c9a227 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -6,129 +6,96 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Signing commits with GPG **(FREE)** -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 -GPG key. +You can sign the commits you make in a GitLab repository with a +GPG ([GNU Privacy Guard](https://gnupg.org/)) key. When you add a cryptographic +signature to your commit, you provide extra assurance that a commit +originated from you, rather than an impersonator. If GitLab can verify a commit +author's identity with a public GPG key, the commit is marked **Verified** in the +GitLab UI. You can then configure [push rules](../push_rules.md#enabling-push-rules) +for your project to reject individual commits not signed with GPG, or reject all +commits from unverified users. NOTE: -The term GPG is used for all OpenPGP/PGP/GPG related material and +GitLab uses the term GPG for all OpenPGP, PGP, and GPG-related material and implementations. -To view a user's public GPG key, you can: - -- Go to `https://gitlab.example.com/<username>.gpg`. -- Select **View public GPG keys** (**{key}**) in the top right of the user's profile. - -GPG verified tags are not supported yet. - -See the [further reading](#further-reading) section for more details on GPG. - -## How GitLab handles GPG - -GitLab uses its own keyring to verify the GPG signature. It does not access any -public key server. - -For a commit to be verified by GitLab: +For GitLab to consider a commit verified: - The committer must have a GPG public/private key pair. -- The committer's public key must have been uploaded to their GitLab - account. -- One of the emails in the GPG key must match a **verified** email address - used by the committer in GitLab. This address will be part of the public key. - If you want to keep this address private, use the automatically generated +- The committer's public key must be uploaded to their GitLab account. +- One of the email addresses in the GPG public key must match a **verified** email address + used by the committer in GitLab. To keep this address private, use the automatically generated [private commit email address](../../../profile/index.md#use-an-automatically-generated-private-commit-email) GitLab provides in your profile. - The committer's email address must match the verified email address from the GPG key. -## Generating a GPG key - -If you don't already have a GPG key, the following steps can help you get -started: - -1. [Install GPG](https://www.gnupg.org/download/index.html) for your operating system. - If your operating system has `gpg2` installed, replace `gpg` with `gpg2` in - the following commands. -1. Generate the private/public key pair with the command appropriate for your version - of `gpg`. This command spawns a series of questions: - - ```shell - # Use this command for the default version of gpg, including - # Gpg4win on Windows, and most macOS versions: - gpg --gen-key +GitLab uses its own keyring to verify the GPG signature. It does not access any +public key server. - # Use this command for versions of GPG later than 2.1.17: - gpg --full-gen-key - ``` +GPG verified tags are not supported. -1. The first question is which algorithm can be used. Select the kind you want - or press <kbd>Enter</kbd> to choose the default (RSA and RSA): +For more details about GPG, refer to the [related topics list](#related-topics). - ```plaintext - Please select what kind of key you want: - (1) RSA and RSA (default) - (2) DSA and Elgamal - (3) DSA (sign only) - (4) RSA (sign only) - Your selection? 1 - ``` +## View a user's public GPG key -1. The next question is key length. We recommend you choose `4096`: +To view a user's public GPG key, you can either: - ```plaintext - RSA keys may be between 1024 and 4096 bits long. - What keysize do you want? (2048) 4096 - Requested keysize is 4096 bits - ``` +- Go to `https://gitlab.example.com/<USERNAME>.gpg`. GitLab displays the GPG key, + if the user has configured one, or a blank page for users without a configured GPG key. +- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the top right + of the user's profile, select **View public GPG keys** (**{key}**). -1. Specify the validity period of your key. This is something - subjective, and you can use the default value, which is to never expire: +## Configure commit signing - ```plaintext - Please specify how long the key should be valid. - 0 = key does not expire - <n> = key expires in n days - <n>w = key expires in n weeks - <n>m = key expires in n months - <n>y = key expires in n years - Key is valid for? (0) 0 - Key does not expire at all - ``` +To sign commits, you must configure both your local machine and your GitLab account: -1. Confirm that the answers you gave were correct by typing `y`: +1. [Create a GPG key](#create-a-gpg-key). +1. [Add a GPG key to your account](#add-a-gpg-key-to-your-account). +1. [Associate your GPG key with Git](#associate-your-gpg-key-with-git). +1. [Sign your Git commits](#sign-your-git-commits). - ```plaintext - Is this correct? (y/N) y - ``` +### Create a GPG key -1. Enter your real name, the email address to be associated with this key - (should match a verified email address you use in GitLab) and an optional - comment (press <kbd>Enter</kbd> to skip): +If you don't already have a GPG key, create one: - ```plaintext - GnuPG needs to construct a user ID to identify your key. +1. [Install GPG](https://www.gnupg.org/download/) for your operating system. + If your operating system has `gpg2` installed, replace `gpg` with `gpg2` in + the commands on this page. +1. To generate your key pair, run the command appropriate for your version of `gpg`: - Real name: Mr. Robot - Email address: <your_email> - Comment: - You selected this USER-ID: - "Mr. Robot <your_email>" + ```shell + # Use this command for the default version of GPG, including + # Gpg4win on Windows, and most macOS versions: + gpg --gen-key - Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O + # Use this command for versions of GPG later than 2.1.17: + gpg --full-gen-key ``` -1. Pick a strong password when asked and type it twice to confirm. -1. Use the following command to list the private GPG key you just created: +1. Select the algorithm your key should use, or press <kbd>Enter</kbd> to select + the default option, `RSA and RSA`. +1. Select the key length, in bits. GitLab recommends 4096-bit keys. +1. Specify the validity period of your key. This value is subjective, and the + default value is no expiration. +1. To confirm your answers, enter `y`. +1. Enter your name. +1. Enter your email address. It must match a + [verified email address](../../../profile/index.md#change-the-email-displayed-on-your-commits) + in your GitLab account. +1. Optional. Enter a comment to display in parentheses after your name. +1. GPG displays the information you've entered so far. Edit the information or press + <kbd>O</kbd> (for `Okay`) to continue. +1. Enter a strong password, then enter it again to confirm it. +1. To list your private GPG key, run this command, replacing + `<EMAIL>` with the email address you used when you generated the key: ```shell - gpg --list-secret-keys --keyid-format LONG <your_email> + gpg --list-secret-keys --keyid-format LONG <EMAIL> ``` - Replace `<your_email>` with the email address you entered above. - -1. Copy the GPG key ID that starts with `sec`. In the following example, that's - `30F2B65B9246B6CA`: +1. In the output, identify the `sec` line, and copy the GPG key ID. It begins after + the `/` character. In this example, the key ID is `30F2B65B9246B6CA`: ```plaintext sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] @@ -137,49 +104,46 @@ started: ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] ``` -1. Export the public key of that ID (replace your key ID from the previous step): +1. To show the associated public key, run this command, replacing `<ID>` with the + GPG key ID from the previous step: ```shell - gpg --armor --export 30F2B65B9246B6CA + gpg --armor --export <ID> ``` -1. Finally, copy the public key and [add it in your user settings](#adding-a-gpg-key-to-your-account) +1. Copy the public key, including the `BEGIN PGP PUBLIC KEY BLOCK` and + `END PGP PUBLIC KEY BLOCK` lines. You need this key in the next step. -## Adding a GPG key to your account +### Add a GPG key to your account -NOTE: -After you add a key, you cannot edit it, only remove it. In case the paste -didn't work, you have to remove the offending key and re-add it. - -You can add a GPG key in your user settings: +To add a GPG key to your user settings: +1. Sign in to GitLab. 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. On the left sidebar, select **GPG Keys**. -1. Paste your _public_ key in the **Key** text box. - -  - -1. Select **Add key** to add it to GitLab. You can see the key's fingerprint, the corresponding - email address, and creation date. +1. On the left sidebar, select **GPG Keys** (**{key}**). +1. In **Key**, paste your _public_ key. +1. To add the key to your account, select **Add key**. GitLab shows the key's + fingerprint, email address, and creation date:  -## Associating your GPG key with Git +After you add a key, you cannot edit it. Instead, remove the offending key and re-add it. -After you have [created your GPG key](#generating-a-gpg-key) and [added it to -your account](#adding-a-gpg-key-to-your-account), it's time to tell Git which -key to use. +### Associate your GPG key with Git -1. Use the following command to list the private GPG key you just created: +After you [create your GPG key](#create-a-gpg-key) and +[add it to your account](#add-a-gpg-key-to-your-account), you must configure Git +to use this key: + +1. Run this command to list the private GPG key you just created, + replacing `<EMAIL>` with the email address for your key: ```shell - gpg --list-secret-keys --keyid-format LONG <your_email> + gpg --list-secret-keys --keyid-format LONG <EMAIL> ``` - Replace `<your_email>` with the email address you entered above. - -1. Copy the GPG key ID that starts with `sec`. In the following example, that's +1. Copy the GPG private key ID that starts with `sec`. In this example, the private key ID is `30F2B65B9246B6CA`: ```plaintext @@ -189,114 +153,103 @@ key to use. ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] ``` -1. Tell Git to use that key to sign the commits: +1. Run this command to configure Git to sign your commits with your key, + replacing `<KEY ID>` with your GPG key ID: ```shell - git config --global user.signingkey 30F2B65B9246B6CA + git config --global user.signingkey <KEY ID> ``` - Replace `30F2B65B9246B6CA` with your GPG key ID. - -1. Optional. If Git is using `gpg` and you get errors like `secret key not available` - or `gpg: signing failed: secret key not available`, run the following command to - change to `gpg2`: +1. Optional. If Git uses `gpg` and you get errors like `secret key not available` + or `gpg: signing failed: secret key not available`, run this command to + use `gpg2` instead: ```shell git config --global gpg.program gpg2 ``` -## Signing commits +### Sign your Git commits -After you have [created your GPG key](#generating-a-gpg-key) and [added it to -your account](#adding-a-gpg-key-to-your-account), you can start signing your -commits: +After you [add your public key to your account](#add-a-gpg-key-to-your-account), +you can sign individual commits manually, or configure Git to default to signed commits: -1. Commit like you used to, the only difference is the addition of the `-S` flag: +- Sign individual Git commits manually: + 1. Add `-S` flag to any commit you want to sign: - ```shell - git commit -S -m "My commit msg" - ``` + ```shell + git commit -S -m "My commit message" + ``` -1. Enter the passphrase of your GPG key when asked. -1. Push to GitLab and check that your commits [are verified](#verifying-commits). + 1. Enter the passphrase of your GPG key when asked. + 1. Push to GitLab and check that your commits [are verified](#verify-commits). +- Sign all Git commits by default by running this command: -If you don't want to type the `-S` flag every time you commit, you can tell Git -to sign your commits automatically: + ```shell + git config --global commit.gpgsign true + ``` -```shell -git config --global commit.gpgsign true -``` +## Verify commits -## Verifying commits +You can review commits for a merge request, or for an entire project: -1. Within a project or [merge request](../../merge_requests/index.md), navigate to - the **Commits** tab. Signed commits show a badge containing either - **Verified** or **Unverified**, depending on the verification status of the GPG - signature. +1. To review commits for a project: + 1. On the top bar, select **Menu > Projects** and find your project. + 1. On the left sidebar, select **Repository > Commits**. +1. To review commits for a merge request: + 1. On the top bar, select **Menu > Projects** and find your project. + 1. On the left sidebar, select **Merge requests**, then select your merge request. + 1. Select **Commits**. +1. Identify the commit you want to review. Signed commits show either a **Verified** + or **Unverified** badge, depending on the verification status of the GPG + signature. Unsigned commits do not display a badge:  -1. By clicking on the GPG badge, details of the signature are displayed. +1. To display the signature details for a commit, select the GPG badge:  -  +  -## Revoking a GPG key +## Revoke a GPG key -Revoking a key **unverifies** already signed commits. Commits that were -verified by using this key changes to an unverified state. Future commits -stay unverified after you revoke this key. This action should be used -in case your key has been compromised. +If a GPG key becomes compromised, revoke it. Revoking a key changes both future and past commits: + +- Past commits signed by this key are marked as unverified. +- Future commits signed by this key are marked as unverified. To revoke a GPG key: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. On the left sidebar, select **GPG Keys**. +1. On the left sidebar, select **GPG Keys** (**{key}**). 1. Select **Revoke** next to the GPG key you want to delete. -## Removing a GPG key +## Remove a GPG key + +When you remove a GPG key from your GitLab account: -Removing a key **does not unverify** already signed commits. Commits that were -verified by using this key stay verified. Only unpushed commits stay -unverified after you remove this key. To unverify already signed commits, you need -to [revoke the associated GPG key](#revoking-a-gpg-key) from your account. +- Previous commits signed with this key remain verified. +- Future commits (including any commits created but not yet pushed) that attempt + to use this key are unverified. To remove a GPG key from your account: 1. In the top-right corner, select your avatar. 1. Select **Edit profile**. -1. On the left sidebar, select **GPG Keys**. -1. Select the trash icon (**{remove}**) next to the GPG key you want to delete. - -## Rejecting commits that are not signed **(PREMIUM)** - -You can configure your project to reject commits that aren't GPG-signed -via [push rules](../push_rules.md). - -## GPG signing API - -Learn how to [get the GPG signature from a commit via API](../../../../api/commits.md#get-gpg-signature-of-a-commit). - -## Further reading - -For more details about GPG, see: - -- [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) -- [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys) -- [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices) -- [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced) -- [Review existing GPG keys in your instance](../../../admin_area/credentials_inventory.md#review-existing-gpg-keys) - -<!-- ## 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. --> +1. On the left sidebar, select **GPG Keys** (**{key}**). +1. Select **Remove** (**{remove}**) next to the GPG key you want to delete. + +If you must unverify both future and past commits, +[revoke the associated GPG key](#revoke-a-gpg-key) instead. + +## Related topics + +- [Sign commits and tags with X.509 certificates](../x509_signed_commits/index.md) +- [Commits API](../../../../api/commits.md) +- GPG resources: + - [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) + - [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys) + - [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices) + - [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced) + - [Review existing GPG keys in your instance](../../../admin_area/credentials_inventory.md#review-existing-gpg-keys) diff --git a/doc/user/project/repository/img/fork_form_v13_10.png b/doc/user/project/repository/img/fork_form_v13_10.png Binary files differdeleted file mode 100644 index 00c2f89a844..00000000000 --- a/doc/user/project/repository/img/fork_form_v13_10.png +++ /dev/null diff --git a/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_10.png b/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_10.png Binary files differdeleted file mode 100644 index 74f65cb663d..00000000000 --- a/doc/user/project/repository/img/forking_workflow_choose_namespace_v13_10.png +++ /dev/null diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 5646f478d9f..cd0c6679d8d 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -25,11 +25,8 @@ GitLab. ## Cleaner diffs -> [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 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. +> - [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. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75500) in GitLab 14.9. Feature flag `jupyter_clean_diffs` removed. 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 cddbc6fd891..c9fa30e39a8 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -96,9 +96,7 @@ Prerequisite: 1. Select **Update now** (**{retry}**):  -## Mirror only protected branches **(PREMIUM)** - -> Moved to GitLab Premium in 13.9. +## Mirror only protected branches You can choose to mirror only the [protected branches](../../protected_branches.md) in the mirroring project, diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index 221616bd41c..ebc4430ac53 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -76,7 +76,7 @@ through the [remote mirrors API](../../../../api/remote_mirrors.md). 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) +1. Create a [GitHub personal access token](https://docs.github.com/en/authentication/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_access_token>@github.com/<github_group>/<github_project>.git`. 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 37b16d90d93..83fafd409e8 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 @@ -13,8 +13,6 @@ Git repositories become larger over time. When large files are added to a Git re - They take up a large amount of storage space on the server. - Git repository storage limits [can be reached](#storage-limits). -Such problems can be detected with [git-sizer](https://github.com/github/git-sizer#getting-started). - Rewriting a repository can remove unwanted history to make the repository smaller. We **recommend [`git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/README.md)** over [`git filter-branch`](https://git-scm.com/docs/git-filter-branch) and @@ -40,7 +38,8 @@ These refs are not automatically downloaded and hidden refs are not advertised, To purge files from a GitLab repository: -1. [Install `git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md) +1. Install either [`git filter-repo`](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md) or + [`git-sizer`](https://github.com/github/git-sizer#getting-started) using a supported package manager or from source. 1. Generate a fresh [export from the @@ -63,31 +62,43 @@ To purge files from a GitLab repository: git clone --bare --mirror /path/to/project.bundle ``` -1. Navigate to the `project.git` directory: +1. Go to the `project.git` directory: ```shell cd project.git ``` -1. Using `git filter-repo`, purge any files from the history of your repository. Because we are +1. Using either `git filter-repo` or `git-sizer`, analyze your repository + and review the results to determine which items you want to purge: + + ```shell + # Using git filter-repo + git filter-repo --analyze + head .git/filter-repo/analysis/*-{all,deleted}-sizes.txt + + # Using git-sizer + git-sizer + ``` + +1. Proceed to purging any files from the history of your repository. Because we are trying to remove internal refs, we rely on the `commit-map` produced by each run to tell us which internal refs to remove. NOTE: - `git filter-repo` creates a new `commit-map` file every run, and overwrite the `commit-map` from + `git filter-repo` creates a new `commit-map` file every run, and overwrites the `commit-map` from the previous run. You need this file from **every** run. Do the next step every time you run `git filter-repo`. - To purge all files larger than 10M, the `--strip-blobs-bigger-than` option can be used: + To purge specific files, the `--path` and `--invert-paths` options can be combined: ```shell - git filter-repo --strip-blobs-bigger-than 10M + git filter-repo --path path/to/file.ext --invert-paths ``` - To purge specific large files by path, the `--path` and `--invert-paths` options can be combined. + To generally purge all files larger than 10M, the `--strip-blobs-bigger-than` option can be used: ```shell - git filter-repo --path path/to/big/file.m4v --invert-paths + git filter-repo --strip-blobs-bigger-than 10M ``` See the @@ -148,7 +159,7 @@ operations before continuing. To clean up a repository: 1. Go to the project for the repository. -1. Navigate to **Settings > Repository**. +1. Go to **Settings > Repository**. 1. Upload a list of objects. For example, a `commit-map` file created by `git filter-repo` which is located in the `filter-repo` directory. @@ -158,7 +169,7 @@ To clean up a repository: split -l 3000 filter-repo/commit-map filter-repo/commit-map- ``` -1. Click **Start cleanup**. +1. Select **Start cleanup**. This: @@ -229,7 +240,7 @@ Until `git gc` runs on the GitLab side, the "removed" commits and blobs still ex must be able to push the rewritten history to GitLab, which may be impossible if you've already exceeded the maximum size limit. -In order to lift these restrictions, the administrator of the self-managed GitLab instance must +To lift these restrictions, the Administrator of the self-managed GitLab instance must increase the limit on the particular project that exceeded it. Therefore, it's always better to proactively stay underneath the limit. If you hit the limit, and can't have it temporarily increased, your only option is to: diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 27ef14d31c5..c9cddad1a91 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -20,15 +20,15 @@ The main difference is the way GitLab determines whether or not the developer's (A trust store is a repository of trusted security certificates.) Combined with any required intermediate certificates in the signature, the developer's certificate can be chained back to a trusted root certificate. -- For GPG, developers [add their GPG key](../gpg_signed_commits/index.md#adding-a-gpg-key-to-your-account) +- For GPG, developers [add their GPG key](../gpg_signed_commits/index.md#add-a-gpg-key-to-your-account) to their account. GitLab uses its own certificate store and therefore defines the -[trust chain](https://www.ssl.com/faqs/what-is-a-chain-of-trust/). +[trust chain](https://www.ssl.com/faqs/what-is-a-certificate-authority/). For a commit or tag to be *verified* by GitLab: - The signing certificate email must match a verified email address in GitLab. -- The GitLab instance must be able to establish a full [trust chain](https://www.ssl.com/faqs/what-is-a-chain-of-trust/) +- The GitLab instance must be able to establish a full trust chain from the certificate in the signature to a trusted certificate in the GitLab certificate store. This chain may include intermediate certificates supplied in the signature. You may need to add certificates, such as Certificate Authority root certificates, diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index d549a22910a..6abe9c08d28 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -10,8 +10,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w NOTE: In 14.4, Requirements was moved under **Issues**. -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2703) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. -> - The ability to add and edit a requirement's long description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/224622) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.5. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2703) in GitLab 12.10. +> - The ability to add and edit a requirement's long description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/224622) in GitLab 13.5. > - [Moved under Issues](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/70748) in 14.4 With requirements, you can set criteria to check your products against. They can be based on users, @@ -64,7 +64,7 @@ next to the requirement title. ## Edit a requirement -> The ability to mark a requirement as Satisfied [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218607) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.5. +> The ability to mark a requirement as Satisfied [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218607) in GitLab 13.5. You can edit a requirement from the requirements list page. @@ -108,7 +108,7 @@ As soon as a requirement is reopened, it no longer appears in the **Archived** t ## Search for a requirement -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212543) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212543) in GitLab 13.1. > - Searching by status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/224614) in GitLab 13.10. You can search for a requirement from the requirements list page based on the following criteria: @@ -131,8 +131,8 @@ You can also sort the requirements list by: ## Allow requirements to be satisfied from a CI job -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/215514) ability to specify individual requirements and their statuses in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in GitLab 13.1. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/215514) ability to specify individual requirements and their statuses in GitLab 13.2. GitLab supports [requirements test reports](../../../ci/yaml/artifacts_reports.md#artifactsreportsrequirements) now. You can add a job to your CI pipeline that, when triggered, marks all existing diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 1e5b818c99d..90732ba4fe2 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -41,7 +41,7 @@ Here's how Service Desk works for you: 1. You provide a project-specific email address to your paying customers, who can email you directly from the application. 1. Each email they send creates an issue in the appropriate project. -1. Your team members navigate to the Service Desk issue tracker, where they can see new support +1. Your team members go to the Service Desk issue tracker, where they can see new support requests and respond inside associated issues. 1. Your team communicates back and forth with the customer to understand the request. 1. Your team starts working on implementing code to solve your customer's problem. @@ -93,8 +93,8 @@ displayed in the information note. ### Using customized email templates -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2460) in GitLab Premium 12.7. -> - Moved to GitLab Free in 13.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2460) in GitLab 12.7. +> - Moved from GitLab Premium to GitLab Free in 13.2. An email is sent to the author when: @@ -153,7 +153,7 @@ To use a custom description template with Service Desk: 1. On the top bar, select **Menu > Projects** and find your project. 1. [Create a description template](description_templates.md#create-an-issue-template). 1. On the left sidebar, select **Settings > General > Service Desk**. -1. From the dropdown **Template to append to all Service Desk issues**, search or select your template. +1. From the dropdown list **Template to append to all Service Desk issues**, search or select your template. ### Using a custom email display name @@ -171,7 +171,7 @@ To edit the custom email display name: ### Using a custom email address **(FREE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in GitLab Premium 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2201) in GitLab 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284656) in GitLab 13.8. It is possible to customize the email address used by Service Desk. To do this, you must configure @@ -190,13 +190,13 @@ 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' -portion of the address, before the `@`. This is used to identify the project +The `address` must include the `+%{key}` placeholder in the 'user' +portion of the address, before the `@`. The placeholder is used to identify the project where the issue should be created. NOTE: When configuring a custom mailbox, the `service_desk_email` and `incoming_email` -configurations must always use separate mailboxes. This is important, because +configurations must always use separate mailboxes. It's important, because emails picked from `service_desk_email` mailbox are processed by a different worker and it would not recognize `incoming_email` emails. @@ -241,7 +241,7 @@ The configuration options are the same as for configuring ##### Microsoft Graph -> Introduced in [GitLab 13.11](https://gitlab.com/gitlab-org/gitlab/-/issues/214900) +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214900) in GitLab 13.11. Service Desk can be configured to read Microsoft Exchange Online mailboxes with the Microsoft Graph API instead of IMAP. Follow the [documentation in the incoming email section for setting up an OAuth2 application for Microsoft Graph](../../administration/incoming_email.md#microsoft-graph). @@ -267,7 +267,7 @@ The Microsoft Graph API is not yet supported in source installations. See [this #### Configuring a custom email address suffix -You can set a custom suffix in your project's Service Desk settings once you have configured a [custom mailbox](#configuring-a-custom-mailbox). +You can set a custom suffix in your project's Service Desk settings after you have configured a [custom mailbox](#configuring-a-custom-mailbox). It can contain only lowercase letters (`a-z`), numbers (`0-9`), or underscores (`_`). When configured, the custom suffix creates a new Service Desk email address, consisting of the @@ -281,7 +281,7 @@ For example, suppose the `mygroup/myproject` project Service Desk settings has t The Service Desk email address for this project is: `contact+mygroup-myproject-support@example.com`. The [incoming email](../../administration/incoming_email.md) address still works. -If you don't configure the custom suffix, the default project identification will be used for identifying the project. You can see that email address in the project settings. +If you don't configure the custom suffix, the default project identification is used for identifying the project. You can see that email address in the project settings. ## Using Service Desk @@ -292,6 +292,7 @@ In these issues, you can also see our friendly neighborhood [Support Bot](#suppo > Support for additional email headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346600) in GitLab 14.6. > In earlier versions, the Service Desk email address had to be in the "To" field. + To create a Service Desk issue, an end user does not need to know anything about the GitLab instance. They just send an email to the address they are given, and receive an email back confirming receipt: @@ -327,7 +328,28 @@ You can read and write comments as you normally do in GitLab: Note that: - The project's visibility (private, internal, public) does not affect Service Desk. -- The path to the project, including its group or namespace, are shown in emails. +- The path to the project, including its group or namespace, is shown in emails. + +#### Issues created on someone's behalf + +To allow third party applications and ticketing systems to interface with Service Desk, +when the email contains the `Reply-To` email header, this email address is used as the address of the +issue author. + +Because the `Reply-To` header can be set to arbitrary values, do not blindly trust that an issue +created on behalf of `someone@example.com` was indeed created by the real owner of such email address. + +For example, an email with headers `To: support@example.com` and `Reply-To:someone@example.com` +creates an issue with the following note: + +> Created (…) by `support@example.com` (reply to: `someone@example.com`) (…) + +#### Privacy considerations + +Service Desk issues are confidential, but the project owner can +[make an issue public](issues/confidential_issues.md#modify-issue-confidentiality). +When a Service Desk issue becomes public, the issue creator's email address is disclosed +to everyone who can view the project. ### Support Bot user diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 8cee567ae93..ae3decb8079 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -229,7 +229,7 @@ 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)** +- [Project import/export administration Rake tasks](../../../administration/raketasks/project_import_export.md) - [Group import/export](../../group/settings/import_export.md) - [Group import/export API](../../../api/group_import_export.md) @@ -305,6 +305,9 @@ reduce the repository size for another import attempt: #### Workaround option 2 +NOTE: +This workaround requires access to the rails console, which isn't available to end-users on GitLab.com. + Rather than attempting to push all changes at once, this workaround: - Separates the project import from the Git Repository import @@ -351,32 +354,32 @@ Rather than attempting to push all changes at once, this workaround: git push -u origin ${COMMIT_SHA}:refs/heads/main done git push -u origin main - git push -u origin -—all - git push -u origin -—tags + git push -u origin --all + git push -u origin --tags ``` ### Manually execute export steps Exports sometimes fail without giving enough information to troubleshoot. In these cases, it can be -helpful to [execute the export process manually within rails](https://gitlab.com/gitlab-com/runbooks/-/blob/master/docs/uncategorized/project-export.md#export-a-project-via-rails-console). +helpful to [open a rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) +and loop through [all the defined exporters](https://gitlab.com/gitlab-org/gitlab/-/blob/b67a5b5a12498d57cd877023b7385f7251e57de8/app/services/projects/import_export/export_service.rb#L65). Execute each line individually, rather than pasting the entire block at once, so you can see any errors each command returns. ```shell +# User needs to have permission to export u = User.find_by_username('someuser') p = Project.find_by_full_path('some/project') e = Projects::ImportExport::ExportService.new(p,u) e.send(:version_saver).send(:save) -e.send(:avatar_saver).send(:save) -e.send(:project_tree_saver).send(:save) -e.send(:uploads_saver).send(:save) -e.send(:wiki_repo_saver).send(:save) -e.send(:lfs_saver).send(:save) -e.send(:snippets_repo_saver).send(:save) -e.send(:design_repo_saver).send(:save) +e.send(:repo_saver).send(:save) +## continue using `e.send(:exporter_name).send(:save)` going through the list of exporters +# The following line should show you the export_path similar to /var/opt/gitlab/gitlab-rails/shared/tmp/gitlab_exports/@hashed/49/94/4994.... s = Gitlab::ImportExport::Saver.new(exportable: p, shared:p.import_export_shared) + +# To try and upload use: s.send(:compress_and_save) s.send(:save_upload) ``` diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 12d75551aac..342b8d80bcf 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -541,7 +541,7 @@ Configure [alert integrations](../../../operations/incident_management/integrati #### Alert integration -Automatically [create](../../../operations/incident_management/incidents.md#create-incidents-automatically), [notify on](../../../operations/incident_management/paging.md#email-notifications), and [resolve](../../../operations/incident_management/incidents.md#automatically-close-incidents-via-recovery-alerts) incidents based on GitLab alerts. +Automatically [create](../../../operations/incident_management/incidents.md#create-incidents-automatically), [notify on](../../../operations/incident_management/paging.md#email-notifications-for-alerts), and [resolve](../../../operations/incident_management/incidents.md#automatically-close-incidents-via-recovery-alerts) incidents based on GitLab alerts. #### PagerDuty integration @@ -555,11 +555,11 @@ Automatically [create](../../../operations/incident_management/incidents.md#crea Configure Error Tracking to discover and view [Sentry errors within GitLab](../../../operations/error_tracking.md). -### Jaeger tracing **(ULTIMATE)** +### Jaeger tracing Add the URL of a Jaeger server to allow your users to [easily access the Jaeger UI from within GitLab](../../../operations/tracing.md). -### Status Page +### Status Page **(ULTIMATE)** [Add Storage credentials](../../../operations/incident_management/status_page.md#sync-incidents-to-the-status-page) to enable the syncing of public Issues to a [deployed status page](../../../operations/incident_management/status_page.md#create-a-status-page-project). diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index aa30c576c7c..a78226ac2f8 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -24,6 +24,8 @@ Project access tokens are similar to [group access tokens](../../group/settings/ and [personal access tokens](../../profile/personal_access_tokens.md), except they are associated with a project rather than a group or user. +In self-managed instances, project access tokens are subject to the same [maximum lifetime limits](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-personal-access-tokens) as personal access tokens if the limit is set. + You can use project access tokens: - 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/). @@ -43,7 +45,8 @@ To create a project access token: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Access Tokens**. 1. Enter a name. The token name is visible to any user with permissions to view the project. -1. Optional. Enter an expiry date for the token. The token will expire on that date at midnight UTC. +1. Optional. Enter an expiry date for the token. The token expires on that date at midnight UTC. An instance-wide [maximum lifetime](../../admin_area/settings/account_and_limit_settings.md#limit-the-lifetime-of-personal-access-tokens) setting can limit the maximum allowable lifetime in self-managed instances. + 1. Select a role for the token. 1. Select the [desired scopes](#scopes-for-a-project-access-token). 1. Select **Create project access token**. diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index 072f5bf1927..7c74a625b92 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -18,18 +18,13 @@ WARNING: This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77246) for use in GitLab 14.7, and is planned for -[removal](https://gitlab.com/groups/gitlab-org/-/epics/7351) in GitLab 15.0. -Users should instead use the [Web Editor](../repository/web_editor.md) or [Web IDE](../web_ide/index.md). +[removal](https://gitlab.com/groups/gitlab-org/-/epics/7351) in GitLab 14.10. +Users should instead use the [Web Editor](../repository/web_editor.md) or [Web IDE](../web_ide/index.md). [Removal instructions](#remove-the-static-site-editor) for existing projects are included on this page. Static Site Editor (SSE) enables users to edit content on static websites without prior knowledge of the underlying templating language, site architecture, or Git commands. A contributor to your project can quickly edit a Markdown page -and submit the changes for review. - -## Use cases - -The Static Site Editor allows collaborators to submit changes to static site -files seamlessly. For example: +and submit the changes for review. For example: - Non-technical collaborators can edit a page directly from the browser. They don't need to know Git and the details of your project to contribute. @@ -37,6 +32,43 @@ files seamlessly. For example: - Temporary collaborators can jump from project to project and quickly edit pages instead of having to clone or fork every single project they need to submit changes to. +## Remove the Static Site Editor + +The Static Site Editor itself isn't part of your project. To remove the Static Site Editor +from an existing project, remove links that point back to the editor: + +1. Remove any links that use `edit_page_url` in your project. If you used the + **Middleman - Static Site Editor** project template, the only instance of this + helper is located in `/source/layouts/layout.erb`. Remove this line entirely: + + ```ruby + <%= link_to('Edit this page', edit_page_url(data.config.repository, current_page.file_descriptor.relative_path), id: 'edit-page-link') %> + ``` + +1. In `/data/config.yml`, delete the `repository` key / value pair: + + ```yaml + repository: https://gitlab.com/<username>/<myproject> + ``` + + - If `repository` is the only value stored in `/data/config.yml`, you can delete the entire file. +1. In `/helpers/custom_helpers.rb`, delete `edit_page_url()` and `endcode_path()`: + + ```ruby + def edit_page_url(base_url, relative_path) + "#{base_url}/-/sse/#{encode_path(relative_path)}/" + end + + def encode_path(relative_path) + ERB::Util.url_encode("master/source/#{relative_path}") + end + ``` + + - If `edit_page_url()` and `encode_path()` are the only helpers, you may delete + `/helpers/custom_helpers.rb` entirely. +1. Clean up any extraneous configuration files. +1. Commit and push your changes. + ## Requirements - In order use the Static Site Editor feature, your project needs to be diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 4565b5f1c91..ff8a076465d 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -17,16 +17,16 @@ You can also open the Web IDE when viewing a file, from the repository file list and from merge requests: - *When viewing a file, or the repository file list* - - 1. In the upper right corner of the page, select **Edit in Web IDE** if it is visible. - 1. If **Edit in Web IDE** is not visible: + 1. In the upper right corner of the page, select **Open in Web IDE** if it is visible. + 1. If **Open in Web IDE** is not visible: 1. Select the **(angle-down)** next to **Edit** or **Gitpod**, depending on your configuration. - 1. Select **Edit in Web IDE** from the list to display it as the editing option. - 1. Select **Edit in Web IDE** to open the editor. + 1. Select **Open in Web IDE** from the list to display it as the editing option. + 1. Select **Open in Web IDE** to open the editor. - *When viewing a merge request* - 1. Go to your merge request, and select the **Overview** tab. 1. Scroll to the widgets section, after the merge request description. - 1. Select **Edit in Web IDE** if it is visible. - 1. If **Edit in Web IDE** is not visible: + 1. Select **Open in Web IDE** if it is visible. + 1. If **Open in Web IDE** is not visible: 1. Select the **(angle-down)** next to **Open in Gitpod**. 1. Select **Open in Web IDE** from the list to display it as the editing option. 1. Select **Open in Web IDE** to open the editor. @@ -145,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 13.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23352) in GitLab 13.1. The Web IDE supports configuration of certain editor settings by using [`.editorconfig` files](https://editorconfig.org/). When opening a file, the @@ -164,8 +164,8 @@ The Web IDE currently supports the following `.editorconfig` settings: ## Commit changes -> - 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. +> - [Starting](https://gitlab.com/gitlab-org/gitlab/-/issues/33441) with GitLab 12.7, files are automatically staged. +> - In GitLab 12.9, support for staging files was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/196609) to prevent loss of unstaged data. All of your current changes must be committed or discarded. After making your changes, select **Commit** on the bottom-left to review the list of changed files. @@ -215,13 +215,13 @@ different branch. ## Markdown editing -> - 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. +> - Support for pasting images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22822) in GitLab 13.1. +> - Side-by-side Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68274) in GitLab 14.3. To edit Markdown files in the Web IDE: 1. Go to your repository, and navigate to the Markdown page you want to edit. -1. Select **Edit in Web IDE**, and GitLab loads the page in a tab in the editor. +1. Select **Open in Web IDE**, and GitLab loads the page in a tab in the editor. 1. Make your changes to the file. GitLab supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown). 1. When your changes are complete, select **Commit** in the left sidebar. 1. Add a commit message, select the branch you want to commit to, and select **Commit**. @@ -286,10 +286,10 @@ An example `package.json`: ## Interactive Web Terminals for the Web IDE -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) to GitLab Free in 13.1. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) from GitLab Ultimate to GitLab Free in 13.1. WARNING: -Interactive Web Terminals for the Web IDE is currently in **Beta**. +Interactive Web Terminals for the Web IDE is currently in [**Beta**](../../../policy/alpha-beta-support.md#beta-features). GitLab.com shared runners [do not yet support Interactive Web Terminals](https://gitlab.com/gitlab-org/gitlab/-/issues/24674), so you must use your own private runner to make use of this feature. @@ -308,7 +308,7 @@ to work: This section requires at least a `session_timeout` value (which defaults to 1800 seconds) and a `listen_address` value. If `advertise_address` is not defined, `listen_address` is used. - If you are using a reverse proxy with your GitLab instance, web terminals must be - [enabled](../../../administration/integration/terminal.md#enabling-and-disabling-terminal-support). **(ULTIMATE SELF)** + [enabled](../../../administration/integration/terminal.md#enabling-and-disabling-terminal-support). If you have the terminal open and the job has finished with its tasks, the terminal blocks the job from finishing for the duration configured in @@ -391,7 +391,7 @@ click **Restart Terminal** to start a new terminal session. ### File syncing to web terminal -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5276) in GitLab Ultimate 12.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5276) in GitLab 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. diff --git a/doc/user/project/wiki/group.md b/doc/user/project/wiki/group.md index 2c499af123c..37f2ef8fc6a 100644 --- a/doc/user/project/wiki/group.md +++ b/doc/user/project/wiki/group.md @@ -7,7 +7,7 @@ type: reference, how-to # Group wikis **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in GitLab 13.5. If you use GitLab groups to manage multiple projects, some of your documentation might span multiple groups. You can create group wikis, instead of [project wikis](index.md), @@ -17,7 +17,7 @@ Group wikis are similar to [project wikis](index.md), with a few limitations: - [Git LFS](../../../topics/git/lfs/index.md) is not supported. - Group wikis are not included in [global search](../../search/advanced_search.md). - Changes to group wikis don't show up in the [group's activity feed](../../group/index.md#group-activity-analytics). -- Group wikis are enabled by default for **(PREMIUM)** and higher tiers. +- Group wikis are enabled by default for GitLab Premium and higher tiers. You [can't turn them off from the GitLab user interface](https://gitlab.com/gitlab-org/gitlab/-/issues/208413). For updates, follow [the epic that tracks feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). @@ -38,7 +38,7 @@ To access a group wiki: ## Export a group wiki -> Introduced in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247) in GitLab 13.9. Users with the Owner role in a group can [import and export group wikis](../../group/settings/import_export.md) when importing diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index 9cfcaf4ee81..19e77d18aca 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -68,9 +68,8 @@ If you're an instance administrator, you can administer all project topics from To create a project in GitLab: -1. On the top bar, select **Menu > Project**. -1. Select **Create new project**. -1. On the **New project** page, choose if you want to: +1. On the top bar, select **Menu > Project > Create new project**. +1. On the **Create new project** page, choose if you want to: - Create a [blank project](#create-a-blank-project). - Create a project from a: - [built-in template](#create-a-project-from-a-built-in-template). @@ -80,21 +79,20 @@ To create a project in GitLab: from a different repository. Contact your GitLab administrator if this option is not available. - [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md). -NOTE: -For a list of words that can't be used as project names see +- For a list of words that you cannot use as project names, see [reserved project and group names](../../user/reserved_names.md). +- For a list of characters that you cannot use in project and group names, see +[limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names). ## Create a blank project To create a blank project: -1. On the top bar, select **Menu > Project**. -1. Select **Create new project**. +1. On the top bar, select **Menu > Projects > Create new project**. 1. Select **Create blank project**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, - underscores, and emoji. You cannot use special characters. After you enter the name, - the **Project slug** populates. + - In the **Project name** field, enter the name of your project. You cannot use special characters at + the start or end of a project name. - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. @@ -121,17 +119,15 @@ Anyone can contribute a built-in template by following [these steps](https://abo To create a project from a built-in template: -1. On the top bar, select **Menu > Project**. -1. Select **Create new project**. +1. On the top bar, select **Menu > Projects > Create new project**. 1. Select **Create from template**. 1. Select the **Built-in** tab. 1. From the list of templates: - To view a preview of the template, select **Preview**. - To use a template for the project, select **Use template**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, - underscores, and emoji. You cannot use special characters. After you enter the name, - the **Project slug** populates. + - In the **Project name** field, enter the name of your project. You cannot use special characters at + the start or end of a project name. - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. @@ -149,17 +145,15 @@ Custom project templates are available at: - The [instance-level](../../user/admin_area/custom_project_templates.md) - The [group-level](../../user/group/custom_project_templates.md) -1. On the top bar, select **Menu > Project**. -1. Select **Create new project**. +1. On the top bar, select **Menu > Projects > Create new project**. 1. Select **Create from template**. 1. Select the **Instance** or **Group** tab. 1. From the list of templates: - To view a preview of the template, select **Preview**. - To use a template for the project, select **Use template**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, - underscores, and emoji. You cannot use special characters. After you enter the name, - the **Project slug** populates. + - In the **Project name** field, enter the name of your project. You cannot use special characters at + the start or end of a project name. - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. @@ -177,17 +171,15 @@ HIPAA Audit Protocol published by the U.S Department of Health and Human Service To create a project from the HIPAA Audit Protocol template: -1. On the top bar, select **Menu > Project**. -1. Select **Create new project**. +1. On the top bar, select **Menu > Projects > Create new project**. 1. Select **Create from template**. 1. Select the **Built-in** tab. 1. Locate the **HIPAA Audit Protocol** template: - To view a preview of the template, select **Preview**. - To use the template for the project, select **Use template**. 1. Enter the project details: - - In the **Project name** field, enter the name of your project. You can use spaces, hyphens, - underscores, and emoji. You cannot use special characters. After you enter the name, - the **Project slug** populates. + - In the **Project name** field, enter the name of your project. You cannot use special characters at + the start or end of a project name. - In the **Project slug** field, enter the path to your project. The GitLab instance uses the slug as the URL path to the project. To change the slug, first enter the project name, then change the slug. @@ -196,7 +188,7 @@ To create a project from the HIPAA Audit Protocol template: change the **Visibility Level**. 1. Select **Create project**. -## Push to create a new project +## Create a new project with Git push > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26388) in GitLab 10.5. @@ -218,7 +210,7 @@ Prerequisites: [added to your GitLab account](../../ssh/index.md#add-an-ssh-key-to-your-gitlab-account). - You must have permission to add new projects to a namespace. To check if you have permission: - 1. On the top bar, select **Menu > Project**. + 1. On the top bar, select **Menu > Projects**. 1. Select **Groups**. 1. Select a group. 1. Confirm that **New project** is visible in the upper right @@ -266,14 +258,14 @@ You can add a star to projects you use frequently to make them easier to find. To add a star to a project: -1. On the top bar, select **Menu > Project**. +1. On the top bar, select **Menu > Projects**. 1. Select **Your projects** or **Explore projects**. 1. Select a project. 1. In the upper right corner of the page, select **Star**. ## View starred projects -1. On the top bar, select **Menu > Project**. +1. On the top bar, select **Menu > Projects**. 1. Select **Starred projects**. 1. GitLab displays information about your starred projects, including: @@ -290,33 +282,33 @@ you can [enable delayed project removal](../group/index.md#enable-delayed-projec To delete a project: -1. On the top bar, select **Menu > Project**. +1. On the top bar, select **Menu > Projects**. 1. Select **Your projects** or **Explore projects**. 1. Select a project. 1. Select **Settings > General**. 1. Expand the **Advanced** section. 1. Scroll down to the **Delete project** section. -1. Select **Delete project** +1. Select **Delete project**. 1. Confirm this action by completing the field. -## Projects pending deletion **(PREMIUM)** +## View projects pending deletion **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37014) in GitLab 13.3 for Administrators. > - [Tab renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/347468) from **Deleted projects** in GitLab 14.6. > - [Available to all users](https://gitlab.com/gitlab-org/gitlab/-/issues/346976) in GitLab 14.8 [with a flag](../../administration/feature_flags.md) named `project_owners_list_project_pending_deletion`. Enabled by default. - -FLAG: -On self-managed GitLab, by default this feature is available to all users. To make it available for administrators only, -ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `project_owners_list_project_pending_deletion`. -On GitLab.com, this feature is available to all users. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/351556) in GitLab 14.9. [Feature flag `project_owners_list_project_pending_deletion`](https://gitlab.com/gitlab-org/gitlab/-/issues/351556) removed. 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: +projects within that group are not deleted immediately, but only after a delay. + +To view a list of all projects that are pending deletion: 1. On the top bar, select **Menu > Projects > Explore projects**. -1. Select the **Pending deletion** tab (in GitLab 14.6 and later) or the **Deleted projects** tab (GitLab 14.5 and earlier). +1. Based on your GitLab version: + - GitLab 14.6 and later: select the **Pending deletion** tab. + - GitLab 14.5 and earlier: select the **Deleted projects** tab. -Listed for each project is: +Each project in the list shows: - The time the project was marked for deletion. - The time the project is scheduled for final deletion. @@ -326,7 +318,7 @@ Listed for each project is: To view the activity of a project: -1. On the top bar, select **Menu > Project**. +1. On the top bar, select **Menu > Projects**. 1. Select **Your projects** or **Explore projects**. 1. Select a project. 1. On the left sidebar, select **Project information > Activity**. @@ -334,12 +326,12 @@ To view the activity of a project: ## Leave a project -If you leave a project you are no longer a project +If you leave a project, you are no longer a project member and cannot contribute. To leave a project: -1. On the top bar, select **Menu > Project**. +1. On the top bar, select **Menu > Projects**. 1. Select **Your projects** or **Explore projects**. 1. Select a project. 1. Select **Leave project**. The **Leave project** option only displays @@ -481,3 +473,4 @@ download starts, the `insteadOf` configuration sends the traffic to the secondar - [Connect an external repository to GitLab CI/CD](../../ci/ci_cd_for_external_repos/index.md). - [Fork a project](repository/forking_workflow.md#creating-a-fork). - [Adjust project visibility and access levels](settings/index.md#sharing-and-permissions). +- [Limitations on project and group names](../../user/reserved_names.md#limitations-on-project-and-group-names) diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index 203b1c9e93a..33ecf252e43 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -4,7 +4,7 @@ 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 --- -# Reserved project and group names +# Reserved project and group names **(FREE)** Not all project & group names are allowed because they would conflict with existing routes used by GitLab. @@ -17,6 +17,13 @@ under the `TOP_LEVEL_ROUTES`, `PROJECT_WILDCARD_ROUTES` and `GROUP_ROUTES` lists - `PROJECT_WILDCARD_ROUTES`: are names that are reserved for child groups or projects. - `GROUP_ROUTES`: are names that are reserved for all groups or projects. +## Limitations on project and group names + +- Special characters are not permitted at the start or end of project or group names. They are permitted in any other location of the name. +- Project or group names cannot end in `.git` or `.atom`. +- Project or group names can only contain letters, digits, emojis, "_", ".", "+", dashes, or spaces. +- Paths can only contain letters, digits, "_", "-", and "." + ## Reserved project names It is currently not possible to create a project with the following names: @@ -45,7 +52,7 @@ It is currently not possible to create a project with the following names: ## Reserved group names -Currently the following names are reserved as top level groups: +Currently, the following names are reserved as top level groups: - `\-` - `.well-known` diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index 05579696d35..cb272b3feed 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -7,7 +7,7 @@ type: reference # GitLab Advanced Search **(PREMIUM)** -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. NOTE: This is the user documentation. To configure the Advanced Search, @@ -147,8 +147,8 @@ its performance: FLAG: On self-managed GitLab, by default this feature is not available. To make it available, - ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `prevent_abusive_searches`. - The feature is not ready for production use. +ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `prevent_abusive_searches`. +The feature is not ready for production use. To prevent abusive searches, such as searches that may result in a Distributed Denial of Service (DDoS), Global Search ignores, logs, and doesn't return any results for searches considered abusive according to the following criteria, if `prevent_abusive_searches` feature flag is enabled: diff --git a/doc/user/search/img/code_search.png b/doc/user/search/img/code_search.png Binary files differdeleted file mode 100644 index 7c62bb6921b..00000000000 --- a/doc/user/search/img/code_search.png +++ /dev/null diff --git a/doc/user/search/img/code_search_git_blame_v14_9.png b/doc/user/search/img/code_search_git_blame_v14_9.png Binary files differnew file mode 100644 index 00000000000..33d4e77e3f5 --- /dev/null +++ b/doc/user/search/img/code_search_git_blame_v14_9.png diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 0a799843d3c..44327af380e 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -34,14 +34,15 @@ in the search field in the upper right corner: > - Filtering by epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195704) in GitLab 12.9. > - Filtering by child epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9029) in GitLab 13.0. -> - Filtering by iterations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6. Moved from GitLab Ultimate to Premium in 13.9. +> - Filtering by iterations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6. +> - Filtering by iterations was moved from GitLab Ultimate to GitLab Premium in 13.9. > - Filtering by type was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322755) in GitLab 13.10 [with a flag](../../administration/feature_flags.md) named `vue_issues_list`. Disabled by default. Follow these steps to filter the **Issues** and **Merge requests** list pages in projects and groups: -1. Click in the field **Search or filter results...**. -1. In the dropdown menu that appears, select the attribute you wish to filter by: +1. Select **Search or filter results...**. +1. In the dropdown list that appears, select the attribute you wish to filter by: - Assignee - Author - Confidential @@ -112,8 +113,8 @@ You can filter the **Issues** list to individual instances by their ID. For exam > 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. +To filter merge requests by an individual eligible approver ([Codeowner](../project/code_owners.md)), you can type (or select from +the dropdown list) **Approver** and select the user.  @@ -123,29 +124,29 @@ the dropdown) **Approver** and select the user. > - Moved to GitLab Premium in 13.9. To filter merge requests already approved by a specific individual, you can type (or select from -the dropdown) **Approved-By** and select the user. +the dropdown list) **Approved-By** and select the user.  -### Filtering merge requests by reviewer **(FREE)** +### Filtering merge requests by reviewer > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47605) in GitLab 13.7. To filter review requested merge requests for a specific individual, you can type (or select from -the dropdown) **Reviewer** and select the user. +the dropdown list) **Reviewer** and select the user. -### Filtering merge requests by environment or deployment date **(FREE)** +### Filtering merge requests by environment or deployment date > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44041) in GitLab 13.6. To filter merge requests by deployment data, such as the environment or a date, -you can type (or select from the dropdown) the following: +you can type (or select from the dropdown list) the following: - Environment - Deployed-before - Deployed-after -When filtering by an environment, a dropdown presents all environments that +When filtering by an environment, a dropdown list presents all environments that you can choose from:  @@ -174,7 +175,7 @@ you must type at least `Sim` before autocomplete displays results. Search history is available for issues and merge requests, and is stored locally in your browser. To run a search from history: -1. In the top menu, click **Issues** or **Merge requests**. +1. In the top menu, select **Issues** or **Merge requests**. 1. To the left of the search bar, click **Recent searches**, and select a search from the list. ## Removing search filters @@ -193,7 +194,7 @@ Some filters can be added multiple times. These include but are not limited to a You can search your [To-Do List](../todos.md) by "to do" and "done". You can filter to-do items per project, author, type, and action. -Also, you can sort them by [**Label priority**](../../user/project/labels.md#label-priority), +Also, you can sort them by [**Label priority**](../../user/project/labels.md#set-label-priority), **Last created**, and **Oldest created**. ## Projects @@ -227,7 +228,7 @@ and sort them by **Last created**, **Oldest created**, **Last updated**, or **Ol From an [issue board](../../user/project/issue_board.md), you can filter issues by **Author**, **Assignee**, **Milestone**, and **Labels**. You can also filter them by name (issue title), from the field **Filter by name**, which is loaded as you type. -To search for issues to add to lists present in your issue board, click +To search for issues to add to lists present in your issue board, select the button **Add issues** on the top-right of your screen, opening a modal window from which you can, besides filtering them by **Name**, **Author**, **Assignee**, **Milestone**, and **Labels**, select multiple issues to add to a list of your choice: @@ -281,13 +282,13 @@ 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. -#### Git blame from code search **(PREMIUM)** +#### Git blame from code search **(FREE)** > [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 @@ -307,7 +308,7 @@ GitLab instance. ## Search settings > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292941) in GitLab 13.8 [with a flag](../../administration/feature_flags.md) named `search_settings_in_page`. Disabled by default. -> - [Added to Group, Administrator, and User settings](https://gitlab.com/groups/gitlab-org/-/epics/4842) in GitLab 13.9. +> - [Added](https://gitlab.com/groups/gitlab-org/-/epics/4842) to Group, Administrator, and User settings in GitLab 13.9. > - [Feature flag `search_settings_in_page` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/294025) in GitLab 13.11. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/294025) in GitLab 13.11. diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md index ebaa5da8e05..e807f251da1 100644 --- a/doc/user/shortcuts.md +++ b/doc/user/shortcuts.md @@ -17,10 +17,6 @@ following methods: - Press <kbd>?</kbd>. - In the Help menu in the top right of the application, select **Keyboard shortcuts**. -In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/22113), -you can disable keyboard shortcuts by using the **Keyboard shortcuts** toggle -at the top of the keyboard shortcut window. - Although [global shortcuts](#global-shortcuts) work from any area of GitLab, you must be in specific pages for the other shortcuts to be available, as explained in each section. @@ -41,21 +37,22 @@ These shortcuts are available in most areas of GitLab: | <kbd>Shift</kbd> + <kbd>i</kbd> | Go to your Issues page. | | <kbd>Shift</kbd> + <kbd>m</kbd> | Go to your [Merge requests](project/merge_requests/index.md) page. | | <kbd>Shift</kbd> + <kbd>t</kbd> | Go to your To-Do List page. | -| <kbd>p</kbd> + <kbd>b</kbd> | Show or hide the Performance Bar. | -| <kbd>g</kbd> + <kbd>x</kbd> | Toggle between [GitLab](https://gitlab.com/) and [GitLab Next](https://next.gitlab.com/) (GitLab SaaS only). | -| <kbd>.</kbd> | Open the [Web IDE](project/web_ide/index.md). | +| <kbd>p</kbd> then <kbd>b</kbd> | Show or hide the Performance Bar. | +| <kbd>g</kbd> then <kbd>x</kbd> | Toggle between [GitLab](https://gitlab.com/) and [GitLab Next](https://next.gitlab.com/) (GitLab SaaS only). | +| <kbd>.</kbd> | Open the [Web IDE](project/web_ide/index.md). | Additionally, the following shortcuts are available when editing text in text fields (for example, comments, replies, issue descriptions, and merge request descriptions): -| Keyboard shortcut | Description | -|---------------------------------------------------------------------------|-------------| -| <kbd>↑</kbd> | Edit your last comment. You must be in a blank text field below a thread, and you must already have at least one comment in the thread. | -| <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd> | Toggle Markdown preview when editing text in a text field that has **Write** and **Preview** tabs at the top. | -| <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>b</kbd> | Bold the selected text (surround it with `**`). | -| <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>i</kbd> | Italicize the selected text (surround it with `_`). | -| <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>k</kbd> | Add a link (surround the selected text with `[]()`). | +| macOS shortcut | Windows shortcut | Description | +|----------------|------------------|-------------| +| <kbd>↑</kbd> | <kbd>↑</kbd> | Edit your last comment. You must be in a blank text field below a thread, and you must already have at least one comment in the thread. | +| <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd> | Toggle Markdown preview when editing text in a text field that has **Write** and **Preview** tabs at the top. | +| <kbd>Command</kbd> + <kbd>b</kbd> | <kbd>Control</kbd> + <kbd>b</kbd> | Bold the selected text (surround it with `**`). | +| <kbd>Command</kbd> + <kbd>i</kbd> | <kbd>Control</kbd> + <kbd>i</kbd> | Italicize the selected text (surround it with `_`). | +| <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>s</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>s</kbd> | Strike through the selected text (surround it with `~~`). | +| <kbd>Command</kbd> + <kbd>k</kbd> | <kbd>Control</kbd> + <kbd>k</kbd> | Add a link (surround the selected text with `[]()`). | The shortcuts for editing in text fields are always enabled, even if other keyboard shortcuts are disabled. @@ -102,7 +99,7 @@ These shortcuts are available when viewing issues and [merge requests](project/m | <kbd>]</kbd> or <kbd>j</kbd> | Move to next file (merge requests only). | | <kbd>[</kbd> or <kbd>k</kbd> | Move to previous file (merge requests only). | | <kbd>b</kbd> | Copy source branch name (merge requests only). | -| <kbd>.</kbd> | Open the [Web IDE](project/web_ide/index.md). | +| <kbd>.</kbd> | Open the [Web IDE](project/web_ide/index.md). | ### Project files @@ -113,7 +110,7 @@ These shortcuts are available when browsing the files in a project (go to |-------------------|-------------| | <kbd>↑</kbd> | Move selection up. | | <kbd>↓</kbd> | Move selection down. | -| <kbd>enter</kbd> | Open selection. | +| <kbd>Enter</kbd> | Open selection. | | <kbd>Escape</kbd> | Go back to file list screen (only while searching for files, **Repository > Files**, then select **Find File**). | | <kbd>y</kbd> | Go to file permalink (only while viewing a file). | | <kbd>.</kbd> | Open the [Web IDE](project/web_ide/index.md). | @@ -122,15 +119,15 @@ These shortcuts are available when browsing the files in a project (go to These shortcuts are available when editing a file with the [Web IDE](project/web_ide/index.md): -| Keyboard shortcut | Description | -|------------------------------------------------------------|-------------| -| <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>p</kbd> | Search for, and then open another file for editing. | -| <kbd>⌘</kbd> (Mac) / <kbd>Control</kbd> + <kbd>Enter</kbd> | Commit (when editing the commit message). | +| macOS shortcut | Windows shortcut | Description | +|---------------------------------|---------------------|-------------| +| <kbd>Command</kbd> + <kbd>p</kbd> | <kbd>Control</kbd> + <kbd>p</kbd> | Search for, and then open another file for editing. | +| <kbd>Command</kbd> + <kbd>Enter</kbd> | <kbd>Control</kbd> + <kbd>Enter</kbd> | Commit (when editing the commit message). | ### Repository graph These shortcuts are available when viewing the project [repository graph](project/repository/index.md#repository-history-graph) -page (navigate to **Repository > Graph**): +page (go to **Repository > Graph**): | Keyboard shortcut | Description | |--------------------------------------------------------------------|-------------| @@ -151,63 +148,64 @@ This shortcut is available when viewing a [wiki page](project/wiki/index.md): ### Content editor -These shortcuts are available when editing a file with the [Content Editor](https://about.gitlab.com/direction/create/editor/content_editor/): +These shortcuts are available when editing a file with the +[Content Editor](https://about.gitlab.com/direction/create/editor/content_editor/): -| Keyboard shortcut | Description | -|-------------------|-------------| -| <kbd>⌘</kbd> + <kbd>C</kbd> (Mac) / <kbd>Control</kbd> + <kbd>C</kbd> | Copy | -| <kbd>⌘</kbd> + <kbd>X</kbd> (Mac) / <kbd>Control</kbd> + <kbd>X</kbd> | Cut | -| <kbd>⌘</kbd> + <kbd>V</kbd> (Mac) / <kbd>Control</kbd> + <kbd>V</kbd> | Paste | -| <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>V</kbd> (Mac) / <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>V</kbd> | Paste without formatting | -| <kbd>⌘</kbd> + <kbd>Z</kbd> (Mac) / <kbd>Control</kbd> + <kbd>Z</kbd> | Undo | -| <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>V</kbd> (Mac) / <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>V</kbd> | Redo | -| <kbd>Shift</kbd> + <kbd>Enter</kbd> | Add a line break | +| macOS shortcut | Windows shortcut | Description | +|----------------|------------------|-------------| +| <kbd>Command</kbd> + <kbd>C</kbd> | <kbd>Control</kbd> + <kbd>C</kbd> | Copy | +| <kbd>Command</kbd> + <kbd>X</kbd> | <kbd>Control</kbd> + <kbd>X</kbd> | Cut | +| <kbd>Command</kbd> + <kbd>V</kbd> | <kbd>Control</kbd> + <kbd>V</kbd> | Paste | +| <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>V</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>V</kbd> | Paste without formatting | +| <kbd>Command</kbd> + <kbd>Z</kbd> | <kbd>Control</kbd> + <kbd>Z</kbd> | Undo | +| <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>V</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>V</kbd> | Redo | +| <kbd>Shift</kbd> + <kbd>Enter</kbd> | <kbd>Shift</kbd> + <kbd>Enter</kbd> | Add a line break | #### Formatting -| Mac | Windows/Linux | Description | -|-----|---------------|-------------| -| <kbd>⌘</kbd> + <kbd>b</kbd> | <kbd>Control</kbd> + <kbd>b</kbd> | Bold | -| <kbd>⌘</kbd> + <kbd>i</kbd> | <kbd>Control</kbd> + <kbd>i</kbd> | Italic | -| <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>s</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>s</kbd> | Strikethrough | -| <kbd>⌘</kbd> + <kbd>e</kbd> | <kbd>Control</kbd> + <kbd>e</kbd> | Code | -| <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>0</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>0</kbd> | Apply normal text style | -| <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>1</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>1</kbd> | Apply heading style 1 | -| <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>2</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>2</kbd> | Apply heading style 2 | -| <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>3</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>3</kbd> | Apply heading style 3 | -| <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>4</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>4</kbd> | Apply heading style 4 | -| <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>5</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>5</kbd> | Apply heading style 5 | -| <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>6</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>6</kbd> | Apply heading style 6 | -| <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>7</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>7</kbd> | Ordered list | -| <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>8</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>7</kbd> | Bullet list | -| <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>9</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>7</kbd> | Task list | -| <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>b</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>b</kbd> | Blockquote | -| <kbd>⌘</kbd> + <kbd>Alt</kbd> + <kbd>c</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>c</kbd> | Code block | -| <kbd>⌘</kbd> + <kbd>,</kbd> | <kbd>Control</kbd> + <kbd>,</kbd> | Subscript | -| <kbd>⌘</kbd> + <kbd>.</kbd> | <kbd>Control</kbd> + <kbd>,</kbd> | Superscript | -| <kbd>Tab</kbd> | | Indent list | -| <kbd>Shift</kbd> + <kbd>Tab</kbd> | | Outdent list | +| macOS shortcut | Windows/Linux shortcut | Description | +|----------------|------------------------|-------------| +| <kbd>Command</kbd> + <kbd>b</kbd> | <kbd>Control</kbd> + <kbd>b</kbd> | Bold | +| <kbd>Command</kbd> + <kbd>i</kbd> | <kbd>Control</kbd> + <kbd>i</kbd> | Italic | +| <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>x</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>x</kbd> | Strikethrough | +| <kbd>Command</kbd> + <kbd>e</kbd> | <kbd>Control</kbd> + <kbd>e</kbd> | Code | +| <kbd>Command</kbd> + <kbd>Alt</kbd> + <kbd>0</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>0</kbd> | Apply normal text style | +| <kbd>Command</kbd> + <kbd>Alt</kbd> + <kbd>1</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>1</kbd> | Apply heading style 1 | +| <kbd>Command</kbd> + <kbd>Alt</kbd> + <kbd>2</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>2</kbd> | Apply heading style 2 | +| <kbd>Command</kbd> + <kbd>Alt</kbd> + <kbd>3</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>3</kbd> | Apply heading style 3 | +| <kbd>Command</kbd> + <kbd>Alt</kbd> + <kbd>4</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>4</kbd> | Apply heading style 4 | +| <kbd>Command</kbd> + <kbd>Alt</kbd> + <kbd>5</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>5</kbd> | Apply heading style 5 | +| <kbd>Command</kbd> + <kbd>Alt</kbd> + <kbd>6</kbd> | <kbd>Control</kbd> + <kbd>Alt</kbd> + <kbd>6</kbd> | Apply heading style 6 | +| <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>7</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>7</kbd> | Ordered list | +| <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>8</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>8</kbd> | Bullet list | +| <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>9</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>9</kbd> | Task list | +| <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>b</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>b</kbd> | Blockquote | +| <kbd>Command</kbd> + <kbd>Alt</kbd> + <kbd>c</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>c</kbd> | Code block | +| <kbd>Command</kbd> + <kbd>,</kbd> | <kbd>Control</kbd> + <kbd>,</kbd> | Subscript | +| <kbd>Command</kbd> + <kbd>.</kbd> | <kbd>Control</kbd> + <kbd>.</kbd> | Superscript | +| <kbd>Tab</kbd> | <kbd>Tab</kbd> | Indent list | +| <kbd>Shift</kbd> + <kbd>Tab</kbd> | <kbd>Shift</kbd> + <kbd>Tab</kbd> | Outdent list | #### Text selection -| Keyboard shortcut | Description | -|-------------------|-------------| -| <kbd>⌘</kbd> + <kbd>a</kbd> (Mac) / <kbd>Control</kbd> + <kbd>a</kbd> | Select all | -| <kbd>Shift</kbd> + <kbd>←</kbd> | Extend selection one character to left | -| <kbd>Shift</kbd> + <kbd>→</kbd> | Extend selection one character to right | -| <kbd>Shift</kbd> + <kbd>↑</kbd> | Extend selection one line up | -| <kbd>Shift</kbd> + <kbd>↓</kbd> | Extend selection one line down | -| <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>↑</kbd> (Mac) / <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>↑</kbd> | Extend selection to the beginning of the document | -| <kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>↓</kbd> (Mac) / <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>↓</kbd> | Extend selection to the end of the document | +| macOS shortcut | Windows shortcut | Description | +|----------------|------------------|-------------| +| <kbd>Command</kbd> + <kbd>a</kbd> | <kbd>Control</kbd> + <kbd>a</kbd> | Select all | +| <kbd>Shift</kbd> + <kbd>←</kbd> | <kbd>Shift</kbd> + <kbd>←</kbd> | Extend selection one character to left | +| <kbd>Shift</kbd> + <kbd>→</kbd> | <kbd>Shift</kbd> + <kbd>→</kbd> | Extend selection one character to right | +| <kbd>Shift</kbd> + <kbd>↑</kbd> | <kbd>Shift</kbd> + <kbd>↑</kbd> | Extend selection one line up | +| <kbd>Shift</kbd> + <kbd>↓</kbd> | <kbd>Shift</kbd> + <kbd>↓</kbd> | Extend selection one line down | +| <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>↑</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>↑</kbd> | Extend selection to the beginning of the document | +| <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>↓</kbd> | <kbd>Control</kbd> + <kbd>Shift</kbd> + <kbd>↓</kbd> | Extend selection to the end of the document | ### Filtered search These shortcuts are available when using a [filtered search input](search/index.md): -| Keyboard shortcut | Description | -|--------------------------------------------------------|-------------| -| <kbd>⌘</kbd> (Mac) + <kbd>⌫</kbd> | Clear entire search filter. | -| <kbd>⌥</kbd> (Mac) / <kbd>Control</kbd> + <kbd>⌫</kbd> | Clear one token at a time. | +| macOS shortcut | Windows shortcut | Description | +|----------------------|----------------------------------------|-------------| +| <kbd>Command</kbd> | <kbd>Delete</kbd> | Clear entire search filter. | +| <kbd>Option</kbd> | <kbd>Control</kbd> + <kbd>Delete</kbd> | Clear one token at a time. | ## Epics **(PREMIUM)** @@ -218,3 +216,13 @@ These shortcuts are available when viewing [epics](group/epics/index.md): | <kbd>r</kbd> | Start writing a comment. Pre-selected text is quoted in the comment. Can't be used to reply in a thread. | | <kbd>e</kbd> | Edit description. | | <kbd>l</kbd> | Change label. | + +## Disable keyboard shortcuts + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22113) in GitLab 12.8. + +To disable keyboard shortcuts: + +1. While viewing a page that supports keyboard shortcuts, and outside a text box, +press <kbd>?</kbd> to display the list of shortcuts. +1. Select **Toggle shortcuts**. diff --git a/doc/user/snippets.md b/doc/user/snippets.md index dc3ab35067e..1750e2c8d10 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -33,20 +33,18 @@ You can create snippets in multiple ways, depending on whether you want to creat 1. Select the kind of snippet you want to create: - **To create a personal snippet**: On the - [Snippets dashboard](https://gitlab.com/dashboard/snippets), click + [Snippets dashboard](https://gitlab.com/dashboard/snippets), select **New snippet**, or: - *If you're on a project's page,* select the plus icon (**{plus-square-o}**) in the top navigation bar, and then select **New snippet** from the - **GitLab** (GitLab SaaS) or **Your Instance** (self-managed) section - of the same dropdown menu. + **GitLab** section of the same dropdown list. - *For all other pages,* select the plus icon (**{plus-square-o}**) - in the top navigation bar, then select **New snippet** from the dropdown - menu. + in the top navigation bar, then select **New snippet** from the dropdown list. - If you installed the [GitLab Workflow VS Code extension](project/repository/vscode.md), use the [`Gitlab: Create snippet` command](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#create-snippet). - **To create a project snippet**: Go to your project's page. Select the plus icon (**{plus-square-o}**), and then select **New snippet** from the - **This project** section of the dropdown menu. + **This project** section of the dropdown list. 1. Add a **Title** and **Description**. 1. Name your **File** with an appropriate extension, such as `example.rb` or `index.html`. Filenames with appropriate extensions display [syntax highlighting](#filenames). @@ -154,15 +152,14 @@ To delete a file from your snippet through the GitLab UI: 1. Go to your snippet in the GitLab UI. 1. Select **Edit** in the top right corner. -1. Select **Delete file** alongside the filename of each file -you wish to delete. +1. Select **Delete file** alongside the filename of each file you wish to delete. 1. Select **Save changes**. ## Clone snippets Instead of copying a snippet to a local file, you may want to clone a snippet to preserve its relationship with the repository, so you can receive or make updates -as needed. Select the **Clone** button on a snippet to display the URLs to clone with SSH or HTTPS: +as needed. Select **Clone** on a snippet to display the URLs to clone with SSH or HTTPS:  @@ -202,7 +199,7 @@ For example: ## Download snippets You can download the raw content of a snippet. By default, they download with Linux-style line endings (`LF`). If -you want to preserve the original line endings you need to add a parameter `line_ending=raw` +you want to preserve the original line endings you must add a parameter `line_ending=raw` (For example: `https://gitlab.com/snippets/SNIPPET_ID/raw?line_ending=raw`). In case a snippet was created using the GitLab web interface the original line ending is Windows-like (`CRLF`). diff --git a/doc/user/tasks.md b/doc/user/tasks.md index 5fde64e3578..8be7fbca213 100644 --- a/doc/user/tasks.md +++ b/doc/user/tasks.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334812) in GitLab 14.5 [with a flag](../administration/feature_flags.md) named `work_items`. Disabled by default. WARNING: -Tasks are in **Alpha**. Current implementation does not have any API requests and works with mocked data. +Tasks are in [**Alpha**](../policy/alpha-beta-support.md#alpha-features). Current implementation does not have any API requests and works with mocked data. For the latest updates, check the [Tasks Roadmap](https://gitlab.com/groups/gitlab-org/-/epics/7103). FLAG: diff --git a/doc/user/todos.md b/doc/user/todos.md index 2486db813ff..ec316d8ebe4 100644 --- a/doc/user/todos.md +++ b/doc/user/todos.md @@ -45,9 +45,30 @@ A to-do item is added to your To-Do List when: When several actions occur for the same user on the same object, GitLab displays the first action as a single to-do item. +To change this behavior, enable +[multiple to-do items per object](#multiple-to-do-items-per-object). To-do items aren't affected by [GitLab notification email settings](profile/notifications.md). +### Multiple to-do items per object **(FREE SELF)** + +<!-- When the feature flag is removed, integrate this topic into the one above. --> + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28355) in GitLab 13.8 [with a flag](../administration/feature_flags.md) named `multiple_todos`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82470) in GitLab 14.9: only mentions create multiple to-do items. + +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 `multiple_todos`. +On GitLab.com, this feature is not available. +The feature is not ready for production use. + +When you enable this feature: + +- Every time you're mentioned, GitLab creates a new to-do item for you. +- Other [actions that create to-do items](#actions-that-create-to-do-items) + create one to-do item per action type on the issue, MR, and so on. + ## Create a to-do item You can manually add an item to your To-Do List. @@ -73,9 +94,7 @@ For example, in the following comment: - @carol can you please have a look? ->>> -@dan what do you think? ->>> +> @dan what do you think? @erin @frank thank you! ``` diff --git a/doc/user/usage_quotas.md b/doc/user/usage_quotas.md index 75d10084328..84a2449f481 100644 --- a/doc/user/usage_quotas.md +++ b/doc/user/usage_quotas.md @@ -2,7 +2,7 @@ type: howto stage: Fulfillment group: Utilization -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Storage usage quota **(FREE)** @@ -10,6 +10,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/13294) in GitLab 12.0. > - Moved to GitLab Free. +NOTE: +Free tier namespaces on GitLab SaaS have a 5GB storage limit. This limit is not visible on the storage quota page nor currently enforced for users who exceed the limit. To learn more, visit our [pricing page](https://about.gitlab.com/pricing/). + A project's repository has a free storage quota of 10 GB. When a project's repository reaches the quota it is locked. You cannot push changes to a locked project. To monitor the size of each repository in a namespace, including a breakdown for each project, you can @@ -39,7 +42,7 @@ namespace to recalculate the storage. > - Enabled on self-managed in GitLab 14.5. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/71270) in GitLab 14.5. -The following storage usage statistics are available to an owner: +The following storage usage statistics are available to a maintainer: - Total namespace storage used: Total amount of storage used across projects in this namespace. - Total excess storage used: Total amount of storage used that exceeds their allocated storage. diff --git a/doc/user/workspace/index.md b/doc/user/workspace/index.md index 0befcbe25d2..0ef3eb8b6fe 100644 --- a/doc/user/workspace/index.md +++ b/doc/user/workspace/index.md @@ -39,4 +39,4 @@ For a video introduction to the new hierarchy concept for groups and projects fo ## Related topics -- [Workspaces developer documentation](../../development/workspaces/index.md) +- [Workspace developer documentation](../../development/workspace/index.md) |
